fastapi/docs/04_deployment.md

部署说明

本文档用于交接云服务器部署、更新、回滚和验证流程。

1. 服务器目录

当前云服务器目录约定：

/home/code/medical-ai/
├── django/
├── fastapi/
├── vueapp/
├── vuecms/
├── data/
├── logs/
└── docker-compose.yml

FastAPI 项目目录：

/home/code/medical-ai/fastapi

FastAPI 容器端口：

9000

公网 Nginx 路径：

http://8.160.178.88/fastapi/

2. 环境变量

服务器环境变量文件：

/home/code/medical-ai/fastapi/.env

.env 不提交 Git。首次部署时从模板复制：

cd /home/code/medical-ai
cp fastapi/.env.production.example fastapi/.env
vi fastapi/.env

必须确认：

• APP_ROOT_PATH=/fastapi
• DATABASE_URL 指向 Docker 网络中的 MySQL
• REDIS_URL 指向 Docker 网络中的 Redis
• AUTH_USER_ME_URL 指向 Django 容器或可访问地址
• LLM_API_KEY 已配置
• MILVUS_URI、MILVUS_HOST、MILVUS_PORT 与 docker-compose 一致
• EMBEDDING_API_KEY 如启用真实 embedding，需要配置

3. 首次部署

cd /home/code/medical-ai
git clone http://82.157.235.104:3000/Liu_JB/LiuJinbao.git fastapi
cp fastapi/.env.production.example fastapi/.env
vi fastapi/.env

docker compose build fastapi
docker compose up -d fastapi
docker compose logs --tail=200 fastapi

4. 日常更新

只更新 FastAPI：

cd /home/code/medical-ai/fastapi
git pull origin main

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

如果 requirements.txt 有变动，必须执行：

docker compose build fastapi

不能只执行 docker compose up -d fastapi。

5. 服务验证

容器内端口验证：

curl http://127.0.0.1:9000/health/ready

公网 Docs：

http://8.160.178.88/fastapi/docs

用户鉴权：

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

AI 学习助手流式问答：

curl -N -X POST "http://8.160.178.88/fastapi/api/v1/learning-assistant/chat/stream" \
  -H "Authorization: Bearer <access_token>" \
  -H "X-Entry-Scene: production_vue" \
  -H "Content-Type: application/json" \
  -d '{"question":"支气管肺炎有哪些典型临床表现？","top_k":5}'

正常应看到：

event: retrieval_done
event: answer_delta
event: answer_done

6. 查看日志

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

查看容器状态：

docker compose ps
docker ps

7. 回滚

查看历史提交：

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

回滚到指定提交：

git checkout <commit_id>

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

回到 main 最新版本：

cd /home/code/medical-ai/fastapi
git checkout main
git pull origin main

cd /home/code/medical-ai
docker compose build fastapi
docker compose up -d fastapi

8. 发布前检查

发布前至少确认：

• Git 工作区已提交
• requirements.txt 无冲突标记
• .env 配置完整
• docker compose build fastapi 成功
• docker compose up -d fastapi 成功
• /health/ready 可访问
• /fastapi/docs 可访问
• /api/v1/auth/me 可用
• 学习助手流式接口可用

9. 常见部署问题

现象	排查方向
/fastapi/docs 打不开	检查 Nginx /fastapi/ 代理和 APP_ROOT_PATH=/fastapi
容器启动失败	docker compose logs --tail=200 fastapi
依赖缺失	重新 docker compose build fastapi
MySQL 连接失败	检查 DATABASE_URL、MySQL 容器状态、网络名
Redis 连接失败	检查 REDIS_URL 和 Redis 容器
鉴权失败	检查 AUTH_USER_ME_URL 和 Django 服务
LLM 无响应	检查 LLM_API_KEY、模型名、网络和超时配置