MikuHAProxy

插件

· 作者 JunXieX

让 Velocity 4.0 同时接受 HAProxy PROXY 协议连接和玩家直连,并且只信任来自白名单来源的 PROXY 头。

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

最新 1.8.0 · 26.3 · Velocity

一键开服(送7天)

MikuHAProxy

让 Velocity 4.0 同时接受「代理连接(HAProxy PROXY protocol)」与「玩家直连」,并且只放行可信来源发来的 PROXY 头。

  • Version: 1.1.0
  • Author: JunXieX (MikuMC Server)
  • QQ Group: 1105054380

Why You Need It

为什么需要它

Velocity 的 velocity.toml 里有一项 proxy-protocol。一旦打开,Velocity 就认为每一条进来的连接都带着 HAProxy 的 PROXY 头,并在管道最前面挂上解码器;不带 PROXY 头的连接会被直接掐断。

这带来一个两难:

  • Leave proxy-protocol off: you cannot see the player's real IP behind HAProxy, so IP bans, login restrictions and risk control all stop working.
    • 不开 proxy-protocol:拿不到经过 HAProxy 之后的玩家真实 IP,IP 封禁、登录限制、风控全部失效。
  • Turn proxy-protocol on: only connections through HAProxy get in, and direct player connections (LAN debugging, backup entry points, ops probes) are all rejected.
    • 开了 proxy-protocol:只有经过 HAProxy 的连接能进,玩家直连(内网调试、备用入口、运维探测)全部被拒。

MikuHAProxy 同时保住两头:在管道首位放一个探测器,按连接开头的那几个字节判断这条连接是代理连接还是直连,分别走各自的路径。

Security Model

安全模型

Only when the TCP peer address — the address of the machine that actually opened the connection — is on the whitelist will its PROXY header be trusted.

只有「TCP 对端地址」——也就是真正发起这条连接的机器的地址——出现在白名单里的连接,它发来的 PROXY 头才会被采信。

There is no room for ambiguity here: the "client address" declared inside a PROXY header is a string written by the sender, and anyone can forge it. If you trusted what the PROXY header says, an attacker could simply stand up their own HAProxy, send a forged header, and impersonate any IP — IP bans would stop working instantly. So the only valid criterion is the TCP peer address: it is a fact of the network layer and cannot be forged.

这一点不能含糊:PROXY 头里声明的「客户端地址」是发送方自己填的字符串,任何人都能伪造。如果按 PROXY 头里的内容去信任,攻击者只要自己架一个 HAProxy 往里发头,就能把自己伪装成任意 IP,IP 封禁立刻失效。所以判据只能是 TCP 对端地址——它是网络层的事实,伪造不了。

When the whitelist is empty, all proxied connections are rejected and only direct connections are kept. That is a deliberate safe default.

白名单为空时,所有代理连接都会被拒绝,只保留直连。这是刻意的安全默认值。

Two things must be said plainly:

有两点必须说清楚:

  • The whitelist governs only whose PROXY header is trusted. It does not restrict direct connections: any address that can reach the proxy port is still let in as a direct connection. If that port is exposed to the internet, control direct access with a firewall of your own.
    • 白名单只管「谁的 PROXY 头会被采信」,它不限制直连:任何能连到代理端口的地址,仍然可以按直连的方式进来。代理端口若对公网开放,请用防火墙单独控制直连来源。
  • The shipped whitelist.conf already contains 127.0.0.0/8 and ::1/128. That is deliberate trust in loopback — the usual deployment puts HAProxy and Velocity on the same machine — and the price is that any process on that machine which can reach the port may send a PROXY header claiming to be any IP, and have it believed. If the machine has untrusted users, delete those two lines and whitelist only HAProxy's actual address.
    • 出厂的 whitelist.conf 里预置了 127.0.0.0/8 与 ::1/128。这是有意的回环信任(绝大多数部署把 HAProxy 与 Velocity 放在同一台机器上),代价是本机上任何能连到这个端口的进程,都可以发一个「自称任意 IP」的 PROXY 头并被采信。若这台机器上有不受信任的其他用户,请删掉这两条,改成只写 HAProxy 的实际地址。

How It Works

工作原理

  1. When a new connection is created, Velocity runs the connection initializer once. This plugin wraps around it: it runs Velocity's initializer unchanged first, then replaces the PROXY decoder at the head of the pipeline with its own detector.

    • 每条新连接创建时,Velocity 会执行一次连接初始化。本插件包了一层,先原样执行 Velocity 的初始化,再把管道最前面的 PROXY 解码器换成探测器。
  2. The detector reads the opening bytes of the connection:

    • 探测器读连接开头的字节:
    • The opening cannot be a PROXY header → it is a direct connection. The detector removes itself from the pipeline and hands the already-buffered bytes over untouched (not a single byte of the handshake packet is lost).
      • 开头不可能是 PROXY 头 → 判定为直连,探测器把自己从管道里摘掉,已缓冲的字节原封不动交给后续处理器(握手包一个字节都不会丢)。
    • The opening is a PROXY header → it checks whether the TCP peer address is on the whitelist. If yes, a real PROXY decoder is put back and control returns to Velocity; if no, the connection is closed immediately.
      • 开头确实是 PROXY 头 → 检查 TCP 对端地址是否在白名单里。在 → 换上真正的 PROXY 解码器交还给 Velocity;不在 → 立即关闭连接。
  3. Once the decision is made, the detector takes no further part in that connection.

    判定完成后探测器就不再参与这条连接的任何后续处理。

The decision is progressive: the v2 signature starts with 0x0D and the v1 prefix is PROXY, so the moment a received byte mismatches, the connection is immediately classified as direct. The vast majority of direct connections are settled by looking at a single byte, with no needless waiting.

判定是渐进式的:v2 的签名以 0x0D 开头、v1 的前缀是 PROXY,只要收到的字节出现失配就立刻定性为直连。绝大多数直连连接只看 1 个字节就能得出结论,不需要白等。

Requirements

环境要求

Item Requirement
Proxy Velocity 4.0 or newer; Velocity-CTD 4.x works as well (both verified)
Java Java 25 (Velocity 4.0 itself requires Java 25)
Prerequisite proxy-protocol = true in velocity.toml
项 要求
代理端 Velocity 4.0 及以上;Velocity-CTD 4.x 同样适用(两者均已核对)
Java Java 25(Velocity 4.0 自身要求 Java 25)
前置配置 velocity.toml 中 proxy-protocol = true

Installation

安装

  1. 将 MikuHAProxy-1.1.0.jar 放入代理端的 plugins/ 目录。
    • 把 MikuHAProxy-1.1.0.jar 放进代理端的 plugins/ 目录。
  2. 启动一次代理。插件会生成数据目录 plugins/MikuHAProxy/,内含 config.toml 和 whitelist.conf。
    • 启动一次代理。插件会生成数据目录 plugins/MikuHAProxy/,内含 config.toml 与 whitelist.conf。
  3. 在 velocity.toml 中设置 proxy-protocol = true,然后重启代理(此选项不支持热重载)。
    • 在 velocity.toml 中设置 proxy-protocol = true,然后重启代理(这一项不支持热重载)。
  4. 将你的 HAProxy 服务器地址写入 plugins/MikuHAProxy/whitelist.conf。
    • 把你的 HAProxy 服务器地址写进 plugins/MikuHAProxy/whitelist.conf。
  5. 运行 /mikuproxy reload 使白名单生效,或直接重启代理。
    • 执行 /mikuproxy reload 让白名单生效,或直接重启代理。

如果启动日志提示 velocity.toml 中未启用 proxy-protocol,说明第 3 步尚未完成,插件将无法生效。

启动日志里如果出现「velocity.toml 里没有启用 proxy-protocol」,说明第 3 步还没做,插件不会起作用。

配置

配置

plugins/MikuHAProxy/config.toml

仅使用最简单的 key = value 格式。任何一项拼写错误都只会回退到默认值并在控制台报错,绝不会导致插件加载失败。

只使用 键 = 值 这一种最简形式。任何一项写错都只会回退到默认值并在控制台报出问题,不会让插件加载失败。

选项 默认值 说明
allow-all-proxies false 是否接受来自任何来源的代理连接。生产环境严禁开启——见下方警告。
whitelist-file "whitelist.conf" 白名单文件路径。相对路径基于 plugins/MikuHAProxy/ 解析;绝对路径同样有效。
log-rejected-connections true 是否输出「代理连接被拒绝」和「判定过程中发生异常」的日志行。建议保持开启:这是发现有人伪造 IP 的首要线索。关闭后这两类日志均不输出,但计数仍可在 status 的「Rejected」和「Errors」中看到。
log-accepted-connections false 是否为每条接受的代理连接输出一条日志行。通常建议保持关闭。
rejected-log-interval-seconds 60 同一来源地址的拒绝日志之间的最小间隔(秒),范围 0 ~ 86400。0 表示禁用限流。
rejected-log-max-tracked 4096 日志限流器同时跟踪的来源地址数量上限,范围 16 ~ 1000000。
配置项 默认值 说明
allow-all-proxies false 是否放行任何来源的代理连接。生产环境绝对不要开启,详见下方警告。
whitelist-file "whitelist.conf" 白名单文件路径。相对路径相对于 plugins/MikuHAProxy/,也可以写绝对路径。
log-rejected-connections true 是否输出「代理连接被拒绝」与「判定过程发生异常」这两类日志。建议保持开启,这是发现有人在伪造 IP 的第一手线索;关闭后两类日志都不再输出,次数仍可在 status 的「拒绝」「异常」计数里看到。
log-accepted-connections false 是否输出「代理连接被接受」的日志(每条代理连接一行)。平时建议关闭。
rejected-log-interval-seconds 60 同一来源地址的拒绝日志最短间隔,单位秒,范围 0 ~ 86400。0 表示不限流。
rejected-log-max-tracked 4096 日志限流器最多同时跟踪多少个来源地址,范围 16 ~ 1000000。

关于 allow-all-proxies:启用它等同于禁用白名单。任何人都可以自行搭建 HAProxy 并向你的代理发送伪造的 PROXY 头,冒充玩家的真实 IP;IP 封禁、登录限制和风控机制都将失效。仅在完全隔离且未暴露于公网的测试环境中使用。

关于 allow-all-proxies:打开它等于关闭白名单。任何人都可以自己架一个 HAProxy 向你的代理发送伪造的 PROXY 头,从而伪造玩家真实 IP,IP 封禁、登录限制、风控全部失效。仅在完全隔离、不对公网暴露的测试环境里才可以使用。

plugins/MikuHAProxy/whitelist.conf

每行一条规则;# 之后的内容为注释,空行将被忽略。

每行一条规则,# 之后是注释,空行忽略。

# Single IPv4 / IPv6
127.0.0.1
::1

# Network range (CIDR)
127.0.0.0/8
10.0.0.0/8
fd00::/8

# Domain name: resolved once at startup, all A / AAAA records are included
proxy.example.com

注意:

说明:

  • 此处检查的是建立 TCP 连接的那台机器的地址(即你的 HAProxy 服务器),而非 PROXY 头中声明的客户端地址。
    • 这里判断的是发起 TCP 连接的那台机器的地址(你的 HAProxy 服务器),不是 PROXY 头里声明的客户端地址。
  • 域名不能带 /前缀:一个域名可能同时拥有 IPv4 和 IPv6 地址,单一的前缀长度无法涵盖两者。如需指定网段,请直接使用 CIDR 格式。
    • 域名不能带 /前缀:一个域名可能同时有 IPv4 和 IPv6 地址,前缀长度无法统一表达。需要网段请直接写 CIDR。
  • 格式错误的行仅会被跳过,控制台会报告具体是哪一行、包含什么内容以及错误原因——这绝不会导致插件加载失败。
    • 某一行写法有误只会跳过该行,并在控制台提示「第几行、什么内容、什么问题」,不会导致插件加载失败。
  • 如果 HAProxy 和 Velocity 运行在同一台机器上,通常只需添加 127.0.0.0/8 和 ::1/128。
    • 如果 HAProxy 和 Velocity 装在同一台机器上,通常只需要 127.0.0.0/8 和 ::1/128 两条。
  • 白名单为空意味着拒绝所有代理连接,仅保留直连。
    • 白名单为空 = 拒绝所有代理连接,只保留直连。

命令与权限

命令与权限

命令 说明
/mikuproxy 显示帮助信息
/mikuproxy status 显示管道注入状态、proxy-protocol 开关、白名单概览、连接计数器和运行时间
/mikuproxy list 列出当前生效的所有白名单规则
/mikuproxy reload 重新读取 config.toml 和白名单;立即对之后新建的连接生效,已建立的连接不受影响。如果配置中有错误项,执行该命令的人会直接看到问题列表(超出列表部分的内容会在控制台日志中显示)
命令 说明
/mikuproxy 显示帮助
/mikuproxy status 查看管道注入状态、proxy-protocol 开关、白名单概览、连接计数、已运行时间
/mikuproxy list 列出当前生效的全部白名单规则
/mikuproxy reload 重新读取 config.toml 与白名单,立即对之后新建的连接生效,已建立的连接不受影响。配置里若有写错的项,执行这条命令的人会直接看到问题清单(列不完的部分在控制台日志里)

别名:/mhp、/mikuhaproxy。

别名:/mhp、/mikuhaproxy。

权限:mikuhaproxy.admin(控制台默认拥有此权限)。

权限:mikuhaproxy.admin(控制台默认拥有)。

status 中的连接计数器含义:

Counter 含义
Direct 被判定为直连的连接数
Proxied 被判定为代理且通过白名单检查的连接数
Rejected 被判定为代理但来源不在白名单中,并已被关闭的连接数
Not injected 在管道中未找到 PROXY 解码器(通常意味着 velocity.toml 中未开启 proxy-protocol)
Errors 决策过程中引发异常或注入失败,并按原有方式处理的连接数

Troubleshooting

常见问题

启用后,玩家的实际 IP 显示为 HAProxy 的地址?

PROXY 头未被信任。请按顺序检查:velocity.toml 中的 proxy-protocol 是否为 true、HAProxy 是否配置了 send-proxy(v1)或 send-proxy-v2、HAProxy 的地址是否在 whitelist.conf 中,以及 /mikuproxy status 中的「Proxied」计数是否在增长。

HAProxy 已正确配置,但连接仍被拒绝?

查看控制台中的拒绝日志以及 /mikuproxy list。最常见的原因是 HAProxy 到 Velocity 连接的实际源地址与白名单中写入的地址不一致(例如中间存在 NAT 或容器网络),此时请将实际的对端地址加入白名单。

插件启动后似乎没有任何作用?

运行 /mikuproxy status 并检查「Pipeline injection」是否为「Installed」,以及 velocity.toml 中的 proxy-protocol 是否为「Enabled」。如果其中任何一项不正确,插件将不会改变连接的处理方式。

如果配置错误会发生什么?

插件照常启动,错误的条目会回退到默认值,问题将以「第几行,什么问题」的形式打印到控制台中。whitelist.conf 的行为也是如此:非法行仅跳过自身。当运行 /mikuproxy reload 时,这些问题会直接回显给执行命令的人,因此无需翻阅日志。

Statement

声明

本项目为 MikuMC 服务器的原创插件,免费公开提供使用。MikuMC 服务器及作者 JunXieX 拥有本项目的著作权。本项目不开源,请注意。

MikuMC 系列插件交流群:1105054380

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

评论 0

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

登录后参与评分

还没有评论,来抢沙发吧

评论配图

相似资源