故障排查

排查 SAG 时先区分“服务未就绪”“文档未就绪”“模型不可用”和“浏览器到 API 的网络路径错误”。下面按最常见症状给出检查顺序。

页面打不开

docker compose ps
docker compose logs --tail=200 web api

确认 Web 端口没有被其他进程占用，并且 web 等待 api 健康后启动。自定义 WEB_PORT 只改变宿主机端口，不改变容器内 3000。

API health 正常但 ready 失败

/system/health 只验证进程；/system/ready 还会检查关键初始化。查看 API 日志中的数据库连接、Schema、数据目录权限和引擎配置错误。

PostgreSQL 覆盖环境中同时运行：

docker compose \
  -f compose.yaml \
  -f compose.postgres.yaml \
  ps

确认 db 健康且密码、数据库名与连接串一致。

文档一直处理中

1. 查看文档 status、progress 与 error。
2. 查询对应 /jobs/{job_id}。
3. 确认 Embedding 与 LLM 分别可用。
4. PDF 使用 MinerU 时检查 Key、版本与轮询超时。
5. 失败任务用“重新处理”，不要反复上传相同文件。

SAG 会在 MinerU 未配置或失败时回退 MarkItDown，但格式复杂的 PDF 可能得到不同版面结果。

快速检索没有结果

• 文档必须是 ready；
• Embedding 必须已经配置并完成向量化；
• 先在正确的信源范围内测试确定存在的内容；
• 更换 Embedding 模型后重新处理旧文档。

增加 top_k 不能修复未建立索引或语义空间不一致的问题。

精确模式或对话失败

精确模式需要 LLM 进行查询理解与重排，对话还需要生成模型。运行设置页连接测试，并核对 provider、Base URL、模型名称、超时与 Key。

界面能打开不代表模型配置已完成，这是预期行为。

浏览器提示网络或 CORS 错误

检查三项：

SAG_CORS_ORIGINS=https://web.example.com
NEXT_PUBLIC_API_BASE=https://api.example.com
BIND_ADDRESS=0.0.0.0

NEXT_PUBLIC_API_BASE 改变后必须重建 Web。反向代理还需正确处理 OPTIONS、Authorization 和 SSE 长连接。

MCP 无法连接

• URL 应以 /mcp/ 结尾；
• HTTP 请求需要 Authorization: Bearer <TOKEN>；
• 使用 source_id 时确认该信源属于当前身份；
• 先调用 list_sources 判断连接范围与鉴权是否成功。

引用打不开

确认对应文档没有被删除或重新处理到新的 chunk 标识。外部系统保存引用时应保存可解释的来源信息，但不要假设 chunk ID 在删除重建后永久不变。

仍无法定位

提交 Issue 前附上 SAG 版本、运行方式、操作系统、最小复现步骤和已脱敏日志。不要上传 JWT、模型 Key、数据库密码或私人文档内容。