# 备份恢复

<cite>
**本文引用的文件**
- [backend/app/core/config.py](file://backend/app/core/config.py)
- [backend/app/core/database.py](file://backend/app/core/database.py)
- [backend/init_db.py](file://backend/init_db.py)
- [backend/alembic/env.py](file://backend/alembic/env.py)
- [backend/alembic.ini](file://backend/alembic.ini)
- [backend/app/models/models.py](file://backend/app/models/models.py)
- [backend/.env.example](file://backend/.env.example)
- [backend/requirements.txt](file://backend/requirements.txt)
- [backend/app/main.py](file://backend/app/main.py)
- [docs/database.md](file://docs/database.md)
</cite>

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

## 简介
本指南面向“医院绩效系统”的数据库备份与恢复，结合现有代码库中的数据库配置、迁移机制与模型定义，提供覆盖全量备份、增量/差异备份思路、自动化脚本编写、调度与存储管理、数据恢复与灾难恢复流程、业务连续性保障、备份验证与完整性检查、恢复测试方法，以及多环境（开发/测试/生产）数据同步与安全（加密传输、异地容灾）建议。由于当前仓库未包含数据库备份脚本与运维配置，本指南在不虚构实现的前提下，给出可落地的策略与流程。

## 项目结构
系统采用 FastAPI + SQLAlchemy 异步 ORM + Alembic 迁移的后端架构，数据库连接与配置集中在核心模块，模型定义位于 models，迁移配置位于 alembic。整体结构清晰，便于扩展备份与恢复能力。

```mermaid
graph TB
subgraph "后端"
CFG["配置模块<br/>backend/app/core/config.py"]
DB["数据库连接模块<br/>backend/app/core/database.py"]
MODELS["数据模型<br/>backend/app/models/models.py"]
ALEMBIC_ENV["迁移环境<br/>backend/alembic/env.py"]
ALEMBIC_INI["迁移配置<br/>backend/alembic.ini"]
INIT_DB["初始化脚本<br/>backend/init_db.py"]
MAIN["应用入口<br/>backend/app/main.py"]
end
CFG --> DB
DB --> MODELS
ALEMBIC_ENV --> MODELS
ALEMBIC_INI --> ALEMBIC_ENV
INIT_DB --> DB
INIT_DB --> MODELS
MAIN --> CFG
```

图表来源
- [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/models/models.py](file://backend/app/models/models.py#L1-L438)
- [backend/alembic/env.py](file://backend/alembic/env.py#L1-L66)
- [backend/alembic.ini](file://backend/alembic.ini#L1-L44)
- [backend/init_db.py](file://backend/init_db.py#L1-L83)
- [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/models/models.py](file://backend/app/models/models.py#L1-L438)
- [backend/alembic/env.py](file://backend/alembic/env.py#L1-L66)
- [backend/alembic.ini](file://backend/alembic.ini#L1-L44)
- [backend/init_db.py](file://backend/init_db.py#L1-L83)
- [backend/app/main.py](file://backend/app/main.py#L1-L92)

## 核心组件
- 配置模块：集中管理数据库连接串、池大小、调试开关等，是备份与恢复策略的配置依据。
- 数据库连接模块：提供异步引擎与会话工厂，确保备份/恢复过程中的事务一致性。
- 模型定义：明确表结构、索引与约束，为备份范围与恢复顺序提供依据。
- 迁移环境与配置：Alembic 提供结构变更的版本化管理，备份策略需考虑结构与数据的协同。
- 初始化脚本：演示了建表与初始数据插入流程，可作为恢复后验证的基础。

章节来源
- [backend/app/core/config.py](file://backend/app/core/config.py#L18-L26)
- [backend/app/core/database.py](file://backend/app/core/database.py#L9-L20)
- [backend/app/models/models.py](file://backend/app/models/models.py#L62-L85)
- [backend/alembic/env.py](file://backend/alembic/env.py#L10-L18)
- [backend/alembic.ini](file://backend/alembic.ini#L7-L7)
- [backend/init_db.py](file://backend/init_db.py#L11-L18)

## 架构总览
系统数据库连接通过异步引擎与会话工厂实现，模型层定义了完整的业务表结构。Alembic 提供结构迁移能力；初始化脚本用于快速搭建测试环境。备份与恢复应围绕这些组件展开，确保结构与数据的一致性。

```mermaid
sequenceDiagram
participant App as "应用入口<br/>app/main.py"
participant Cfg as "配置模块<br/>app/core/config.py"
participant Db as "数据库连接<br/>app/core/database.py"
participant Alembic as "迁移环境<br/>alembic/env.py"
participant Models as "数据模型<br/>models/models.py"
App->>Cfg : 读取配置
Cfg-->>App : 返回数据库URL/池参数
App->>Db : 创建异步引擎与会话工厂
Db->>Models : 使用Base元数据
App->>Alembic : 执行迁移(结构)
Alembic->>Models : 读取metadata
App->>Db : 初始化/写入数据
```

图表来源
- [backend/app/main.py](file://backend/app/main.py#L15-L77)
- [backend/app/core/config.py](file://backend/app/core/config.py#L18-L26)
- [backend/app/core/database.py](file://backend/app/core/database.py#L9-L20)
- [backend/alembic/env.py](file://backend/alembic/env.py#L10-L18)
- [backend/app/models/models.py](file://backend/app/models/models.py#L23-L25)

## 详细组件分析

### 数据库连接与备份影响面
- 异步引擎与会话工厂：备份应在数据库空闲时段执行，避免长事务阻塞；恢复后需重启应用以重新建立连接。
- 事务语义：备份期间的写入可能被截断，需结合 WAL/逻辑复制实现近零停机。

```mermaid
flowchart TD
Start(["开始备份"]) --> CheckConn["检查数据库连接与可用性"]
CheckConn --> TxnCheck{"是否存在长事务?"}
TxnCheck --> |是| WaitIdle["等待事务结束或选择快照级别"]
TxnCheck --> |否| ChooseMethod["选择备份方法<br/>物理/逻辑/快照"]
WaitIdle --> ChooseMethod
ChooseMethod --> ExecBackup["执行备份"]
ExecBackup --> Verify["校验备份完整性"]
Verify --> End(["结束"])
```

图表来源
- [backend/app/core/database.py](file://backend/app/core/database.py#L9-L20)

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

### 模型与索引对备份的影响
- 索引与约束：备份需保证索引与约束在恢复后一致，避免后续查询异常。
- 关系与级联：恢复后需验证外键关系与级联行为。

```mermaid
erDiagram
DEPARTMENTS ||--o{ STAFF : "1:N"
STAFF ||--o{ ASSESSMENTS : "1:N"
INDICATORS ||--o{ ASSESSMENT_DETAILS : "1:N"
ASSESSMENTS ||--o{ ASSESSMENT_DETAILS : "1:N"
STAFF ||--o{ SALARY_RECORDS : "1:N"
USERS ||--o{ ASSESSMENTS : "1:N(assessor)"
USERS ||--o{ ASSESSMENTS : "1:N(reviewer)"
```

图表来源
- [backend/app/models/models.py](file://backend/app/models/models.py#L62-L85)
- [backend/app/models/models.py](file://backend/app/models/models.py#L88-L114)
- [backend/app/models/models.py](file://backend/app/models/models.py#L117-L146)
- [backend/app/models/models.py](file://backend/app/models/models.py#L149-L178)
- [backend/app/models/models.py](file://backend/app/models/models.py#L181-L202)
- [backend/app/models/models.py](file://backend/app/models/models.py#L205-L230)
- [backend/app/models/models.py](file://backend/app/models/models.py#L244-L260)
- [backend/app/models/models.py](file://backend/app/models/models.py#L270-L311)
- [backend/app/models/models.py](file://backend/app/models/models.py#L314-L338)

章节来源
- [backend/app/models/models.py](file://backend/app/models/models.py#L62-L85)
- [backend/app/models/models.py](file://backend/app/models/models.py#L88-L114)
- [backend/app/models/models.py](file://backend/app/models/models.py#L117-L146)
- [backend/app/models/models.py](file://backend/app/models/models.py#L149-L178)
- [backend/app/models/models.py](file://backend/app/models/models.py#L181-L202)
- [backend/app/models/models.py](file://backend/app/models/models.py#L205-L230)
- [backend/app/models/models.py](file://backend/app/models/models.py#L244-L260)
- [backend/app/models/models.py](file://backend/app/models/models.py#L270-L311)
- [backend/app/models/models.py](file://backend/app/models/models.py#L314-L338)

### Alembic 迁移与备份的关系
- 结构变更：迁移文件记录了数据库结构演进，备份时需同时备份迁移历史与当前结构，确保恢复后能正确升级。
- 版本控制：备份应包含 Alembic 配置与版本目录，以便在新环境中按版本回放。

```mermaid
sequenceDiagram
participant Dev as "开发者"
participant Alembic as "Alembic"
participant Repo as "版本库"
participant Prod as "生产数据库"
Dev->>Alembic : 生成迁移文件
Alembic->>Repo : 提交迁移文件
Dev->>Prod : 执行迁移(结构变更)
Prod-->>Dev : 升级完成
```

图表来源
- [docs/database.md](file://docs/database.md#L272-L285)
- [backend/alembic/env.py](file://backend/alembic/env.py#L21-L32)
- [backend/alembic/env.py](file://backend/alembic/env.py#L56-L65)

章节来源
- [docs/database.md](file://docs/database.md#L272-L285)
- [backend/alembic/env.py](file://backend/alembic/env.py#L21-L32)
- [backend/alembic/env.py](file://backend/alembic/env.py#L56-L65)

### 初始化脚本与恢复验证
- 初始化脚本展示了建表与插入初始数据的流程，可用于恢复后的基础数据验证。

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

## 依赖关系分析
- 配置模块驱动数据库连接模块，后者依赖模型基类；迁移环境读取配置与模型元数据；应用入口加载配置与路由。
- 备份策略需考虑这些依赖链路的连通性与一致性。

```mermaid
graph LR
CFG["config.py"] --> DB["database.py"]
DB --> MODELS["models.py"]
ALEMBIC_ENV["alembic/env.py"] --> MODELS
ALEMBIC_INI["alembic.ini"] --> ALEMBIC_ENV
MAIN["app/main.py"] --> CFG
INIT_DB["init_db.py"] --> DB
INIT_DB --> MODELS
```

图表来源
- [backend/app/core/config.py](file://backend/app/core/config.py#L9-L47)
- [backend/app/core/database.py](file://backend/app/core/database.py#L4-L25)
- [backend/app/models/models.py](file://backend/app/models/models.py#L23-L25)
- [backend/alembic/env.py](file://backend/alembic/env.py#L10-L18)
- [backend/alembic.ini](file://backend/alembic.ini#L7-L7)
- [backend/app/main.py](file://backend/app/main.py#L10-L12)
- [backend/init_db.py](file://backend/init_db.py#L6-L8)

章节来源
- [backend/app/core/config.py](file://backend/app/core/config.py#L9-L47)
- [backend/app/core/database.py](file://backend/app/core/database.py#L4-L25)
- [backend/app/models/models.py](file://backend/app/models/models.py#L23-L25)
- [backend/alembic/env.py](file://backend/alembic/env.py#L10-L18)
- [backend/alembic.ini](file://backend/alembic.ini#L7-L7)
- [backend/app/main.py](file://backend/app/main.py#L10-L12)
- [backend/init_db.py](file://backend/init_db.py#L6-L8)

## 性能考量
- 备份窗口：选择业务低峰时段，避免与长事务冲突。
- 连接池：备份期间可临时降低最大连接数，减少资源竞争。
- 并发策略：逻辑备份支持并发，但需注意锁与一致性；物理备份需确保一致性快照。
- 恢复速度：索引重建与约束检查是恢复耗时的关键环节，建议在专用实例上进行恢复演练。

## 故障排查指南
- 连接失败：检查数据库 URL、凭据与网络连通性；确认配置模块的环境变量加载。
- 迁移异常：核对 Alembic 配置与版本目录；确保模型元数据与迁移目标一致。
- 恢复不完整：核对备份集是否包含结构与数据；确认恢复顺序与外键约束满足条件。
- 权限问题：确保备份/恢复账户具备必要权限；遵循最小权限原则。

章节来源
- [backend/.env.example](file://backend/.env.example#L3-L10)
- [backend/app/core/config.py](file://backend/app/core/config.py#L18-L26)
- [backend/alembic/env.py](file://backend/alembic/env.py#L21-L32)
- [backend/alembic/env.py](file://backend/alembic/env.py#L56-L65)

## 结论
本指南基于现有代码库的数据库配置、模型与迁移机制，提出了备份与恢复的整体策略与流程。建议在现有基础上补充自动化脚本、调度任务与存储管理规范，并定期开展恢复测试与演练，以确保业务连续性与灾难恢复的有效性。

## 附录

### 备份策略与配置方法
- 全量备份
  - 逻辑备份：适用于 PostgreSQL，支持跨平台与增量点定位；建议开启压缩与并行度。
  - 物理备份：适用于需要零停机的场景，需使用一致性快照或只读副本。
- 增量/差异备份
  - 增量：基于 WAL 的增量备份，适合频繁写入场景；需配合 PITR（Point-in-Time Recovery）。
  - 差异：每日差异备份+周期性全量，降低恢复时间；需严格管理差异链。
- 自动化脚本
  - 使用定时任务触发备份；脚本需包含连接参数、输出路径、压缩与校验步骤。
  - 对于 PostgreSQL，可参考官方工具与扩展（如逻辑复制、物理快照）。
- 备份调度
  - 低峰时段执行；设置重试与告警；记录备份元数据（版本、时间戳、校验和）。
- 存储管理
  - 多层存储：本地热存储、近线归档、远端冷存储；分级保留策略。
  - 去重与压缩：降低存储成本；注意解压性能对恢复时间的影响。

### 数据恢复流程
- 准备阶段：确认目标环境与依赖（数据库版本、驱动、连接参数）。
- 结构恢复：优先恢复迁移历史与结构，确保模型与索引一致。
- 数据恢复：按备份集顺序恢复数据；校验主键/唯一性与外键关系。
- 应用启动：重启应用，执行必要的迁移升级；运行初始化脚本进行基础数据验证。

### 灾难恢复计划与业务连续性
- RTO/RPO：根据业务需求设定恢复目标；优先保证结构与关键数据的恢复。
- 多活/异地：部署多活实例或异地副本；定期进行切换演练。
- 降级策略：在极端情况下，优先恢复核心模块（如认证、基础数据），再逐步恢复其他模块。

### 备份数据验证、完整性检查与恢复测试
- 校验清单：备份集完整性、结构一致性、关键数据抽样比对。
- 完整性检查：导入到隔离环境进行一致性校验（索引、约束、外键）。
- 恢复测试：定期在非生产环境进行恢复演练，评估恢复时间与数据可用性。

### 多环境部署的备份策略
- 开发/测试：使用独立数据库或容器化实例；定期从生产拉取受限数据进行备份与恢复测试。
- 生产：采用企业级备份解决方案；结合逻辑复制或物理快照实现近零停机。

### 备份存储安全、加密传输与异地容灾
- 加密：备份文件与传输通道均需加密；密钥管理遵循最小权限与轮换策略。
- 传输：使用安全协议（如 SFTP/HTTPS）；对敏感数据进行脱敏处理。
- 异地容灾：在不同地理区域保留备份副本；定期进行异地恢复演练。