常见问题与排障

工作流或 RPA 失败时不要立刻重录、重建。先看日志，再分类。绝大多数问题都属于下面几个类别，本页给你一份固定的排查路径。

---

第一步：永远先看日志

看日志的顺序：

1. 找 第一个失败节点（不是最后一个），后面的失败一般是连锁反应。
2. 看节点的 输入 是不是预期的值。
3. 看节点的 错误信息 是不是已知模式（超时 / 401 / 元素未找到 / 文件不存在）。
4. 对照 上一次成功 的日志，找差异。

如果日志没有错误但结果不对，多半是 数据问题，往下看“数据 / 输出不对”一节。

---

客户端启动 / 环境异常

现象

• 客户端打开后一直在初始化。
• 工作流报“无法连接到本地引擎”。
• 桌面 RPA 启动后立刻失败。

处理

1. 重启客户端。
2. 检查端口 20317 是否被占用：
   • macOS：lsof -i :20317
   • Windows：netstat -ano | findstr 20317
3. 杀掉占用端口的进程，或在客户端设置中改端口。
4. 检查防火墙 / 杀毒软件是否拦截 MagicAI。
5. 仍不行：记录客户端版本、系统、错误截图，找管理员。

更多客户端环境检查：第一次使用前准备。

---

元素找不到 / 点击失败（RPA）

现象

• “Element not found / 元素未找到”。
• 点击没有反应，但日志说成功。
• 截图里看不到目标元素或全黑。

处理

1. 在录制 / 元素管理中重新捕获该元素。
2. 给它加 等待 节点，等页面加载完成再操作。
3. 检查页面状态：
   • 是不是没登录、跳到了登录页？
   • 是不是弹出了风控 / 同意条款？
   • 是不是 iframe / 新标签页？
4. 检查 macOS 系统权限：辅助功能、屏幕录制、输入监控。
5. 高 DPI 显示器若坐标偏移，开启 DPI 适配。

更多：录制、元素与调试。

---

连接 / 凭据失败

现象

• HTTP 节点返回 401 / 403。
• 通知节点报“鉴权失败”。
• 数据库节点报“authentication failed”。

处理

1. 进入 连接，找到对应连接。
2. 先点 测试连接。
3. 失败的话：
   • 401 / 403：Token 过期或权限变了，去对方平台重发凭据。
   • 5xx / 超时：对方系统挂了或网络不通，先确认对方。
   • SSL / 证书错：检查时间是否对、证书是否过期。
4. 修好之后回工作流再跑一次。

切记：不要把账号 / Token 写在节点里临时绕过，永远走连接。

---

数据 / 输出不对

现象

• 流程跑成功，但输出字段缺失或错值。
• 写入数据库后值不对。
• 通知文案错位。

处理

1. 看每个节点 输入 / 输出：
   • 上游节点是否真的产生了你以为的字段？
   • 字段名拼写是否一致？
   • 数据类型是否匹配（字符串 vs 数字 vs 日期）？
2. 看变量引用：
   • 是否拿了错的变量？
   • 列表 / 对象的层级写对了吗？
3. 关键字段加 断言节点 或 日志输出节点，提前拦截异常。
4. 涉及时间：
   • 时区是否一致？
   • 跨日 / 月底 / 节假日是否需要特殊处理？

---

定时任务没跑 / 跑失败

现象

• 到点没触发。
• 触发了但状态一直“失败”。
• 没收到失败告警。

处理

1. 看任务详情：是不是 未启用 或 被暂停。
2. 看 最近 N 次执行记录：
   • 都失败 → 工作流本身有问题，先回到手动运行 debug。
   • 偶尔失败 → 配重试和指数退避。
3. 检查 客户端 / 引擎 是否在线（如果是本地执行）。
4. 告警没收到 → 检查告警 连接 是否还有效。
5. 长期没人值守的任务，先关掉再排查。

更多：定时任务。

---

发布 / 版本相关

现象

• 上线后行为和测试不一致。
• 用户反馈“以前是这样，现在变了”。

处理

1. 看工作流 当前发布版本，再对比草稿。
2. 看定时任务 绑定的版本号，是固定还是“跟随最新”。
3. 紧急情况下回滚到上一个稳定版本。
4. 修复后通过新版本发布，不要直接覆盖发布过的版本。

---

第一次心里没底时的检查清单

[ ] 看了第一个失败节点的日志
[ ] 看了节点的输入 / 输出
[ ] 看了对应连接的状态
[ ] 看了客户端 / 本地引擎是否在线
[ ] 看了系统权限（macOS / Windows）
[ ] 在测试环境复现过一次
[ ] 已记录失败现象 / 时间 / 截图，准备提交支持

---

提交支持时请准备

• 工作流名称、版本号、最近一次成功 / 失败时间。
• 失败节点 + 错误信息原文（不要截掉）。
• 输入参数 / 上下游节点输出（脱敏）。
• 客户端版本、操作系统、是否使用代理 / VPN。
• 是否最近改过：连接、技能版本、知识库、客户端、操作系统。

---

下一步

• 想避免常见坑：阅读 使用最佳实践。
• 想稳定上线：阅读 定时任务 中的“前置条件”。
• 想加强 RPA 稳定性：阅读 录制、元素与调试。
• 想集中管理凭据：阅读 连接外部系统。