17. 故障排查

Troubleshooting 描述 FlowNex 常见问题的排查思路。

排障时建议优先获取：

  1. traceId。
  2. tenantCode。
  3. userId。
  4. conversationId。
  5. taskId。
  6. messageId。
  7. 发生时间。
  8. 渠道类型。
  9. 用户原始输入。

17.1 对话无响应

可能原因：

  1. SSE 未建立成功。
  2. control-center 创建任务失败。
  3. agent-runtime-gateway 未找到 runtime 实例。
  4. share-harness 实例不可用。
  5. 模型调用超时。
  6. Runtime 事件未正确回推。

排查步骤：

  1. 查询网关日志，确认请求是否进入。
  2. 查询 control-center 是否创建 Message 和 Task。
  3. 查询 agent-runtime-gateway 会话绑定。
  4. 查询 share-harness runtime 日志。
  5. 查询 SSE push 事件。
  6. 根据 traceId 串联完整链路。

17.2 SSE 断连

可能原因：

  1. 客户端网络中断。
  2. 网关连接超时。
  3. SSE session 丢失。
  4. runtime 事件推送失败。
  5. 代理或负载均衡超时配置不合理。

排查步骤：

  1. 按入口查询 ai-claw-gateway 或 ai-app-runtime-gateway SSE 连接日志。
  2. 查询是否存在 close event。
  3. 查询 agent-runtime-gateway 是否继续收到 runtime 事件。
  4. 检查负载均衡 idle timeout。
  5. 检查客户端重连策略。

17.3 Runtime 任务失败

可能原因：

  1. 模型调用失败。
  2. Tool 调用失败。
  3. Skill 加载失败。
  4. 文件读取失败。
  5. 知识检索失败。
  6. 上下文超预算。
  7. Runtime 实例异常退出。

排查步骤：

  1. 查询 Task 终态和错误码。
  2. 查询 Task Step。
  3. 查询 runtime event。
  4. 查询 share-harness 日志。
  5. 检查模型 provider 返回。
  6. 检查本轮 toolCodes 和 skillCodes。
  7. 检查文件和知识权限。

17.4 Skill 未命中或不可用

可能原因：

  1. 用户未安装 Skill。
  2. Skill 未发布或已下线。
  3. Skill 未进入本轮 skillCodes。
  4. Skill 描述不足，Planner 未选择。
  5. Skill 依赖 Tool 未授权。
  6. Skill 依赖知识不可见。

排查步骤：

  1. 查询用户当前 Skill 授权。
  2. 查询消息落库的 skillCodes。
  3. 查询 runtime selected skill 事件。
  4. 查询 Skill 状态。
  5. 查询 Skill 绑定知识和 Tool 依赖。
  6. 检查 Planner 输出。

17.5 知识库无召回

可能原因：

  1. 用户无知识库权限。
  2. 前端手选范围为空。
  3. Skill 绑定范围过窄。
  4. OpenViking 知识库未完成索引。
  5. query 不适合当前知识库。
  6. 检索阈值过高。
  7. 知识库 Provider 超时。

排查步骤：

  1. 查询 KnowledgeScopeAdapter 返回授权范围。
  2. 查询本轮 knowledgeAccess。
  3. 查询用户手选 knowledgeScope。
  4. 查询 Skill-Knowledge Binding。
  5. 查询知识检索请求和响应。
  6. 查询 OpenViking 后台资源状态。

17.6 文件上传或恢复失败

可能原因：

  1. OSS object key 不存在。
  2. 文件大小超限。
  3. 文件类型不支持。
  4. 文件权限不足。
  5. runtime restore 失败。
  6. AGFS mount 未准备好。

排查步骤：

  1. 查询消息附件记录。
  2. 查询 OSS 对象是否存在。
  3. 查询 runtime 文件恢复日志。
  4. 查询 AGFS file node。
  5. 查询当前 task 是否有文件读取权限。

17.7 AGFS 挂载异常

可能原因：

  1. AGFS Server 不可用。
  2. Metadata Service 不可用。
  3. Mount 参数错误。
  4. rootFileId 不存在。
  5. FUSE Client 异常。
  6. 权限校验失败。
  7. Version Tree 首次加载失败。

排查步骤：

  1. 查询 AGFS Server 健康状态。
  2. 查询 Metadata Service 日志。
  3. 查询 mount 请求参数。
  4. 查询 Space 和 rootFileId。
  5. 查询 FUSE Client 日志。
  6. 查询 AGFS 权限拒绝事件。

17.8 多 Agent 子任务卡住

可能原因：

  1. Task Graph 依赖未满足。
  2. 上游子任务失败。
  3. 某个 Agent runtime 不可用。
  4. 子任务等待文件但文件未生成。
  5. Reviewer 驳回后未触发重试。
  6. checkpoint rollback 阻塞。

排查步骤：

  1. 查询 Task Graph 状态。
  2. 查询各节点状态。
  3. 查询节点依赖边。
  4. 查询子任务 runtime 状态。
  5. 查询 AGFS 文件产物。
  6. 查询 handoff event。
  7. 查询 Reviewer 结果。