Перейти к основному содержимому

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

ResourcePackManager работает в прокси-сетях. Существует один jar — ResourcePackManager.jar — и вы устанавливаете тот же jar на каждый бэкенд И на прокси. На бэкенде он работает в роли бэкенда (объединение, хостинг, отправка, преобразование); на прокси Velocity или BungeeCord/Waterfall тот же jar автоматически определяет загрузчик платформы и работает в роли прокси (доставка Bedrock на стороне сети). Две роли находят друг друга автоматически через общий файл plugins/floodgate/key.pem — никаких отдельных прокси-jar, никакого proxy-extension для извлечения, никакого ключа для вставки.

На этой странице «прокси-плагин» — это сокращение для того же ResourcePackManager.jar, работающего в роли прокси.

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

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

  1. Опрашивает небольшой HTTP-сервер каждого бэкенда каждые 5 секунд для получения /bedrock.zip и /mappings.json, используя If-Modified-Since, чтобы неизменившиеся файлы стоили почти нулевого трафика. Каждый бэкенд объявляет точный HTTP-порт, на который он привязался, поэтому прокси обычно автоматически попадает в нужный порт (см. Разрешение HTTP-порта бэкенда).
  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: скопируйте ResourcePackManager.jar на прокси​

Существует только один jar. Тот же ResourcePackManager.jar, который вы устанавливаете на бэкенды Bukkit/Paper, является и прокси-плагином — он содержит реализации для Velocity и BungeeCord/Waterfall вместе в одном shaded-jar и автоматически определяет, на какой платформе он работает. Нет отдельного прокси-jar под каждую платформу, который нужно было бы извлекать.

Скопируйте тот же ResourcePackManager.jar в папку plugins/ вашего прокси:

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

Вы можете подтвердить это с бэкенда в любой момент, запустив /rspm status; секция Proxy deployment печатает Network proxy jar: ResourcePackManager.jar и Use the same jar on Bukkit/Paper, Velocity, and BungeeCord/Waterfall.

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

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

Первый опрос прокси срабатывает примерно через 2 секунды после загрузки, затем каждые 5 секунд. В сочетании с одноцикловым порогом стабильности первое объединение публикуется примерно через 7 секунд после того, как прокси сможет увидеть хотя бы один бэкенд, который уже производит контент.

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

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

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

[ResourcePackManager] Network-key auto-derived from Floodgate key.pem ✓
[ResourcePackManager] NetworkSync starting (poll interval 5000 ms, network-http-offset 1 - endpoint announcements preferred, fallback HTTP port = mcPort + offset)
[ResourcePackManager] NetworkSync: inbox stabilized — merging 2 Bedrock zip(s) and 2 mappings file(s) across 2 backend(s).
[ResourcePackManager] Merged Bedrock pack published at .../merged/Bedrock.zip (sha1=...).
[ResourcePackManager] ✔ Network resource pack is now ready (... KB, sha1 ABCD1234)

/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 для полной истории разрешения портов.

В обычной работе каждый бэкенд автоматически объявляет прокси свой реальный HTTP-порт (через реестр endpoint'ов на magmaguy.com), поэтому смещение используется только как запасной вариант при старте/сбое. См. Разрешение HTTP-порта бэкенда ниже.

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

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

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

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

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

Разрешение HTTP-порта бэкенда​

Прокси нужно знать, на какой HTTP-порт опрашивать каждый бэкенд для /bedrock.zip и /mappings.json. Он разрешает этот порт в таком порядке:

  1. Объявленный бэкендом endpoint (предпочтительно). Каждый бэкенд загружает точный HTTP-порт, на который привязался, в реестр endpoint'ов на magmaguy.com, привязанный к сетевому ключу. При каждом опросе прокси обновляет этот список и сопоставляет объявленный порт бэкенда с записью списка серверов по Minecraft-порту (и хосту, когда тот доступен). Это означает, что администратор, задавший явный selfHostPort на бэкенде, или чей бэкенд автоматически попал на mcPort + 1, обрабатывается одинаково — прокси использует то, на что бэкенд реально привязался.
  2. mcPort + network-http-offset-v2 (запасной вариант). Используется только когда нет совпадающего объявления (например, первый опрос до того, как какой-либо бэкенд объявил, или реестр endpoint'ов кратковременно недоступен). Вот почему два смещения всё же должны совпадать, если вы полагаетесь на запасной вариант.

Прокси намеренно не сканирует порты бэкенда как запасной вариант — это выглядит для хостинга как недопустимое поведение. Когда прямая загрузка вообще не может сработать, путь через ретранслятор (ниже) — это категорический ответ.

/rspm status на прокси показывает по каждому бэкенду, какой порт был выбран и пришёл ли он из объявления или из запасного смещения.

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

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

Бэкенды записывают свой bedrock.zip во временный файл и атомарно его переименовывают, поэтому маршрут /bedrock.zip всегда раздаёт полный zip — прокси никогда не приходится защищаться от чтения наполовину записанных файлов, поэтому порог составляет один цикл, а не два.

Прямая загрузка 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-имя, которое не резолвится из сети прокси), и что HTTP-порт бэкенда открыт между прокси и бэкендом. Предупреждение печатает точный HTTP host:port, который оно пробовало для каждого бэкенда, и пришёл ли этот порт из объявления бэкенда или из запасного варианта 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 также пере-копируйте тот же ResourcePackManager.jar в папку plugins/ прокси и перезапустите прокси. Это один и тот же jar на каждом бэкенде и на прокси, поэтому держите все компоненты на одной версии.

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

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