云屿故障排查
用统一的判断顺序和场景化检查单快速定位登录、知识、工作流、工具和通知问题。
功能概述
故障排查页的目标不是解释所有原理，而是在问题出现时给出一条可执行的定位路径。
它的重点是先缩小范围，再逐步定位，而不是从一开始就凭经验猜原因。
通用排查顺序
遇到问题时，建议始终按下面顺序检查：
- 先确认是不是账号、权限或入口问题
- 再确认资源状态是否正常，例如文档是否处理完成、工作流是否已发布
- 再看消息记录、执行日志、通知结果或审计日志
- 最后才去怀疑模型、工具或平台本身缺陷
这个顺序的意义是：优先排除最常见、最容易验证的问题。
场景化排查步骤
登录失败
建议按下面顺序查：
- 账号是否存在
- 当前登录方式是否被策略关闭
- SSO、密码或 TOTP 是否配置错误
- 是否仍保留管理员回退入口
Agent 回答异常
建议按下面顺序查：
- 提示词边界是否清楚
- 知识库是否命中正确内容
- 工具是否真的被调用
- 模型是否选错或配置异常
知识库命中差
建议按下面顺序查：
- 文档是否处理成功
- 分块是否明显失真
- 检索参数是否过松或过紧
- 测试问题是否接近真实用户提问
工作流执行失败
建议按下面顺序查：
- 输入变量是否完整
- 节点输入输出是否正确
- 外部依赖是否超时或报错
- 是否是某个固定节点持续失败
通知未送达
建议按下面顺序查：
- 通知渠道是否已经配置成功
- 测试发送是否通过
- 接收地址、Webhook 或群配置是否正确
- 事件是否真的触发了通知链路
排查完成后应得到什么
一次有效排查，至少应产出下面 4 类信息：
- 具体出错环节
- 可以复现的条件
- 短期缓解方案
- 后续治理建议
如果排查结束后只能得到“又好了”或“好像是某个问题”，说明排查并没有真正完成。
常见问题
为什么很多问题最后都不是模型本身的问题
因为真实系统里更常见的问题通常来自：
- 权限和入口
- 文档状态
- 节点输入输出
- 通知和渠道配置
模型只是最终表象，不一定是根因。
为什么排查时要一次只改一个变量
如果你一次改很多项，就很难判断到底是哪一步真正修复了问题。
为什么要先看记录，再改配置
因为记录和日志是最直接的现场证据。
如果没看就开始改配置，通常会把原始问题现场破坏掉。
注意事项
- 先判断范围，再逐步深入，不要一开始就重构或重配
- 一次只改一个变量，便于确认修复是否有效
- 如果问题涉及权限、SSO 或站点策略，优先用测试账号复现