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

14 KiB
Raw Permalink Blame History

部署运维

**本文引用的文件** - [backend/app/main.py](file://backend/app/main.py) - [backend/app/core/config.py](file://backend/app/core/config.py) - [backend/.env.example](file://backend/.env.example) - [backend/requirements.txt](file://backend/requirements.txt) - [backend/init_db.py](file://backend/init_db.py) - [backend/app/core/database.py](file://backend/app/core/database.py) - [backend/app/core/logging_config.py](file://backend/app/core/logging_config.py) - [backend/app/api/v1/__init__.py](file://backend/app/api/v1/__init__.py) - [docs/backend.md](file://docs/backend.md) - [docs/database.md](file://docs/database.md) - [frontend/package.json](file://frontend/package.json)

目录

  1. 简介
  2. 项目结构
  3. 核心组件
  4. 架构总览
  5. 详细组件分析
  6. 依赖关系分析
  7. 性能考虑
  8. 故障排查指南
  9. 结论
  10. 附录

简介

本指南面向医院绩效系统的生产部署与运维，覆盖以下主题：

  • 生产环境部署流程与环境变量配置
  • Docker 容器化部署与 Nginx 反向代理、SSL 证书管理
  • 数据库备份策略、日志管理与性能监控
  • 负载均衡、高可用架构与灾难恢复计划
  • 运维脚本、自动化部署与版本升级流程
  • 安全加固、漏洞扫描与合规性检查

项目结构

后端采用 FastAPI + SQLAlchemy 2.0 异步架构，前端为 Vue 3 + Vite。系统通过 .env 管理运行时配置，支持 Alembic 数据库迁移。

graph TB
subgraph "后端"
A["app/main.py<br/>应用入口与路由注册"]
B["app/core/config.py<br/>配置管理"]
C["app/core/database.py<br/>异步数据库引擎"]
D["app/core/logging_config.py<br/>日志配置"]
E["app/api/v1/__init__.py<br/>路由聚合"]
F["init_db.py<br/>初始化与测试数据"]
end
subgraph "前端"
G["frontend/package.json<br/>构建与依赖"]
end
A --> E
A --> B
A --> D
E --> C
F --> C
G --> A

图表来源

章节来源

核心组件

  • 应用入口与路由：创建 FastAPI 实例、注册 CORS、健康检查、全局异常处理，并挂载 v1 路由前缀。
  • 配置管理：集中管理应用名称、版本、调试模式、API 前缀、数据库连接、JWT 密钥算法与过期时间、CORS 源、分页参数等。
  • 数据库层：异步 SQLAlchemy 引擎与会话工厂，提供依赖注入式数据库会话。
  • 日志模块：按日轮转的多处理器日志记录，区分应用日志与错误日志。
  • 初始化脚本：自动建表与插入测试数据，避免重复初始化。

章节来源

架构总览

系统采用前后端分离架构，后端提供 REST API，前端通过 Axios 访问后端接口；数据库为 PostgreSQL，使用异步驱动。

graph TB
FE["前端应用<br/>Vue 3 + Vite"] --> API["后端API<br/>FastAPI"]
API --> DB["数据库<br/>PostgreSQL"]
API --> LOG["日志系统<br/>按日轮转"]
API --> CFG["配置中心<br/>.env + pydantic-settings"]

图表来源

详细组件分析

配置管理（Settings）

  • 环境变量文件：.env.example 提供数据库 URL、JWT 密钥、调试开关等示例。
  • 运行时配置：Settings 使用 pydantic-settings 从 .env 加载，支持缓存单例。
  • 关键项：
    • 应用名称与版本、调试模式、API 前缀
    • 数据库连接串、连接池大小与溢出
    • JWT 密钥、算法与过期时间
    • CORS 源列表
    • 分页默认与最大页大小

章节来源

数据库层（异步引擎与会话）

  • 异步引擎：基于配置的 DATABASE_URL 创建 asyncpg 引擎，DEBUG 控制 echo。
  • 会话工厂：异步会话构造与生命周期管理，提供依赖注入。
  • 依赖函数：get_db 提供事务语义（提交/回滚/关闭），确保异常安全。

章节来源

日志模块（RotatingFileHandler）

  • 日志目录：位于 backend/logs，按日期命名文件。
  • 处理器：
    • 控制台 INFO 级别输出
    • 文件 DEBUG 级别轮转（10MB，保留7份）
    • 错误 ERROR 级别单独文件轮转
  • 获取子日志器：统一命名空间，便于模块化追踪。

章节来源

应用入口与路由（FastAPI）

  • 应用实例：设置标题、版本、OpenAPI 文档路径前缀。
  • CORS 中间件：允许指定源、凭证、方法与头。
  • 路由注册：聚合 v1 子路由，统一前缀。
  • 健康检查：/health 返回状态与版本。
  • 异常处理：HTTP、请求校验、全局异常统一记录与抛出。

章节来源

初始化脚本（建表与测试数据）

  • 自动建表：创建所有模型对应的数据表。
  • 测试数据：若 departments 表为空则批量插入默认数据。
  • 管理员账户：创建 admin 用户并设置密码哈希。

章节来源

前端构建与依赖

  • 构建脚本：dev/build/preview。
  • 依赖：Vue 3、Vue Router、Pinia、Axios、Element Plus、ECharts、Day.js。
  • 与后端交互：通过 Axios 访问后端 API（具体接口见 API 文档）。

章节来源

依赖关系分析

后端模块之间的依赖关系如下：

graph LR
main_py["app/main.py"] --> api_v1_init["app/api/v1/__init__.py"]
main_py --> cfg_py["app/core/config.py"]
main_py --> log_cfg_py["app/core/logging_config.py"]
api_v1_init --> db_py["app/core/database.py"]
init_db_py["init_db.py"] --> db_py

图表来源

性能考虑

  • 数据库连接池：通过配置 DATABASE_POOL_SIZE 与 DATABASE_MAX_OVERFLOW 控制并发与溢出。
  • 异步 I/O：使用 SQLAlchemy 2.0 异步引擎与 asyncpg，减少阻塞。
  • 日志级别：生产建议提升控制台级别至 INFO，避免过多 DEBUG 输出。
  • 分页限制：MAX_PAGE_SIZE 限制单页最大条数，防止资源滥用。
  • 健康检查：/health 用于探活，结合负载均衡实现快速摘除不健康实例。

章节来源

故障排查指南

  • 健康检查失败：确认 /health 返回 healthy 与版本号。
  • 数据库连接异常：检查 DATABASE_URL、网络连通性与 PostgreSQL 服务状态。
  • 日志定位：查看 backend/logs 下按日期命名的日志文件，优先关注 ERROR 日志。
  • CORS 问题：确认前端地址在 CORS_ORIGINS 列表中。
  • 初始化未生效：确认 init_db.py 执行顺序与数据库权限。

章节来源

结论

本指南提供了从配置、部署到运维监控的完整实践路径。建议在生产环境中严格管理 .env，启用 HTTPS 与 TLS，完善数据库备份与日志归档，并结合负载均衡与健康检查实现高可用。

附录

A. 生产环境部署流程

  • 准备阶段
    • 准备 PostgreSQL 实例，创建数据库与用户。
    • 生成并妥善保管 SECRET_KEY（至少 32 字符）。
  • 配置
    • 复制 .env.example 为 .env，填写 DATABASE_URL、SECRET_KEY、DEBUG=false。
    • 设置 CORS_ORIGINS 为前端域名或 IP。
  • 启动
    • 安装依赖：pip install -r backend/requirements.txt
    • 初始化数据库：python backend/init_db.py
    • 启动服务：uvicorn app.main:app --host 0.0.0.0 --port 8000
  • 验证
    • 访问 /health 检查服务状态
    • 访问 /api/v1/docs 或 /api/v1/redoc 查看接口文档

章节来源

B. 环境变量清单

  • DATABASE_URL：数据库连接串（PostgreSQL）
  • SECRET_KEY：JWT 密钥
  • DEBUG：调试模式开关
  • CORS_ORIGINS：允许跨域的源列表
  • API_PREFIX：API 前缀（如 /api/v1）

章节来源

C. Docker 容器化部署（步骤说明）

  • 构建镜像
    • 基于 Python 3.11+ 镜像
    • 复制 requirements.txt 并安装依赖
    • 复制后端代码与 .env
    • 暴露端口 8000
  • 运行容器
    • 挂载日志目录 backend/logs 至宿主机
    • 指定环境变量（DATABASE_URL、SECRET_KEY、DEBUG、CORS_ORIGINS、API_PREFIX）
    • 通过健康检查 /health 配置探针
  • 注意
    • 将 .env 放置于受控位置，避免泄露
    • 使用只读卷挂载代码，仅挂载日志目录为可写

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

D. Nginx 反向代理与 SSL 证书

  • 反代配置要点
    • 将 /api/* 反代至后端服务（如 http://backend:8000）
    • 静态资源指向前端 dist 目录（如 /dist）
    • 启用 gzip/ssl，开启 HSTS
  • SSL 证书
    • 使用 Let’s Encrypt 或企业 CA
    • 自动续期脚本与监控告警
  • 健康检查
    • upstream 中配置 /health 探针，失败自动摘除

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

E. 数据库备份策略

  • 全量备份：每周日凌晨执行 pg_dump -U -h > backup.sql
  • 增量/归档：开启 WAL 归档，配合 PITR
  • 存储备份：加密存储于对象存储或磁带库，保留 4-8 周
  • 验证恢复：每季度执行恢复演练

[本节为通用运维实践，不直接分析具体文件，故无“章节来源”]

F. 日志管理与性能监控

  • 日志
    • 后端：backend/logs 按日轮转，保留 7 天
    • 前端：浏览器控制台与网络面板排查
  • 监控
    • 指标：CPU/内存/连接数/慢查询/错误率
    • 告警：阈值触发与收敛策略
    • 链路追踪：结合 OpenTelemetry 或 APM

[本节为通用运维实践，不直接分析具体文件，故无“章节来源”]

G. 负载均衡、高可用与灾难恢复

  • 高可用
    • 多实例部署（至少 2 个后端实例）
    • PostgreSQL 主从复制或托管服务
    • 健康检查与自动摘除
  • 灾难恢复
    • RTO/RPO 目标明确
    • 快速恢复流程与角色分工
    • 定期演练与文档更新

[本节为通用运维实践，不直接分析具体文件，故无“章节来源”]

H. 运维脚本、自动化部署与版本升级

  • 自动化
    • CI/CD：拉取代码 → 单元测试 → 构建镜像 → 发布
    • 蓝绿/滚动发布：灰度流量切换
  • 升级流程
    • 数据库迁移：alembic upgrade head
    • 前后端版本对齐：锁定依赖版本
    • 回滚预案：镜像标签回滚与数据库 downgrade

章节来源

I. 安全加固、漏洞扫描与合规

  • 安全加固
    • 禁用 DEBUG，最小权限原则
    • 强密码与密钥轮换，HTTPS 强传输
    • 输入校验与 SQL 注入防护（ORM 已内置）
  • 漏洞扫描
    • 依赖扫描：pip-audit/安全扫描工具
    • 漏洞修复与补丁管理
  • 合规
    • 数据最小化与访问审计
    • 签名与完整性校验（如需要）

[本节为通用运维实践，不直接分析具体文件，故无“章节来源”]