Skip to content

Latest commit

 

History

History
410 lines (320 loc) · 37.2 KB

updates.md

File metadata and controls

410 lines (320 loc) · 37.2 KB

Обновления

pnLibrary обновляет себя и плагины pnFolder, которые зарегистрировались в её сервисе обновлений. Чужие плагины в каталог не попадают: их список используется только для проверки зависимостей. Bukkit, BungeeCord и Velocity используют один каталог, одни правила, один журнал и одни транзакции. Различаются только команды и то, как подготовленные файлы попадают на место при перезапуске.

Главное правило: работающий jar-файл никогда не заменяется на ходу. Обновление подготавливается, а применяется при следующем запуске сервера. Библиотека никогда не говорит «обновлено», пока новая версия действительно не запустилась.

1. Как проходит обновление

проверить каталоги → подобрать совместимые версии → проверить права → сохранить выбранные конфиги
→ скачать и сверить SHA-256 → подготовить транзакцию → перезапуск → убедиться, что запустились
нужные версии → записать итог в журнал

Автоматическая подготовка разрешена, только если выполнено всё сразу:

  • администратор явно разрешил автозагрузку;
  • совпадают версия API pnLibrary, Java и платформа;
  • все зависимости совместимы;
  • у файлов есть контрольные суммы от издателя;
  • есть всё, что нужно для отката;
  • нет другой незавершённой транзакции.

Совместимость не означает, что код чужого плагина безопасен. Поэтому сервер никогда не перезапускается сам.

Каталог обязан публиковать настоящие SHA-256 файлов (require-sha256: true по умолчанию). Если суммы нет или она не совпала, подготовка отклоняется. Сумму, посчитанную при скачивании, библиотека не подставляет вместо суммы издателя.

2. Настройка: командами и в меню

Файла настроек обновлений нет. Всё, что меняет администратор, делается командами или в меню /pn gui, а выбор хранится в папке data/updates/ и применяется сразу:

  • /pn updates set <плагин> auto on|off: автоскачивание одного плагина (у pnlibrary это сама библиотека);
  • /pn updates set all auto on|off: автоскачивание для всех плагинов сразу, включая те, что подключатся позже;
  • /pn updates set <плагин> channel <канал>: канал релизов. Сейчас можно выбрать только dev (остальные каналы ещё не выпускаются и отклоняются) или default: тогда канал снова задаёт плагин;
  • /pn updates set <плагин> java <8|11|17|21|default>: сборка Java для продукта. Список берётся из каталога (файлы, подходящие платформе и вашей Java). Если ничего не выбрано, берётся сборка, как у установленного продукта, а потом любая подходящая. В меню: карточка продукта, «Сборка Java»;
  • /pn updates set <плагин> hold <период>: пауза от 1 минуты до 7 суток, потом обновления возвращаются сами.

По умолчанию автоскачивание включено у всех. Отключить обновление навсегда нельзя: списка «не обновлять» нет, остаётся только пауза. Проверки и напоминания работают всегда. Остальное зашито в коде (UpdateDefaults): проверка каталогов на GitHub раз в 6 часов (первая сразу при старте), таймауты скачивания 10 с и 30 с, файл не больше 512 МБ, SHA-256 обязателен.

Напоминания. Пока обновление доступно или ждёт перезапуска, оно напоминается в консоли и в чате администраторам (оп, *, pnlibrary.admin или pnlibrary.updates.notify), а также при входе. Интервал напоминаний по умолчанию 6 часов, разработчик библиотеки может задать его в коде от 1 минуты до 6 часов, администратор не может. Напоминание не обращается к GitHub: оно показывает уже известное состояние, а когда очередная проверка видит, что релиз исчез, напоминания прекращаются. Чат-напоминания есть на Bukkit, Velocity и BungeeCord.

Файл updates.yml старых версий больше не читается. При запуске он переименовывается в updates.yml.old, а в консоль идёт предупреждение; значения из него не переносятся.

Если релиз плагина заблокирован уровнем API, команды и меню пишут причину; когда библиотека слишком старая для плагина, добавляется подсказка сначала обновить pnLibrary.

Это разрешает только подготовку проверенных файлов: ни замены jar на ходу, ни перезапуска не будет. Если в одном плане меняется несколько модулей, каждый должен быть разрешён своей настройкой. Разрешение для pnLibrary не обходит выключенный модуль.

3. Команды

Команда везде одна: /pn (запасные названия /pnlib и /pnlibrary на случай, если /pn занят другим плагином). Набор команд одинаков на Bukkit, BungeeCord и Velocity. Они работают и из консоли, и у игроков, у каждого действия своё право (см. ниже). Отличие одно: /pn update restart есть только на Bukkit, прокси перезапускают своей обычной командой.

Команда Что делает
/pn или /pn updates list [страница] все управляемые плагины: текущая и доступная версия, состояние
/pn updates available [страница] только плагины с доступным или подготовленным обновлением
/pn check обновить каталоги и составить план
/pn status [плагин] состояние плана и что ему мешает
/pn update <плагин> скачать, проверить и подготовить обновление плагина
/pn update rollback попросить откат всего плана обновления; в ответ приходит код подтверждения
/pn update restart (только Bukkit) перезапуск, который применит подготовленные обновления: карточка с тремя кнопками «Сейчас», «Через 5 мин», «Когда никого нет», у каждой свой код; работает и из консоли. Игрокам приходит отсчёт. Карточка появляется сама после подготовки обновления или отката
/pn update restart cancel (только Bukkit) отменить запланированный перезапуск
/pn update confirm <код> выполнить то, для чего выдан код: откат плана, откат к резервному набору или перезапуск
/pn updates info <плагин> карточка: версия, канал, свежая версия каждого канала (по клику канал переключается), автозагрузка, пауза, API, Java, ссылки
/pn updates settings <плагин> канал, автозагрузка и пауза кнопками
/pn updates set <плагин> channel <stable|rc|beta|alpha|dev> сменить канал
/pn updates set <плагин> auto <on|off> включить или выключить автозагрузку
/pn updates set <плагин> hold <1m..7d|on|off> поставить обновления на паузу; on значит 7 дней, новая пауза заменяет старую, пауза снимается сама
/pn updates history [страница] события, новые сверху, по дням: переход версий, итог, кто сделал
/pn updates history plugin <имя> [страница] история одного плагина
/pn updates backups [plugin <плагин>] [since <7d|2026-10-31>] [sort <new|old|plugin>] [страница] сохранённые наборы для отката. Условия можно сочетать в любом порядке, каждое один раз: только наборы с этим плагином, только за последние N дней или с даты, порядок «сначала новые», «сначала старые» или «по плагину». Кнопки страниц и порядка сохраняют условия, «Сбросить» их снимает
/pn updates rollback <транзакция> попросить откат к сохранённому набору jar; в ответ приходит код подтверждения
/pn updates rollback <транзакция> configs то же, вместе с сохранёнными конфигами
/pn updates backups restore <id> <плагин> <имя базы> вернуть сохранённую базу (сначала предупреждение, потом команда с confirm)
/pn updates backups files <id> <плагин> выдать сохранённые базы и выгрузки плагина файлами
/pn updates backups delete <id> удалить резервный набор

Настройки и паузы запоминаются в одном файле data/updates/preferences.json (разделы channels, automatic, allPlugins, freezes, javaBuilds). Каждое изменение попадает в историю вместе с автором.

Опасные действия требуют права и подтверждения. Схема всегда одна: сначала просишь действие (update rollback, update restart, updates rollback …) и получаешь одноразовый код на 30 секунд, потом выполняешь /pn update confirm <код>. Код привязан к тому, кто просил (игроку или консоли), и к самому действию, поэтому чужой код или код другого действия не сработает. Слова confirm, status, rollback, restart и all заняты командой, поэтому плагин с таким именем не может зарегистрировать обновления. Кнопки в чате вызывают те же проверенные обработчики, что и набранные команды. В консоли всё читается без наведения и кликов. Ссылка на список изменений открывает страницу релиза: Markdown в чат не выводится.

Права

Право Что разрешает
pnlibrary.admin всё управление pnLibrary и обновлениями
pnlibrary.updates.view смотреть план обновлений
pnlibrary.updates.settings менять канал, автозагрузку и паузу
pnlibrary.updates.download скачивать и проверять план
pnlibrary.updates.install разрешать установку новых компонентов
pnlibrary.updates.restart подтверждать перезапуск после подготовки
pnlibrary.updates.rollback смотреть резервные наборы и откатывать
pnlibrary.updates.notify получать напоминание об обновлениях при входе

Для плагинов: library.updates

UpdateService разделён на пять частей, в каждой работает всё: необязательных операций нет.

Часть Что делает Методы
products какие продукты зарегистрированы all(), get(имя), require(имя)
plans проверка релизов и план check(actor), current(), recent(), stage(план, actor)
settings выбор администратора для продукта channel, automaticDownload, automaticDownloadForAll, hold(продукт, срок), release, heldUntil, javaBuild
backups резервные наборы и откат list(), rollback(actor), rollback(набор, actor, restoreConfigurations), delete, restoreDatabase, extract
history журнал событий page(страница, продукт), count(продукт)
val updates = library.updates
updates.register(plugin, product, request)                            // начать следить за релизами
updates.plans.check(actor).thenCompose { plan -> updates.plans.stage(plan.id, actor) }
updates.settings.hold("shop", Duration.ofDays(3), actor)              // не предлагать три дня
updates.settings.release("shop", actor)                               // снять досрочно
updates.backups.list().thenAccept { sets -> sets.forEach { println(it.id) } }
updates.history.page(1, "shop")                                       // последние десять событий

Каждый метод, который что-то меняет, принимает actor: он пишется в журнал, но прав не даёт. Без него записывается UpdateActor.UNKNOWN. Подтверждение чувствительных шагов (/pn update confirm <код>) выполняют команды и меню, в API его нет.

4. Применение перед запуском: pnLibrary-updater

В релиз входит отдельный pnLibrary-updater-<версия>.jar. Это не плагин: держите его вне папки plugins и запускайте только тогда, когда JVM сервера полностью остановлена:

java -jar pnLibrary-updater-<версия>.jar --server-stopped plugins/pnLibrary

Скрипт запуска должен стартовать сервер, только если установщик завершился успешно. Сам установщик сервер не останавливает и не запускает. Его файловая блокировка не даст работать параллельно с живой pnLibrary или другим установщиком, но не заменяет проверку администратора, что сервер остановлен. Не запускайте его во время старта сервера или после простого выключения pnLibrary при работающих других плагинах.

Что делает установщик:

  1. Ещё раз сверяет суммы сохранённых файлов.
  2. Ведёт отдельную транзакцию восстановления.
  3. Публикует новый набор jar и забирает подготовленные файлы платформы.

Проверка, что всё запустилось, происходит при следующем старте сервера, а не в том же процессе. Прерванную запись jar-файлов восстанавливает только этот установщик.

5. Резервные копии: тип, имя, срок

Автор плагина перечисляет файлы явно и говорит, что это такое. Тип и имя видны администратору в меню и в /pn updates backups:

PluginUpdateRequest.builder()
    .configurationBackup(dataDirectory, "config.yml", "messages.yml")
    .backup(BackupKind.DATABASE, "Кланы", dataDirectory, "clans.db")
    .backup(BackupKind.PLAYER_DATA, "Балансы", dataDirectory, "balances.json")

Типы: CONFIGURATION (до 4 МБ на файл и до 16 МБ всего), DATABASE, PLAYER_DATA, OTHER (до 1 ГБ на файл, до 4 ГБ всего). Имя копии не длиннее 64 символов. Базу SQLite или H2 библиотека копирует сама, пока плагин остановлен для обновления. Сохраняются только файлы изменившихся зарегистрированных компонентов. Свои настройки (data/settings.json) pnLibrary сохраняет сама. Номер снимка хранится в той же транзакции обновления.

Срок и размер:

  • набор хранится 30 дней, потом удаляется сам (при старте сервера); набор, который ещё проверяется после перезапуска, не удаляется;
  • если копии (конфиги, транзакции, выгрузки и базы вместе) занимают 500 МБ и больше, при очистке в консоль выводится предупреждение с командой удаления;
  • данные, которые библиотека не копирует как файл (например MySQL), плагин выгружает сам: .backupExport(BackupKind.DATABASE, "Кланы", "clans.sql") { файл -> выгрузить(файл) }. Имена файлов выгрузок в одном плагине не повторяются. Файл лежит в plugins/pnLibrary/data/updates/exports/<план>/<плагин>/, откат его не восстанавливает: загрузите вручную. Если выгрузка упала, обновление не готовится;
  • удалить набор вручную: /pn updates backups delete <id> (право на управление обновлениями), в API updates.backups.delete(id, actor).

Базы данных MySQL/MariaDB

Плагин помечает раздел конфига с подключением. Имя в @BackupDatabase — это ID базы у плагина, оно должно быть разным у разных баз:

class Config {
    @field:BackupDatabase(DatabaseKind.MYSQL, "Кланы")
    var clans = Connection()

    @field:BackupDatabase(DatabaseKind.MYSQL, "Банк")
    var bank = Connection()
}

class Connection {
    @field:DatabaseField(DatabaseRole.HOST) var address = "localhost"   // имя поля любое
    var port = 3306
    var database = ""
    var user = ""
    @field:ConfigSecret var password = ""
}

Поля находятся по обычным именам (host, port, database, user/username, password) или по @DatabaseField(роль), если названы иначе. Аннотацию можно поставить и на сам класс конфига, когда поля подключения лежат в корне файла. Драйвер загружается через Libby при первой копии.

Несколько баз в одном классе, без отдельных классов и без аннотаций на классе. Тип и имя базы пишутся на поле с названием базы, остальные поля подключения помечаются тем же именем (database = "имя"):

class GlobalConfig {
    @field:BackupDatabase(DatabaseKind.MYSQL, "Игроки", tables = ["players", "stats"])
    var playersDb = "players"
    @field:DatabaseField(DatabaseRole.HOST, database = "Игроки") var playersHost = "db1.local"
    @field:DatabaseField(DatabaseRole.USER, database = "Игроки") var playersUser = "app"
    @field:DatabaseField(DatabaseRole.PASSWORD, database = "Игроки") @field:ConfigSecret var playersPass = ""

    @field:BackupDatabase(DatabaseKind.POSTGRESQL, "Кланы")
    var clansDb = "clans"
    @field:DatabaseField(DatabaseRole.HOST, database = "Кланы") var clansHost = "pg.local"
    @field:DatabaseField(DatabaseRole.USER, database = "Кланы") var clansUser = "clans"
    @field:DatabaseField(DatabaseRole.PASSWORD, database = "Кланы") @field:ConfigSecret var clansPass = ""
}

Поле без database общее для всех баз класса (например, один пароль на всё). @BackupDatabase можно поставить и на сам класс (повторяемая), тогда имя базы берётся из @DatabaseField(DATABASE, database = "имя"). @BackupTable(database = "имя") привязывается к базе так же; без database относится ко всем базам класса. Имена баз в одном плагине должны быть разными.

Только свои таблицы. Если база общая с другими плагинами, копируйте только нужное:

@field:BackupDatabase(DatabaseKind.MYSQL, "Кланы", tables = ["clans", "clan_members"])
var storage = Connection()

Если имя таблицы задаётся в конфиге, пометьте это поле @field:BackupTable (полей может быть несколько, списки складываются). Без tables и @BackupTable копируется вся база. В MongoDB то же самое для коллекций; в PostgreSQL копируются ещё последовательности этих таблиц. Возврат трогает только таблицы из копии. В имени работает *: tables = ["log_*"] берёт таблицы, которые плагин создаёт сам (по датам и т. п.).

Выдать файлы вместо возврата: в меню «Резервные копии → плагин → дата» кнопка «Выдать файлы» или команда /pn updates backups files <id> <плагин> кладёт сохранённые базы и выгрузки в plugins/pnLibrary/data/updates/handout/ и показывает путь. Список в меню теперь идёт так: плагин, дата, способ возврата.

Перед обновлением библиотека делает копию каждой помеченной базы (одним снимком, без остановки плагина) в plugins/pnLibrary/data/updates/databases/<план>/<плагин>/<имя>.db.gz. Копия одной базы не больше 2 ГБ. Если копия не получилась, обновление не готовится. Копируются таблицы; триггеры, процедуры и представления нет.

Вернуть базу: в меню «Резервные копии → набор» кнопка «Вернуть базу «…»» открывает предупреждение о потере данных, или командой /pn updates backups restore <id> <плагин> <имя>: она сначала предупреждает и показывает команду с confirm. Перед заменой текущее состояние базы сохраняется отдельной копией (before-restore). Откат JAR базы не трогает, её возвращают отдельно. После возврата перезапустите плагин.

MongoDB

@BackupDatabase(DatabaseKind.MONGODB, "Профили") работает так же. Подключение: host, port (27017), database, user, password (user можно не указывать) или одна строка uri (mongodb://...); другие имена полей помечаются @DatabaseField, строку подключения задаёт роль DatabaseRole.URI. Копируются все коллекции с индексами, типы значений сохраняются. У MongoDB нет снимка на момент времени: если плагин пишет во время копии, коллекции могут отличаться на доли секунды.

PostgreSQL

@BackupDatabase(DatabaseKind.POSTGRESQL, "Экономика"): подключение как у MySQL (порт по умолчанию 5432). Копируются таблицы текущей схемы (current_schema()) с индексами, ограничениями, внешними ключами, значениями по умолчанию и позициями последовательностей, одним снимком в транзакции только для чтения. Представления, функции, триггеры и другие схемы не копируются. При возврате таблицы пересоздаются; внешние ключи таблиц, которых нет в копии и которые ссылались на возвращаемые, снимаются.

Что и когда скачивается

Только Kotlin нужен всегда (и то лишь в лёгком JAR). Всё остальное скачивается через Libby в первый момент, когда оно понадобилось, и только если нужно: драйверы MySQL/MariaDB, PostgreSQL и MongoDB при первой копии или возврате базы, компилятор ECJ при первой проверке политики на сервере без javac. Нет аннотации @BackupDatabase или политик, ничего не скачивается.

Правила:

  • копируются только зарегистрированные пути компонента, а не вся папка плагина или сервера;
  • символические ссылки, пути за пределами зарегистрированных папок и совпадающие имена отклоняются; есть ограничения на число и размер файлов;
  • кэши, ключи и прочие файлы сами собой никогда не попадают в копию, только то, что плагин назвал;
  • у копии есть манифест с хешами;
  • копии, на которые ссылается возможный откат, не удаляются при очистке.

Обычный откат конфиги не трогает. Чтобы вернуть и их:

/pn updates rollback <транзакция> configs и подтверждение /pn update confirm <код>; код привязан к тому, кто его запросил (игроку или консоли).

Команда только ставит задачу и ничего не восстанавливает на живом сервере. Остановите JVM и запустите установщик. В момент восстановления текущие файлы сохраняются ещё раз, включая те, которых не было в исходном снимке. Посторонние файлы не удаляются. Если установка не удалась, установщик возвращает и прежние jar, и прежние конфиги. Если вернуть не получилось, он завершается с ненулевым кодом, и скрипт запуска не должен стартовать сервер.

6. Проверка после запуска

События старта сохраняют исходную транзакцию и реальные переходы версий, даже если новая проверка уже составила другой план. Подтверждение отката записывается отдельным событием HEALTH_ROLLBACK. Проверяется, что загрузились нужные версии зарегистрированных плагинов, а не их бизнес-логика.

Фоновые проверки начинаются после сверки при старте. На прокси зарегистрированным плагинам даётся 30 секунд на инициализацию. Если проверка не прошла, автоматическая подготовка для этих плагинов останавливается. Снять запрет может только следующая проверка, которая увидит ожидаемые версии. Простой перезапуск или загрузка каталога его не снимают.

7. Журнал обновлений

Файлы лежат в data/ папки данных pnLibrary:

updates/
  state.json                 последний снимок плана
  history/                   ограниченная история снимков плана
  catalog/                   кэш каталогов релизов
  staging/<план>/            скачанные файлы до публикации
  transactions/<id>/         транзакции и резервные jar
  events/                    события с временем, удаляются по возрасту и количеству
  components.json            компоненты, версии и настройки на прошлом старте
  configurations/<id>/       выбранные резервные копии конфигов и файлов данных
  configuration-restores/    журналы восстановления конфигов и снимки перед восстановлением
  databases/<план>/<плагин>/ копии баз MySQL, PostgreSQL, MongoDB (<имя>.db.gz)
  exports/<план>/<плагин>/   выгрузки, которые плагин сделал сам (backupExport)
  handout/                   файлы, выданные командой backups files
  install.lock               не даёт рантайму и установщику работать одновременно
  preferences.json           канал, автозагрузка по плагинам и паузы

Каждое событие хранит:

  • номер события и номер транзакции или плана;
  • время в UTC;
  • кто сделал (игрок, консоль или SYSTEM);
  • действие, плагины, старую и новую версию;
  • итог.

Ключи и значения конфигов в журнал не попадают. Время установки никогда не выводится из даты релиза или даты файла.

Кроме операций плана (CHECK, STAGE, ROLLBACK, HEALTH, HEALTH_ROLLBACK, STATE_OBSERVED), журнал отмечает изменения, найденные сравнением components.json с прошлым стартом:

  • COMPONENT_ADDED, COMPONENT_REMOVED;
  • VERSION_CHANGED: версия поменялась не через обновление;
  • SETTINGS_CHANGED: сменился канал или автозагрузка.

Первый старт только записывает исходное состояние.

Журнал ограничен: удаляются события старше 90 дней и всё сверх последних 1000. Наблюдение, совпадающее с предыдущим событием, повторно не пишется.

8. Для разработчиков библиотеки: приёмка на настоящих серверах

Эти тесты используют jar-файлы серверов, которые вы указываете сами. Они создают свои папки в build/update-catalog-native, слушают только локальные порты, выключают метрики и сохраняют логи каждого этапа. Существующие серверы не трогаются. Синтетический релиз меняет только метаданные версий, никуда не загружается и не выдаётся за настоящий.

Проверяются:

  • хеши установленных jar;
  • команды;
  • привязка к исходной транзакции;
  • настоящие перезапуски процесса;
  • события проверки после запуска;
  • явное восстановление конфигов.

Сетевую часть (каталог, подбор версий, правила подготовки) покрывают тесты core.

gradlew :modules:updates:verifyNativeProxyUpdates -PvelocityServerJar=<velocity.jar> -PbungeeServerJar=<bungeecord.jar>
gradlew :modules:updates:verifyNativeBukkitUpdates -PpaperServerJar=<paper.jar> -PpaperEulaFile=<уже-принятый-eula.txt>

Тест Paper запускается только с разрешения администратора и с уже принятым EULA: сам он условия не принимает. Копируются только кэши серверного ПО, никогда миры, данные плагинов или секреты.

В Actions workflow Native platform acceptance запускает эти циклы отдельно для Paper, Folia, Velocity и Bungee. Для каждой платформы администратор задаёт repository variables NATIVE_PAPER_URL / NATIVE_PAPER_SHA256 (аналогично FOLIA, VELOCITY, BUNGEE). URL должен вести на JAR по HTTPS; SHA-256 фиксирует конкретную сборку. Для Paper/Folia secret NATIVE_MINECRAFT_EULA содержит уже принятый администратором eula.txt. Отсутствие параметров завершает выбранный job ошибкой, а не пропускает проверку. Логи и отчёты сохраняются как artifacts.

Версия Java для серверов выбирается при ручном запуске workflow; сам Gradle работает на Java 21. Локально можно передать -PnativeJavaExecutable=<java>; отдельный proxy выбирается через -PnativePlatform=velocity или bungee, Folia — через -PbukkitPlatform=folia и -PpaperServerJar=<folia.jar>. Основной CI отдельно проверяет запуск упакованного updater на Java 8, 17 и 21. Это smoke-проверка updater, а не доказательство совместимости всех подсистем сервера с каждой JVM.