prepare fastapi root layout for server deployment

2026-06-04 10:55:23 +08:00
parent eb43573a44
commit b46e43aadc
103 changed files with 347 additions and 197 deletions
@@ -1,143 +1,174 @@
-# 医疗问诊 Agent 后端
+# 医疗问诊 Agent FastAPI 后端

-医疗问诊 Agent 是宿主医疗教学平台中的问诊训练子功能。后端基于 FastAPI 构建，负责病例读取、训练会话、多轮问诊、检查申请、诊断治疗提交、AI 评价、PDF 报告导出和历史记录查询。
+医疗问诊 Agent 是医疗教学平台中的问诊训练服务。后端负责 Django 用户身份校验、病例读取、多轮问诊、检查申请、诊断治疗提交、AI 评价、评分明细、PDF 报告和历史训练记录。

-## 技术栈
+## 项目结构
+
+仓库根目录可以直接部署为服务器的 `fastapi/` 目录：
+
+```text
+fastapi/
+├── app/                    # FastAPI 应用、Agent、服务、模型与提示词
+├── scripts/                # 数据库迁移、结构检查与运维脚本
+├── tests/                  # 核心逻辑与接口测试
+├── Dockerfile
+├── requirements.txt
+├── .env.example
+└── .env.production.example
+```
+
+## 核心依赖

 - Python 3.11
 - FastAPI
 - SQLAlchemy 2.x
- MySQL
- Redis
- OpenAI-compatible LLM Adapter
- ReportLab PDF
-
-## 核心功能
-
- Django 用户中心 token 校验
- 病例列表与病例详情
- 病例 SQL 安全导入与删除
- 训练会话创建
- 多轮问诊与 SSE 流式回复
- 练习提示
- 检查/检验申请
- 诊断与治疗提交
- AI 评价报告生成
- 评分明细落库
- PDF 报告导出
- 历史评价查询
- LLM Fast/Reason 测试
+- MySQL 8
+- Redis 7
+- OpenAI-compatible LLM API
+- Django 用户中心 `/api/user/users/me/`

 ## 本地启动

 ```powershell
-cd backend
 python -m venv .venv
 .\.venv\Scripts\activate
 pip install -r requirements.txt
-cd ..
 copy .env.example .env
-```
-
-编辑 `.env`，填写 MySQL、Redis、Django 用户中心和 LLM 配置。
-
-启动服务：
-
-```powershell
-cd backend
 uvicorn app.main:app --host 127.0.0.1 --port 9000
 ```

-访问：
+本地 Swagger：

 ```text
 http://127.0.0.1:9000/docs
 ```

-## Docker 启动
+真实密码、LLM Key 和 access token 只写入本地 `.env` 或服务器环境变量，不提交到 Git。

-```powershell
-copy .env.example .env
-docker build -t medical-consultation-agent-backend .
-docker run --env-file .env -p 9000:9000 medical-consultation-agent-backend
+## Docker Compose 部署
+
+服务器目录：
+
+```text
+/home/code/medical-ai/
+├── django/
+├── fastapi/                # 本仓库
+├── vueapp/
+├── vuecms/
+└── docker-compose.yml
 ```

-## 环境变量
+首次拉取：

-关键配置见 `.env.example`：
-
-```env
-DATABASE_URL=mysql+pymysql://root:<password>@mysql:3306/medical_platform?charset=utf8mb4
-MYSQL_URL=mysql+aiomysql://root:<password>@mysql:3306/medical_platform?charset=utf8mb4
-REDIS_URL=redis://redis:6379/0
-AUTH_USER_ME_URL=http://django:8000/api/user/users/me/
-LLM_BASE_URL=https://api.deepseek.com/chat/completions
-LLM_API_KEY=
+```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
 ```

-真实数据库密码、LLM Key 和 access token 只写入本地 `.env` 或部署环境变量。
+必须在服务器 `.env` 中填写：
+
+- MySQL 密码和数据库名
+- `LLM_API_KEY`
+- 实际前端来源 `CORS_ALLOW_ORIGINS`
+- Nginx 使用 `/fastapi/` 前缀时保留 `APP_ROOT_PATH=/fastapi`
+
+父目录 `docker-compose.yml` 的 FastAPI 服务需要包含：
+
+```yaml
+fastapi:
+  build:
+    context: ./fastapi
+  container_name: fastapi
+  restart: always
+  ports:
+    - "9000:9000"
+  env_file:
+    - ./fastapi/.env
+  volumes:
+    - ./logs/fastapi:/app/logs
+    - ./data/fastapi-reports:/app/storage/reports
+  depends_on:
+    - mysql
+    - redis
+    - django
+  networks:
+    - medical
+```
+
+构建并启动：
+
+```bash
+cd /home/code/medical-ai
+docker compose config
+docker compose build fastapi
+docker compose up -d fastapi
+docker compose logs --tail=200 fastapi
+```
+
+后续更新：
+
+```bash
+cd /home/code/medical-ai/fastapi
+git pull origin main
+cd ..
+docker compose build fastapi
+docker compose up -d fastapi
+```

 ## 数据库初始化与检查

-数据库需先创建好，表结构由后端脚本创建和校验。
-
-```powershell
-cd backend
-.\.venv\Scripts\python.exe scripts\migrate_to_new_schema.py
-.\.venv\Scripts\python.exe scripts\migrate_user_department_score_detail.py
-.\.venv\Scripts\python.exe scripts\check_final_schema.py
-.\.venv\Scripts\python.exe scripts\check_final_demo_readiness.py
-```
-
-清空训练运行数据和本地报告文件：
-
-```powershell
-cd backend
-.\.venv\Scripts\python.exe scripts\clear_training_runtime_data.py --confirm CLEAR_TRAINING_DATA --reports
-```
-
-该脚本只清理训练会话、检查申请、提交、评价记录、评分明细、审计日志和本地 PDF 报告，不删除病例、用户、科室、检查项、评分规则、提示词和知识库。
-
-## 用户认证
-
-前端请求医疗问诊 Agent 时携带宿主系统 access token：
-
-```http
-Authorization: Bearer <access_token>
-X-Entry-Scene: mac_vue_dev
-```
-
-后端会转发 token 到 Django 用户中心：
-
-```text
-GET /api/user/users/me/
-```
-
-Django 返回 200 后，后端使用返回的 `id` 作为本系统内部用户隔离 ID。前端不需要传 `X-User-Id`。
-
-验证接口：
+服务启动后先进行只读结构检查：

 ```bash
-curl -X GET "http://127.0.0.1:9000/api/v1/auth/me" \
+cd /home/code/medical-ai
+docker compose exec fastapi python scripts/check_final_schema.py
+docker compose exec fastapi python scripts/check_final_demo_readiness.py
+```
+
+仅在结构检查确认缺少 Agent 所需表时，备份数据库后执行：
+
+```bash
+docker compose exec fastapi python scripts/migrate_to_new_schema.py
+docker compose exec fastapi python scripts/migrate_user_department_score_detail.py
+```
+
+迁移脚本使用 `create_all` 补齐 Agent 所需表，不删除 Django 或现有业务表；`migrate_to_new_schema.py` 会在缺少对应数据时写入 Demo 病例和基础数据。
+
+## 部署验证
+
+容器内部端口验证：
+
+```bash
+curl http://127.0.0.1:9000/health/live
+curl http://127.0.0.1:9000/health/ready
+```
+
+使用 Nginx `/fastapi/` 代理后的公网验证：
+
+```text
+http://8.160.178.88/fastapi/docs
+http://8.160.178.88/fastapi/openapi.json
+http://8.160.178.88/fastapi/health/ready
+```
+
+`/health/live` 返回 200 表示 FastAPI 进程正常。`/health/ready` 返回 200 表示 MySQL、Redis 和关键配置已经就绪；返回 503 时查看响应中的检查项和容器日志。
+
+验证 Django 用户中心联调：
+
+```bash
+curl "http://8.160.178.88/fastapi/api/v1/auth/me" \
  -H "Authorization: Bearer <access_token>" \
-  -H "X-Entry-Scene: mac_vue_dev"
+  -H "X-Entry-Scene: production_vue"
 ```

 ## 测试

 ```powershell
-cd backend
-.\.venv\Scripts\python.exe -m compileall app scripts tests
-.\.venv\Scripts\python.exe tests\test_core_logic.py
-.\.venv\Scripts\python.exe tests\test_api_contract.py
-.\.venv\Scripts\python.exe tests\test_demo_flow.py
-```
-
-## API 文档
-
-启动后访问：
-
-```text
-http://127.0.0.1:9000/docs
-http://127.0.0.1:9000/openapi.json
+python -m compileall app scripts tests
+python tests\test_core_logic.py
+python tests\test_api_contract.py
+python tests\test_demo_flow.py
+python tests\test_import_source_case_sql.py
 ```