add minecraft protocol

2026-03-05 15:48:45 +08:00
parent daba0d704e
commit 66ded37577
16 changed files with 2447 additions and 8 deletions
@@ -0,0 +1,121 @@
+--- /dev/null
+++ b/docs/configuration/inbound/minecraft.zh.md
+@@ -0,0 +1,118 @@
+### 结构
+
+```json
+{
+  "type": "minecraft",
+  "tag": "mc-in",
+
+  ... // 监听字段
+
+  "users": [
+    {
+      "username": "Steve",
+      "password": "my-secret-password"
+    }
+  ],
+  "status": {
+    "forward": false,
+    "version": {
+      "name": "1.20.4",
+      "protocol": 765
+    },
+    "description": "A Minecraft Server",
+    "players": {
+      "max": 20,
+      "online": 1,
+      "sample": [
+        {
+          "name": "Notch",
+          "id": "069a79f4-44e9-4726-a5be-fca90e38aaf5"
+        }
+      ]
+    },
+    "favicon": "data:image/png;base64,<data>",
+    "enforces_secure_chat": false
+  },
+  "fallback": {
+    "server": "mc.example.com",
+    "server_port": 25565,
+    "tag": "mc-fallback"
+  }
+}
+```
+
+### 监听字段
+
+详见 [监听字段](/configuration/shared/listen/)。
+
+### 字段
+
+#### users
+
+允许通过代理认证的用户列表，每项包含 `username` 和 `password`。
+
+不在列表中的用户名连接将被透明转发至 `fallback` 服务器（如已配置），使真实 Minecraft 玩家可以正常连接。
+
+#### status
+
+控制向 Minecraft 客户端返回的服务器列表 ping 响应。
+
+##### status.forward
+
+若为 `true`，status ping 将转发至 `fallback` 服务器而非本地响应。需要配置 `fallback`。
+
+##### status.version
+
+服务器列表中显示的版本信息。
+
+- `name`：版本字符串（如 `"1.20.4"`）
+- `protocol`：协议号（如 `765`）。默认为 `765`（即 1.20.4）。
+
+##### status.description
+
+服务器列表中显示的 MOTD。支持纯文本字符串或 [JSON Chat Component](https://wiki.vg/Text_formatting#JSON_text_component) 对象以实现富文本格式：
+
+```json
+"description": "纯文本 MOTD"
+```
+
+```json
+"description": {"text": "带颜色的 MOTD", "color": "green"}
+```
+
+##### status.players
+
+- `max`：显示的最大玩家数。
+- `online`：显示的在线玩家数。
+- `sample`：鼠标悬停时显示的玩家列表，每项包含 `name` 和可选的 `id`（UUID）。若省略 `id`，将根据用户名生成确定性离线 UUID。
+
+##### status.favicon
+
+服务器图标，格式为 `data:image/png;base64,<data>`，显示在服务器列表中。
+
+##### status.enforces_secure_chat
+
+是否要求客户端使用签名聊天消息，将原样传递给客户端。
+
+#### fallback
+
+配置后，未知用户的连接将通过 sing-box 路由器透明代理至此 Minecraft 服务器。
+
+- `server`：fallback 服务器的主机名或 IP。
+- `server_port`：fallback 服务器端口，默认为 `25565`。
+- `tag`：设置后，fallback 连接在路由元数据中使用该标识，允许通过路由规则将 fallback 流量与代理流量分别发往不同出站。
+
+### 说明
+
+Minecraft 入站将代理流量伪装为 Minecraft Java Edition 协议流量。
+
+连接流程：
+
+1. 客户端连接并发送 Minecraft 握手包
+2. 若下一状态为 **Status**：服务端返回伪造的服务器列表 ping 响应（若启用了 `status.forward` 则转发至 fallback）
+3. 若下一状态为 **Login**：服务端执行标准 Minecraft 加密握手（RSA 密钥交换 + AES/CFB8）
+4. 认证通过 `SHA-256(password + verify_token)[:16]` 派生共享密钥进行验证；真实 Minecraft 客户端会自然失败，并收到真实的"Failed to verify username!"错误
+5. 登录完成后，smux 多路复用在 AES/CFB8 加密连接上运行
+6. 每个 smux 流携带 1 字节命令（`0x01` 表示 TCP，`0x03` 表示 UDP）加 SOCKS 地址头
+
+同时也支持 1.7 之前的旧版 ping（`0xFE`），并返回格式正确的响应。