生产故障排查手册

AI 请求的定位顺序

拿到 sessionId/runId/messageId/traceId 后，依次查看 dispatcher/队列、channel 等待、最后一个 graph node、LLM/Tool/RAG call、checkpoint/JSONL sequence 和 SSE pending/response snapshot。HTTP 200 只说明接入层处理成功，不能证明 Agent 已完成。

现象	追加检查
Agent 配置未生效	发布状态、缓存失效、LoadAgentConfigNode、toolset hash
工具重复执行	toolCallId、ToolExecutionJournal、STARTED 未知结果
RAG 为空	Dataset/tenant filter、向量维度、索引加载、activated
页面无文本但状态完成	token flush、assistant snapshot、pending event
重启后无法继续	JSONL header、checkpoint schema/graph/toolset hash、workspace
只在多实例失败	session lease、共享队列、外部 IM 回复路由、临时目录

保留失败请求的脱敏参数、版本、配置摘要和下游响应码；不要为了重试直接清空 session 或删除 checkpoint。

现象	首查位置	常见原因
网关 503	Nacos、Gateway 路由	服务未注册、端口错、健康检查失败
登录失败	Auth、Redis、UPMS	Token/验证码过期、租户或权限缺失
AI 无输出	AI Trace、消息队列、模型连接	session 队列阻塞、模型超时、SSE 断开
文件上传失败	DocSpace、OSS、multipart 配置	大小限制、临时目录、对象存储权限
向量检索为空	Embedding、Milvus/ES	维度不匹配、索引未加载、租户过滤
消费重复	消费日志、业务状态表	幂等键缺失、确认/重试配置错误

排障时保留 Trace ID、时间窗口、服务实例、请求路径和业务 ID，避免只截取单行异常。