HAProxyCompat

模组

· 作者 the_atmerek

通过读取 PROXY 协议(v1/v2),在反向代理(FRP、nginx、HAProxy、Traefik)后方的模组服务器中恢复真实的客户端 IP。

0 本站下载 0 关注 更新于 1 个月前

最新 1.1.0 · 26.3 · Fabric / NeoForge

一键开服(送7天)

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),该版本仍然可用,但不再接收更新。

快速开始

  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: 可以发送 PROXY 头的 IP 地址/CIDR 范围。只信任列出的这些地址;任何其他发送 PROXY 头的地址都会被丢弃。在此处添加你的代理地址。
  • log_connections: 为每次连接决策打印一行信息。非常适合调试,但在正常运行时会显得杂乱。
  • kick_message: 当客户端直接连接且 require_proxy_protocol 为 true 时,在断开连接屏幕上显示的消息。如果没有此消息,客户端将会挂起直到读取超时触发。

为什么 trusted_proxies 很重要

PROXY 头只是连接方发送的文本。任何能够直接访问你服务器端口的人都可以发送伪造的头并声称自己是任意 IP,从而让他们躲避封禁或陷害他人。为了防止这种情况,HAProxyCompat 仅在头来自你在 trusted_proxies 中列出的地址时才予以信任。其他人将被忽略或丢弃。

两条简单规则:

  1. 添加你代理的真实地址。 默认列表仅信任本地机器。如果你的代理位于其他主机或子网上,除非你在此处添加其 IP 或 CIDR,否则其头将被拒绝。
  2. 锁好代理后面的门。 对 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 许可证。

你是这个资源的作者?登录后可认领此资源。

评论 0

0.0
暂无评分
5 星
0
4 星
0
3 星
0
2 星
0
1 星
0
我的评分

登录后参与评分

还没有评论,来抢沙发吧

评论配图

相似资源