
NATS 玩家数据桥接
使用NATS在Minecraft服务器之间同步玩家数据。
NATS 玩家数据桥接
本项目处于早期阶段,正在积极开发中。 请在 GitHub 上报告任何问题,或加入 Discord 社区。 任何反馈都很有价值,非常感谢!
一个服务端 Fabric 模组,使用 NATS JetStream 在多个 Minecraft 服务器之间同步玩家物品栏、末影箱、生命值、经验值、统计数据和进度。
当玩家离开时,其数据会保存到 NATS Key-Value 存储桶中。当他们加入同一集群中的另一台服务器时,会在其生成前获取并应用该数据。
要求
- 启用了 JetStream 的 NATS 服务器。
- Fabric API。
安装
- 将模组 jar 放入你的
mods/文件夹。 - 启动一次服务器以生成两个配置文件。
- 使用你的 NATS 服务器 URL、认证令牌和此服务器的唯一名称配置
config/nats-fabric.json。 - 重启。
设置 NATS 服务器
在设置 NATS 服务器时,创建一个名为 nats-server.conf 的新文本文件,并将以下最小配置粘贴到其中:
port: 4222
authorization {
token: "your_secret_token_here"
}
jetstream {
store_dir: "./jetstream-data"
}
然后,通过将 NATS 服务器指向你刚刚创建的配置文件来启动它:
- Linux/macOS:
./nats-server -c nats-server.conf - Windows:
nats-server.exe -c nats-server.conf
确保 config/nats-fabric.json 中的认证令牌与此处设置的一致。
Velocity 代理支持
如果你运行 Velocity,请在 config/nats-player-data-bridge.json 中设置 "proxyMode": true。否则,重叠登录会被直接拒绝,这将破坏服务器切换。
如果你还使用 FabricProxy-Lite,则必须在 FabricProxy-Lite.toml 中设置 hackEarlySend = true,模组才能正常工作。
配置(config/nats-player-data-bridge.json)
| 键 | 默认值 | 描述 |
|---|---|---|
proxyMode |
false |
为 Velocity 代理设置启用 RPC 锁交接。 |
rpcTimeoutSeconds |
15 |
跨服务器 RPC 请求的超时时间(秒)(例如在代理转移期间)。 |
syncStats |
true |
同步玩家统计数据。 |
syncAdvancements |
true |
同步进度。 |
filterMode |
"whitelist" |
"whitelist" 仅同步列出的 NBT 键。"blacklist" 同步除列出键之外的所有内容。 |
filterKeys |
Inventory、health、XP 等 | 根据 filterMode 包含或排除的 NBT 键。 |
backupHistoryCount |
20 |
在备份存储桶中为每位玩家保留的历史快照数量。 |
autoBackupPolicies |
[DEATH, DIMENSION_CHANGE] |
自动创建快照的触发器列表。 |
管理员命令
所有命令都需要操作员权限。
| 命令 | 描述 |
|---|---|
/nats sync [player] |
手动将玩家数据推送到集群。 |
/nats sessions list [page] |
查看集群中的 DIRTY 会话锁(分页)。 |
/nats sessions clean <player/uuid> |
按名称或 UUID 清除特定玩家的卡住会话锁。 |
/nats backup push <player> |
手动创建玩家数据的快照。 |
/nats backup list <player> |
查看快照。将鼠标悬停在条目上可查看标签(death、dim_change 等)。 |
/nats backup restore <player> <rev> |
暂存恢复操作。需要 /nats backup confirm 才能执行。 |
/nats backup confirm |
执行暂存的恢复操作。玩家将被踢出以安全应用数据。 |
数据处理
该桥接专为数据完整性和网络稳定性至关重要的环境而构建。
- 集群范围锁定: 每个玩家会话都会被分配一个唯一锁。服务器只有在持有该锁时才能写入数据。
- 故障安全(保管): 如果 NATS 不可达,玩家数据会保存到本地磁盘保管库(
nats-player-data-bridge/pending_sync/),并在连接恢复后自动同步回来。 - 自愈: 服务器在启动时执行恢复步骤,以协调孤立锁并清除任何本地保管库数据。
- 自动备份: 可配置的触发器(死亡、维度切换)会自动创建快照。
- 二进制格式: 数据打包为 CBOR 二进制格式,并使用 Zstd 压缩,以最小化网络开销。
- 就绪门控: 服务器会阻止玩家加入,直到后台同步和修复 100% 完成。
许可证
MIT
正在加载版本记录…
正在加载评论…
评论在新手盒子客户端中发表,这里同步展示。