fastapi/docs/07_troubleshooting.md

# 常见故障排查

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

## 1. `/fastapi/docs` 打不开

现象：

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

排查：

```bash
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`

处理：

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

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

现象：

```json
{
  "code": "AUTH_CREDENTIAL_REQUIRED"
}
```

排查：

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

验证：

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

## 3. Django 用户中心不可达

现象：

```json
{
  "code": "AUTH_USER_CENTER_UNAVAILABLE"
}
```

排查：

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

处理：

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

## 4. MySQL 连接失败

现象：

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

排查：

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

检查 `.env`：

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

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

## 5. Redis 连接失败

排查：

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

检查 `.env`：

```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 学习助手没有知识库来源

现象：

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

说明：

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

排查知识库：

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

## 8. Milvus 连接失败

排查：

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

检查 `.env`：

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

## 9. PDF 下载失败

现象：

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

排查：

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

命令：

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

## 10. Docker build 失败

排查：

```bash
docker compose build fastapi
```

常见原因：

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

本地先跑：

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

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

排查：

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

如果接口已改动：

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

## 12. Git 拉取后服务没变化

处理：

```bash
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。