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）。
这是什么
普通跨服切换的延迟来自两段串行等待：
玩家切到目标子服后，目标服才开始读 Redis / MySQL 拿玩家数据（远端数据库延迟 200ms+）
主线程反序列化背包 / 末影箱、批量 setItem 应用（10–30ms）
预加载利用 Velocity / BungeeCord 比子服早 500ms~2s 知道玩家要去哪台子服的窗口，提前完成：
源服立即冻结 + 同步保存 + 释放锁（省掉"等玩家真断开"的串行等待）
目标服抢锁 + 拉取完整 PlayerData 到内存（省掉跨服切换瞬间的数据库往返）
vanilla 顶层字段直接离线写入 playerdata/
玩家进入目标子服时，数据已就位，主线程几乎只剩"应用扩展字段"的开销。
实际效果
跨服切换从 数据库延迟 + 主线程应用 ≈ 250ms~500ms 缩短至 几乎无感知。
支持代理端
代理端
状态
Velocity
✅ 支持
BungeeCord
✅ 支持
WebSocket 通信，无需依赖 Redis 远端往返。
安全兜底
WS 断连 → 自动退化为原 trySync 流程，无功能损失
离线写失败 / 玩家提前上线 → 任务被 cancel，走原同步路径
切服失败 / 玩家断网 → 5 秒超时自动解冻
详细部署文档参见 https://bai.xbaimiao.com/dashboard/doc_view?name=invsyncfast
📦 支持同步的数据
原版数据
字段
说明
默认开启状态
inventory
背包
✅
ender
末影箱
✅
exp
经验 / 等级
✅
health
血量
✅
food
饥饿值
✅
statistic
统计数据
✅
advancement
成就
✅
buff
药水效果
✅
maxHealth
最大血量
❌
persistentDataContainer
玩家 PDC 持久化数据（1.14.1+）
❌
gameMode
游戏模式
❌
op
是否为管理员
❌
location
服务器中的位置
❌
通过 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 指令使用文档
命令
作用
权限 / 备注
/invsync
查看当前可用的子命令帮助
invsync.command
/invsync reloadLang
重载语言文件 lang.yml
invsync.command
/invsync edit <玩家> INVENTORY
编辑离线玩家背包数据
invsync.command，仅玩家可执行，目标玩家必须离线且未锁定
/invsync edit <玩家> ENDER_CHEST
编辑离线玩家末影箱数据
invsync.command，仅玩家可执行，目标玩家必须离线且未锁定
/invsync backup <在线玩家>
为在线玩家手动创建备份
invsync.command、invsync.backup，仅玩家可执行，需要开启 backup.enabled
/invsync restore <玩家>
打开玩家备份恢复界面
invsync.command、invsync.restore，仅玩家可执行，需要开启 backup.enabled
/invsync migrator <迁移器> all
从其他插件迁移全部支持的数据
invsync.command，迁移前建议先备份数据库
/invsync migrator <迁移器> statistic
从其他插件只迁移统计数据
invsync.command，迁移前建议先备份数据库
/invsync compress
将 v1 旧玩家数据表批量迁移到 v2 新表
invsync.command，仅支持 MySQL 存储
/invsync compressBackup
将 v1 旧备份表批量迁移到 v2 新备份表
invsync.command，仅支持 MySQL 存储
/invsync dev save <在线玩家>
手动保存在线玩家当前数据
invsync.command、invsync.dev
/invsync dev delete <玩家>
删除玩家在 Redis 和后端存储中的同步数据
invsync.command、invsync.dev，危险操作，执行前请确认备份
/invsync dev freeze <在线玩家> true
冻结在线玩家
invsync.command、invsync.dev
/invsync dev freeze <在线玩家> false
解冻在线玩家
invsync.command、invsync.dev
/invsync dev debug
切换插件全局 debug 模式
invsync.command、invsync.dev、op
/invsync dev debug <在线玩家>
切换指定玩家的 debug 状态
invsync.command、invsync.dev、op
/invsync dev preload <玩家>
手动触发目标服侧跨服预加载流程
invsync.command、invsync.dev，主要用于测试
/invsync dev prequit <在线玩家>
手动触发源服侧 pre-quit 流程
invsync.command、invsync.dev，主要用于测试
/invsync dev testPdc
向执行者 PDC 写入随机测试值
invsync.command、invsync.dev，仅玩家可执行
/invsync dev lookPdc
查看执行者 PDC 测试值
invsync.command、invsync.dev，仅玩家可执行
迁移器可选值
迁移器
来源
HuskSync
HuskSync
NoneBase64
旧版本 InvSync
KTG4
KnapsackToGo4
MysqlPlayerDataBridge
MysqlPlayerDataBridge
PlayerDataSQL
PlayerDataSQL
MySqlPlayerBridge
MySqlPlayerBridge
PlayerSync
PlayerSync
在线玩家参数
<在线玩家> 支持在线玩家名，也支持 @a、@p、@s、@r。
📊 bStats
仅统计 2.0.0+ 版本数据，仅供参考。
🔄 数据迁移
InvSync 支持从主流同类插件一键迁移，全程保留原数据。
通用流程
保留源插件的配置和数据库，先不要卸载源插件
关闭所有子服，选择其中一个安装好 InvSync，确保 MySQL / Redis 链接正常
执行对应的迁移命令，等待完成
关服，卸载源插件
支持的源插件
源插件
命令
备注
PlayerDataSQL
/invsync migrator playerdatasql all
需在配置文件中开启 migrator-pds: true，迁移完成前保持开启
KnapsackToGo4
/invsync migrator ktg4 all
—
MysqlPlayerDataBridge
/invsync migrator mysqlplayerdatabridge all
—
MySqlPlayerBridge
/invsync migrator MySqlPlayerBridge all
保留 MySqlPlayerBridge 配置文件和数据库
HuskSync
/invsync migrator husksync all
—
PlayerSync
/invsync migrator playersync all
—
❓ 常见问题
MySQL 怎么都连不上？
MySQL 5.7+ 某些安装方式会在启动时默认加上 -SSL。在确认账号 / 密码 / 端口 / 数据库无误后：
关服 → 修改 InvSync 配置文件 → 把 ssl: false 改为 ssl: true → 重启
🏷️ PAPI 变量
变量
说明
%invsync_
获取指定子服的在线玩家数量
%invsync_totalOnline%
获取当前代理端总在线玩家数
🚫 配置物品不同步
配置文件中有两个字段用于过滤"不希望玩家带到别的服"的物品：
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/
#
# 任何环节失败都会自动回退到原 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'
# 玩家数据目录（含
# 留空时自动取第一个 isAutoSave 世界的 worldFolder/playerdata，大多数情况够用
# 如果服务器所有世界都关闭了 autoSave，或者用了非标布局，请在这里显式配置：
# 绝对路径：/home/mc/server/world/playerdata
# 相对路径：world/playerdata （相对服务器根目录）
player-data-folder: ''
💰 购买
产品
价格
说明
InvSync 主插件
128 RMB
跨服同步核心功能，无任何验证系统
跨服预加载模块（Preload）
68 RMB
增值功能，仅支持 Java 17+ 服务端，需先拥有主插件
自助购买链接 购买后会自动发货
https://bai.xbaimiao.com/
售后或购买问题联系 QQ：3104026189
无任何验证系统，售后网站可随时下载最新版插件。