---
title: 核心程序故障排查
description: 设备连接失败、截图识别不准、调度卡住或恢复异常、配置改了不生效、远程访问不通的定位顺序与处理办法。
updated: 2026-10-20
---

# 核心程序故障排查

## <DocIcon name="smartphone" /> 设备与 ADB

| 现象 | 原因 | 处理 |
| --- | --- | --- |
| `adb devices` 为空 | 模拟器未开调试，或 adb server 未启动 | 模拟器设置里开启 ADB；`adb start-server` |
| 设备 `offline` | adb 版本冲突（多个模拟器自带不同版本） | 用模拟器自带的 adb，或统一版本 |
| 多个设备时连错 | Serial 写错 / `auto` 猜错 | 手动填 `host:port` |
| 频繁掉线 | 模拟器省资源、USB 选择性挂起 | 关闭模拟器省电，改用 `ADB_nc` |
| 重启模拟器无效 | 未登记安装路径或实例名 | 填写 `EmulatorInfo.name` / `path` |

## <DocIcon name="eye" /> 截图

| 现象 | 原因 | 处理 |
| --- | --- | --- |
| 全黑 | 模拟器用独立渲染后端，ADB 截图拿不到 | 换 `DroidCast_raw`、`nemu_ipc`（MuMu）或 `ldopengl`（雷电） |
| 超时 | 后端卡死 | 换方案；开「检测不到设备时重启 adb」 |
| 花屏/撕裂 | 编码或缩放问题 | 关闭「去除图片色彩抖动」再试 |
| 尺寸不是 1280×720 | 模拟器分辨率/DPI 被改 | 改成 1280×720，重启游戏 |
| 截图正常但点击偏移 | 缩放与坐标映射不一致 | 恢复默认分辨率与 DPI，避免系统缩放 |

## <DocIcon name="brain" /> 识别

| 现象 | 原因 | 处理 |
| --- | --- | --- |
| 找不到按钮 | 皮肤/装备遮挡、UI 改版 | 恢复默认外观；更新核心资源 |
| OCR 读错数字 | 字色预处理不匹配、字体缩放 | 确认分辨率；换模型版本（`OcrModelVersion*`） |
| 卡在未知页面 | 弹窗未处理 | 看错误截图；手动关掉弹窗后重跑 |
| 识别在真机正常、模拟器异常 | 渲染差异 | 换截图方案，而不是改模板 |

::: tip 先看错误现场
`log/error/<实例>/<时间戳>/` 里的截图就是脚本当时看到的画面。它比你的记忆可靠。
:::

## <DocIcon name="zap" /> 调度

| 现象 | 原因 | 处理 |
| --- | --- | --- |
| 任务完全不跑 | 未启用、`NextRun` 在未来、队列为空 | 检查 `Enable` 与时间 |
| 总是先跑某个任务 | 优先级更高且已到期 | 调整自定义优先级或时间 |
| 反复重启游戏 | `GameStuckError` / 页面无法识别 | 查截图与服务器维护状态 |
| 实例自己停了 | 敏感任务失败 / `ScriptError` 3 次 | 看日志最后 100 行 |
| 卡在同一任务几小时 | 逻辑死循环，日志仍在动 | 开运行监护（`Watchdog*`） |
| 任务延后到明天 | 触发 `TaskRestartLimit` | 修复根因，或临时调大上限 |
| 多实例互相干扰 | 同一 Serial 或同一实例名 | 一实例一模拟器一进程 |

### 日志关键词

| 关键词 | 含义 |
| --- | --- |
| `连续失败` | 失败计数上升，可能升级为重启模拟器 |
| `Restart` | 注入重启任务 |
| `EmulatorOpBusy` | 已有启停操作在跑，本轮跳过 |
| `ScriptError` | 代码异常 |
| `RequestHumanTakeover` | 无法安全判断，尝试自动恢复 |
| `[服务器检查]` | 维护检测 |

## <DocIcon name="settings" /> 配置

| 现象 | 原因 | 处理 |
| --- | --- | --- |
| 改了没生效 | 任务执行中，配置在边界才重载 | 等任务结束或重启实例 |
| 值自动回退 | 被 `override.yaml` 强制覆盖 | 查该字段是否用户可改 |
| 保存冲突 | 两个页面同时编辑 | 刷新后重试 |
| 导入后缺字段 | 跨版本迁移 | 逐页检查关键开关 |
| 中文变键名 | i18n 缺翻译 | 更新核心或补翻译 |

## <DocIcon name="cloud" /> 远程访问

| 现象 | 原因 | 处理 |
| --- | --- | --- |
| 局域网打不开 | 监听 `127.0.0.1` 或防火墙 | 改 `WebuiHost`，放行端口 |
| 固定入口 302 到 `/error` | 设备离线、租约过期、Tunnel 失效 | 看远程访问页状态 |
| 一直转圈 | WebSocket 被中间网络阻断 | 换网络；确认 7844 端口 |
| 配对码过期 | 超过 5 分钟 | 重新生成 |
| 撤销后仍能连 | 只在本机移除了入口 | 在主机侧撤销配对 |
| MCP 401 | 未带密码或改密码后未重启 | 带 Bearer；重启 WebUI |

## <DocIcon name="badge-dollar" /> 性能

| 现象 | 原因 | 处理 |
| --- | --- | --- |
| 识别慢 | 截图方案慢、OCR 用 CPU | 跑性能测试；换方案；调 OCR 设备 |
| CPU 打满 | 多实例 + 高帧率 | 降并发，错开任务 |
| 内存增长 | 长时间运行、截图缓存 | 开每日重启，限制错误现场保留 |
| 磁盘满 | 日志/截图/备份堆积 | 调 `RetentionDays`、`KeepDays` |

## <DocIcon name="refresh" /> 更新后异常

1. 记录更新前的提交（`git log`）。
2. 看 `frontend/dist` 是否重建成功。
3. 检查 `pip`/`uv` 依赖是否同步。
4. 回滚代码后 `uv sync --frozen` 再启动。

```bash
git log --oneline -5
git checkout <上一个可用提交>
uv sync --frozen
```

不要用 `git reset --hard` 清掉本地修改。

## <DocIcon name="compass" /> 升级排查顺序（推荐）

```text
1. 截图测试 → 能拿到画面？
2. 手动点一次 → 控制方案有效？
3. 单任务「立即执行」→ 能完成？
4. 开调度 → 能按时触发？
5. 加第二个任务 → 不互相干扰？
6. 加第二个实例 → 资源够？
```

每一步通过后再进下一步，比一次性开满所有任务更容易定位问题。