InvSYNC
基于 MySQL 实现跨服务器玩家数据同步,适用于 Paper 和 Folia 1.21+。
作者:LucasTHCR -
功能介绍
通过一个 MySQL 数据库,在任意数量的服务器之间共享玩家的物品栏、护甲、副手、末影箱、经验值、生命值、饥饿度、药水效果以及状态值(吸收、耗竭、空气量、燃烧、坠落距离)。每个部分都可以单独关闭。
自定义模组物品通过服务器自身的物品格式进行存储,因此完整的 NBT 和组件数据得以保留。无需 ProtocolLib,无额外依赖。
独特之处
大多数物品同步插件采用“退出时写入,加入时读取”并在两者之间设置固定延迟的方式。当计时不匹配时,会导致物品重复或会话丢失。InvSYNC 不依赖计时机制。
基于所有权而非延迟。 玩家的记录行同一时间只能由一个服务器占用。当玩家离开时,该服务器写入其数据并将该行释放。下一个服务器等待的是数据交接,而不是定时器。两个服务器绝不可能同时持有同一个玩家的数据。
所有操作均在玩家进入世界之前发生。 区块的声明、读取和解码均在登录前阶段运行。如果失败,会导致登录被拒绝,而不是部分应用物品栏数据。
失败永远不会导致数据丢失。
| 情况 |
发生的事 |
| 另一台服务器仍拥有该数据 |
登录被拒绝,请稍后重试 |
| 存储的数据无法解码 |
登录被拒绝,存储数据保持不变,副本保留以供检查 |
| 数据由更新版本的 Minecraft 写入 |
拒绝。物品数据可以升级,但绝不可降级 |
| 登录时数据库不可达 |
登录被拒绝,因为让一个没有数据的玩家进入意味着之后要保存这份“空无” |
| 保存时数据库不可达 |
写入操作暂存于磁盘并重试;所有权仍由当前服务器持有,防止其他服务器提供过时的版本 |
| 无法读取背包内容 |
保留上一版本的数据,并将所有权交还 |
| 服务器在持有行时崩溃 | 下次启动时自动释放 |
“空”不等于“缺失”。 同步但空的物品栏会被应用,已关闭的部分则保持不变。若将两者混为一谈,会导致物品重复:玩家在某个服务器上清空自己的物品栏后,在下一个服务器中又会重新获得这些物品。
快照。 每次保存都会保留一份可恢复的副本。使用 /invsync snapshots <玩家> 列出它们,使用 /invsync restore <玩家> <ID> 回滚到其中一个。
安装
- 创建一个空的 MySQL 数据库。InvSYNC 会自动创建所需的表。
- 将
.jar 文件放入每个需要共享数据的服务器上的 plugins/ 目录中。
- 首次启动以生成
config.yml,然后停止服务器。
- 填写数据库配置部分。
- 为每台服务器分配一个独立的
server-id。留空则会自动从主机名和端口派生 ID,只要没有两台服务器的 ID 冲突即可。
- 启动服务器。
所有服务器必须运行相同版本的 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。
InvSYNC
Cross-server player data synchronisation over MySQL, for Paper and Folia 1.21+.
Author: LucasTHCR -
What it does
Shares inventory, armour, offhand, ender chest, XP, health, hunger, potion
effects and status values (absorption, exhaustion, air, burning, fall distance)
between any number of servers through one MySQL database. Every part can be
switched off individually.
Custom and modded items are stored through the server's own item format, so full
NBT and component data survives. No ProtocolLib, no extra dependency.
What makes it different
Most inventory sync plugins write on quit, read on join and put a fixed delay in
between. When the timing does not hold, items duplicate or a session is lost.
InvSYNC does not rely on timing.
Ownership instead of a delay. A player's row is claimed by exactly one server
at a time. When the player leaves, that server writes their data and hands the row
back. The next server waits for the handover, not for a timer. Two servers can
never hold the same player at once.
Everything happens before the player enters the world. Claiming, reading and
decoding run in the pre-login phase. A failure ends as a login refusal rather
than a half applied inventory.
Failures never destroy data.
| Situation |
What happens |
| Another server still owns the data |
Login refused, retry in a moment |
| Stored data cannot be decoded |
Login refused, stored data untouched, copy kept for inspection |
| Data written by a newer Minecraft version |
Refused. Item data can be upgraded, never downgraded |
| Database unreachable at login |
Login refused, because letting a player in without their data means saving that emptiness later |
| Database unreachable at save |
Write parked on disk and retried; ownership stays held so no other server serves the outdated revision |
| Inventory cannot be read |
Previous revision stays, ownership handed back |
| Server crashed while holding rows |
Released automatically on next start |
Empty is not the same as missing. A synchronised but empty inventory is
applied, a section that is switched off is left alone. Collapsing the two
duplicates items: a player who empties their inventory on one server gets the
contents back on the next one.
Snapshots. Every save keeps a restorable copy. /invsync snapshots <player>
lists them, /invsync restore <player> <id> rolls one back.
Install
- Create an empty MySQL database. InvSYNC creates the tables itself.
- Drop the jar into
plugins/ on every server that should share data.
- Start once to generate
config.yml, then stop.
- Fill in the database section.
- Give every server its own
server-id. Leave it empty to derive one from the
hostname and port, which is fine as long as no two servers collide.
- Start.
All servers must run the same Minecraft version, or at least never an older one
than the version that last wrote the data.
Commands
| Command |
Purpose |
/invsync status |
Connection, ownership, parked saves |
/invsync save <player> |
Write their data now |
/invsync unlock <player> |
Release data stuck on a server that will not come back |
/invsync snapshots <player> |
List restorable copies |
/invsync restore <player> <id> |
Roll back to a copy |
/invsync reload |
Re-read config.yml |
Permissions: invsync.admin covers all of them, or grant
invsync.admin.<subcommand> individually.
invsync.sync (default true) marks a player as synchronised, invsync.bypass
excludes them entirely.
Configuration notes
database.* and server-id are only read on startup. Everything else is picked
up by /invsync reload.
ownership.on-timeout decides what happens when the previous server does not hand
the data back in time. deny refuses the login and loses nothing. takeover
loads the data anyway and can duplicate items. The default is deny.
auto-save only protects against crashes. A normal quit always saves.
Building
mvn clean package
Produces target/InvSYNC-<version>.jar. MySQL Connector and HikariCP are shaded
and relocated, so the jar has no external dependencies.
Tests
mvn test
The ownership tests start a real MariaDB for the run, because the locking depends
on MySQL behaviour that a compatibility layer does not reproduce: INSERT IGNORE,
affected row counts and InnoDB row locking. That server binary is a 149 MB test
artifact; mvn package -DskipTests avoids it entirely.
What is covered:
- 1000 races between 8 servers claiming the same player, exactly one winner each.
- 500 consecutive server switches without losing or forking a revision.
- Stale takeover, crash recovery scoping, refused writes after ownership moved,
snapshot pruning, maintenance skipping claimed rows.
- 2000 randomised snapshot round trips, plus format 1 and format 2 payloads
decoding correctly under the current version.
- Truncated, foreign and newer-format payloads raising an error rather than
producing plausible looking data.
- 1000 randomised economy settle runs against a fake economy plugin that loads
late and overwrites, asserting no run ever reports success with a wrong balance.
Not covered: anything that needs a running Paper server, which includes item
serialisation itself and the real Vault path.
Limits worth knowing
- Ender chest size is assumed to be the vanilla 27 slots. Plugins that resize it
are not accounted for.
- Economy balances can be synchronised through Vault, but the feature is off by
default and needs a second switch to enable. A balance changed while the player
is offline is overwritten on their next login, and no design inside this plugin
can prevent that. Pointing the economy plugin at a shared database is the better
answer. See
docs/vault-economy-plan.md.
- Homes, claims and other plugin data are not synchronised.
Metrics
InvSYNC reports anonymous usage data to bStats:
server software and version, Java version, player count, and a handful of InvSYNC settings
(timeout behaviour, which sections are synchronised, snapshot count, whether economy sync is
on, and how many saves are currently parked on disk). No player names, no UUIDs, no inventory
data, no database credentials.
Opt out for every plugin at once in plugins/bStats/config.yml.
License
GNU General Public License v3.0. See LICENSE.
评论 0
登录后参与评分
还没有评论,来抢沙发吧