HAProxyCompat

HAProxyCompat

Хватит видеть 127.0.0.1. Узнай, кто на самом деле подключается.

Когда твой Minecraft-сервер стоит за обратным прокси вроде FRP, nginx, HAProxy или Traefik, каждый игрок выглядит так, будто подключается с прокси. Баны, логи и IP-инструменты видят адрес прокси вместо настоящего. HAProxyCompat это исправляет. Он читает заголовок PROXY protocol (v1 и v2), который отправляет твой прокси, вытаскивает реальный IP клиента и передаёт его Minecraft так, будто игрок подключился напрямую.

Результат: настоящие IP в логах, работающие IP-баны и точная геолокация. Никаких клиентских модов, никакой дополнительной настройки для игроков.

Внимание: часто это вообще не опция. Как только твой прокси начинает отправлять заголовки PROXY, ванильный сервер понятия не имеет, что это за лишние байты, и давится ими, так что игроки не могут подключиться, а сервер просто выглядит офлайн в клиенте. Установка HAProxyCompat — это то, что вообще заставляет соединение работать. Настоящий IP — приятный бонус.

• Для: выделенных серверов на NeoForge и Fabric. Один jar покрывает все поддерживаемые загрузчики и версии.
• Нужно: ничего больше. Единственный кусок Netty, который Minecraft не поставляет, спрятан внутри jar для тебя, так что это остаётся одним файлом для простого добавления.

Поддерживаемые версии

Fabric на 1.21.x покрывается старым релизом 1.0.1 (haproxycompat-fabric-1.21-1.0.1.jar), который всё ещё работает, но больше не получает обновлений.

Быстрый старт

1. Закинь jar в папку mods/ твоего сервера.
2. Скажи своему прокси отправлять заголовок PROXY (см. Направь свой прокси на него).
3. Если твой прокси работает на другой машине, добавь его IP в trusted_proxies (см. ниже).
4. Запусти сервер. Готово.

Из коробки работает для прокси, запущенного на той же машине, что и сервер. Это единственный случай, который требует нулевой настройки.

Настройка

NeoForge: настройки лежат в config/haproxycompat-common.toml. Редактируй их, пока сервер работает, и они применяются мгновенно, перезапуск не нужен.

Fabric: настройки лежат в config/haproxycompat.json. Для применения изменений нужен перезапуск.

# NeoForge (haproxycompat-common.toml)
[general]
    enabled = true
    require_proxy_protocol = true
    trusted_proxies = ["127.0.0.1/32", "::1/128"]
    log_connections = false
    kick_message = "This server requires a proxy connection."

// Fabric (haproxycompat.json)
{
  "enabled": true,
  "requireProxyProtocol": true,
  "trustedProxies": ["127.0.0.1/32", "::1/128"],
  "logConnections": false,
  "kickMessage": "This server requires a proxy connection."
}

Настройки

• enabled: главный выключатель вкл/выкл.
• require_proxy_protocol: когда true, разрешает только подключения с валидным заголовком PROXY от доверенного прокси. Используй, когда порт Minecraft доступен только через твой прокси. Когда false, также разрешает обычные прямые подключения без изменений.
• trusted_proxies: IP-адреса / CIDR-диапазоны, которым можно отправлять заголовки PROXY. Только им верят; все остальные, отправляющие заголовок PROXY, отбрасываются. Добавь сюда адрес своего прокси.
• log_connections: печатать одну строку на каждое решение о подключении. Отлично для отладки, шумно когда всё работает.
• kick_message: сообщение, показываемое на экране отключения, когда клиент подключается напрямую и require_proxy_protocol равен true. Без этого клиенты зависнут до срабатывания таймаута чтения.

Почему trusted_proxies важен

Заголовок PROXY — это просто текст, который отправляет подключающаяся сторона. Любой, кто может добраться до порта твоего сервера напрямую, мог бы отправить поддельный и заявить, что он с любого IP, какого захочет, что позволило бы ему обойти баны или подставить кого-то другого. Чтобы это пресечь, HAProxyCompat верит заголовку только тогда, когда он приходит с адреса, который ты указал в trusted_proxies. Все остальные игнорируются или отбрасываются.

Два простых правила:

1. Добавь реальный адрес своего прокси. Список по умолчанию доверяет только локальной машине. Если твой прокси живёт на другом хосте или подсети, его заголовки будут отклоняться, пока ты не добавишь его IP или CIDR сюда.
2. Закрой дверь за прокси. Закрой порт Minecraft файрволом, чтобы до него мог добраться только твой прокси. Тогда подделанный заголовок просто не сможет дойти.

Если список пуст, никому нет доверия и реальные IP не применяются. Сервер пишет предупреждение при запуске, чтобы ты не гадал.

Настрой свой прокси на него

HAProxyCompat только слушает. Прокси всё равно нужно сказать, чтобы он отправлял заголовок:

• HAProxy: добавь send-proxy (v1) или send-proxy-v2 в строку server.
• nginx (stream): поставь proxy_protocol on; в блоке server.
• FRP: поставь transport.proxyProtocolVersion = "v2" на проксируемом сервисе.
• Traefik: включи proxyProtocol на сервере TCP-сервиса.

Сборка из исходников

Для запуска Gradle нужен JDK 21 или новее; он сам скачает нужный тулчейн.

gradlew.bat build

Jar появится в `build/libs/haproxycompat-.jar(игнорируй-slim` — в нём нет встроенного Netty-кодека).

Тестирование

serverTest запускает настоящие выделенные серверы со собранным jar и общается с ними по протоколу Minecraft: пинги статуса и логины с заголовками PROXY v1/v2, проверка здоровья PROXY LOCAL, прямые подключения (кик, красный крестик в списке серверов) и заголовок PROXY с недоверенного адреса.

:: Набор по умолчанию: крайние точки диапазона каждой линейки версий
gradlew.bat serverTest
:: Все поддерживаемые загрузчики и версии
gradlew.bat serverTest -Ptargets=all
:: Выбрать цели (голый загрузчик означает все его версии)
gradlew.bat serverTest -Ptargets=neoforge:26.3,fabric

Серверы устанавливаются один раз в .servertest/ (самая новая сборка NeoForge / Fabric Loader для каждой версии) и переиспользуются при следующих запусках. Запуск означает принятие Minecraft EULA для этих тестовых серверов. Каждый запуск оставляет вывод консоли в `.servertest//servertest-latest.log`.

Под капотом

Каждое новое подключение сначала встречает небольшой привратник (ProxyProtocolDetector), который стоит в самом начале сетевого конвейера. Он заглядывает в первые байты, чтобы понять, есть ли там заголовок PROXY, и проверяет, пришло ли подключение от доверенного прокси. Затем он решает, что делать:

Когда заголовок нужно прочитать, привратник передаёт байты собственному парсеру PROXY от Netty, достаёт реальный адрес и записывает его прямо в объект подключения Minecraft. Этот последний шаг происходит в момент прихода заголовка — именно этот трюк заставляет IP появляться везде: в логе входа, в проверках бана и везде, где сервер спрашивает «кто это?». Пинги проверки здоровья, не несущие реального клиента (команда PROXY LOCAL), распознаются и не трогаются.

Это мод только для выделенного сервера, так что он никогда не касается одиночных или LAN-миров.

Один jar обслуживает оба загрузчика: он несёт и neoforge.mods.toml, и fabric.mod.json, и каждый загрузчик читает только свой. Все поддерживаемые версии работают на собственных именах классов Mojang, так что одни и те же скомпилированные миксины работают везде. NeoForge использует ModConfigSpec для конфига с живой перезагрузкой; Fabric читает haproxycompat.json при запуске.

Лицензия

GPL-3.0-or-later. Смотри LICENSE. Встроенный netty-codec-haproxy (перемещённый в xyz.atmerek.haproxycompat.shadow.haproxy внутри jar) сохраняет свою собственную лицензию Apache-2.0.