🔄 数据迁移

迁移不是“任意版本一键无损”。本页依据 2.5.31 的迁移入口，实际版本与数据格式需要先在测试环境确认。

操作前

备份源数据库、配置、目标库与世界数据。关闭所有对同一玩家数据写入的节点，限制登录。all 只表示迁移器已支持的字段，不包括源插件所有数据或历史快照。

通用流程

1. 完整备份源、目标数据，保留原插件配置与 JAR。
2. 在隔离环境使用副本测试，核对 UUID 策略、存储类型和源插件版本。
3. 停止生产网络的其他写入，选择一台维护子服安装 InvSync，完成数据服务配置。
4. 部分迁移器依赖源插件实例，按下表保留安装；不要放行玩家让两套同步插件同时写档。
5. 执行对应命令，保存进度、跳过、失败日志。部分迁移器异步提交保存，输出“完成”后仍需确认存储结果，不能立即强杀。
6. 抽样核对背包、末影箱、经验与适配的数据项，检查错误，验证退出重启后数据仍在。
7. 确认后停服，移除源插件，保持其数据备份不动；其他子服同版上线再开放。

来源与前置条件

来源	命令	当前已核对的限制
HuskSync	/invsync migrator husksync all	需要安装源 HuskSync，源端 MySQL；项目编译依赖 3.4 API，不能直接保证 4.x；优先核对背包、末影箱、经验、统计、进度，当前实现未完整迁移 PDC/药水等
KnapsackToGo4	/invsync migrator ktg4 all	需要安装源插件，读取对应 YAML 格式；非全部扩展格式通用；不支持单独迁移统计
MysqlPlayerDataBridge	/invsync migrator mysqlplayerdatabridge all	需对应旧配置和存储格式，按源版本验证，不能与同名 MySqlPlayerBridge 混用
PlayerDataSQL	/invsync migrator playerdatasql all	安装源插件，migrator-pds: true；目标 MySQL，源 MySQL，当前只读取未锁定记录；不支持统计单项
MySqlPlayerBridge	/invsync migrator MySqlPlayerBridge all	保留 plugins/MySqlPlayerBridge/mysql.yml 和源库，对应的 Base64/NBT 数据格式
PlayerSync	/invsync migrator playersync all	保留 plugins/PlayerSync/settings.yml 和源表；不支持统计单项
旧 InvSync 格式	/invsync migrator NoneBase64 all	旧格式转换入口；v1→v2 表升级还需看下方升级指南，不盲选

统计单项

命令层允许 statistic，但不代表所有迁移器都实现。支持时可用：

/invsync migrator husksync statistic

先迁移基础数据并确认源端统计存在，再使用对应入口。不支持时按迁移器提示处理。

PDS 的后续读取

迁移命令先搬运 PDS 原始记录，后续登录转换还依赖相关监听和源插件。migrator-pds 不要在全部玩家转换完成前直接关闭；按实际测试与作者指导退场。

回退

出错时先停止新增写入，保存源、目标和日志。恢复预先备份的整套环境，不只换回 JAR。若迁移后已有新进度，先归档再决定如何处理，旧源数据不包含这些新进度。

InvSync 自身升级 · 验证流程