InvSync 跨服数据同步插件

支持版本：Minecraft 1.12.2 – 26.1.x

InvSync 是一款基于 Redis + MySQL/MongoDB 的高效跨服同步插件，让多个子服之间无缝同步玩家背包、物品、经验、状态等数据，兼顾数据安全与实时性。

• 配置简单，开箱即用
• 支持从主流同类插件平滑迁移，无需担心玩家数据丢失
• 在线玩家可用 CMI 等插件直接编辑背包；离线玩家可用 InvSync 内置编辑功能修改背包与末影箱
• 提供完整 开发者 API，可安全地自行扩展同步任意字段

---

🚀 跨服预加载（Preload）—— 增值功能

售价 68 RMB（独立购买，需先拥有 InvSync 主插件）

⚠️ 重要前提

预加载模块仅支持运行在 Java 17 及以上版本的服务端。低于 Java 17 的服务端无法使用本功能，但不影响 InvSync 主插件本身的运行（主插件最低支持 Java 8）。

这是什么

普通跨服切换的延迟来自两段串行等待：

1. 玩家切到目标子服后，目标服才开始读 Redis / MySQL 拿玩家数据（远端数据库延迟 200ms+）
2. 主线程反序列化背包 / 末影箱、批量 setItem 应用（10–30ms）

预加载利用 Velocity / BungeeCord 比子服早 500ms~2s 知道玩家要去哪台子服的窗口，提前完成：

• 源服立即冻结 + 同步保存 + 释放锁（省掉"等玩家真断开"的串行等待）
• 目标服抢锁 + 拉取完整 PlayerData 到内存（省掉跨服切换瞬间的数据库往返）
• vanilla 顶层字段直接离线写入 playerdata/<uuid>.dat（背包、末影箱、血量、饥饿、经验等由 NMS 自动加载，主线程零反序列化开销）

玩家进入目标子服时，数据已就位，主线程几乎只剩"应用扩展字段"的开销。

实际效果

跨服切换从 数据库延迟 + 主线程应用 ≈ 250ms~500ms 缩短至 几乎无感知。

支持代理端

WebSocket 通信，无需依赖 Redis 远端往返。

安全兜底

• WS 断连 → 自动退化为原 trySync 流程，无功能损失
• 离线写失败 / 玩家提前上线 → 任务被 cancel，走原同步路径
• 切服失败 / 玩家断网 → 5 秒超时自动解冻

详细部署文档参见 https://bai.xbaimiao.com/dashboard/doc_view?name=invsyncfast

---

📦 支持同步的数据

原版数据

通过 API 可安全地自行同步任意自定义字段。

Mod 数据

Mod 部分代码借鉴聪聪的 PlayerDataSQL

• 像素宝可梦 (Pixelmon) 世代 (1.12.2) — 默认关闭
• 像素宝可梦 (Pixelmon) 重铸 (1.12.2) — 默认关闭
• 时装工坊 (Armourer’s Workshop) (1.12.2) — 默认关闭
• FTB Quests (1.12.2) — 默认关闭
• 精妙背包 — 需额外购买扩展（扩展非本人开发）
• 1.16.5 宝可梦 — 需额外购买扩展（扩展非本人开发）

其他插件数据

• LibsDisguises
• CMI Fly Charge（CMI 飞行能量）
• Vault 经济系统 — 默认关闭

  ⚠️ 仅同步在线玩家进出服务器时的金币数据。玩家离线期间通过其他插件（如 GUI 商店、奖励指令等）对其账户产生的金币变动不会跨服同步，玩家下次上线时会以源服记录的金币数为准覆盖此变动。

---

🔌 插件 API

完整开发者文档：https://halo.xbaimiao.com/archives/invsynckai-fa-zhe-wen-dang

---

InvSync 指令使用文档

迁移器可选值

在线玩家参数

<在线玩家> 支持在线玩家名，也支持 @a、@p、@s、@r。

---

📊 bStats

仅统计 2.0.0+ 版本数据，仅供参考。

---

🔄 数据迁移

InvSync 支持从主流同类插件一键迁移，全程保留原数据。

通用流程

1. 保留源插件的配置和数据库，先不要卸载源插件
2. 关闭所有子服，选择其中一个安装好 InvSync，确保 MySQL / Redis 链接正常
3. 执行对应的迁移命令，等待完成
4. 关服，卸载源插件

支持的源插件

---

❓ 常见问题

MySQL 怎么都连不上？

MySQL 5.7+ 某些安装方式会在启动时默认加上 -SSL。在确认账号 / 密码 / 端口 / 数据库无误后：

关服 → 修改 InvSync 配置文件 → 把 ssl: false 改为 ssl: true → 重启

---

🏷️ PAPI 变量

---

🚫 配置物品不同步

配置文件中有两个字段用于过滤"不希望玩家带到别的服"的物品：

• skip-items — 按物品名匹配（忽略颜色符号，完全匹配）
• skip-items-lore — 按 lore 子串匹配（保留颜色符号）

---

📄 内置文件

配置文件（config.yml）

# 调试模式（开启此选项后台日志会变多）  
debug: false  
# 是否 hook plan插件  
hook-plan: false  
redis:  
 host: localhost port: 6379 # redis 数据库编号，可选 0-15 database: 0 # 在线玩家续锁周期，单位 tick，默认 15 秒  
 # 60 秒锁过期时间下，建议保持在 100-400 tick 之间  
 lockRefreshIntervalTicks: 300 #  password: "" #  prefix: "server"# 玩家冻结系统  
# def 使用Bukkit拦截事件(默认)  
# pe 使用PacketEvents拦截数据包  
# plib 使用ProtocolLib拦截数据包  
freeze: 'def'  
# 自动保存  
auto-save:  
 # 是否启用  
 enable: false # 保存的时间 这里单位是tick   1秒=20tick  
 time: 6000# 玩家数据序列化方式 可选 gson 和 kryo# 默认最开始是GSON，自2.3.77起增加了Kryo  
# 如果之前用的是Gson 要改用kryo的话 需要全服都改成kryo并清空redis的invsync数据才能使用  
data-serializer: 'kryo'  
# 是否在世界保存的时候保存玩家数据  
world-save-player-data: true  
# 存储类型: mysql 或 mongodbstorage: 'mysql'  
mysql:  
 host: 'localhost' port: 3306 database: 'database' user: 'user' passwd: 'passwd' ssl: falsemongodb:  
 host: 'localhost' port: 27017 database: 'database' #  authenticationDatabase: 'admin' #  user: 'user' #  passwd: 'passwd'mobs:  
 # 是否同步宝可梦数据  
 pixelmon: false # 是否同步时装工坊数据  
 armourersWorkshop: false # 是否同步 ftbQuests ftbQuests: false # 是否同步神秘时代  
 thaumcraft: falseoptions:  
 # 是否使用主线程同步成就  
 advancement-main-thread: falsesync:  
 # 关闭所有同步项，仅用于玩家数据备份  
 disableAll: false # 是否同步统计数据  
 statistics: true # 是否同步经验等级  
 exp: true # 是否同步末影箱  
 ender: true # 是否同步血量  
 health: true # 是否同步饥饿值  
 food: true # 是否同步背包  
 inventory: true # 是否同步成就数据  
 advancement: true # 是否同步药水效果  
 buff: true # 是否同步游戏模式  
 gameMode: false # 是否同步最大血量  
 maxHealth: false # 是否同步PersistentDataContainer数据  
 persistentDataContainer: false # 是否同步OP  
 op: false # 是否同步CMI飞行能量  
 cmiFlyCharge: true # 如果数据库没有飞行能量数据是否从这个服务器读取  
 initFlyCharge: true # 是否同步vault经济  
 vault: false # 如果数据库没有vault数据是否从这个服务器读取  
 initVault: true # 是否同步服务器中的位置  
 location: false # 玩家退出时延迟多少tick再保存数据  
 # 用于兼容在退出前最后一刻才回写物品状态的插件（如部分收纳袋/背包插件）  
 disconnectSaveDelay: 1 # 玩家退出保存监听优先级  
 # 可选: LOWEST, LOW, NORMAL, HIGH, HIGHEST, MONITOR  
 # 建议默认 MONITOR，让其他插件先完成同tick的物品状态刷新  
 quitSavePriority: 'MONITOR' # 玩家进服时按字段比对 PDC 指纹与数据库指纹，命中的字段跳过对应的 write 分支  
 # 同服重连场景下绝大多数字段都能命中，跨服切换时未变的字段也能命中  
 # 遇到玩家进服后状态不正确等问题可关闭回退到全量写入  
 skipWriteWhenFieldMatch: true# 同步时跳过的物品名称 名称会忽略颜色符号完全匹配  
skip-items:  
 - '不同步物品名1'  
 - '不同步物品名2'  
# 同步时跳过的物品lore 有这个lore就会跳过 会检测颜色符号  
skip-items-lore:  
 - '不同步的lore'  
# 物品反序列化失败时的处理策略（例如物品包含服务器不存在的附魔）  
# remove - 移除无效附魔，保留物品其余数据  
# skip - 跳过整个物品，该槽位变为空  
# deny - 直接报错，阻止玩家进入服务器（默认行为）  
invalid-item-policy: 'deny'  
# PlayerDataSQL 迁移程序 执行迁移命令后还需一直开着这个选项 增加这个开关是因为并不是所有人都有pds  
migrator-pds: false  
# DragonArmourers 刷新延迟时间  
dragon-armourers-delay: 80  
# 玩家数据备份  
backup:  
 # 是否启用备份功能  
 enabled: false # 玩家退出时自动备份  
 on-disconnect: true # 自动保存时自动备份  
 on-auto-save: false # 世界保存时自动备份  
 on-world-save: false # 跳过空数据备份（背包和末影箱都为空时不备份，防止空数据覆盖有效备份）  
 skip-empty: true # 备份保留策略（多层保留，防止数据丢失后空备份覆盖所有有效备份）  
 retention: # 最近保留的备份数量  
 latest: 10 # 每天保留一个备份，保留最近多少天  
 daily: 7 # 每周保留一个备份，保留最近多少周  
 weekly: 4 # 每月保留一个备份，保留最近多少个月  
 monthly: 3  

语言文件（lang.yml）

inventory:  
 lock: '&7[&e&l!&7] &c你的背包已被锁定'  
 error: '&7[&e&l!&7] &c数据同步出错,请联系管理处理'  
 timeout-new: '&7[&e&l!&7] §c加载数据超时,请等待15秒后进入服务器'  
 sync-busy: '&7[&e&l!&7] &c数据同步中,请稍后再进入服务器'  
 not-exist: '&7[&e&l!&7] §c玩家数据不存在'  
 # 填空不会触发  
 load-start: '&7[&e&l!&7] &c正在加载数据'  
 load-done: '&7[&e&l!&7] &c同步已完成 主线程耗时 {0} 异步耗时 {1}' edit: success: '&7[&e&l!&7] &a编辑已生效'  
 title: inventory: '&7编辑玩家 &a{0} &7背包数据'  
 ender: '&7编辑玩家 &a{0} &7末影箱数据'  
command:  
 reload-lang: '&7[&e&l!&7] &7语言文件已重载'  
 save: '&7[&e&l!&7] &7玩家 &a{0} &7的数据已保存'  
 save-busy: '&7[&e&l!&7] &c玩家 &e{0} &c正在同步数据, 已跳过保存'  
 freeze: '&7[&e&l!&7] &7玩家 &a{0} &7被冻结的状态为{1}'  
 unlockAll: '&7[&e&l!&7] &a成功解锁所有玩家数据'  
 lock: '&7[&e&l!&7] §a锁定状态: {0}'  
 edit-online: '&7[&e&l!&7] §c玩家在线,请使用CMI编辑或其他插件'  
 edit-lock: '&7[&e&l!&7] §c数据已被锁定(玩家可能在线),请使用CMI编辑或其他插件'  
 restoresMaxHealth: start: '&7[&e&l!&7] §a开始恢复所有玩家最大血量,此过程可能有点漫长,请不要关服'  
 end: '&7[&e&l!&7] §a成功恢复玩家最大血量'  
 backup: created: '&7[&e&l!&7] &a已为玩家 &e{0} &a创建备份'  
 empty: '&7[&e&l!&7] &c该玩家没有备份数据'  
 restore-success: '&7[&e&l!&7] &a已成功恢复玩家 &e{0} &a的备份数据'  
 restore-fail: '&7[&e&l!&7] &c恢复备份失败'  
 not-found: '&7[&e&l!&7] &c未找到指定的备份'  
 disabled: '&7[&e&l!&7] &c备份功能未启用'  
  

预加载功能 （preload.yml)

# InvSync 跨服预加载子系统配置  
#  
# 该子系统让 Velocity / Bungee 在玩家切服前通知本服提前抢锁 + 预读 + 离线写入 vanilla 字段到  
# playerdata/<uuid>.dat。玩家进服 trySync 直接跳过抢锁循环 + skip 已写入字段的 write 分支。  
#  
# 任何环节失败都会自动回退到原 trySync 流程，无功能损失。  
  
# 是否启用整个预加载子系统（关闭后所有相关组件不会启动 / 不会触发）  
enabled: false  
  
ws:  
 # 本服在 Velocity 那边注册时使用的子服名  
 # 空串时启动时自动用服务端根目录名填充（仅生效在当前进程内存里）  
 # 想要固定可直接在这里写死，必须和 Velocity 的 allowed-servers 列表中某项严格一致  
 server-name: '' # Velocity WS 服务端地址，一般是内网地址 + Velocity 配置的端口  
 url: 'ws://localhost:8765/invsync' # 注册鉴权密钥，必须和 Velocity 端 config.toml 的 secret 一致  
 secret: 'change-me'  
# 玩家数据目录（含 <uuid>.dat 的目录）  
# 留空时自动取第一个 isAutoSave 世界的 worldFolder/playerdata，大多数情况够用  
# 如果服务器所有世界都关闭了 autoSave，或者用了非标布局，请在这里显式配置：  
# 绝对路径：/home/mc/server/world/playerdata  
# 相对路径：world/playerdata （相对服务器根目录）  
player-data-folder: ''  

---

💰 购买

购买联系 QQ：3104026189

无任何验证系统，售后网站可随时下载最新版插件。