刘金宝
248 lines
4.0 KiB
Markdown
248 lines
4.0 KiB
Markdown
# 常见故障排查
|
||
|
||
本文档用于接手人快速定位本地和云服务器常见问题。
|
||
|
||
## 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。
|