# 环境部署
**本文引用的文件**
- [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)
## 目录
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["前端开发服务器
Vite (5173)"]
FE_DEV --> API_PROXY["Vite 代理 /api -> 后端 8000"]
subgraph "后端"
UVICORN["Uvicorn 服务器
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)