[MD]
# GeyserBraid 扩展
## 这是什么？
GeyserBraid 是一个 **Geyser 扩展**。它让 Geyser 的 `transport: both` 模式**只占用一个公网 UDP 端口**：RakNet 与 NetherNet 的流量在同一个端口上按 RFC 7983 首字节自动分流。
对于只能映射**单个 UDP 端口**的主机环境（家用宽带、部分服务商面板、frp 单端口转发），它绕开了 Geyser 强制要求两个传输各占一个 UDP 端口的限制。
> ⚠️ 这是 Geyser 扩展，**不能单独使用**，必须放入 Geyser 的 `extensions/` 文件夹（不是服务器的 `plugins/` 文件夹）。
## 前置要求
1. **Geyser 2.12.x**（支持 Standalone / Spigot / Paper / Bungee / Velocity 等所有运行平台）
2. `bedrock.transport` 必须设为 `both`
3. `webrtc-port` 必须是一个与 `bedrock.port` **不同**的空闲端口（Geyser 内部回环中继使用，**无需**对外映射）
## 安装与配置
### 1. 放入扩展文件
从 GitHub Releases 下载 `GeyserBraid.jar`，放入 Geyser 平台配置目录下的 `extensions/` 文件夹。不同平台的路径如下：
```text
# Standalone (独立版)
/extensions/
# Spigot / Paper
/plugins/Geyser-Spigot/extensions/
# BungeeCord
/plugins/Geyser-BungeeCord/extensions/
# Velocity
/plugins/Geyser-Velocity/extensions/
```
### 2. 修改 Geyser 监听配置
打开你的 Geyser `config.yml`，确保开启了双协议，并为其分配一个**不与主端口冲突**的本地空闲端口：
```yaml
bedrock:
port: 19132
transport: both
# webrtc-port 必须设置，且不能与 bedrock.port 相同
webrtc-port: 19133
```
### 3. （可选）配置真实 IP 透传
从 **v0.1.0-rc.2** 起，扩展在回环中继中默认使用 **PROXY protocol v2** 传递数据。**如果你的服务器不需要获取玩家真实 IP**（即后台看到 `127.0.0.1` 无所谓），**可以跳过此步**，不影响正常进服。
如果你有 IP 封禁、白名单或玩家统计需求，需要在 Geyser `config.yml` 中显式信任回环中继：
```yaml
advanced:
bedrock:
webrtc-proxy-protocol-relays:
- "127.0.0.1"
```
### 4. 验证是否生效
重启服务器。观察 Geyser 启动日志，看到以下信息即表示扩展成功挂载并在单端口上开始分流：
```text
[GeyserBraid] Assembled: demultiplexer mounted on 1 listener channel(s)...
[GeyserBraid] Advertising NetherNet candidates on the shared port: [/x.x.x.x:19132]
```
## 国内服务器注意事项
Geyser 的内置信令是明文 HTTP 请求。**如果没有完成 ICP 备案**，运营商会拦截未备案域名上的 HTTP 请求，导致客户端无法连接（通常表现为 Terracotta 错误）。
**规避方式**：让玩家使用裸 IP 直接加入，或者完成域名 ICP 备案。
## 常用命令
安装后可在服务器控制台或游戏内使用 `/braid` 命令：
- `/braid status`：查看分流器装配状态与监听端口
- `/braid list`：按传输类型（RakNet / NetherNet）列出在线玩家
- `/braid legs`：查看当前活跃的回环中继段
- `/braid advertise`：查看正在向客户端通告的候选地址
## 已验证环境
Geyser **2.12.1-b1280**（BungeeCord 插件），NAT 端口重映射部署（外网 35132 → 内网 19132）。26.60 客户端经 NetherNet 加入并完成游戏内实测（ICE connected → SCTP connected → 进入游戏）。
## 下载与文档
- **GitHub Releases（下载 jar）**：https://github.com/EnderRealmMC/GeyserBraid/releases
- **Modrinth（审核中）**：https://modrinth.com/mod/geyserbraid （目前页面正在审核排队中，通过后将提供更方便的国内/国际下载体验）
- **部署指南（端口规划、frp 配置、排障）**：https://github.com/EnderRealmMC/GeyserBraid/blob/main/DEPLOY.zh-CN.md
- **中文 README**：https://github.com/EnderRealmMC/GeyserBraid/blob/main/README.zh-CN.md
[/MD]
