故障排查

先确认使用的包版本、运行目录和访问地址，再检查服务状态。不要先删除数据或混换镜像。

网页能打开，但无法进游戏

检查 docker compose ps -a 的健康状态，然后查看 gateway、login、char、map 和 web-api 日志。能够访问网页只证明静态入口可达，不代表登录和地图连接已经成功。

手机访问时不能使用服务器的 127.0.0.1；公开地址见配置。域名入口检查 WebSocket 升级及代理超时，见反向代理。

保持登录接口返回 403

核对页面 Origin 与转发 Host，包括端口。不要将 Host 替换为内部容器名；/api/game-session/* 保留原路径、Cookie 和 Set-Cookie，禁止代理缓存。更换域名或 HTTP/HTTPS 入口需要分别登录。

更新后仍显示旧界面或资源

确认完整包、镜像与资源属于同一版本。源码开发必须重新完整构建 PWA，重启 Gateway 不会编译客户端；部署包按升级更新。然后强制刷新，必要时重新进入游戏以重新解码资源。

后台目录为空或自定义内容不同步

确认 api-init 本轮成功完成迁移与目录导入。只执行数据库迁移不等于导入资料。自定义更改分别执行游戏重载及目录刷新。

校验或初始化失败

先检查文件是否缺失、是否混用了不同版本的配置和镜像；不通过改清单哈希掩盖损坏。已有环境不要重新初始化空库，先查看日志并保存备份。

自动战斗一直正在获取范围

先确认角色已经完成地图加载且连接正常。客户端需要地图服发送当前同步范围，未收到时会等待；确认 PWA 与地图服使用同一套当前版本，不能只替换前端或只重启旧地图服二进制。完整更新后重新登录，并检查浏览器连接错误及 map 日志。

游戏设置一直等待确认

在修改记录查看请求状态，核对 api、web-api、map 是否正常及 API 日志中的 automatic settings recovery pending。自动恢复需要读取地图服实际状态；控制通道中断或文件被外部编辑时会继续等待。不要删除待确认记录、手工释放锁或反复重发保存来掩盖状态不明。恢复通道后再次查看修改记录与实际值，规则见游戏设置。

导航链接不能点击或传送被拒绝

普通文字可能没有可用坐标或对应图鉴结果；交易等操作窗口也会限制导航。NPC 对话里的地点链接需要正常结束对话后再打开地图。可点击不表示当前位置一定存在目标 NPC，最终传送仍受权限、冷却、地图加载和安全落点检查限制。失败或超时以实际提示为准，见说明链接与帮助。

报告问题

记录包版本、系统和 CPU 架构、浏览器、访问方式、出错步骤及相关日志。删去密码、令牌、Cookie 和个人数据后通过社区入口反馈。