🔍 预加载排查

代理无法启动

检查 java -version，代理需要 Java 17+。若出现 UnsupportedClassVersionError，按报错 class 版本确认运行时；不要把所有启动错误都归因于 Java，保留完整堆栈。

代理看不到某子服

1. 子服 enabled: true，transport 与代理一致。
2. /invsync dev serverName 查看实际名字，不是只看文件原文。
3. Redis 地址、认证、数据库编号、prefix 一致，代理能连通。
4. 子服名字唯一，WS 模式检查白名单、地址、密钥、防火墙。
5. 保留订阅、心跳与接入日志，排除旧代理版本。

名字重复

复制服务端目录后没有改 server-name，可能让多个子服处理同一个请求。设置唯一稳定名字，重启并确认告警消失。

玩家进入后仍有等待

检查是否经过安装增强组件的代理，目标服是否认领预加载，是否首次进入目标服（没有本地档案），以及等待资源包、磁盘慢或其他插件占用。不是所有等待都属于数据同步。

可用 /invsync dev playerDataFolder 查看解析出的玩家数据目录。新版本会检测 playerdata 与 players/data 等布局，只有失败时显式设置目录，不按旧路径盲填。

连接失败或断网

当前协议由代理回报最终交接结果，失败时源服恢复流程与超时兜底配合。旧协议存在五秒在线状态兜底，不保证所有场景五秒统一解冻。

Redis 服务故障不是普通回退

预加载通道不可用时可以不走加速；但主插件的锁和热数据同样依赖 Redis。基础 Redis 连接故障可能触发停服保护，不能写成“Redis 宕机仍无损继续跨服”。

临时停用

正常停服后将子服 preload.yml 的 enabled 改为 false，再启动，验证基础同步。不要在玩家正在交接时强制热卸载组件。

手工 prequit / preload 是内部诊断入口，会影响玩家冻结与所有权。仅对测试账号、在理解流程并保留回退方案时使用。