Прокси-сети (BungeeCord / Waterfall / Velocity)

ResourcePackManager работает в прокси-сетях. Серверный плагин запускается на каждом бэкенде, а отдельный прокси-плагин (Velocity ИЛИ BungeeCord, никогда оба сразу) запускается на прокси. Эти две части находят друг друга автоматически через общий файл plugins/floodgate/key.pem.

Что делает прокси-плагин

Задача прокси-плагина — объединение и доставка Bedrock-пака. В сети с несколькими бэкендами каждый бэкенд производит свой собственный Bedrock-пак (преобразованную версию собранного на нём Java-пака). Прокси-плагин:

1. Опрашивает небольшой HTTP-сервер каждого бэкенда каждые 5 секунд для получения /bedrock.zip и /mappings.json, используя If-Modified-Since, чтобы неизменившиеся файлы стоили почти нулевого трафика.
2. Ждёт, пока состояние входящих файлов стабилизируется в двух последовательных опросах.
3. Объединяет Bedrock-пак каждого бэкенда в единый общесетевой пак.
4. Копирует объединённый файл кастомных маппингов Geyser в plugins/Geyser-*/custom_mappings/ на прокси.
5. Раздаёт объединённый пак Bedrock-клиентам при подключении через SessionLoadResourcePacksEvent Geyser.

Прокси-плагин полезен только для Bedrock-игроков. Доставка Java-пака в сетях по-прежнему происходит на каждом бэкенде отдельно через обычный API setResourcePack / addResourcePack — Java-клиенты видят тот пак, который их текущий бэкенд решил отправить. Если ваша сеть только для Java, прокси-плагин вам не нужен.

Настройка — два шага

Шаг 1: установите Floodgate на прокси и на каждом бэкенде

Floodgate необходим, чтобы Bedrock-игроки могли аутентифицироваться на прокси. RSPM использует plugins/floodgate/key.pem от Floodgate для вывода сетевой идентичности — этот файл должен быть побайтово идентичным на прокси И на каждом бэкенде. Floodgate и так требует это для Bedrock-аутентификации, поэтому если Bedrock-игроки сейчас работают в вашей сети — это уже сделано.

Если у вас ещё нет Floodgate, установите его на каждый компонент, затем скопируйте один канонический key.pem на каждый другой компонент, прежде чем продолжать.

Шаг 2: скопируйте подходящий прокси-jar с любого бэкенда

После того как серверный RSPM хоть раз запустился, посмотрите в:

plugins/ResourcePackManager/proxy-extension/

Эта папка будет содержать:

ResourcePackManager-Velocity.jar
ResourcePackManager-BungeeCord.jar
README.md  (плюс 9 переведённых README-файлов)

Бэкенд извлекает оба jar-файла при каждом запуске независимо от обнаруженной топологии, поэтому они всегда доступны. Скопируйте ровно один в папку plugins/ вашего прокси:

Прокси-софт	Используйте этот jar
Velocity	ResourcePackManager-Velocity.jar
BungeeCord	ResourcePackManager-BungeeCord.jar
Waterfall (форк Bungee)	ResourcePackManager-BungeeCord.jar

Не устанавливайте оба — только подходящий. Установка обоих вызовет ошибки загрузки на той платформе, которая попытается загрузить «не свой».

Перезапустите прокси. Это всё.

Намеренно нет конфига для редактирования и нет ключа для вставки. Прокси-плагин читает plugins/floodgate/key.pem на прокси при загрузке и выводит из него сетевую идентичность. Поскольку Floodgate и так требует, чтобы этот файл был одинаковым на каждом бэкенде и на прокси, выводимый ключ автоматически совпадает с ключом каждого бэкенда.

Первое объединение обычно завершается в течение ~10 секунд после того, как все бэкенды поднялись.

Проверка работоспособности

Консоль прокси

В течение ~10 секунд после перезапуска (при условии, что бэкенды запущены) вы должны увидеть:

[ResourcePackManager] Network-key auto-derived from Floodgate key.pem ✓
[ResourcePackManager] NetworkSync starting (poll interval 5000 ms, ...)
[ResourcePackManager] Merged pack ready at .../merged/Bedrock.zip (sha1 ...)
[ResourcePackManager] Geyser mappings deployed to .../custom_mappings
[ResourcePackManager] ✔ Network resource pack is now ready (... KB, sha1ABCD1234)

/rspm status на прокси

Выводит снимок состояния: список бэкендов, результаты загрузки по каждому бэкенду и пути (200 / 304 / 404 / CONNECT_FAILED), счётчик последовательных пустых опросов, текущий путь и размер объединённого пака, network-http-offset, а также наличие Floodgate / Geyser на прокси. Требует право resourcepackmanager.command.status или resourcepackmanager.*. У консоли всегда есть оба; выдайте одно из прав игрокам через ваш плагин прав, если хотите, чтобы они могли её запускать. Вывод не раскрывает секретов (сетевой ключ маскируется, токены аутентификации не печатаются), поэтому щедрая выдача прав безопасна.

/rspm status на бэкенде

Строка Deploy mode должна показывать network-backend. Строка Network key должна показывать маскированный ключ (видны последние 4 символа) — сверьте его с маскированным ключом прокси, чтобы подтвердить, что обе стороны согласованы.

Bedrock-клиент

Подключитесь через Bedrock. Вы должны увидеть запрос на скачивание ресурс-пака до попадания в мир. Кастомные предметы должны рендериться с предполагаемыми моделями вместо обычных подставок для брони.

Справочник по конфигурации

Бэкенд: plugins/ResourcePackManager/config.yml

Сетевой режим определяется автоматически — нет флага networkMode: true, который нужно было бы выставлять. Сигналы для обнаружения (достаточно любого одного):

1. Floodgate присутствует, Geyser-Spigot отсутствует — сильнейший сигнал в пользу случая «Bedrock через прокси».
2. spigot.yml: settings.bungeecord: true — устаревший переключатель IP-форвардинга BungeeCord / Waterfall.
3. paper-global.yml: proxies.velocity.enabled: true — современный форвардинг Velocity.

Единственная настройка, имеющая значение именно для сетевого режима, — это networkHttpOffset-v2, которая контролирует HTTP-порт, на который прокси будет опрашивать каждый бэкенд. По умолчанию 1 работает практически на любом хостинге. См. Self-hosting для полной истории разрешения портов.

Прокси: plugins/ResourcePackManager/config.yml

Прокси-плагин записывает минимальный конфиг по умолчанию при первом запуске:

# Принудительно заставить клиентов принять пак (кик при отказе). По умолчанию: false.
force-resource-pack: false

# Смещение, добавляемое к Minecraft-порту каждого бэкенда для получения HTTP-порта,
# на который этот прокси будет обращаться за /bedrock.zip и /mappings.json. По умолчанию 1.
# Должно совпадать с networkHttpOffset-v2 на каждом бэкенде.
network-http-offset-v2: 1

Намеренно нет записи network-key — она была убрана ещё до релиза, потому что ручная вставка ключа была главным источником ошибок конфигурации (опечатки молча ломали связь прокси↔бэкенд). Ключ автоматически выводится из plugins/floodgate/key.pem.

Стабильность и частота объединения

Прокси ждёт, пока состояние входящих файлов стабилизируется в двух последовательных опросах, прежде чем выполнять объединение. С интервалом опроса по умолчанию 5 с это означает, что первое объединение происходит примерно через 10 с после того, как прокси видит хотя бы один бэкенд, производящий контент. Последующие объединения перепаковывают zip только если меняется набор SHA-1 файлов в инбоксе, поэтому длительный период покоя стоит почти ничего.

Прямая загрузка vs резервная ретрансляция

Путь по умолчанию — прямая загрузка: прокси делает HTTP GET по адресу http://<backend-host>:<mcPort + offset><path> для каждого бэкенда.

Если прокси не может напрямую достучаться до HTTP-порта бэкенда (типично для shared / managed Minecraft-хостингов, где MC-порты открыты, но соседние порты блокируются файрволом), бэкенд отправляет свои bedrock.zip и mappings.json на endpoint ретрансляции на magmaguy.com под пространством имён сети (выведенным из ключа Floodgate). Прокси перечисляет и скачивает из ретранслятора, когда прямая загрузка жёстко падает.

Оба пути ведут в один и тот же шаг объединения, поэтому администратору никогда не нужно выбирать — прямая загрузка предпочтительна (нулевой трафик на magmaguy.com), ретранслятор подключается прозрачно, когда нужно.

У ретранслятора TTL 30 минут на стороне сервера. Бэкенды пушат каждые 25 минут, чтобы запись оставалась активной; чистое выключение немедленно удаляет запись, не дожидаясь TTL.

Устранение типичных проблем

«Floodgate key.pem missing» при загрузке прокси

Прокси-плагин не смог найти plugins/floodgate/key.pem и перешёл в режим ожидания. Без него RSPM не может связаться ни с одним бэкендом.

Исправление: установите Floodgate на прокси, затем убедитесь, что plugins/floodgate/key.pem на прокси побайтово идентичен такому же файлу на каждом бэкенде. Floodgate по умолчанию автогенерирует разные ключи на каждой установке — скопируйте один канонический key.pem с любого бэкенда на каждый другой компонент и перезапустите всё.

Предупреждение «No merged pack content» через ~20 секунд

После 4 последовательных пустых циклов опроса прокси записывает однократное многострочное предупреждение, перечисляющее каждый опрошенный бэкенд, URL, который он пытался запросить, и результат. Предупреждение объясняет наиболее распространённые способы исправления:

• CONNECT_FAILED на каждом бэкенде — прокси вообще не может достучаться до HTTP-порта бэкенда. Проверьте, что адрес в velocity.toml / config.yml — это адрес, до которого прокси действительно может дозваниться (а не, например, внутрисетевое Docker-имя, которое не резолвится из сети прокси), и что mcPort + networkHttpOffset-v2 открыт между прокси и бэкендом. Если у вас нет способа открыть этот порт (managed-хостинг), смотрите раздел про резервную ретрансляцию выше — бэкенд должен автоматически загружать в ретранслятор.
• NOT_FOUND_404 на каждом бэкенде — бэкенды работают, но не производят Bedrock-пак. Запустите /rspm status на каждом бэкенде; диагностический блок Bedrock Pack скажет вам, почему (чаще всего: нет определений предметов в собранном паке или первый цикл миксинга ещё не завершился).

Предупреждение срабатывает один раз за период «застоя». Строка NetworkSync: recovered записывается, когда хотя бы один бэкенд снова начинает возвращать контент.

Bedrock-игроки не видят кастомных моделей при первой загрузке прокси

Geyser регистрирует свою таблицу кастомных предметов только при запуске прокси. Если прокси стартовал раньше, чем хоть один бэкенд произвёл Bedrock-пак, Geyser работает с пустой таблицей маппингов и остаётся такой до конца сессии.

Исправление: перезапустите прокси один раз после того, как бэкенд записал свою первую строку Merged Bedrock pack published. RSPM заранее раскладывает маппинги предыдущего запуска при каждой загрузке прокси, поэтому это бьёт только на абсолютно новой установке — последующие загрузки имеют что-то готовое до того, как Geyser сканирует.

Предупреждения «Duplicate bedrock_identifier» при загрузке прокси

Два бэкенда выдали один и тот же Bedrock-идентификатор для одного и того же базового предмета. Побеждает последний; это безвредно, если вам достаточно, чтобы один бэкенд предоставлял этот предмет. Если оба бэкенда должны хостить разные кастомные предметы под одним базовым предметом, переименуйте одну из исходных Java-моделей, чтобы автогенерируемые хеши различались.

Bedrock-игрок подключился, но не видит пак

Прокси отправляет чат-баннер всем онлайн-Java-игрокам, когда сессия Bedrock загружается без работоспособного RSPM-пака:

⚠ [RSPM] Bedrock player Alice connected before the resource pack was ready — they're seeing plain armor stands instead of custom models. Tell them to disconnect and reconnect; the pack will load on their next session. (Cause: ...)

Сам Bedrock-игрок также получает модальное всплывающее окно, а консоль прокси получает баннер. Если нужно копнуть глубже, включите debug-поток (доступен как на Velocity, так и на BungeeCord):

/rspm debug bedrock on

Это включает подробные строки лога [RSPM-BedrockDebug] от GeyserBinder. Воспроизведите проблему, затем выключите:

/rspm debug bedrock off

Настройка сбрасывается в off при перезапуске прокси, чтобы её нельзя было случайно оставить включённой.

Обновление RSPM в сети

После обновления серверного jar RSPM также пере-копируйте подходящий прокси-jar из plugins/ResourcePackManager/proxy-extension/ с любого бэкенда на прокси и перезапустите прокси. Бэкенд перегенерирует эти jar-файлы при каждой загрузке, поэтому они всегда синхронизированы с версией бэкенда.

Что пока не поддерживается

• Java-паки в сетях через прокси-плагин. Java-клиенты получают паки от каждого бэкенда напрямую через обычный API. На стороне прокси нет миксера Java-пака.
• Объединение Java-паков между бэкендами. Java-пак каждого бэкенда независим. Если игрок переключает бэкенд, он получает пак нового бэкенда.
• Живое перенастраивание сетевого ключа. Ключ привязан к key.pem Floodgate. Его изменение требует перезапуска прокси И каждого бэкенда (что вы и так бы сделали при ротации ключа Floodgate).