Безопасное обновление ядра Paper: автоматизация сборок, совместимость миров и плагинов

Регулярное обновление ядра Paper — обязательная процедура для поддержания стабильности, защиты от уязвимостей и устранения багов на сервере Minecraft. Команда PaperMC выпускает десятки сборок в неделю, оптимизируя сетевой код и исправляя ошибки ванильного движка Mojang. Однако «слепое» скачивание нового .jar файла без предварительного создания точки отката чревато крахом плагинов, повреждением структур мира и необратимым сбросом чанков.

В этом материале разобран регламент безопасного обновления Paper, получение проверенных сборок через официальный REST API v2, автоматизация процесса через Bash-скрипты и проверка совместимости плагинов после старта.

Архитектура версий PaperMC и риски обновлений#

Серверное ядро Paper распространяется в виде исполняемого jar-пакета Paperclip, который динамически патчит ванильный сервер Minecraft на лету. Версионирование строится по схеме: <Minecraft_Version>-<Build_Number> (например, 1.21.1-118).

Обновления ядра делятся на два типа с разным уровнем риска:

1. Патч-сборки внутри одной версии (Minor builds): Например, обновление со сборки 80 на сборку 115 внутри Minecraft 1.21.1. Риск минимален: они содержат точечные фиксы производительности и не ломают Bukkit API.
2. Переход на новую версию игры (Major/Minor version bumps): Например, с 1.20.4 на 1.21.0. Высокий риск: Mojang изменяет схему сериализации NBT-тегов в файлах регионов. Мир, однажды запущенный на более новой версии, невозможно откатить назад без предварительного бэкапа — старое ядро просто посчитает новые чанки повреждёнными и перегенерирует их заново.

Создание точки отката: резервное копирование мира и плагинов#

Перед заменой исполняемого файла всегда останавливайте службу сервера. Запись на диск во время работы сервера приведет к несогласованности файлов:

sudo systemctl stop minecraft
sudo systemctl status minecraft --no-pager

Создайте изолированный архив рабочей папки мира, плагинов и конфигурационных файлов:

BACKUP_DIR="/opt/minecraft/backups"
TIMESTAMP=$(date +%Y%m%d_%H%M%S)
mkdir -p "$BACKUP_DIR"

tar -czf "$BACKUP_DIR/pre_update_${TIMESTAMP}.tar.gz" \
  -C /opt/minecraft world world_nether world_the_end plugins config

Проверьте, что архив успешно создан и имеет ненулевой размер:

ls -lh "$BACKUP_DIR/pre_update_${TIMESTAMP}.tar.gz"

При использовании панели управления серверами снапшоты состояния и точек отката выполняются автоматически перед установкой каждого нового билда ядра.

Получение актуальной сборки через официальный REST API PaperMC#

Вместо ручного скачивания файлов из браузера используйте официальный публичный REST API PaperMC v2.

Узнайте номер последней стабильной сборки для вашей версии игры (например, 1.21.1):

MINECRAFT_VERSION="1.21.1"
API_URL="https://api.papermc.io/v2/projects/paper/versions/${MINECRAFT_VERSION}"

LATEST_BUILD=$(curl -s "$API_URL" | jq '.builds[-1]')
echo "Latest available Paper build: $LATEST_BUILD"

Загрузите .jar файл напрямую с сервера PaperMC:

DOWNLOAD_URL="https://api.papermc.io/v2/projects/paper/versions/${MINECRAFT_VERSION}/builds/${LATEST_BUILD}/downloads/paper-${MINECRAFT_VERSION}-${LATEST_BUILD}.jar"

curl -o "/opt/minecraft/paper-${MINECRAFT_VERSION}-${LATEST_BUILD}.jar" "$DOWNLOAD_URL"

Сверьте контрольную сумму SHA256 загруженного файла с данными API:

EXPECTED_SHA=$(curl -s "https://api.papermc.io/v2/projects/paper/versions/${MINECRAFT_VERSION}/builds/${LATEST_BUILD}" | jq -r '.downloads.application.sha256')
ACTUAL_SHA=$(sha256sum "/opt/minecraft/paper-${MINECRAFT_VERSION}-${LATEST_BUILD}.jar" | awk '{print $1}')

test "$EXPECTED_SHA" = "$ACTUAL_SHA" && echo "Checksum verified successfully!"

Автоматизация скриптом обновления и проверка контрольных сумм#

Для регулярного обновления настройте символическую ссылку paper.jar, указывающую на активный билд:

cd /opt/minecraft
ln -sf "paper-${MINECRAFT_VERSION}-${LATEST_BUILD}.jar" paper.jar

Настройте права доступа системного пользователя minecraft:

sudo chown -R minecraft:minecraft /opt/minecraft
sudo chmod 644 /opt/minecraft/paper*.jar

Запустите службу сервера и контролируйте журнал загрузки:

sudo systemctl start minecraft
sudo journalctl -u minecraft -f --no-pager

Диагностика несовместимости плагинов после обновления#

Во время инициализации сервера обратите внимание на предупреждения в логах:

1. Ошибка UnsupportedClassVersionError: Новая версия Paper собрана под более свежую версию Java (например, Java 21). Убедитесь, что сервер использует актуальный пакет OpenJDK (java -version).
2. Ошибка PluginClassLoader или NoSuchMethodError: Устаревший плагин попытался вызвать метод Bukkit API, удалённый в свежем билде. Отключите проблемный плагин (переименуйте расширение в .jar.disabled) и проверьте наличие обновления на Modrinth или SpigotMC.
3. Откат к предыдущей версии: Если критический плагин не работает, просто переключите симлинк paper.jar назад на предыдущий рабочий билд и перезапустите службу:
   bashКопироватьСкопированоНе удалосьКопировать

   ln -sf paper-previous-stable.jar paper.jar
   sudo systemctl restart minecraft
   

Источники#

• PaperMC Official REST API Documentation
• PaperMC Downloads Portal and Build Automation
• Bukkit and Paper API Compatibility Guidelines