InvSYNC

插件

· 作者 LucasTHCR

通过 MySQL 实现跨服务器玩家数据同步。物品栏、末影箱、统计数据和效果跟随玩家转移,以所有权交接替代延迟等待,确保无重复、无丢失。

0 本站下载 0 关注 更新于 4 周前

最新 1.2.1-RELEASE · 26.3 · Bukkit / Folia

一键开服(送7天)
InvSYNC

Built with Java 21 Available for Paper Available for Folia Available for Bukkit

Chat with us on Discord Available on Codeberg

InvSYNC

基于 MySQL 实现跨服务器玩家数据同步,适用于 Paper 和 Folia 1.21+。

作者:LucasTHCR -


功能介绍

通过一个 MySQL 数据库,在任意数量的服务器之间共享玩家的物品栏、护甲、副手、末影箱、经验值、生命值、饥饿度、药水效果以及状态值(吸收、耗竭、空气量、燃烧、坠落距离)。每个部分都可以单独关闭。

自定义模组物品通过服务器自身的物品格式进行存储,因此完整的 NBT 和组件数据得以保留。无需 ProtocolLib,无额外依赖。

独特之处

大多数物品同步插件采用“退出时写入,加入时读取”并在两者之间设置固定延迟的方式。当计时不匹配时,会导致物品重复或会话丢失。InvSYNC 不依赖计时机制。

基于所有权而非延迟。 玩家的记录行同一时间只能由一个服务器占用。当玩家离开时,该服务器写入其数据并将该行释放。下一个服务器等待的是数据交接,而不是定时器。两个服务器绝不可能同时持有同一个玩家的数据。

所有操作均在玩家进入世界之前发生。 区块的声明、读取和解码均在登录前阶段运行。如果失败,会导致登录被拒绝,而不是部分应用物品栏数据。

失败永远不会导致数据丢失。

情况 发生的事
另一台服务器仍拥有该数据 登录被拒绝,请稍后重试
存储的数据无法解码 登录被拒绝,存储数据保持不变,副本保留以供检查
数据由更新版本的 Minecraft 写入 拒绝。物品数据可以升级,但绝不可降级
登录时数据库不可达 登录被拒绝,因为让一个没有数据的玩家进入意味着之后要保存这份“空无”
保存时数据库不可达 写入操作暂存于磁盘并重试;所有权仍由当前服务器持有,防止其他服务器提供过时的版本
无法读取背包内容 保留上一版本的数据,并将所有权交还

| 服务器在持有行时崩溃 | 下次启动时自动释放 |

“空”不等于“缺失”。 同步但空的物品栏会被应用,已关闭的部分则保持不变。若将两者混为一谈,会导致物品重复:玩家在某个服务器上清空自己的物品栏后,在下一个服务器中又会重新获得这些物品。

快照。 每次保存都会保留一份可恢复的副本。使用 /invsync snapshots <玩家> 列出它们,使用 /invsync restore <玩家> <ID> 回滚到其中一个。

安装

  1. 创建一个空的 MySQL 数据库。InvSYNC 会自动创建所需的表。
  2. 将 .jar 文件放入每个需要共享数据的服务器上的 plugins/ 目录中。
  3. 首次启动以生成 config.yml,然后停止服务器。
  4. 填写数据库配置部分。
  5. 为每台服务器分配一个独立的 server-id。留空则会自动从主机名和端口派生 ID,只要没有两台服务器的 ID 冲突即可。
  6. 启动服务器。

所有服务器必须运行相同版本的 Minecraft,或者至少不能低于上次写入数据时所使用的版本。

命令

指令 用途
/invsync status 连接状态、所有权信息、已暂存的存档
/invsync save <玩家> 立即写入其数据
/invsync unlock <玩家> 释放卡在无法返回的服务器上的数据
/invsync snapshots <玩家> 列出可恢复的备份副本
/invsync restore <玩家> <ID> 回滚到某个备份副本
/invsync reload 重新读取 config.yml 配置文件

权限:invsync.admin 涵盖所有权限,也可以单独授予 invsync.admin.<子命令>。

invsync.sync(默认 true)将玩家标记为已同步,而 invsync.bypass 则完全排除他们。

配置说明

database.* 和 server-id 仅在启动时读取。其余配置由 /invsync reload 命令重新加载。

ownership.on-timeout 用于决定当上一个服务器未能在规定时间内交还数据时发生的情况。deny(拒绝)会拒绝登录且不会丢失任何内容。takeover(接管)则会强行加载数据,但可能导致物品重复。默认值为 deny。

auto-save(自动保存)仅防止崩溃时的数据丢失。正常退出游戏时总是会进行保存。

构建

mvn clean package

生成 target/InvSYNC-<version>.jar。MySQL Connector 和 HikariCP 已被阴影处理(shaded)并重新定位,因此该 jar 包没有外部依赖项。

测试

mvn test

所有权测试会启动一个真实的 MariaDB 实例,因为锁定机制依赖于 MySQL 的行为特性,而兼容性层无法复现这些行为:INSERT IGNORE、受影响行数以及 InnoDB 行锁。该服务器二进制文件是一个 149 MB 的测试制品;使用 mvn package -DskipTests 可完全跳过它。

覆盖范围包括:

  • 8 个服务器争夺同一个玩家的所有权,共发生 1000 次竞态条件,每次仅有一个获胜者。
  • 500 次连续服务器切换,未丢失或分叉任何修订版本。
  • 过期的接管、崩溃恢复的作用域、所有权转移后拒绝写入、快照修剪、跳过已声明行的维护操作。
  • 2000 次随机化快照往返测试,以及在当前版本下正确解码格式 1 和格式 2 的有效载荷。
  • 截断的、来自外部的以及较新版本格式的有效载荷会引发错误,而不是产生看似合理的数据。
  • 1000 次随机化经济结算运行,针对一个加载较晚且会进行覆盖的假经济插件,断言没有任何一次运行在余额错误的情况下报告成功。

未覆盖范围:任何需要运行中的 Paper 服务器的内容,包括物品序列化本身以及真实的 Vault 路径。

值得注意的限制

  • 末影箱大小假设为原版 27 格。调整其大小的插件未被考虑在内。
  • 经济余额可以通过 Vault 同步,但该功能默认关闭,需要额外的开关才能启用。如果玩家在离线期间余额发生变化,下次登录时将被覆盖,本插件内部的设计无法防止这种情况。将经济插件指向共享数据库是更好的解决方案。请参阅 docs/vault-economy-plan.md。
  • 家园、领地声明以及其他插件数据不同步。

指标

InvSYNC 向 bStats 报告匿名使用数据:服务器软件和版本、Java 版本、玩家数量,以及若干 InvSYNC 设置(超时行为、哪些部分被同步、快照数量、经济同步是否开启、当前有多少存档暂存在磁盘上)。不包含玩家名称、UUID、库存数据或数据库凭据。

可通过 plugins/bStats/config.yml 一次性禁用所有插件的数据上报。

许可证

GNU General Public License v3.0。详见 LICENSE。

你是这个资源的作者?登录后可认领此资源。

评论 0

0.0
暂无评分
5 星
0
4 星
0
3 星
0
2 星
0
1 星
0
我的评分

登录后参与评分

还没有评论,来抢沙发吧

评论配图

相似资源