安装与配置
前置条件
- 一台能跑 Bngeuit 机器人 的机器（Windows / Linux 都行），已装好 Bngeuit 并能正常收发群消息 —— 没装过先看 Bngeuit 快速开始
- 一个 Bukkit / Spigot / Paper 系服务端（Java 8 及以上）
- MC 服务器能访问到 Bngeuit 所在机器的 WebSocket 端口（默认
8765），如果不在同一台机器，记得放行防火墙
第一步：Bngeuit 侧装 BngeuitBridge
- 把
BngeuitBridge.jar放进 Bngeuit 根目录下的plugins/ - 启动一次 Bngeuit，插件会生成
plugins/BngeuitBridge/config.yml - 打开配置，把
token改成一串你自己定的密钥（下面这个不重要，是网关上唯一的共享密码）
# 认证 Token —— MC 服务器连接时必须填一模一样的值
token: "change-me-to-a-secret"
websocket:
enabled: true
# 0.0.0.0 = 允许外部机器连接；127.0.0.1 = 只允许本机
host: "0.0.0.0"
port: 8765
# 心跳间隔（秒），0 = 关闭心跳
heartbeat-interval: 30
# 单条消息最大字节数，超过直接拒收
max-message-size: 65536- 让配置生效：控制台执行
plugin reload BngeuitBridge，或直接重启 Bngeuit
启动日志里能看到监听地址：
[BridgeChannel] WebSocket 通道已启动，0.0.0.0:8765（心跳间隔 30s，最大消息 65536B）公网部署
如果 Bngeuit 和 MC 不在内网互通的环境（比如 MC 在另一家的机房），ws:// 是明文传输，token 会裸奔。生产环境建议在 BngeuitBridge 前面套一层 TLS 反向代理（nginx 的 wss://），MC 侧把 url 改成 wss://你的域名/ 即可，插件本身对 wss:// 无感知。
第二步：MC 侧装 MC-BngeuitBridge
- 把
MC-BngeuitBridge.jar放进服务端的plugins/ - 启动服务器，插件会生成
plugins/MC-BngeuitBridge/config.yml和script/目录 - 填写配置：
# 是否释放脚本示例文件。改成 false 后，重启不会再生成那两个示例脚本
create script example: true
# 必须和 BngeuitBridge 的 token 一字不差
token: "change-me-to-a-secret"
websocket:
# 本服务器在桥接里的名字，必填，多台服务器之间不能重复
client-id: "survival"
# BngeuitBridge 的地址：同一台机器用 localhost，跨机填 Bngeuit 的 IP
url: "ws://localhost:8765"
# 断线后多久重连（秒）
reconnect-interval: 5
# 多久没收到数据就判定断线（秒）。心跳由服务端发起，客户端自动回 Pong
connection-timeout: 60- 重启服务器（或重载本插件）
第三步：Bngeuit 侧配套脚本
通道通了只代表数据能跑通，QQ 群里的效果要靠 Bngeuit 侧的脚本。官方配套了三个脚本，全部放在 Bngeuit 的 plugins/ 目录（不是 MC 服务器的 plugins/）：
| 脚本 | 作用 | 对应文档 |
|---|---|---|
McJoinAndQuit.nc | 玩家上下线转发到 QQ 群 | 示例一 |
McCommandRelay.nc | 群内 /mccmd 远程执行服务器命令 | 示例二 |
McBridgeStatus.nc | 应答 /bngeuitbridge status 的状态查询 | 示例三 |
三个脚本都声明了 pluginDepend = listOf("BngeuitBridge")，所以 BngeuitBridge 必须先装好。丢进 plugins/ 后重启 Bngeuit（或 plugin load 脚本名），控制台会打印各自的 已启用 日志。
不装 McBridgeStatus.nc，/bngeuitbridge status 就用不了
/bngeuitbridge status 做的事只是发一条 bridge/status 请求然后等回执。BngeuitBridge 本身不会应答，必须由 McBridgeStatus.nc 收到请求后 reply 回去。
缺这个脚本时，游戏里执行命令会先提示「正在查询 BngeuitBridge 状态...」，卡满 30 秒后报 查询失败: 请求超时。这只说明没人应答，不代表通道断了 —— 玩家上下线、群内命令照常工作。
装好之后 /bngeuitbridge status 的返回：
[MC-BngeuitBridge] BngeuitBridge 状态:
{version=1.0.1, uptimeSeconds=3612, connectedClients=2, clientIds=[survival, creative]}| 字段 | 含义 |
|---|---|
version | BngeuitBridge 插件版本 |
uptimeSeconds | BngeuitBridge 已运行秒数 |
connectedClients | 当前在线的 MC 服务器数量 |
clientIds | 具体是哪几台（client-id 列表） |
只认 .nc
这些脚本是 nc 脚本（nacre 引擎），文件后缀必须是 .nc。早期的 .js 脚本支持已经从 Bngeuit 移除，放了也不会被加载。
配置项速查
MC-BngeuitBridge
| 配置项 | 默认值 | 说明 |
|---|---|---|
create script example | true | 启动时是否释放 script/JoinAndQuit.nc、script/CommandRelay.nc。注意这个键名带空格 |
token | 空 | 与服务端一致，为空插件会直接卸载并报错 |
websocket.client-id | 空 | 本服标识，为空插件会直接卸载并报错 |
websocket.url | ws://localhost:8765 | 服务端地址，支持 ws:// 与 wss:// |
websocket.reconnect-interval | 5 | 断线重连间隔，最小 1 秒 |
websocket.connection-timeout | 60 | 连接空闲超时，0 表示不检测 |
BngeuitBridge
| 配置项 | 默认值 | 说明 |
|---|---|---|
token | 空 | 共享密钥，为空插件不启动 |
websocket.enabled | true | 关闭后不监听任何端口 |
websocket.host | 0.0.0.0 | 监听网卡，跨机必须 0.0.0.0 或具体内网 IP |
websocket.port | 8765 | 监听端口 |
websocket.heartbeat-interval | 30 | Ping 间隔，0 关闭 |
websocket.max-message-size | 65536 | 单条消息上限（字节），发大消息时是这个先顶住 |
联调：怎么确认真的通了
MC 控制台按顺序应该出现这三行：
[MC-BngeuitBridge] [WS] 已连接到 BngeuitBridge: ws://localhost:8765
[MC-BngeuitBridge] [WS] 已通过 BngeuitBridge 认证, clientId=survival同时 Bngeuit 控制台出现：
[BridgeChannel] 客户端认证成功: /127.0.0.1:xxxxx → survival看到 认证成功 就通了。这时候进一次服务器，QQ 群里应该能收到上下线消息（前提是 Bngeuit 侧也配好了脚本，见 内置示例）。
游戏内用 /bngeuitbridge status 可以查当前状态，/bngeuitbridge r 重载脚本（OP 默认可用）。
status 需要 Bngeuit 侧装了 McBridgeStatus.nc
这个命令靠对面应答，应答脚本就是 第三步 里的 McBridgeStatus.nc。没装就会超时（30 秒后提示「查询失败: 请求超时」），但通道本身没问题 —— 不要拿它当连通性测试，连通性看上面那行 已通过 BngeuitBridge 认证 就够了。
多台 MC 服务器共用一个 Bridge
这一节改的全是 MC 侧配置，Bngeuit 侧不需要动任何东西。 一个 BngeuitBridge 天然支持多个客户端同时连接，连上来就注册，不用事先登记。
MC 侧：每台填不同的 client-id
每台服务器的 plugins/MC-BngeuitBridge/config.yml 里，token 和 url 完全一样，只有 websocket.client-id 不同：
| MC 服务器 | websocket.client-id | websocket.url |
|---|---|---|
| 生存服 | survival | ws://Bngeuit的IP:8765 |
| 创造服 | creative | 同上 |
| 大厅 | lobby | 同上 |
Bngeuit 侧：不用配置，只在脚本里区分
Bngeuit 侧没有「服务器列表」要维护，也不用为每台服务器加配置。clientId 是在脚本里用的：
- 收消息时：
e.getClientId()就是来源服务器，多服时可以据此加前缀、分流、过滤 - 发消息时：
channel.send("survival", ...)只发给某一台；channel.broadcast(...)发给全部；channel.getConnectedClients()看当前在线的是哪几台
// 只回给发起查询的那台（这就是 bridge/status 的做法）
channel.send(e.getClientId(), msg.reply(status))
// 只推给生存服
channel.send("survival", "mc_notice", "broadcast", payload)
// 推给所有服务器
channel.broadcast("mc_notice", "broadcast", payload)若两台服务器用了同一个 client-id，后连上的会被踢掉，MC 控制台报：
[WS] clientId "survival" 已被占用，请修改 config.yml改完配置怎么生效
MC 侧（plugins/MC-BngeuitBridge/）
| 改了什么 | 怎么生效 | 说明 |
|---|---|---|
config.yml 的 token / client-id / url / 重连参数 | 重载插件或重启服务器 | /bngeuitbridge r 只重载脚本，不会重连通道 |
script/ 下的 .nc 脚本内容 | /bngeuitbridge r | 秒生效，不用重启 |
| 新增 / 删除脚本文件 | /bngeuitbridge r | 会重新扫描整个 script/ 目录（含子目录） |
Bngeuit 侧（plugins/BngeuitBridge/ 与 plugins/）
| 改了什么 | 怎么生效 | 说明 |
|---|---|---|
BngeuitBridge/config.yml（token / port / host / 心跳） | plugin reload BngeuitBridge 或重启 Bngeuit | 改了 port 记得同步 MC 侧 url |
桥接脚本（McJoinAndQuit.nc、McCommandRelay.nc、McBridgeStatus.nc） | plugin reload 脚本名 或重启 Bngeuit | 脚本名就是文件里的 pluginName |
认证失败后不会自己重连
token 填错、client-id 被占用这类认证层错误，客户端会主动断开且不会自动重连（避免拿错钥匙反复敲门把日志刷爆）。改完配置记得重载插件。 网络层断线（对方重启、网络抖动）才会按 reconnect-interval 自动重连。