knowhere | 番外篇 03：生产问题排查手册

番外定位

番外篇 03 面向线上问题排查。前面的课程分别讲了 API、Worker、解析、检索、计费、Webhook 和可观测性；这篇把它们组合成运维视角：当用户反馈“任务卡住”“检索结果不对”“Webhook 没收到”“余额扣错”“接口 429”时，应该按什么顺序查。

这不是替代监控平台的文档，而是一份工程排查路径。它适合维护者值班、问题复盘和结业项目答辩使用。

1. 排查总原则

生产问题先分层：

请求层：API 是否收到请求，request_id 是什么 认证层：用户身份和权限是否正确 准入层：是否被限流、配额、余额、scope 拦截 任务层：Job 状态机是否推进 执行层：Worker 是否执行、是否失败、是否清理 数据层：DB/Redis/Storage 是否一致 外部层：Webhook、Stripe、QStash、OSS/S3 是否回调 观测层：日志、error_code、details 是否能解释失败

不要先猜原因。先拿到最小事实：

• request_id
• user_id
• job_id
• document_id
• namespace
• error.code
• job.status