# 部署运维

<cite>
**本文引用的文件**
- [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)
</cite>

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

## 简介
本指南面向医院绩效系统的生产部署与运维，覆盖以下主题：
- 生产环境部署流程与环境变量配置
- Docker 容器化部署与 Nginx 反向代理、SSL 证书管理
- 数据库备份策略、日志管理与性能监控
- 负载均衡、高可用架构与灾难恢复计划
- 运维脚本、自动化部署与版本升级流程
- 安全加固、漏洞扫描与合规性检查

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

```mermaid
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
```

图表来源
- [backend/app/main.py](file://backend/app/main.py#L1-L92)
- [backend/app/core/config.py](file://backend/app/core/config.py#L1-L47)
- [backend/app/core/database.py](file://backend/app/core/database.py#L1-L39)
- [backend/app/core/logging_config.py](file://backend/app/core/logging_config.py#L1-L65)
- [backend/app/api/v1/__init__.py](file://backend/app/api/v1/__init__.py#L1-L17)
- [backend/init_db.py](file://backend/init_db.py#L1-L83)
- [frontend/package.json](file://frontend/package.json#L1-L27)

章节来源
- [backend/app/main.py](file://backend/app/main.py#L1-L92)
- [docs/backend.md](file://docs/backend.md#L1-L475)

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

章节来源
- [backend/app/main.py](file://backend/app/main.py#L15-L77)
- [backend/app/core/config.py](file://backend/app/core/config.py#L9-L47)
- [backend/app/core/database.py](file://backend/app/core/database.py#L9-L39)
- [backend/app/core/logging_config.py](file://backend/app/core/logging_config.py#L10-L65)
- [backend/init_db.py](file://backend/init_db.py#L11-L83)

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

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

图表来源
- [docs/backend.md](file://docs/backend.md#L3-L15)
- [backend/app/main.py](file://backend/app/main.py#L19-L51)
- [backend/app/core/database.py](file://backend/app/core/database.py#L10-L20)
- [backend/app/core/logging_config.py](file://backend/app/core/logging_config.py#L18-L20)
- [backend/app/core/config.py](file://backend/app/core/config.py#L35-L37)

## 详细组件分析

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

章节来源
- [backend/app/core/config.py](file://backend/app/core/config.py#L9-L47)
- [backend/.env.example](file://backend/.env.example#L1-L11)

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

章节来源
- [backend/app/core/database.py](file://backend/app/core/database.py#L9-L39)

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

章节来源
- [backend/app/core/logging_config.py](file://backend/app/core/logging_config.py#L10-L65)

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

章节来源
- [backend/app/main.py](file://backend/app/main.py#L15-L77)
- [backend/app/api/v1/__init__.py](file://backend/app/api/v1/__init__.py#L1-L17)

### 初始化脚本（建表与测试数据）
- 自动建表：创建所有模型对应的数据表。
- 测试数据：若 departments 表为空则批量插入默认数据。
- 管理员账户：创建 admin 用户并设置密码哈希。

章节来源
- [backend/init_db.py](file://backend/init_db.py#L11-L83)

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

章节来源
- [frontend/package.json](file://frontend/package.json#L6-L26)
- [docs/backend.md](file://docs/backend.md#L470-L475)

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

```mermaid
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
```

图表来源
- [backend/app/main.py](file://backend/app/main.py#L10-L51)
- [backend/app/api/v1/__init__.py](file://backend/app/api/v1/__init__.py#L1-L17)
- [backend/app/core/config.py](file://backend/app/core/config.py#L9-L47)
- [backend/app/core/logging_config.py](file://backend/app/core/logging_config.py#L27-L65)
- [backend/app/core/database.py](file://backend/app/core/database.py#L9-L39)
- [backend/init_db.py](file://backend/init_db.py#L14-L15)

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

章节来源
- [backend/app/core/config.py](file://backend/app/core/config.py#L18-L33)
- [backend/app/core/database.py](file://backend/app/core/database.py#L10-L20)
- [backend/app/main.py](file://backend/app/main.py#L53-L56)

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

章节来源
- [backend/app/main.py](file://backend/app/main.py#L53-L77)
- [backend/app/core/logging_config.py](file://backend/app/core/logging_config.py#L18-L20)
- [backend/app/core/config.py](file://backend/app/core/config.py#L28-L29)
- [backend/init_db.py](file://backend/init_db.py#L20-L25)

## 结论
本指南提供了从配置、部署到运维监控的完整实践路径。建议在生产环境中严格管理 .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 查看接口文档

章节来源
- [backend/.env.example](file://backend/.env.example#L1-L11)
- [backend/requirements.txt](file://backend/requirements.txt#L1-L17)
- [backend/init_db.py](file://backend/init_db.py#L81-L83)
- [docs/backend.md](file://docs/backend.md#L454-L475)

### B. 环境变量清单
- DATABASE_URL：数据库连接串（PostgreSQL）
- SECRET_KEY：JWT 密钥
- DEBUG：调试模式开关
- CORS_ORIGINS：允许跨域的源列表
- API_PREFIX：API 前缀（如 /api/v1）

章节来源
- [backend/.env.example](file://backend/.env.example#L3-L10)
- [backend/app/core/config.py](file://backend/app/core/config.py#L12-L33)

### 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 <user> -h <host> <db> > 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

章节来源
- [docs/backend.md](file://docs/backend.md#L438-L452)

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

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