核心程序故障排查
设备与 ADB
| 现象 | 原因 | 处理 |
|---|---|---|
adb devices 为空 | 模拟器未开调试，或 adb server 未启动 | 模拟器设置里开启 ADB；adb start-server |
设备 offline | adb 版本冲突（多个模拟器自带不同版本） | 用模拟器自带的 adb，或统一版本 |
| 多个设备时连错 | Serial 写错 / auto 猜错 | 手动填 host:port |
| 频繁掉线 | 模拟器省资源、USB 选择性挂起 | 关闭模拟器省电，改用 ADB_nc |
| 重启模拟器无效 | 未登记安装路径或实例名 | 填写 EmulatorInfo.name / path |
截图
| 现象 | 原因 | 处理 |
|---|---|---|
| 全黑 | 模拟器用独立渲染后端，ADB 截图拿不到 | 换 DroidCast_raw、nemu_ipc（MuMu）或 ldopengl（雷电） |
| 超时 | 后端卡死 | 换方案；开「检测不到设备时重启 adb」 |
| 花屏/撕裂 | 编码或缩放问题 | 关闭「去除图片色彩抖动」再试 |
| 尺寸不是 1280×720 | 模拟器分辨率/DPI 被改 | 改成 1280×720，重启游戏 |
| 截图正常但点击偏移 | 缩放与坐标映射不一致 | 恢复默认分辨率与 DPI，避免系统缩放 |
识别
| 现象 | 原因 | 处理 |
|---|---|---|
| 找不到按钮 | 皮肤/装备遮挡、UI 改版 | 恢复默认外观；更新核心资源 |
| OCR 读错数字 | 字色预处理不匹配、字体缩放 | 确认分辨率；换模型版本（OcrModelVersion*） |
| 卡在未知页面 | 弹窗未处理 | 看错误截图；手动关掉弹窗后重跑 |
| 识别在真机正常、模拟器异常 | 渲染差异 | 换截图方案，而不是改模板 |
先看错误现场
log/error/<实例>/<时间戳>/ 里的截图就是脚本当时看到的画面。它比你的记忆可靠。
调度
| 现象 | 原因 | 处理 |
|---|---|---|
| 任务完全不跑 | 未启用、NextRun 在未来、队列为空 | 检查 Enable 与时间 |
| 总是先跑某个任务 | 优先级更高且已到期 | 调整自定义优先级或时间 |
| 反复重启游戏 | GameStuckError / 页面无法识别 | 查截图与服务器维护状态 |
| 实例自己停了 | 敏感任务失败 / ScriptError 3 次 | 看日志最后 100 行 |
| 卡在同一任务几小时 | 逻辑死循环，日志仍在动 | 开运行监护（Watchdog*） |
| 任务延后到明天 | 触发 TaskRestartLimit | 修复根因，或临时调大上限 |
| 多实例互相干扰 | 同一 Serial 或同一实例名 | 一实例一模拟器一进程 |
日志关键词
| 关键词 | 含义 |
|---|---|
连续失败 | 失败计数上升，可能升级为重启模拟器 |
Restart | 注入重启任务 |
EmulatorOpBusy | 已有启停操作在跑，本轮跳过 |
ScriptError | 代码异常 |
RequestHumanTakeover | 无法安全判断，尝试自动恢复 |
[服务器检查] | 维护检测 |
配置
| 现象 | 原因 | 处理 |
|---|---|---|
| 改了没生效 | 任务执行中，配置在边界才重载 | 等任务结束或重启实例 |
| 值自动回退 | 被 override.yaml 强制覆盖 | 查该字段是否用户可改 |
| 保存冲突 | 两个页面同时编辑 | 刷新后重试 |
| 导入后缺字段 | 跨版本迁移 | 逐页检查关键开关 |
| 中文变键名 | i18n 缺翻译 | 更新核心或补翻译 |
远程访问
| 现象 | 原因 | 处理 |
|---|---|---|
| 局域网打不开 | 监听 127.0.0.1 或防火墙 | 改 WebuiHost，放行端口 |
固定入口 302 到 /error | 设备离线、租约过期、Tunnel 失效 | 看远程访问页状态 |
| 一直转圈 | WebSocket 被中间网络阻断 | 换网络；确认 7844 端口 |
| 配对码过期 | 超过 5 分钟 | 重新生成 |
| 撤销后仍能连 | 只在本机移除了入口 | 在主机侧撤销配对 |
| MCP 401 | 未带密码或改密码后未重启 | 带 Bearer；重启 WebUI |
性能
| 现象 | 原因 | 处理 |
|---|---|---|
| 识别慢 | 截图方案慢、OCR 用 CPU | 跑性能测试；换方案；调 OCR 设备 |
| CPU 打满 | 多实例 + 高帧率 | 降并发，错开任务 |
| 内存增长 | 长时间运行、截图缓存 | 开每日重启，限制错误现场保留 |
| 磁盘满 | 日志/截图/备份堆积 | 调 RetentionDays、KeepDays |
更新后异常
- 记录更新前的提交（
git log）。 - 看
frontend/dist是否重建成功。 - 检查
pip/uv依赖是否同步。 - 回滚代码后
uv sync --frozen再启动。
bash
git log --oneline -5
git checkout <上一个可用提交>
uv sync --frozen不要用 git reset --hard 清掉本地修改。
升级排查顺序（推荐）
text
1. 截图测试 → 能拿到画面？
2. 手动点一次 → 控制方案有效？
3. 单任务「立即执行」→ 能完成？
4. 开调度 → 能按时触发？
5. 加第二个任务 → 不互相干扰？
6. 加第二个实例 → 资源够？每一步通过后再进下一步，比一次性开满所有任务更容易定位问题。