Как устанавливать и обновлять плагины на сервере Minecraft Paper
Переведите ванильный сервер Minecraft на Paper без потери мира, затем устанавливайте и обновляйте плагины на VPS или выделенном Linux-сервере.
На этой странице
Ваши значения
Укажите их один раз, и команды в руководстве обновятся.
Официальный (ванильный) сервер Minecraft не загружает плагины. Это руководство объясняет, как заменить его на Paper, сохранив ваш мир, а затем правильно устанавливать и обновлять плагины.
Оно продолжает руководство Создание сервера Minecraft и использует его элементы: пользователя minecraft, папку /opt/minecraft/server, файл server.jar и сервис minecraft.service.
В итоге у вас будут:
- Java 25 и Paper вместо ванильного сервера, а ваш мир останется нетронутым
- команда
mc-consoleдля работы с консолью сервера, запущенного через systemd - первый установленный плагин и безопасный способ обновления
Предварительные требования
- Сервер, установленный по руководству Создание сервера Minecraft
- SSH-доступ с пользователем, у которого есть
sudo - Достаточно места на диске для полной копии папки сервера
Проверка текущего сервера
Сначала посмотрите, какая версия Minecraft запущена и работает ли сервер уже на Paper:
sudo grep -m1 'Starting minecraft server version' /opt/minecraft/server/logs/latest.log
unzip -l /opt/minecraft/server/server.jar | grep -q 'io/papermc/paperclip/Main.class' && echo Paper || echo VanillaЕсли вторая команда выводит Paper, ваш сервер уже переведён: сделайте резервную копию и переходите сразу к активации консоли.
Остановка и резервное копирование сервера
Остановите сервер, проверьте свободное место, затем создайте полный архив:
sudo systemctl stop minecraft.service
sudo du -sh /opt/minecraft/server
df -h /opt/minecraft
sudo mkdir -p /opt/minecraft/backups
sudo tar -czf /opt/minecraft/backups/avant-paper-$(date +%F-%H%M).tar.gz -C /opt/minecraft server
sudo ls -lh /opt/minecraft/backupsЕсли вы запускаете сервер в screen, вместо первой команды введите stop в его консоли.
Установка Java 25
Paper рекомендует Amazon Corretto, доступный для Debian и Ubuntu. Добавьте его репозиторий, затем установите Java 25:
sudo apt update
sudo apt install -y ca-certificates apt-transport-https gnupg wget curl jq
wget -O - https://apt.corretto.aws/corretto.key | sudo gpg --dearmor --yes -o /usr/share/keyrings/corretto-keyring.gpg
echo "deb [signed-by=/usr/share/keyrings/corretto-keyring.gpg] https://apt.corretto.aws stable main" | sudo tee /etc/apt/sources.list.d/corretto.list
sudo apt update
sudo apt install -y java-25-amazon-corretto-jdk libxi6 libxtst6 libxrender1Сервис запускает /usr/bin/java. Если у вас установлена и Java 21, направьте эту команду на Java 25:
sudo update-alternatives --set java "$(update-alternatives --list java | grep -m1 'java-25')"
java --versionВывод должен начинаться с openjdk 25.
Переход на Paper без потери мира
Переход сводится к замене server.jar файлом Paper. Поскольку имя остаётся прежним, сервис systemd менять не нужно, а папка world, файл server.properties и списки игроков остаются на месте.
Создайте скрипт, который загружает последнюю стабильную сборку, проверяет её контрольную сумму и заменяет server.jar. Он пригодится и при каждом обновлении:
sudo nano /opt/minecraft/paper-update.sh#!/bin/bash
# Загружает последнюю стабильную сборку Paper и заменяет server.jar
set -euo pipefail
MC_VERSION="${1:?Укажите версию Minecraft, например 26.3}"
UA="mon-serveur-minecraft/1.0 (https://your-domain.com)"
API="https://fill.papermc.io/v3/projects/paper/versions/$MC_VERSION/builds"
cd /opt/minecraft/server
BUILD=$(curl -fsSL -H "User-Agent: $UA" "$API" | jq -c 'map(select(.channel == "STABLE")) | .[0]')
if [ "$BUILD" = "null" ]; then
echo "Не найдена стабильная сборка для Minecraft $MC_VERSION." >&2
exit 1
fi
URL=$(echo "$BUILD" | jq -r '.downloads."server:default".url')
SHA256=$(echo "$BUILD" | jq -r '.downloads."server:default".checksums.sha256')
curl -fL -H "User-Agent: $UA" -o server.jar.new "$URL"
echo "$SHA256 server.jar.new" | sha256sum -c -
if [ -f server.jar ]; then
mv server.jar server.jar.old
fi
mv server.jar.new server.jar
echo "Paper $MC_VERSION, сборка $(echo "$BUILD" | jq -r '.id'), установлен."В строке UA замените your-domain.com адресом вашего сайта или другим способом связи с вами: API Paper требует User-Agent, который идентифицирует ваш проект и содержит контакт.
Сделайте скрипт исполняемым, затем запустите его от имени пользователя minecraft:
sudo chmod 755 /opt/minecraft/paper-update.sh
sudo -u minecraft /opt/minecraft/paper-update.sh 26.3Строка server.jar.new: OK подтверждает, что загруженный файл не повреждён. Прежний сервер сохраняется под именем server.jar.old.
Активация консоли сервиса
В сервисе из базового руководства указано StandardInput=null, поэтому консоли у него нет, а многие плагины настраиваются командами. Вы добавите её с помощью именованного канала, не открывая сетевой порт.
Создайте юнит, который отвечает за этот канал:
sudo nano /etc/systemd/system/minecraft.socket[Unit]
Description=Консоль сервера Minecraft
PartOf=minecraft.service
[Socket]
ListenFIFO=/run/minecraft.stdin
SocketMode=0600Записывать в этот канал может только root, поэтому перед mc-console стоит sudo.
Затем добавьте дополнение к сервису. Этот файл расширяет minecraft.service, не изменяя его:
sudo mkdir -p /etc/systemd/system/minecraft.service.d
sudo nano /etc/systemd/system/minecraft.service.d/console.conf[Unit]
Requires=minecraft.socket
After=minecraft.socket
[Service]
Sockets=minecraft.socket
StandardInput=socket
StandardOutput=journal
StandardError=journal
SuccessExitStatus=130 143
TimeoutStopSec=180SuccessExitStatus не даёт сервису отображаться как сбойный после обычной остановки, а TimeoutStopSec оставляет серверу три минуты на сохранение мира.
Наконец, создайте команду mc-console, которая отправляет команду серверу и показывает его ответ:
sudo nano /usr/local/bin/mc-console#!/bin/bash
# Отправляет команду в консоль Minecraft и показывает ответ из журнала
if [ "$#" -eq 0 ]; then
echo "Использование: mc-console <команда>" >&2
exit 1
fi
if ! systemctl is-active --quiet minecraft.service; then
echo "Сервис minecraft.service не запущен." >&2
exit 1
fi
DEBUT=$(date '+%Y-%m-%d %H:%M:%S')
printf '%s\n' "$*" > /run/minecraft.stdin
sleep "${MC_CONSOLE_WAIT:-2}"
journalctl -u minecraft.service --since "$DEBUT" --no-pager -o catsudo chmod 755 /usr/local/bin/mc-console
sudo systemctl daemon-reloadЗапуск Paper
sudo systemctl start minecraft.service
sudo journalctl -u minecraft.service -fПервый запуск занимает больше времени: Paper загружает файлы Minecraft, а затем преобразует мир. Он выводит World storage migration is required during startup и ждёт 30 секунд, прежде чем продолжить, так что вы успеете прервать запуск, если у вас нет резервной копии.
Сервер готов, когда появляется строка Done (…)! For help, type "help". Выйдите из просмотра журнала клавишами Ctrl+C: сервер продолжит работать.
Проверка результата
sudo mc-console version
sudo mc-console plugins
sudo ls /opt/minecraft/server /opt/minecraft/server/worldВы должны получить:
- строку
This server is running Paper version 26.3-… Server Plugins (0), так как ни один плагин ещё не установлен- новые файлы
bukkit.yml,spigot.ymlи папкуconfig, а также вашу папкуworld
Папки plugins/spark и plugins/bStats создаёт сам Paper: это нормально. Наконец, подключитесь к серверу через клиент Minecraft и убедитесь, что ваши постройки на месте.
Установка плагина
Выбор совместимого плагина
Перед загрузкой плагина проверьте на его странице три момента:
- он предназначен для Paper (или Spigot/Bukkit), а не для Fabric или Forge, которые являются модами
- заявлена поддержка вашей версии Minecraft
- указаны его зависимости, если они есть: их тоже нужно установить
Загружайте плагины только из надёжных источников: Hangar (репозиторий плагинов Paper), Modrinth, официальный сайт или репозиторий проекта на GitHub. Плагин выполняется с правами пользователя minecraft и может читать всю папку сервера.
Установка из Hangar
В примере ниже устанавливается Chunky — плагин для предварительной генерации мира. Сначала посмотрите его последнюю версию и поддерживаемые версии Minecraft:
sudo -u minecraft bash
cd /opt/minecraft/server/plugins
UA="mon-serveur-minecraft/1.0 (https://your-domain.com)"
API="https://hangar.papermc.io/api/v1/projects/Chunky/versions?limit=1&channel=Release&platform=PAPER"
curl -fsSL -H "User-Agent: $UA" "$API" | jq '.result[0] | {version: .name, minecraft: .platformDependencies.PAPER, fichier: .downloads.PAPER.fileInfo.name}'Если ваша версия Minecraft есть в списке, загрузите файл и выйдите из сессии minecraft:
URL=$(curl -fsSL -H "User-Agent: $UA" "$API" | jq -r '.result[0].downloads.PAPER.downloadUrl')
curl -fLO -H "User-Agent: $UA" "$URL"
ls -l
exitЕсли адрес равен null, плагин размещён в другом месте: перейдите по ссылке на его странице в Hangar.
Установка с вашего компьютера
Отправьте файл .jar на сервер, затем поместите его в папку plugins с правильным владельцем:
scp MonPlugin.jar ВАШ_ПОЛЬЗОВАТЕЛЬ@IP_СЕРВЕРА:/tmp/sudo install -o minecraft -m 644 /tmp/MonPlugin.jar /opt/minecraft/server/plugins/Файл должен лежать прямо в plugins: вложенные папки Paper не читает. Если вы загрузили архив .zip, распакуйте его и оставьте .jar, предназначенный для Paper или Bukkit.
Загрузка плагина
Перезапустите сервер, дождитесь строки Done, затем выведите список плагинов:
sudo systemctl restart minecraft.service
sudo journalctl -u minecraft.service -fsudo mc-console pluginsВ игре загруженный плагин отображается зелёным в выводе /plugins. В журнале он присутствует в списке, а при запуске нет сообщений об ошибках.
Его конфигурация затем находится в /opt/minecraft/server/plugins/<ИмяПлагина>/. Изменяйте её от имени пользователя minecraft, затем перезапустите сервер или используйте команду перезагрузки самого плагина.
Обновление плагинов
Paper умеет заменять плагины при запуске благодаря папке plugins/update. Поэтому вручную ничего удалять не нужно.
Сначала сделайте резервную копию плагинов и их конфигурации:
sudo tar -czf /opt/minecraft/backups/plugins-$(date +%F-%H%M).tar.gz -C /opt/minecraft/server pluginsЗатем поместите новую версию в update. Вот пример для Chunky:
sudo -u minecraft bash
mkdir -p /opt/minecraft/server/plugins/update
cd /opt/minecraft/server/plugins/update
UA="mon-serveur-minecraft/1.0 (https://your-domain.com)"
API="https://hangar.papermc.io/api/v1/projects/Chunky/versions?limit=1&channel=Release&platform=PAPER"
URL=$(curl -fsSL -H "User-Agent: $UA" "$API" | jq -r '.result[0].downloads.PAPER.downloadUrl')
curl -fLO -H "User-Agent: $UA" "$URL"
exitНаконец, перезапустите сервер:
sudo systemctl restart minecraft.serviceПри запуске Paper распознаёт плагин по имени, объявленному в его файле, а не по имени .jar. Он заменяет старую версию, сохраняет имя нового файла и очищает папку update.
Обновление Paper
Paper часто выпускает исправления и рекомендует обновляться как минимум раз в неделю. При этом он не советует использовать автоматические обновления, поскольку возможен конфликт с плагином.
sudo systemctl stop minecraft.service
sudo tar -czf /opt/minecraft/backups/avant-maj-$(date +%F-%H%M).tar.gz -C /opt/minecraft server
sudo -u minecraft /opt/minecraft/paper-update.sh 26.3
sudo systemctl start minecraft.service
sudo journalctl -u minecraft.service -fСледите за запуском: именно там проявляются конфликты плагинов.
Настройка автоматического резервного копирования
Скрипт backup.sh из базового руководства архивирует папки мира, имеющиеся на сервере. Чтобы сохранять также плагины, замените строку for в /opt/minecraft/backup.sh на:
for item in world world_nether world_the_end plugins config server.properties; doВосстановление из резервной копии
Если миграция прошла неудачно, восстановите архив, созданный в начале. Замените имя файла на то, которое показала команда ls:
sudo systemctl stop minecraft.service
sudo ls -lh /opt/minecraft/backups
sudo mv /opt/minecraft/server /opt/minecraft/server-echec
sudo tar -xzf /opt/minecraft/backups/avant-paper-ГГГГ-ММ-ДД-ЧЧММ.tar.gz -C /opt/minecraft
sudo systemctl start minecraft.serviceПапку server-echec можно удалить, когда всё снова заработает.
При возникновении проблем
Всегда начинайте с чтения начала журнала, где загружаются плагины:
sudo journalctl -u minecraft.service -n 200 --no-pager
sudo less /opt/minecraft/server/logs/latest.log«Minecraft 26.1 and newer requires running the server with Java 25 or above»
Сервис всё ещё использует старую версию Java. Проверьте java --version, затем повторите команду update-alternatives из раздела Установка Java 25. Ошибка UnsupportedClassVersionError имеет ту же причину, в том числе когда она касается плагина.
«Server attempted to load chunk saved with newer version of minecraft!»
Мир был сохранён более новой версией, чем установленная версия Paper. Установите нужную версию с помощью paper-update.sh или восстановите резервную копию.
Скрипт paper-update.sh завершается с ошибкой
curl: (22) … 404: такой версии Minecraft у Paper нет, проверьте номерНе найдена стабильная сборка: версия существует, но стабильной сборки у неё пока нетsha256sum: WARNING: загруженный файл повреждён, запустите скрипт снова. Вашserver.jarне был изменён
Плагин не загружается
Найдите имя плагина в журнале. Самые распространённые сообщения:
| Сообщение | Причина | Решение |
|---|---|---|
Unknown/missing dependency plugins или UnknownDependencyException |
Отсутствует зависимость | Установите указанный плагин |
Ambiguous plugin name |
Два файла одного и того же плагина | Оставьте только один .jar |
Invalid plugin.yml или zip END header not found |
Это не плагин Paper, либо файл неполный | Загрузите нужный файл заново |
Unsupported API version |
Плагин рассчитан на более новую версию, чем ваш сервер | Обновите Paper или возьмите совместимую версию плагина |
AccessDeniedException или «Permission denied»
Файл был создан через sudo и не принадлежит minecraft. Верните папку этому пользователю. Базовое руководство создаёт системную учётную запись без отдельной группы, поэтому указывайте только пользователя:
sudo chown -R minecraft /opt/minecraft/servermc-console не отвечает
Сервис minecraft.service не запущен: запустите сервер командойsudo systemctl start minecraft.service- Ответ не отображается: сервер ещё запускается или команда выполняется долго. Дождитесь строки
Doneили увеличьте задержку:sudo MC_CONSOLE_WAIT=10 mc-console version Socket service minecraft.service already active, refusing: сервер работал в момент создания канала. Остановите его командойsudo systemctl stop minecraft.service, затем запустите снова
Что дальше
Ваш сервер готов к установке других плагинов:
- Управление рангами и правами с помощью LuckPerms
- Установка и настройка EssentialsX
- Подключение игроков Bedrock с помощью Geyser и Floodgate
Подробнее о параметрах Paper читайте в официальной документации.