docs: add handover and deployment guides

docs/04_deployment.md

@@ -0,0 +1,210 @@
+# 部署说明
+
+本文档用于交接云服务器部署、更新、回滚和验证流程。
+
+## 1. 服务器目录
+
+当前云服务器目录约定：
+
+```text
+/home/code/medical-ai/
+├── django/
+├── fastapi/
+├── vueapp/
+├── vuecms/
+├── data/
+├── logs/
+└── docker-compose.yml
+```
+
+FastAPI 项目目录：
+
+```text
+/home/code/medical-ai/fastapi
+```
+
+FastAPI 容器端口：
+
+```text
+9000
+```
+
+公网 Nginx 路径：
+
+```text
+http://8.160.178.88/fastapi/
+```
+
+## 2. 环境变量
+
+服务器环境变量文件：
+
+```text
+/home/code/medical-ai/fastapi/.env
+```
+
+`.env` 不提交 Git。首次部署时从模板复制：
+
+```bash
+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. 首次部署
+
+```bash
+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：
+
+```bash
+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` 有变动，必须执行：
+
+```bash
+docker compose build fastapi
+```
+
+不能只执行 `docker compose up -d fastapi`。
+
+## 5. 服务验证
+
+容器内端口验证：
+
+```bash
+curl http://127.0.0.1:9000/health/ready
+```
+
+公网 Docs：
+
+```text
+http://8.160.178.88/fastapi/docs
+```
+
+用户鉴权：
+
+```bash
+curl "http://8.160.178.88/fastapi/api/v1/auth/me" \
+  -H "Authorization: Bearer <access_token>" \
+  -H "X-Entry-Scene: production_vue"
+```
+
+AI 学习助手流式问答：
+
+```bash
+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}'
+```
+
+正常应看到：
+
+```text
+event: retrieval_done
+event: answer_delta
+event: answer_done
+```
+
+## 6. 查看日志
+
+```bash
+cd /home/code/medical-ai
+docker compose logs -f fastapi
+docker compose logs --tail=200 fastapi
+```
+
+查看容器状态：
+
+```bash
+docker compose ps
+docker ps
+```
+
+## 7. 回滚
+
+查看历史提交：
+
+```bash
+cd /home/code/medical-ai/fastapi
+git log --oneline
+```
+
+回滚到指定提交：
+
+```bash
+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 最新版本：
+
+```bash
+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`、模型名、网络和超时配置 |