HAProxyCompat
别再看到 127.0.0.1。看看究竟是谁在连接。
当你的 Minecraft 服务器位于反向代理(如 FRP、nginx、HAProxy 或 Traefik)之后时,每个玩家看起来都像是从代理连接的。封禁记录、日志和 IP 工具看到的都是代理的地址,而非真实地址。HAProxyCompat 解决了这个问题。它读取你的代理发送的 PROXY 协议头(v1 和 v2),提取出真实的客户端 IP,并将其作为玩家直接连接的方式传递给 Minecraft。
结果:日志中显示真实 IP,IP 封禁功能正常,地理位置定位准确。无需客户端模组,也无需为玩家进行额外设置。
注意: 这通常不是可选的。一旦你的代理开始发送 PROXY 头,原版服务器根本不知道这些额外字节是什么,并会因无法处理而崩溃,导致玩家无法连接,服务器在客户端看来处于离线状态。安装 HAProxyCompat 是让连接正常工作的前提。获取真实 IP 只是附加的好处。
- 适用于: NeoForge 和 Fabric 专用服务器。一个 jar 文件涵盖所有支持的加载器和版本。
- 需求: 无需其他依赖。Minecraft 未内置的那部分 Netty 组件已包含在 jar 文件中,因此它只是一个可即插即用的单一文件。
支持的版本
| 加载器 |
MC 版本 |
| NeoForge |
1.21 至 1.21.11, 26.1.x, 26.2.x, 26.3.x |
| Fabric |
26.1.x, 26.2.x, 26.3.x |
1.21.x 上的 Fabric 由较旧的 1.0.1 版本覆盖 (haproxycompat-fabric-1.21-1.0.1.jar),该版本仍然可用,但不再接收更新。
快速开始
- 将 jar 文件放入服务器的
mods/ 文件夹中。
- 配置你的代理以发送 PROXY 头(参见 指向你的代理)。
- 如果你的代理运行在不同的机器上,请将其 IP 添加到
trusted_proxies(见下文)。
- 启动服务器。完成。
开箱即用即可用于与服务器在同一台机器上运行的代理。这是唯一不需要任何配置的情况。
配置
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: 可以发送 PROXY 头的 IP 地址/CIDR 范围。只信任列出的这些地址;任何其他发送 PROXY 头的地址都会被丢弃。在此处添加你的代理地址。
- log_connections: 为每次连接决策打印一行信息。非常适合调试,但在正常运行时会显得杂乱。
- kick_message: 当客户端直接连接且
require_proxy_protocol 为 true 时,在断开连接屏幕上显示的消息。如果没有此消息,客户端将会挂起直到读取超时触发。
为什么 trusted_proxies 很重要
PROXY 头只是连接方发送的文本。任何能够直接访问你服务器端口的人都可以发送伪造的头并声称自己是任意 IP,从而让他们躲避封禁或陷害他人。为了防止这种情况,HAProxyCompat 仅在头来自你在 trusted_proxies 中列出的地址时才予以信任。其他人将被忽略或丢弃。
两条简单规则:
- 添加你代理的真实地址。 默认列表仅信任本地机器。如果你的代理位于其他主机或子网上,除非你在此处添加其 IP 或 CIDR,否则其头将被拒绝。
- 锁好代理后面的门。 对 Minecraft 端口进行防火墙设置,以便只有你的代理可以访问它。这样伪造的头根本无法到达。
如果列表为空,则不信任任何人,也不会应用任何真实 IP。服务器会在启动时记录警告,以免你感到困惑。
指向你的代理
HAProxyCompat 仅监听。你的代理仍必须被告知要发送头:
- HAProxy: 在
server 行中添加 send-proxy (v1) 或 send-proxy-v2。
- nginx (stream): 在
server 块中设置 proxy_protocol on;。
- FRP: 在被代理的服务上设置
transport.proxyProtocolVersion = "v2"。
- Traefik: 在 TCP 服务的服务器上启用
proxyProtocol。
从源代码构建
你需要 JDK 21 或更高版本来运行 Gradle;它会下载所需的精确工具链。
gradlew.bat build
jar 文件位于 build/libs/haproxycompat-<version>.jar(忽略 -slim 版本,它缺少捆绑的 Netty 编解码器)。
测试
serverTest 使用构建好的 jar 启动真实的专用服务器,并通过 Minecraft 协议与之通信:状态 ping 和使用 PROXY v1/v2 头登录、PROXY LOCAL 健康检查、直接连接(被踢出,服务器列表中显示红色 X)以及来自不受信任地址的 PROXY 头。
:: 默认集:每个版本行的范围端点
gradlew.bat serverTest
:: 所有支持的加载器和版本
gradlew.bat serverTest -Ptargets=all
:: 选择目标(裸加载器意味着其所有版本)
gradlew.bat serverTest -Ptargets=neoforge:26.3,fabric
服务器一次性安装到 .servertest/ 中(每个版本的最新 NeoForge 构建/Fabric Loader),并在后续运行中重复使用。运行它将接受那些测试服务器的 Minecraft EULA。每次运行都会将其控制台输出留在 .servertest/<target>/servertest-latest.log 中。
幕后原理
每个新连接首先会遇到一个位于网络管道最前端的小型守门员(ProxyProtocolDetector)。它会窥探起始字节,查看是否存在 PROXY 标头,并检查该连接是否来自受信任的代理。然后它决定采取何种操作:
| 来自受信任的代理? |
存在 PROXY 标头? |
结果 |
| 是 |
是 |
解码标头并应用真实客户端 IP |
| 否 |
是 |
关闭连接。有人正在尝试伪造 IP |
| 任意 |
否 |
使用 kick_message 踢出并在服务器列表显示红色 X(如果 require_proxy_protocol 为关闭状态,则放行) |
当需要读取标头时,守门员将字节交给 Netty 自带的 PROXY 解析器,获取真实地址,并将其直接写入 Minecraft 的连接对象。最后这一步在标头到达的瞬间发生,这正是 IP 能出现在所有地方(加入日志、封禁检查以及服务器询问“这是谁?”的任何其他位置)的关键所在。不携带真实客户端的健康检查 ping(PROXY LOCAL 命令)会被识别并忽略。
这是一个仅限专用服务器的模组,因此不会影响单人游戏或局域网世界。
单个 jar 文件同时支持两个加载器:它同时包含 neoforge.mods.toml 和 fabric.mod.json,而每个加载器仅读取属于自己的配置。所有支持的版本均使用 Mojang 自己的类名,因此相同的编译混合代码可在各处运行。NeoForge 使用 ModConfigSpec 实现配置的实时重载;Fabric 在启动时读取 haproxycompat.json。
许可证
GPL-3.0-or-later。详见 LICENSE。捆绑的 netty-codec-haproxy(在 jar 内重定位至 xyz.atmerek.haproxycompat.shadow.haproxy)保留其自身的 Apache-2.0 许可证。
HAProxyCompat
Stop seeing 127.0.0.1. See who's actually connecting.
When your Minecraft server sits behind a reverse proxy like FRP, nginx, HAProxy, or Traefik, every
player looks like they're connecting from the proxy. Bans, logs, and IP tools all see the proxy's
address instead of the real one. HAProxyCompat fixes that. It reads the PROXY protocol header
(v1 and v2) that your proxy sends, pulls out the real client IP, and hands it to Minecraft as if the
player connected directly.
The result: real IPs in your logs, working IP bans, and accurate geolocation. No client mod, no
extra setup for players.
Heads up: this is often not optional. Once your proxy starts sending PROXY headers, a vanilla
server has no idea what those extra bytes are and chokes on them, so players can't connect and the
server just looks offline in the client. Installing HAProxyCompat is what makes the connection work
at all. The real-IP part is the bonus.
- For: NeoForge and Fabric dedicated servers. One jar covers every supported loader and version.
- Needs: Nothing else. The one Netty piece Minecraft doesn't ship is tucked inside the jar for
you, so it stays a single drop-in file.
Supported versions
| Loader |
MC versions |
| NeoForge |
1.21 to 1.21.11, 26.1.x, 26.2.x, 26.3.x |
| Fabric |
26.1.x, 26.2.x, 26.3.x |
Fabric on 1.21.x is covered by the older 1.0.1 release (haproxycompat-fabric-1.21-1.0.1.jar),
which still works but no longer gets updates.
Quick start
- Drop the jar into your server's
mods/ folder.
- Tell your proxy to send the PROXY header (see Point your proxy at it).
- If your proxy runs on a different machine, add its IP to
trusted_proxies (see below).
- Start the server. Done.
Out of the box it works for a proxy running on the same machine as the server. That's the only case
that needs zero config.
Configure it
NeoForge: settings live in config/haproxycompat-common.toml. Edit them while the server is
running and they apply instantly, no restart needed.
Fabric: settings live in config/haproxycompat.json. Restart required for changes to take effect.
# 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."
}
Settings
- enabled: master on/off switch.
- require_proxy_protocol: when
true, only allow connections with a valid PROXY header from
a trusted proxy. Use when the Minecraft port is reachable only through your proxy. When false,
also allow plain direct connections through untouched.
- trusted_proxies: IP addresses / CIDR ranges that may send PROXY headers. Only these are
believed; anyone else sending a PROXY header is dropped. Add your proxy's address here.
- log_connections: print one line per connection decision. Great for debugging, noisy once working.
- kick_message: message shown in the disconnect screen when a client connects directly and
require_proxy_protocol is true. Without this, clients would hang until a read timeout fires.
Why trusted_proxies matters
The PROXY header is just text the connecting side sends. Anyone who can reach your server port
directly could send a fake one and claim to be any IP they like, which would let them dodge bans or
frame someone else. To stop that, HAProxyCompat only believes the header when it comes from an
address you've listed in trusted_proxies. Everyone else is ignored or dropped.
Two simple rules:
- Add your proxy's real address. The default list only trusts the local machine. If your proxy
lives on another host or subnet, its headers get rejected until you add its IP or CIDR here.
- Lock the door behind the proxy. Firewall the Minecraft port so only your proxy can reach it.
That way a forged header can never arrive in the first place.
If the list is empty, nobody is trusted and no real IPs get applied. The server logs a warning at
startup so you're not left guessing.
Point your proxy at it
HAProxyCompat only listens. Your proxy still has to be told to send the header:
- HAProxy: add
send-proxy (v1) or send-proxy-v2 to the server line.
- nginx (stream): set
proxy_protocol on; in the server block.
- FRP: set
transport.proxyProtocolVersion = "v2" on the proxied service.
- Traefik: enable
proxyProtocol on the TCP service's server.
Build from source
You need a JDK 21 or newer to run Gradle; it downloads the exact toolchain it needs.
gradlew.bat build
The jar lands in build/libs/haproxycompat-<version>.jar (ignore the -slim one, it lacks the
bundled Netty codec).
Testing
serverTest starts real dedicated servers with the built jar and talks to them over the Minecraft
protocol: status pings and logins with PROXY v1/v2 headers, a PROXY LOCAL health check, direct
connections (kicked, red X in the server list) and a PROXY header from an untrusted address.
:: Default set: the range endpoints of each version line
gradlew.bat serverTest
:: Every supported loader and version
gradlew.bat serverTest -Ptargets=all
:: Pick targets (a bare loader means all of its versions)
gradlew.bat serverTest -Ptargets=neoforge:26.3,fabric
Servers are installed once into .servertest/ (the newest NeoForge build / Fabric Loader for each
version) and reused on later runs. Running it accepts the Minecraft EULA for those test servers.
Each run leaves its console output in .servertest/<target>/servertest-latest.log.
Under the hood
Every new connection first meets a small gatekeeper (ProxyProtocolDetector) that sits at the very
front of the network pipeline. It peeks at the opening bytes to see if a PROXY header is there, and
checks whether the connection came from a trusted proxy. Then it decides what to do:
| From a trusted proxy? |
Has a PROXY header? |
What happens |
| Yes |
Yes |
Decode the header and apply the real client IP |
| No |
Yes |
Close the connection. Someone's trying to spoof an IP |
| Any |
No |
Kick with kick_message and show a red X in the server list (or let it through, if require_proxy_protocol is off) |
When a header should be read, the gatekeeper hands the bytes to Netty's own PROXY parser, grabs the
real address, and writes it straight onto Minecraft's connection object. That last step happens the
moment the header arrives, which is the trick that makes the IP show up everywhere: in the join log,
in ban checks, and anywhere else the server asks "who is this?". Health-check pings that carry no
real client (the PROXY LOCAL command) are recognized and left alone.
It's a dedicated-server-only mod, so it never touches singleplayer or LAN worlds.
One jar serves both loaders: it carries both neoforge.mods.toml and fabric.mod.json, and each
loader only reads its own. All supported versions run on Mojang's own class names, so the same
compiled mixins work everywhere. NeoForge uses ModConfigSpec for live-reloading config; Fabric
reads haproxycompat.json at startup.
License
GPL-3.0-or-later. See LICENSE. The bundled netty-codec-haproxy (relocated to
xyz.atmerek.haproxycompat.shadow.haproxy inside the jar) keeps its own Apache-2.0 license.
评论 0
登录后参与评分
还没有评论,来抢沙发吧