NATS 玩家数据桥接

NATS 玩家数据桥接

使用NATS在Minecraft服务器之间同步玩家数据。

管理

NATS 玩家数据桥接

状态

本项目处于早期阶段,正在积极开发中。 请在 GitHub 上报告任何问题,或加入 Discord 社区。 任何反馈都很有价值,非常感谢!

一个服务端 Fabric 模组,使用 NATS JetStream 在多个 Minecraft 服务器之间同步玩家物品栏、末影箱、生命值、经验值、统计数据和进度。

当玩家离开时,其数据会保存到 NATS Key-Value 存储桶中。当他们加入同一集群中的另一台服务器时,会在其生成前获取并应用该数据。


要求

  • 启用了 JetStream 的 NATS 服务器。
  • Fabric API。

安装

  1. 将模组 jar 放入你的 mods/ 文件夹。
  2. 启动一次服务器以生成两个配置文件。
  3. 使用你的 NATS 服务器 URL、认证令牌和此服务器的唯一名称配置 config/nats-fabric.json。
  4. 重启。

设置 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