迁移、备份与日常运维

为什么会有旧物品

SealItems 物品保存定义指纹、schema 版本和实例 revision。修改物品定义后，已经发出去的物品不会自动重抽，但会被识别为定义过期；插件升级也可能提升 schema。迁移负责在明确规则下安全更新。

当前物品 schema 为 5，并能识别受支持的 1..4 旧版本。未知版本、缺 ID、坏指纹、非法 UUID/revision 或损坏 codec 会进入 PROTECTED，而不是猜测修复。

自动迁移的真实范围

config.yml：

safety:
  auto-migrate-stale-items: true

自动迁移只在在线玩家背包的安全接触/事件入口工作。它不扫描：

• 离线玩家数据；
• 世界掉落物；
• 漏斗流转中的物品；
• 未打开容器；
• 任意第三方数据库。

因此开启后不能宣称“全服所有旧物品已迁移”。

手动迁移

/si migrate 只显示迁移状态；/si migrate <在线玩家> 才把该玩家的在线背包加入队列。可能结果包括 APPLIED、UNCHANGED、CONFLICT、PROTECTED、BLOCKED、FAILED。遇到冲突应重新读取当前物品，不要循环强制提交。

宝石稳定 ID 迁移

gameplay/sockets/migrations.yml 只用于 gem/socket-type/profile 改名：

gems: { old_ruby: ruby_t1 }
socket-types: { old_attack: attack }
profiles: { old_weapon: standard-weapon }

映射必须无环、最终目标存在。安全接触时懒迁移，只改 ID，不重抽孔位、宝石、保底或属性数值。

配置变更发布流程

1. 完整备份配置、玩家/世界与外部经济数据。
2. 在测试服复制真实配置和少量脱敏玩家物品。
3. 修改一个系统。
4. 最小粒度 reload。
5. /si health。
6. 测试新物品和旧物品。
7. 测试费用不足、背包满、移动物品、断线、重复点击。
8. 记录配置版本和回滚点。
9. 正式服低峰发布并持续观察。

停服与 JAR 升级

1. 正常 /stop，等待所有世界保存。
2. 备份。
3. 替换 JAR，不保留多个 SealItems JAR。
4. 比较新增默认配置；不要盲目覆盖自定义文件。
5. 检查 ArcartX .new。
6. 启动后等待 Done，执行 /si health。
7. 抽查旧装备、新装备、三种 GUI 和外部费用。

不要强制杀进程、热替换正在加载的 JAR 或直接编辑玩家 PDC。

日常巡检

• /si health 是否 READY、provider 是否 frozen。
• 控制台是否持续报告 missing quality、protected item、migration failed。
• 重载失败后是否仍使用旧快照。
• 外部经济和 SealAttributes 版本是否变化。
• ArcartX 是否出现未处理 .new。
• 备份是否真的可恢复。