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

Самостоятельный хостинг ресурс-пака

ResourcePackManager поставляется с собственным небольшим HTTP-сервером. Когда autoHost: true (по умолчанию) и preferSelfHost: true (по умолчанию), плагин пытается хостить собранный пак из той же JVM, что и сам Minecraft-сервер — без внешнего файлового хоста, без отдельного веб-сервера, без ручной вставки URL.

Эта страница описывает, как работает этот путь самостоятельного хостинга, что делают проверки исправности, как выбирается порт и hostname, и что настраивать, когда значения по умолчанию вам не подходят.

Чтобы поставить перед RSPM обратный прокси с HTTPS и сохранить автоматическую доставку, используйте selfHostExternalUrl, как описано ниже. Используйте autoHost: false, только если другая система отвечает и за хостинг, и за доставку игрокам.

Дерево решений по доставке​

Когда игрок подключается, RSPM выбирает URL для доставки по такому приоритету:

Обычная автоматическая доставка требует autoHost: true. При autoHost: false URL отправляется только при явном переопределении selfHostForce: true.

  1. selfHostForce: true — сразу пробует собственный хостинг без проверок доступности и удалённой загрузки. В основном для проверки этого пути. Переопределяет autoHost и selfHostEnabled, но проверка URL и запуск HTTP-сервера всё равно должны пройти успешно.
  2. preferSelfHost: true И selfHostEnabled: true: попробовать собственный хостинг с проверками ниже, включая бэкенды прокси. При неудачной проверке перейти на удалённый хостинг.
  3. Иначе — повторно использовать или загрузить пак на https://magmaguy.com/rsp/ и объявить этот URL. При сбое инициализации, проверки SHA1 или загрузки попробовать проверенный собственный хостинг, если selfHostEnabled: true. SESSION_NOT_FOUND также сбрасывает удалённую сессию, чтобы следующая попытка могла инициализировать её заново. Автоматический резерв проходит те же проверки, что и приоритетный собственный хостинг; при отказе обоих путей новый URL доставки не объявляется.

Удалённый хост принимает Java-паки размером до 50 000 КиБ (51 200 000 байт). RSPM проверяет размер перед загрузкой. Пак большего размера никогда не загружается: консоль выводит Automatic hosting skipped: resource pack is <size> bytes; the limit is 51200000 bytes. После этого RSPM перестаёт использовать удалённый хостинг для этого пака и продолжает пробовать проверенный собственный хостинг (при selfHostEnabled: true), пока хостинг не перезапустится для нового пака или при перезагрузке. Уменьшите размер пака или сделайте собственный хостинг доступным, затем выполните /rspm reload.

Как только URL получен, RSPM использует multi-pack API Minecraft, поэтому его Java-пак может сосуществовать с другими паками, отправляемыми сервером. Текущий дескриптор Bukkit-плагина требует Minecraft 1.21.4 или новее.

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

RSPM выполняет эти проверки по порядку перед выбором автоматического собственного хостинга, включая переход на него после сбоя удалённого хостинга. Только selfHostForce: true позволяет их пропустить:

Уровень 1 — эвристическая проверка разрешённого внешнего хоста​

Если определённый хост (см. «Определение внешнего хоста») относится к RFC1918 (10.*, 172.16-31.*, 192.168.*), loopback (127.* или localhost), link-local (169.254.*) либо является неопределённым адресом (0.0.0.0), собственный хостинг пропускается. Также отклоняются IPv6-адреса unspecified, loopback, link-local, site-local и unique-local. Это эвристика по строке хоста; имя хоста всё равно должно пройти проверки скачивания ниже.

Это ловит очень распространённый сценарий «ipify-запрос не удался, откатился на LAN-IP».

Уровень 2 — скачивание локально и по объявленному URL​

RSPM отправляет GET с диапазоном байтов сначала на http://127.0.0.1:<port>/rspm.zip, затем на точный URL, который получили бы игроки. Первые байты, максимум 1 КиБ, сравниваются с локальным паком. Принимается HTTP 200 или 206; указанные длины должны совпадать, а ответ 206 должен содержать ожидаемый Content-Range. Перенаправления отклоняются. Это выявляет:

  • коллизии при привязке порта (что-то другое уже на выбранном порту)
  • отсутствующий файл пака (маршрут зарегистрирован, но zip ещё не на диске)
  • неверные маршруты, HTML-страницы ошибок или отличающиеся байты пака
  • невозможность скачать объявленный URL с самого сервера, включая сбои NAT loopback

На каждое подключение и чтение установлен таймаут 3 с, а на чтение образца действует отдельный срок 3 с. Это ограниченные проверки образцов, а не полное скачивание клиентом.

Уровень 3 — проверка внешней доступности​

POST анонсированного URL на POST /rsp/probe на хостере magmaguy.com. Хостер скачивает URL с публичной vantage point (с SSRF-защитой и жёстким таймаутом) и отчитывается, доступен ли он.

Ловит наиболее распространённую боевую проблему: у сервера есть публичный IP, но HTTP-порт не проброшен на роутере или файрволе. Уровень 2 проходит (сервер отвечает на 127.0.0.1), но ни один реальный клиент никогда не сможет скачать пак.

Политика принятия решений по результатам проверки:

  • reachable=true и HTTP 200 или 206 → проверка достигла URL из своей публичной сети. Выбирается собственный хостинг.
  • reachable=false или другой HTTP-статус → проверка не пройдена. Предполагаемый Java URL отзывается, затем выполняется попытка удалённого хостинга через magmaguy.com. В сетевом режиме HTTP-сервер бэкенда остаётся доступен для опроса артефактов прокси.
  • сбой связи проверки (IOException) или недоступный клиент проверки → доступность не подтверждена. Выполняется попытка удалённого хостинга: невозможность связаться со службой проверки не доказывает, что загрузка тоже не удастся. Автоматический резерв не может обойти эту проверку.

Ограничения проверок​

Скачивание по объявленному URL теперь выявляет сбои NAT loopback из сети самого сервера. Оно не подтверждает доступность из сети каждого игрока и не доказывает успешное полное скачивание клиентом Minecraft. Проверьте полное скачивание и принятие пака реальным клиентом; для проверки публичного доступа используйте отдельную внешнюю сеть.

Для быстрой проверки с хост-машины выставьте preferSelfHost: false и используйте удалённый резерв либо проверьте публичный URL из сотовой/внешней сети. Для постоянной self-host установки используйте split-horizon DNS (то же публичное имя хоста внутри вашей сети резолвится в LAN-адрес сервера). Не выставляйте selfHostExternalHost в 127.0.0.1: loopback и приватные хосты отклоняются проверкой публичности хоста и не могут обслуживать внешних клиентов.

Разрешение порта​

Две настройки взаимодействуют:

  • selfHostPort — явный порт от 1 до 65535 либо -1 (по умолчанию) для автоматического расчёта. Рассчитанный порт также должен находиться в этом диапазоне; другие значения препятствуют запуску HTTP-сервера.
  • networkHttpOffset-v2 — учитывается только когда selfHostPort = -1. Прибавляется к порту Minecraft-сервера для вывода HTTP-порта. По умолчанию 1. (В прокси-сетях это же значение является ещё и запасной догадкой прокси о HTTP-порте бэкенда — см. ниже.)

По умолчанию selfHostPort: -1 + networkHttpOffset-v2: 1, поэтому:

  • MC порт 25565 → HTTP порт 25566
  • MC порт 25584 → HTTP порт 25585

Разные порты Minecraft дают разные рассчитанные HTTP-порты, однако результат может совпасть с портом Minecraft другого бэкенда или с портом другого сервиса. Проверьте все слушающие службы и выделенные хостингом порты.

Почему смещение 1?​

Общий или управляемый хостинг может выделять контейнеру лишь несколько портов. Смещение 1 оставляет рассчитанный порт рядом с игровым, но не резервирует его и не гарантирует, что хостинг выделил или открыл этот порт. Уточните точный HTTP-порт в панели управления.

Самостоятельные администраторы с полным контролем над портами могут увеличить это до любого значения. В прокси-сети бэкенд автоматически объявляет прокси точный HTTP-порт, на который привязался, поэтому прокси следует за ним, даже если вы измените смещение или зададите явный selfHostPort. Увеличивать network-http-offset-v2 прокси для совпадения имеет смысл только как запасной вариант на короткий промежуток до того, как бэкенд объявил порт (или если объявление не может достичь прокси).

Осторожно: коллизия с RCON​

Если ваш хостинг включает RCON по умолчанию на MC port + 1, выберите смещение 2 или 3 во избежание коллизии портов. Проверьте server.properties на rcon.port=.

Версионированный ключ конфига​

Ключ в config.yml называется именно networkHttpOffset-v2. Прежний ключ networkHttpOffset имел значение по умолчанию 100, из-за чего HTTP-порт мог оказаться за пределами выделенного диапазона. В v2 значение по умолчанию — 1; этот порт всё равно должен быть свободен и доступен.

Если вы обновляетесь с v1, мёртвый ключ v1 сидит в вашем конфиге как безвредный артефакт, пока вы не уберёте его вручную — RSPM намеренно его не читает.

Определение внешнего хоста​

selfHostExternalHost контролирует, какое имя хоста клиенты видят в URL. Оставьте пустым (по умолчанию), чтобы авто-определить в таком порядке приоритета:

  1. api.ipify.org / checkip.amazonaws.com — возвращает публичный IPv4 этого хоста. Кешируется один раз на /rspm reload, чтобы IP-сервисы не нагружались.
  2. Bukkit.getIp() — bind-адрес сервера, когда непустой и не 0.0.0.0. Обычно LAN-адрес.
  3. InetAddress.getLocalHost() — best-effort.
  4. localhost — последний резерв. Клиенты вне коробки сюда не достучатся.

Если авто-определение приводит к не-маршрутизируемому адресу и preferSelfHost: true, эвристическая проверка Уровня 1 проваливается, и плагин переключается на удалённый хостинг.

Для максимально надёжной настройки self-host выставьте selfHostExternalHost явно на ваше публичное имя хоста (например, play.example.com). Это полностью пропускает определение через ipify/AWS, и проверка запускается против явного значения.

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

HTTPS и обратные прокси​

Задайте в selfHostExternalUrl полный публичный URL для скачивания:

autoHost: true
selfHostEnabled: true
preferSelfHost: true
selfHostPort: 25566
selfHostExternalUrl: "https://packs.example.com/rspm.zip"

Настройте обратный прокси на передачу этого публичного пути внутреннему маршруту RSPM http://<server>:25566/rspm.zip и завершение TLS. RSPM по-прежнему запускает HTTP-сервер; эта настройка не устанавливает сертификат и не настраивает ваш веб-сервер.

Точный URL отправляется Java-игрокам и используется внешней проверкой доступности. Суффикс /rspm.zip не добавляется. Для Java-доставки он переопределяет selfHostExternalHost и определение публичного IP; selfHostPort по-прежнему управляет внутренним портом. Прокси продолжает опрашивать Bedrock-артефакты через HTTP-адрес бэкенда.

Принимаются только полные HTTP- или HTTPS-URL с хостом, без встроенных учётных данных и фрагментов. Явный порт в URL должен быть от 1 до 65535. Неверный URL блокирует собственный хостинг. Обычный автоматический хостинг может перейти на удалённый, принудительный собственный — нет. Оставьте поле пустым для определения хоста и порта.

Настройки​

# Whether the built-in HTTP server may be used as a delivery path at all.
# When false, ordinary self-host attempts are disabled. selfHostForce still overrides it.
selfHostEnabled: true

# Port for the self-host HTTP server.
# -1 (default) = auto-derive: HTTP port = Minecraft server port + networkHttpOffset-v2.
# Set to a value from 1 to 65535 to force an explicit port.
selfHostPort: -1

# Added to the Minecraft server port when selfHostPort = -1.
# Default 1 (MC 25565 -> HTTP 25566). On a proxy network this is only a FALLBACK:
# the backend announces the exact HTTP port it actually bound to the proxy, so
# you no longer have to match this against the proxy's network-http-offset-v2.
networkHttpOffset-v2: 1

# Public hostname or IP clients use to reach the self-host server.
# Leave empty for auto-detect (api.ipify.org / checkip.amazonaws.com).
selfHostExternalHost: ""

# Optional complete public Java-pack URL, including the path.
# Your reverse proxy supplies HTTPS and forwards to the internal /rspm.zip route.
selfHostExternalUrl: ""

# Try self-host FIRST with three sanity checks, fall back to remote if any fail.
# When false, use the legacy order: remote upload first, self-host only on upload failure.
preferSelfHost: true

# Skip ALL other delivery paths and force self-hosting.
# Bypasses sanity checks AND remote upload. Mainly for testing.
selfHostForce: false

# Print every step of pack preparation and the hosting handshake.
# Default false — see "What the console actually prints" below.
# `/rspm verbose on|off` flips this same key at runtime and saves it here.
verboseLogging: false

Что консоль на самом деле печатает​

При сбоях удалённого Java-хостинга и ретранслятора Bedrock задержки между попытками растут экспоненциально со случайным разбросом. Каждый процесс допускает одну активную попытку и до пяти повторных, затем ждёт 15–30 минут перед новой серией. Успех сбрасывает счётчик; HTTP-клиент не добавляет собственных автоматических повторов. Java-хостинг проверяет удалённый SHA-1 перед загрузкой. Повторные попытки Bedrock до 20 минут используют уже успешно загруженные файлы, если они не изменились. Обычное обновление ретранслятора каждые 25 минут по-прежнему загружает файлы, чтобы продлить их срок хранения на сервере.

RSPM намеренно печатает одну строку о хостинге при обычной загрузке — результат, а не путь к нему:

[ResourcePackManager] Resource pack is live via self-hosting — http://play.example.com:25566/rspm.zip

или, когда победил удалённый путь:

[ResourcePackManager] Resource pack is live via automatic hosting — https://magmaguy.com/rsp/<uuid>

Эта строка печатается один раз при каждой свежей инициализации пути доставки, а не при повторных попытках игроков или тиках keep-alive. Перезагрузка, при которой пак не изменился, может переиспользовать существующую регистрацию хостинга вместо того, чтобы печатать новый результат.

Неудачные проверки доступности записываются на уровне подробного журнала. Например: Self-host check: local pack link is not public. This is OK. Проверки хоста и localhost заканчиваются на This is OK.; скачивание по объявленному URL и внешняя проверка сообщают о своём сбое без этого окончания. Неверные URL, сбои запуска HTTP-сервера и удалённой связи по-прежнему могут вызывать предупреждения. Неудачная проверка сама по себе не доказывает успешность удалённого резерва; проверьте итоговый статус доставки.

Чтобы увидеть всю цепочку решений — какая проверка не прошла, URL пробы, код причины, каждый подготовленный пак и каждый объединённый кластер — выполните:

/rspm verbose on

Затем выполните /rspm reload. Это тот переключатель, который надо включить до того, как открывать баг-репорт по хостингу. Команда записывает verboseLogging: true в config.yml, и настройка сохраняется между перезапусками, поэтому выполните /rspm verbose off, когда закончите; ручное изменение ключа в конфиге даёт ровно тот же эффект.

Учтите, что verboseLogging охватывает подготовку пака и хостинг. У Bedrock-конвертера есть собственный отдельный переключатель, bedrockConverterDebug — см. Преобразование в Bedrock.

Маршруты бэкенд-HTTP-сервера​

Встроенный HTTP-сервер всегда раздаёт zip пака по адресу:

http://<host>:<port>/rspm.zip

В сетевом режиме (RSPM находится за прокси Velocity / BungeeCord) регистрируются дополнительные маршруты, из которых забирает данные прокси-плагин:

http://<host>:<port>/bedrock.zip   # the Bedrock-converted pack
http://<host>:<port>/mappings.json # the Geyser custom-mappings JSON
http://<host>:<port>/rspm-update.jar # the universal RSPM update jar (authenticated)

Маршруты пака и Bedrock-артефактов работают с файлами и при каждом запросе определяют текущий опубликованный артефакт. Успешно опубликованная пересборка доступна без перезапуска HTTP-сервера; простая замена файла на диске не разрешает его раздачу. Маршруты возвращают 404, если нет текущего разрешённого артефакта, файл отсутствует или его байты больше не совпадают с хешем публикации. Bedrock-маршруты также требуют, чтобы конвертация оставалась включённой. Строгие ETag поддерживают If-None-Match, который имеет приоритет над проверкой совместимости If-Modified-Since; опросы без изменений могут получать 304 без тела ответа. Маршрут обновления отдельно защищён bearer-токеном из общего сетевого ключа и доступен только при наличии допустимого jar обновления.

Проверка, что self-host активен​

/rspm status показывает:

  • Active delivery: SELF-HOSTED — self-host используется
  • Active delivery: REMOTE (magmaguy.com) — удалённый авто-хостинг используется
  • URL: ... — фактический URL, который увидят клиенты
  • Resolved external host — во что разрешилось selfHostExternalHost
  • Public IP (auto-detected) — что вернули ipify/AWS, если что-то
  • selfHostPort — авто vs явный, и разрешённое значение

Если вы ожидали self-host, но видите удалённый, смотреть нужно в /rspm status — лог загрузки намеренно молчит о самоустранённых сбоях проб. Выполните /rspm verbose on и /rspm reload, чтобы увидеть, какая проверка исправности не прошла и почему.

Типичные ошибки​

  • Считать успешную проверку полноценным клиентским тестом — локальный образец и публичная проверка охватывают отдельные сетевые пути. Проверьте полное скачивание и принятие пака реальным игроком; принудительный собственный хостинг полностью пропускает эти проверки.
  • Увеличение networkHttpOffset-v2 за пределы диапазона портов вашего хостинг-провайдера — симптом — молчаливый CONNECT_FAILED навсегда на стороне прокси. Бэкенды объявляют прокси свой реальный привязанный порт, но HTTP-серверу всё равно нужно привязаться к доступному порту, а прокси всё равно нужно иметь возможность до него достучаться; если mcPort + offset уходит за пределы выделенной полосы портов вашего контейнера, привязка/файрвол падает независимо от объявления. Проверьте, что порт находится в выделенной полосе вашего контейнера, прежде чем увеличивать смещение.