🧰 故障排查与反馈

先保留现场

玩家报告物品丢失或回档时，停止反复切服、恢复、删除、清缓存等尝试。记录玩家 UUID、节点、时间和操作，归档数据库/世界副本与完整日志，必要时限制登录。

MySQL / MongoDB 连不上

按错误区分：

表现	检查
Connection refused / timeout	地址、端口、监听、防火墙、容器网络；容器 localhost 不是宿主
Access denied / authentication failed	账号密码、连接来源权限、Mongo 认证库
Unknown database / 表权限错误	库是否存在、读写与建表升级权限
SSL / certificate / handshake	实际 TLS 要求、证书与驱动参数；不是盲改 ssl
Column / schema 问题	全网插件版本、表结构及升级日志，保存备份后处理

不要因为连接失败把库指向一份空数据库继续放行。

Redis 出错

确认主配置中的地址、密码、编号、前缀，检查服务健康和网络。主插件运行时 Redis 操作故障可能触发服务器关闭保护，避免用“预加载会回退”误解为 Redis 可有可无。

恢复后检查持久化是否完成、是否有旧缓存和残留锁。共享库禁止直接 FLUSHALL，在线禁止随意解锁全部玩家。

一直锁定 / 加载超时

先判断目标是否仍在另一子服在线、保存是否未完成、源服是否低 TPS 或数据服务延迟。锁 TTL 和实际交接状态共同影响等待，不能统一让玩家等固定 15 秒就认定安全。

确认全网离线、原节点已停止写入、持久化已核对后再按作者指导处理。不要调用 unlockAll 作为玩家投诉的快捷修复。

物品解析失败

检查自定义附魔注册表、模组/物品插件、MC 与 NBT-API 支持版本是否一致，查看完整堆栈中的真正原因。保留原始记录，参考失败策略，不直接启用 skip 后保存空槽。

进服状态不对

对照同步开关和其他插件加载顺序。字段优化可在维护期间关闭 sync.skipWriteWhenFieldMatch 对比；只是定位手段，不替代修复。查看最大血量、Vault 与扩展数据回调是否成功。

预加载问题见专用排查。

如何反馈

提供以下信息给 QQ 3104026189：

1. InvSync 与代理组件版本、MC、服务端分支、Java。
2. 数据库/Redis 类型与版本（不发送密码）。
3. 玩家名或 UUID、准确时间、源服→目标服、是否在 GUI/死亡/重启场景。
4. 完整相关日志与堆栈，不只截最后一行。
5. 物品/模组/背包/经济插件版本，是否最近升级。
6. 已尝试的操作、原始备份是否保留。

debug 默认关闭，可在测试复现期间开启，完成后关闭。公开分享时移除账号密码、令牌、密钥与不必要的玩家隐私；诊断记录不要放入公开文档仓库。