chenqi/hospital_performance
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
hospital_performance/.qoder/repowiki/zh/content/部署运维/环境部署.md
chenqi 44f250f58e 提交文件
2026-02-28 15:16:15 +08:00

13 KiB
Raw Permalink Blame History

环境部署

**本文引用的文件** - [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 管理数据库迁移
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

图表来源

章节来源

核心组件

  • 后端配置与运行
    • 配置来源：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 端口，解决跨域
  • 初始化脚本
    • 数据库初始化：创建表并插入测试数据（若表为空）

章节来源

架构总览

系统采用前后端分离部署：

  • 前端通过 Vite 开发服务器运行，开发时通过代理将 /api 请求转发到后端
  • 后端使用 Uvicorn 运行，暴露 REST API，Swagger UI 与 ReDoc 文档位于 /api/v1/docs 与 /api/v1/redoc
  • 数据库使用 PostgreSQL，Alembic 管理迁移
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 迁移"]

图表来源

章节来源

详细组件分析

后端环境准备与依赖安装

  • Python 3.10+
    • 建议使用虚拟环境隔离依赖，确保与系统 Python 解耦
  • 安装后端依赖
    • 使用 requirements.txt 安装 FastAPI、SQLAlchemy、Alembic、Pydantic、JWT、密码哈希、异步数据库驱动等
  • 环境变量
    • 复制 .env.example 为 .env，按需修改数据库连接、JWT 密钥、调试模式等
  • 数据库初始化
    • 可选：执行数据库初始化脚本创建表与测试数据
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

图表来源

章节来源

前端环境准备与依赖安装

  • Node.js 与包管理器
    • 安装 Node.js，使用 npm 安装依赖
  • 安装前端依赖
    • 依据 package.json 的 dependencies 与 devDependencies 安装
  • 开发与构建
    • 开发：npm run dev
    • 构建：npm run build
    • 预览：npm run preview
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

图表来源

章节来源

数据库安装与迁移

  • PostgreSQL 安装
    • 安装 PostgreSQL，创建数据库与用户
  • 连接配置
    • 在 .env 或配置文件中设置 DATABASE_URL，确保与 alembic.ini 中的 SQLAlchemy URL 一致或按需调整
  • 迁移与升级
    • 使用 Alembic 生成、升级、降级与查看迁移历史
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(["完成"])

图表来源

章节来源

环境变量配置说明

  • 必填项
    • 数据库连接：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

章节来源

虚拟环境创建、依赖隔离与版本兼容性检查

  • 虚拟环境
    • 使用 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+

章节来源

Docker 容器化部署与传统部署对比

  • 传统部署（本机直装）
    • 优点：部署简单、资源占用低、便于调试
    • 缺点：环境差异大、依赖冲突风险高
  • 容器化部署（Docker）
    • 优点：环境一致、可移植性强、易于扩展与回滚
    • 缺点：学习成本、镜像体积与网络配置
  • 建议
    • 生产环境优先采用容器化；开发环境可按需选择

[本节为概念性说明，不直接分析具体文件，故无章节来源]

依赖关系分析

后端与前端的关键依赖关系如下：

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

图表来源

章节来源

性能注意事项

  • 数据库连接池
    • 合理设置连接池大小与溢出数量，避免高并发下的连接争用
  • 异步 I/O
    • 使用异步数据库驱动与异步 ORM，提升 I/O 密集场景性能
  • 前端静态资源
    • 生产构建后启用缓存与压缩，减少带宽与加载时间
  • 日志与监控
    • 生产环境开启结构化日志，结合外部监控系统追踪性能瓶颈

[本节提供一般性指导，不直接分析具体文件，故无章节来源]

故障排查指南

  • 前端跨域问题
    • 确认 Vite 代理配置指向后端 8000 端口，代理前缀 /api 与后端 API 前缀一致
  • 后端无法连接数据库
    • 检查 DATABASE_URL、数据库服务状态、网络连通性与凭据
  • JWT 令牌无效
    • 确认 SECRET_KEY 设置正确且前后端一致，注意生产环境必须足够复杂
  • Alembic 迁移失败
    • 检查迁移脚本与数据库版本一致性，必要时执行降级再升级
  • 健康检查
    • 访问后端 /health 端点确认服务可用

章节来源

结论

通过本指南，您可以在开发与生产环境中快速搭建“医院绩效系统”。建议：

  • 使用虚拟环境隔离后端依赖，使用包管理器安装前端依赖
  • 正确配置 .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

章节来源