fastapi/docs/07_troubleshooting.md

常见故障排查

本文档用于接手人快速定位本地和云服务器常见问题。

1. /fastapi/docs 打不开

现象：

• 浏览器访问 http://8.160.178.88/fastapi/docs 失败

排查：

curl http://127.0.0.1:9000/docs
docker compose ps
docker compose logs --tail=200 fastapi

可能原因：

• FastAPI 容器未启动
• Nginx /fastapi/ 代理配置错误
• .env 中 APP_ROOT_PATH 未设置为 /fastapi

处理：

cd /home/code/medical-ai
docker compose up -d fastapi
docker compose logs --tail=200 fastapi

2. /api/v1/auth/me 返回 401

现象：

{
  "code": "AUTH_CREDENTIAL_REQUIRED"
}

排查：

• 是否携带 Authorization: Bearer <access_token>
• token 是否过期
• AUTH_USER_ME_URL 是否可访问
• Django 容器是否正常

验证：

curl "http://8.160.178.88/fastapi/api/v1/auth/me" \
  -H "Authorization: Bearer <access_token>" \
  -H "X-Entry-Scene: production_vue"

3. Django 用户中心不可达

现象：

{
  "code": "AUTH_USER_CENTER_UNAVAILABLE"
}

排查：

docker compose ps django
docker compose logs --tail=200 django

处理：

• 检查 AUTH_USER_ME_URL
• 检查 Docker 网络
• 检查 Django 服务是否能访问 MySQL

4. MySQL 连接失败

现象：

• 服务启动时报数据库连接错误
• /health/ready 不通过

排查：

docker compose ps mysql
docker compose logs --tail=100 mysql

检查 .env：

DATABASE_URL=mysql+pymysql://root:<password>@mysql:3306/medical?charset=utf8mb4

Docker 内部访问应使用服务名 mysql，不是 127.0.0.1。

5. Redis 连接失败

排查：

docker compose ps redis
docker compose logs --tail=100 redis

检查 .env：

RUNTIME_MEMORY_BACKEND=redis
REDIS_URL=redis://redis:6379/0

如果 Redis 不可用，短期会话 memory 会受影响。

6. LLM 调用失败或很慢

现象：

• 流式问诊长时间无返回
• 返回 LLM_STREAM_FAILED

排查：

• LLM_BASE_URL
• LLM_API_KEY
• LLM_FAST_MODEL
• 网络是否能访问模型服务
• 超时时间配置是否过短

建议：

• 先用 /api/v1/learning-assistant/chat/stream 测试最简单问题
• 查看 FastAPI 日志
• 确认模型服务账号额度

7. AI 学习助手没有知识库来源

现象：

retrieval_hit=false
retrieval_error=当前机构知识库暂未初始化或检索不可用...

说明：

这是允许的降级行为。学习助手会继续用 LLM 通用回答。

排查知识库：

• 用户是否有 institution_id
• 是否已有 kb_knowledge_space
• Milvus 是否运行
• Embedding 是否配置

8. Milvus 连接失败

排查：

docker compose ps milvus-standalone
docker compose logs --tail=200 milvus-standalone

检查 .env：

MILVUS_URI=http://milvus-standalone:19530
MILVUS_HOST=milvus-standalone
MILVUS_PORT=19530

9. PDF 下载失败

现象：

• 评价详情有，但 PDF 下载 404 或 500

排查：

• 评价是否属于当前 user_id
• 是否已经调用过导出 PDF
• storage/reports 是否挂载
• 容器是否有写权限

命令：

docker compose exec fastapi ls -lah /app/storage/reports

10. Docker build 失败

排查：

docker compose build fastapi

常见原因：

• requirements.txt 依赖下载失败
• 网络无法访问 pip 源
• Python 版本不兼容
• 文件编码或语法错误

本地先跑：

.\backend\.venv\Scripts\python.exe -m compileall app scripts tests

11. API 文档和实际接口不一致

排查：

curl http://8.160.178.88/fastapi/openapi.json

如果接口已改动：

• 更新 docs/03_api_design.md
• 运行 tests/test_api_contract.py
• 再提交 Git

12. Git 拉取后服务没变化

处理：

cd /home/code/medical-ai/fastapi
git log -1 --oneline

cd /home/code/medical-ai
docker compose build fastapi
docker compose up -d fastapi
docker compose logs --tail=200 fastapi

如果 requirements.txt 或 Dockerfile 有变动，必须重新 build。