提交文件

2026-02-28 15:16:15 +08:00
parent 1a4e50e0a4
commit 44f250f58e
159 changed files with 61268 additions and 0 deletions
--- a/.qoder/repowiki/zh/content/部署运维/环境部署.md
+++ b/.qoder/repowiki/zh/content/部署运维/环境部署.md
@@ -0,0 +1,352 @@
+# 环境部署
+
+<cite>
+**本文引用的文件**
+- [backend/.env.example](file://backend/.env.example)
+- [backend/requirements.txt](file://backend/requirements.txt)
+- [backend/app/core/config.py](file://backend/app/core/config.py)
+- [backend/app/main.py](file://backend/app/main.py)
+- [backend/init_db.py](file://backend/init_db.py)
+- [backend/alembic.ini](file://backend/alembic.ini)
+- [frontend/package.json](file://frontend/package.json)
+- [frontend/vite.config.js](file://frontend/vite.config.js)
+- [docs/backend.md](file://docs/backend.md)
+- [docs/frontend.md](file://docs/frontend.md)
+- [docs/database.md](file://docs/database.md)
+</cite>
+
+## 目录
+1. [简介](#简介)
+2. [项目结构](#项目结构)
+3. [核心组件](#核心组件)
+4. [架构总览](#架构总览)
+5. [详细组件分析](#详细组件分析)
+6. [依赖关系分析](#依赖关系分析)
+7. [性能注意事项](#性能注意事项)
+8. [故障排查指南](#故障排查指南)
+9. [结论](#结论)
+10. [附录](#附录)
+
+## 简介
+本指南面向开发与运维团队，提供“医院绩效系统”的完整环境部署方案，覆盖开发与生产环境的搭建步骤、Python 3.10+ 与 Node.js 环境准备、PostgreSQL 数据库安装、后端 FastAPI 与前端 Vue 依赖安装、环境变量配置、虚拟环境与依赖隔离、版本兼容性检查，以及 Docker 容器化与传统部署方案的对比说明。
+
+## 项目结构
+系统采用前后端分离架构：
+- 后端：Python + FastAPI + SQLAlchemy 2.x + Alembic + PostgreSQL
+- 前端：Vue 3 + Vite + Element Plus + Axios
+- 配置与文档：Pydantic Settings 管理后端配置；Vite 代理将前端请求转发至后端；Alembic 管理数据库迁移
+
+```mermaid
+graph TB
+subgraph "前端"
+FE_PKG["frontend/package.json"]
+FE_VITE["frontend/vite.config.js"]
+end
+subgraph "后端"
+BE_REQ["backend/requirements.txt"]
+BE_CFG["backend/app/core/config.py"]
+BE_MAIN["backend/app/main.py"]
+BE_ENV_EXAMPLE["backend/.env.example"]
+BE_ALEMBIC["backend/alembic.ini"]
+end
+FE_PKG --> FE_VITE
+BE_REQ --> BE_CFG
+BE_CFG --> BE_MAIN
+BE_ENV_EXAMPLE --> BE_CFG
+BE_ALEMBIC --> BE_CFG
+```
+
+图表来源
+- [frontend/package.json](file://frontend/package.json#L1-L27)
+- [frontend/vite.config.js](file://frontend/vite.config.js#L1-L22)
+- [backend/requirements.txt](file://backend/requirements.txt#L1-L17)
+- [backend/app/core/config.py](file://backend/app/core/config.py#L1-L47)
+- [backend/app/main.py](file://backend/app/main.py#L1-L92)
+- [backend/.env.example](file://backend/.env.example#L1-L11)
+- [backend/alembic.ini](file://backend/alembic.ini#L1-L44)
+
+章节来源
+- [docs/backend.md](file://docs/backend.md#L1-L475)
+- [docs/frontend.md](file://docs/frontend.md#L1-L416)
+- [docs/database.md](file://docs/database.md#L1-L286)
+
+## 核心组件
+- 后端配置与运行
+  - 配置来源：Pydantic Settings 从 .env 读取环境变量，支持调试模式、数据库连接、JWT 密钥、CORS、分页等参数
+  - 应用入口：FastAPI 应用创建、CORS 中间件注册、路由挂载、健康检查与异常处理
+- 数据库与迁移
+  - 数据库：PostgreSQL（异步驱动 asyncpg），默认 URL 与池大小、溢出配置
+  - 迁移：Alembic 管理数据库版本，支持升级/降级/历史查看
+- 前端开发与构建
+  - 依赖：Vue 3、Vue Router、Pinia、Element Plus、Axios、ECharts、Day.js、Vite、Sass
+  - 代理：Vite 将 /api 前缀代理到后端 8000 端口，解决跨域
+- 初始化脚本
+  - 数据库初始化：创建表并插入测试数据（若表为空）
+
+章节来源
+- [backend/app/core/config.py](file://backend/app/core/config.py#L9-L47)
+- [backend/app/main.py](file://backend/app/main.py#L15-L92)
+- [backend/alembic.ini](file://backend/alembic.ini#L1-L44)
+- [frontend/package.json](file://frontend/package.json#L1-L27)
+- [frontend/vite.config.js](file://frontend/vite.config.js#L1-L22)
+- [backend/init_db.py](file://backend/init_db.py#L11-L83)
+
+## 架构总览
+系统采用前后端分离部署：
+- 前端通过 Vite 开发服务器运行，开发时通过代理将 /api 请求转发到后端
+- 后端使用 Uvicorn 运行，暴露 REST API，Swagger UI 与 ReDoc 文档位于 /api/v1/docs 与 /api/v1/redoc
+- 数据库使用 PostgreSQL，Alembic 管理迁移
+
+```mermaid
+graph TB
+Browser["浏览器/客户端"] --> FE_DEV["前端开发服务器<br/>Vite (5173)"]
+FE_DEV --> API_PROXY["Vite 代理 /api -> 后端 8000"]
+subgraph "后端"
+UVICORN["Uvicorn 服务器<br/>FastAPI 应用 (8000)"]
+CORS["CORS 中间件"]
+ROUTER["API 路由 /api/v1/*"]
+LOGGING["日志与异常处理"]
+end
+UVICORN --> CORS
+UVICORN --> ROUTER
+UVICORN --> LOGGING
+ROUTER --> DB["PostgreSQL 数据库"]
+ROUTER --> ALEMBIC["Alembic 迁移"]
+```
+
+图表来源
+- [frontend/vite.config.js](file://frontend/vite.config.js#L12-L20)
+- [backend/app/main.py](file://backend/app/main.py#L19-L51)
+- [backend/alembic.ini](file://backend/alembic.ini#L7-L7)
+
+章节来源
+- [docs/backend.md](file://docs/backend.md#L454-L475)
+- [docs/frontend.md](file://docs/frontend.md#L380-L416)
+
+## 详细组件分析
+
+### 后端环境准备与依赖安装
+- Python 3.10+
+  - 建议使用虚拟环境隔离依赖，确保与系统 Python 解耦
+- 安装后端依赖
+  - 使用 requirements.txt 安装 FastAPI、SQLAlchemy、Alembic、Pydantic、JWT、密码哈希、异步数据库驱动等
+- 环境变量
+  - 复制 .env.example 为 .env，按需修改数据库连接、JWT 密钥、调试模式等
+- 数据库初始化
+  - 可选：执行数据库初始化脚本创建表与测试数据
+
+```mermaid
+flowchart TD
+Start(["开始"]) --> PyVer["检查 Python 3.10+"]
+PyVer --> Venv["创建并激活虚拟环境"]
+Venv --> PipReq["pip install -r backend/requirements.txt"]
+PipReq --> EnvCfg["复制 .env.example 为 .env 并配置参数"]
+EnvCfg --> DBInit{"是否需要初始化数据库?"}
+DBInit --> |是| RunInit["执行数据库初始化脚本"]
+DBInit --> |否| SkipInit["跳过初始化"]
+RunInit --> Done(["完成"])
+SkipInit --> Done
+```
+
+图表来源
+- [backend/requirements.txt](file://backend/requirements.txt#L1-L17)
+- [backend/.env.example](file://backend/.env.example#L1-L11)
+- [backend/init_db.py](file://backend/init_db.py#L11-L83)
+
+章节来源
+- [docs/backend.md](file://docs/backend.md#L454-L475)
+- [backend/requirements.txt](file://backend/requirements.txt#L1-L17)
+- [backend/.env.example](file://backend/.env.example#L1-L11)
+- [backend/init_db.py](file://backend/init_db.py#L11-L83)
+
+### 前端环境准备与依赖安装
+- Node.js 与包管理器
+  - 安装 Node.js，使用 npm 安装依赖
+- 安装前端依赖
+  - 依据 package.json 的 dependencies 与 devDependencies 安装
+- 开发与构建
+  - 开发：npm run dev
+  - 构建：npm run build
+  - 预览：npm run preview
+
+```mermaid
+flowchart TD
+StartFE(["开始"]) --> NodeCheck["检查 Node.js 版本"]
+NodeCheck --> NpmInstall["npm install"]
+NpmInstall --> DevRun["npm run dev (5173)"]
+DevRun --> ProxyCfg["Vite 代理 /api -> 后端 8000"]
+NpmInstall --> Build["npm run build (dist)"]
+Build --> Preview["npm run preview"]
+ProxyCfg --> DoneFE(["完成"])
+Preview --> DoneFE
+```
+
+图表来源
+- [frontend/package.json](file://frontend/package.json#L6-L10)
+- [frontend/vite.config.js](file://frontend/vite.config.js#L12-L20)
+
+章节来源
+- [docs/frontend.md](file://docs/frontend.md#L380-L416)
+- [frontend/package.json](file://frontend/package.json#L1-L27)
+- [frontend/vite.config.js](file://frontend/vite.config.js#L1-L22)
+
+### 数据库安装与迁移
+- PostgreSQL 安装
+  - 安装 PostgreSQL，创建数据库与用户
+- 连接配置
+  - 在 .env 或配置文件中设置 DATABASE_URL，确保与 alembic.ini 中的 SQLAlchemy URL 一致或按需调整
+- 迁移与升级
+  - 使用 Alembic 生成、升级、降级与查看迁移历史
+
+```mermaid
+flowchart TD
+DBStart(["开始"]) --> InstallPG["安装 PostgreSQL 并创建数据库"]
+InstallPG --> CfgURL["配置 DATABASE_URL (.env 或配置)"]
+CfgURL --> AlembicInit["初始化 Alembic (如未初始化)"]
+AlembicInit --> Gen["生成迁移 alembic revision --autogenerate"]
+Gen --> Upgrade["升级到最新 alembic upgrade head"]
+Upgrade --> DoneDB(["完成"])
+```
+
+图表来源
+- [backend/.env.example](file://backend/.env.example#L4-L4)
+- [backend/alembic.ini](file://backend/alembic.ini#L7-L7)
+- [docs/database.md](file://docs/database.md#L274-L285)
+
+章节来源
+- [docs/database.md](file://docs/database.md#L274-L285)
+- [backend/.env.example](file://backend/.env.example#L4-L4)
+- [backend/alembic.ini](file://backend/alembic.ini#L7-L7)
+
+### 环境变量配置说明
+- 必填项
+  - 数据库连接：DATABASE_URL（示例值来自 .env.example）
+  - JWT 密钥：SECRET_KEY（生产环境建议至少 32 字符且随机）
+  - 调试模式：DEBUG（开发环境开启，生产关闭）
+- 可选项
+  - CORS 允许源：CORS_ORIGINS（前端开发端口 3000/5173）
+  - API 前缀：API_PREFIX（默认 /api/v1）
+  - 数据库连接池：DATABASE_POOL_SIZE、DATABASE_MAX_OVERFLOW
+  - 分页参数：DEFAULT_PAGE_SIZE、MAX_PAGE_SIZE
+
+章节来源
+- [backend/.env.example](file://backend/.env.example#L1-L11)
+- [backend/app/core/config.py](file://backend/app/core/config.py#L18-L33)
+
+### 虚拟环境创建、依赖隔离与版本兼容性检查
+- 虚拟环境
+  - 使用 venv 或 conda 创建独立 Python 环境，避免全局污染
+- 依赖隔离
+  - 后端使用 requirements.txt；前端使用 package.json；分别在各自目录安装
+- 版本兼容性
+  - 后端：FastAPI >= 0.115、SQLAlchemy >= 2.0.36、Alembic >= 1.14、Pydantic >= 2.10、asyncpg >= 0.30、uvicorn >= 0.32
+  - 前端：Vue 3.4+、Vite 5.0+、Element Plus 2.5+、Axios 1.6+
+
+章节来源
+- [backend/requirements.txt](file://backend/requirements.txt#L1-L17)
+- [docs/backend.md](file://docs/backend.md#L3-L15)
+- [frontend/package.json](file://frontend/package.json#L11-L25)
+- [docs/frontend.md](file://docs/frontend.md#L3-L16)
+
+### Docker 容器化部署与传统部署对比
+- 传统部署（本机直装）
+  - 优点：部署简单、资源占用低、便于调试
+  - 缺点：环境差异大、依赖冲突风险高
+- 容器化部署（Docker）
+  - 优点：环境一致、可移植性强、易于扩展与回滚
+  - 缺点：学习成本、镜像体积与网络配置
+- 建议
+  - 生产环境优先采用容器化；开发环境可按需选择
+
+[本节为概念性说明，不直接分析具体文件，故无章节来源]
+
+## 依赖关系分析
+后端与前端的关键依赖关系如下：
+
+```mermaid
+graph LR
+subgraph "后端依赖"
+FASTAPI["FastAPI"]
+SQLA["SQLAlchemy 2.x"]
+ALEMBIC["Alembic"]
+PYDANTIC["Pydantic / Pydantic Settings"]
+ASYNC["asyncpg / aiosqlite"]
+UVICORN["Uvicorn"]
+end
+subgraph "前端依赖"
+VUE["Vue 3"]
+ROUTER["Vue Router"]
+PINIA["Pinia"]
+AXIOS["Axios"]
+ELEM["Element Plus"]
+ECHARTS["ECharts"]
+DAYJS["Day.js"]
+VITE["Vite"]
+SASS["Sass"]
+end
+VITE --> AXIOS
+AXIOS --> BACKEND["后端 API (/api/v1)"]
+BACKEND --> SQLA
+SQLA --> ALEMBIC
+BACKEND --> ASYNC
+BACKEND --> UVICORN
+BACKEND --> PYDANTIC
+```
+
+图表来源
+- [backend/requirements.txt](file://backend/requirements.txt#L1-L17)
+- [frontend/package.json](file://frontend/package.json#L11-L25)
+
+章节来源
+- [backend/requirements.txt](file://backend/requirements.txt#L1-L17)
+- [frontend/package.json](file://frontend/package.json#L1-L27)
+
+## 性能注意事项
+- 数据库连接池
+  - 合理设置连接池大小与溢出数量，避免高并发下的连接争用
+- 异步 I/O
+  - 使用异步数据库驱动与异步 ORM，提升 I/O 密集场景性能
+- 前端静态资源
+  - 生产构建后启用缓存与压缩，减少带宽与加载时间
+- 日志与监控
+  - 生产环境开启结构化日志，结合外部监控系统追踪性能瓶颈
+
+[本节提供一般性指导，不直接分析具体文件，故无章节来源]
+
+## 故障排查指南
+- 前端跨域问题
+  - 确认 Vite 代理配置指向后端 8000 端口，代理前缀 /api 与后端 API 前缀一致
+- 后端无法连接数据库
+  - 检查 DATABASE_URL、数据库服务状态、网络连通性与凭据
+- JWT 令牌无效
+  - 确认 SECRET_KEY 设置正确且前后端一致，注意生产环境必须足够复杂
+- Alembic 迁移失败
+  - 检查迁移脚本与数据库版本一致性，必要时执行降级再升级
+- 健康检查
+  - 访问后端 /health 端点确认服务可用
+
+章节来源
+- [frontend/vite.config.js](file://frontend/vite.config.js#L14-L18)
+- [backend/app/main.py](file://backend/app/main.py#L54-L56)
+- [docs/backend.md](file://docs/backend.md#L454-L475)
+- [docs/frontend.md](file://docs/frontend.md#L396-L416)
+
+## 结论
+通过本指南，您可以在开发与生产环境中快速搭建“医院绩效系统”。建议：
+- 使用虚拟环境隔离后端依赖，使用包管理器安装前端依赖
+- 正确配置 .env 与配置模块，确保数据库、JWT、CORS 等关键参数生效
+- 使用 Alembic 管理数据库迁移，生产环境优先容器化部署
+- 遵循版本兼容性要求，关注性能与可观测性
+
+[本节为总结性内容，不直接分析具体文件，故无章节来源]
+
+## 附录
+- 快速命令参考
+  - 后端安装与运行：pip install -r backend/requirements.txt；uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
+  - 前端安装与运行：npm install；npm run dev；npm run build；npm run preview
+  - 数据库迁移：alembic revision --autogenerate -m "..."；alembic upgrade head；alembic downgrade -1；alembic history
+
+章节来源
+- [docs/backend.md](file://docs/backend.md#L454-L475)
+- [docs/frontend.md](file://docs/frontend.md#L380-L416)
+- [docs/database.md](file://docs/database.md#L274-L285)