<!-- gitea-wiki-mirror:start -->
generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
wiki_page: Troubleshooting
wiki_url: https://git.ilapage.cn/OPC/goauto/wiki/Troubleshooting
wiki_revision: 779ea2d826cb6f09b7a3df98f243a22bdd8bf6f5
synchronized_at: 2026-08-17T03:28:14Z
<!-- gitea-wiki-mirror:end -->

# 故障排查

## 设备显示离线

1. 检查服务器 API 地址和 HTTPS 证书。
2. 检查 Device Token 是否属于该设备且未吊销。
3. 检查 Android 网络、电池限制、自启动和 Portal 进程。
4. 对比服务端 `last_seen_at` 与最近心跳失败原因。

## 一加通过 ADB 安装一直不返回

ColorOS 开启“安装增强防护”时，电脑端未知来源 APK 可能不会直接失败，而是让 `adb install` 一直等待系统确认：

1. 保持手机解锁，查看系统弹出的 Mobile Agent 安装详情页。
2. 点右上角“更多” → “开始深度扫描”。
3. 查看扫描结论后点“继续安装”。
4. 更新同一签名 APK 通常可直接执行；首次安装仍以手机实际提示为准。

不要为方便联调长期关闭系统安装防护，也不要用脚本修改系统安全策略。若只是局域网 Debug 联调，确认安装的是 Debug APK；Release 仍只连接 HTTPS 服务端。

## Debug 局域网地址提示 Cleartext HTTP 不允许

- 确认使用包含 `src/debug/AndroidManifest.xml` 的最新 Debug APK，而不是 Release APK。
- 重新运行 `assembleDebug` 并覆盖安装；应用诊断页会显示具体错误。
- 正式部署不要放开明文 HTTP，应为服务端配置可信 HTTPS 证书。

## 无法打开 PDD

1. 检查 Portal 无障碍是否 Enabled 且 Bound。
2. 一加检查后台运行、电池优化和浏览器跳转权限。
3. 检查浏览器“打开拼多多APP”和系统“打开”是否被最新控件树唯一识别。
4. 动作后验证包名和 Activity，不只检查 RPC success。

## 控件树数据不全

- 在系统设置页与 PDD 页分别对照。
- 一加/ColorOS 若只剩根节点，先重启设备验证 UiAutomation 状态。
- 不通过放宽业务选择器掩盖系统抓树故障。

## 任务一直运行

1. 检查设备租约是否过期。
2. 检查 Android 本地是否仍持有执行锁。
3. 检查最后心跳、步骤名、任务规则快照和错误码。
4. 网络断开应由超时器把任务置为失败，不能静默回到待领取。

## 采集结果不完整

保存已有结果并标记 `completed_partial`；展示缺失维度和值。不要伪造缺失 SKU，也不要自动重试。

## 规则疑似失效

复制现有规则创建或编辑可用规则，用测试任务验证。删除旧规则只阻止创建新任务，已经创建的任务仍按自身快照执行。