提交文件

2026-02-28 15:16:15 +08:00
parent 1a4e50e0a4
commit 44f250f58e
159 changed files with 61268 additions and 0 deletions
--- a/.qoder/repowiki/zh/content/部署运维/备份恢复.md
+++ b/.qoder/repowiki/zh/content/部署运维/备份恢复.md
@@ -0,0 +1,303 @@
+# 备份恢复
+
+<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）；对敏感数据进行脱敏处理。
+- 异地容灾：在不同地理区域保留备份副本；定期进行异地恢复演练。