HAProxyCompat

Minecraft 版本： 26.2

平台： fabric

标签： utility

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. Pick the jar that matches your loader and MC 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.

Quick start

1. Drop the right jar into your server's mods/ folder.
2. Tell your proxy to send the PROXY header (see Point your proxy at it).
3. If your proxy runs on a different machine, add its IP to trusted_proxies (see below).
4. 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 — true: only allow connections with a valid PROXY header from a
  trusted proxy. Use when the Minecraft port is reachable only through your proxy. 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:

1. 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.
2. 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.

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:

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.

The core logic (ProxyProtocolDetector, ProxyProtocolHandler, mixins) is shared between both
loaders. NeoForge uses ModConfigSpec for live-reloading config; Fabric reads haproxycompat.json
at startup.