Миграция с Paper и Folia

Chunkwake запускает обычные плагины Paper и Folia, читает и пишет миры Anvil в обе стороны и использует тот же server.properties. Но это не замена одного файла: ядро другое, часть настроек Paper не импортируется, а NMS-плагины нужно проверять отдельно.

Сначала — копия. Не мигрируйте рабочий сервер без резервной копии и тестового клона. Chunkwake находится в ранней стадии, и фич-матрица честно показывает, что ещё не готово.

Что переноситсяСкопировать ссылку

• Мир Anvil. Обычные .mca-регионы, level.dat, данные игроков. Chunkwake читает и пишет миры, которые понимает ваниль, в обе стороны.
• Плагины. plugins/*.jar, plugin.yml и paper-plugin.yml, libraries: из Maven, loader и bootstrapper.
• События и планировщики. Bukkit/Paper события в порядке Paper, GlobalRegionScheduler, RegionScheduler, AsyncScheduler и EntityScheduler для всех плагинов.
• server.properties. Поддерживаемые ключи читаются оттуда же; часть настроек мира и игры пока сохраняется, но не применяется.
• Команды и права. Ванильное дерево команд, ops.json, консоль и права плагинов.

Что не переносится автоматическиСкопировать ссылку

Чеклист миграцииСкопировать ссылку

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

Порядок миграцииСкопировать ссылку

1. Проверьте плагины и фичиСкопировать ссылку

Откройте фич-матрицу и список плагинов. Строки «частично» и «нет» показывают, что ещё не готово для рабочего сервера.

Особенно проверьте:

• плагины с NMS/CraftBukkit;
• плагины, которые предполагают один глобальный поток;
• плагины с собственным планировщиком и региональными допущениями;
• плагины, которые читают конфиги Paper напрямую;
• мультимир и кастомные измерения.

2. Сделайте полную копиюСкопировать ссылку

Остановите Paper/Folia и скопируйте весь каталог сервера, а не только мир:

server/
├── world/
├── world_nether/
├── world_the_end/
├── plugins/          # jar'ы и папки с данными плагинов
├── server.properties
├── ops.json
├── whitelist.json
├── banned-ips.json
├── banned-players.json
└── config/           # Paper-конфиги: сохранить, но не ждать импорта

Дополнительно можно снять бэкап средствами Chunkwake уже после первого запуска:

chunkwake backup create --dir /srv/chunkwake
chunkwake backup verify <id> --dir /srv/chunkwake

Бэкап делается только при остановленном сервере.

3. Поставьте Chunkwake рядомСкопировать ссылку

Не удаляйте Paper-инсталляцию. Поставьте Chunkwake в отдельный каталог и оставьте старый сервер на месте — это ваш план отката.

mkdir /srv/chunkwake
chunkwake setup --dir /srv/chunkwake

Готового релиза пока нет: соберите бинарник из исходников или возьмите артефакт CI.

git clone https://github.com/chunkwake/core.git
cd core
cargo build --release -p chunkwake-server

Для плагинов нужна Java 25+. Сервер ищет её через java-path, CHUNKWAKE_JAVA или PATH.

4. Перенесите мирСкопировать ссылку

Скопируйте каталоги миров и level.dat в каталог Chunkwake. Имена должны совпадать с level-name в server.properties.

cp -a /srv/paper/world /srv/chunkwake/
cp -a /srv/paper/world_nether /srv/chunkwake/
cp -a /srv/paper/world_the_end /srv/chunkwake/

Chunkwake читает .mca с gzip, zlib, без сжатия и lz4, включая внешние c.X.Z.mcc для больших чанков. Запись тоже совместима с ванилью.

Не запускайте два сервера на одном каталоге мира одновременно.

5. Перенесите плагиныСкопировать ссылку

Скопируйте plugins/ целиком, включая папки с конфигами и базами. Проверьте, что для плагинов есть Java 25+.

cp -a /srv/paper/plugins /srv/chunkwake/

Плагины с folia-supported: true не нужно включать отдельно: планировщики Folia доступны всем. Обычные Paper-плагины при этом не отключаются.

6. Перенесите настройкиСкопировать ссылку

server.properties можно скопировать как есть, но не все ключи применяются. Сверьте сеть, порт, MOTD, online-mode, level-name, сид, сжатие и пути к Java:

chunkwake config show --dir /srv/chunkwake
chunkwake config set server-port 25565 --dir /srv/chunkwake
chunkwake doctor --dir /srv/chunkwake

Если сервер стоит за Velocity, включите только modern forwarding:

online-mode=false
velocity-enabled=true
velocity-secret=<секрет из forwarding.secret>

Legacy/BungeeCord forwarding не поддерживается. Backend-порт должен быть доступен только прокси.

7. Запустите и проверьтеСкопировать ссылку

chunkwake doctor --dir /srv/chunkwake
chunkwake --dir /srv/chunkwake

Первый запуск распаковывает данные игры (≈27 МБ) и API плагинов (≈37 МБ). Дальше старт быстрый.

Проверьте по списку:

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

Если плагин падает, отключите его и повторите. Не переносите все плагины в рабочую среду одновременно.

8. Оставьте путь назадСкопировать ссылку

Не удаляйте Paper-инсталляцию и бэкапы, пока Chunkwake не отработает хотя бы несколько дней под реальной нагрузкой.

Откат:

1. Остановите Chunkwake командой stop.
2. Верните Paper-каталог и его server.properties.
3. Запустите Paper на том же мире.
4. Если мир уже изменён Chunkwake, восстановите копию, снятую до миграции.

Docker: itzg/minecraft-serverСкопировать ссылку

Образ itzg/minecraft-server:java25 умеет запускать кастомный сервер через TYPE=CUSTOM, но по умолчанию запускает его как Java-jar. Chunkwake — нативный бинарник, поэтому образу нужно явно включить native-режим:

services:
  chunkwake:
    image: itzg/minecraft-server:java25
    tty: true
    stdin_open: true
    ports:
      - "25565:25565"
    environment:
      EULA: "TRUE"
      TYPE: "CUSTOM"
      FAMILY: "NATIVE"
      CUSTOM_SERVER: "/data/chunkwake"
      ENABLE_RCON: "false"
    volumes:
      - ./data:/data

1. Соберите Linux-бинарник и положите его в ./data/chunkwake.
2. Сделайте файл исполняемым: chmod +x data/chunkwake.
3. Запустите docker compose up -d и смотрите docker compose logs -f.

CUSTOM_SERVER может быть URL на сам бинарник. Ссылку на .tar.gz не используйте: образ скачает архив и попробует запустить его как файл.

Почему так:

• TYPE=CUSTOM включает ветку кастомного сервера;
• FAMILY=NATIVE заставляет start-finalExec запускать файл напрямую, а не через java -jar;
• ENABLE_RCON=false — RCON в Chunkwake пока нет;
• java25 в образе нужен для плагинов, ядро работает без JVM;
• EULA=TRUE требует сам образ.

Оговорки:

• FAMILY=NATIVE — внутренняя ветка образа для нативных серверов (так работает Pumpkin). После обновления образа проверьте запуск.
• Файл должен быть доступен пользователю контейнера (UID 1000) и исполняемым.
• Образ создаёт server.properties и eula.txt; Chunkwake читает поддерживаемые ключи.
• Не запускайте два сервера на одном /data.

Folia: что меняетсяСкопировать ссылку

В Folia обычные плагины отключаются и требуют folia-supported. В Chunkwake:

• GlobalRegionScheduler, RegionScheduler, AsyncScheduler и EntityScheduler доступны всем;
• обычные плагины продолжают работать;
• региональная модель Folia не навязывается плагинам, которые её не ждут.

Но код, который полагается на «один главный поток на весь мир» или на порядок выполнения между регионами, всё равно нужно проверять.

Ожидания по производительностиСкопировать ссылку

На стенде проекта Chunkwake запускается за 0.6–0.9 с против 6.6–11.4 с у ванили, вход 20 ботов даёт p95 11–26 мс против 845–860 мс, а пик памяти — 182–236 МиБ против 845–929 МиБ. Подробности и оговорки — в бенчмарке и docs/perf.md.

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

Если что-то пошло не такСкопировать ссылку

• chunkwake doctor --dir ... — конфигурация, порт, Java, целостность мира.
• logs/latest.log — обычный лог, logs/chunkwake.<дата>.log — суточные файлы.
• chunkwake backup rollback --dir ... — вернуть состояние после прерванного восстановления.
• Issues — приложите версию, плагин, шаги и поведение ванили.