Files

2026-02-28 15:16:15 +08:00

18 KiB

Raw Blame History

数据库管理

**本文引用的文件** - [backend/app/core/database.py](file://backend/app/core/database.py) - [backend/app/core/config.py](file://backend/app/core/config.py) - [backend/app/core/init_db.py](file://backend/app/core/init_db.py) - [backend/alembic/env.py](file://backend/alembic/env.py) - [backend/alembic.ini](file://backend/alembic.ini) - [backend/alembic/versions/001_initial.py](file://backend/alembic/versions/001_initial.py) - [backend/alembic/versions/002_template.py](file://backend/alembic/versions/002_template.py) - [backend/app/models/models.py](file://backend/app/models/models.py) - [backend/init_db.py](file://backend/init_db.py) - [backend/create_menu_tables.py](file://backend/create_menu_tables.py) - [backend/create_plan_tables.py](file://backend/create_plan_tables.py) - [backend/init_indicator_templates.py](file://backend/init_indicator_templates.py) - [backend/migrate_indicators.py](file://backend/migrate_indicators.py) - [backend/app/scripts/init_templates.py](file://backend/app/scripts/init_templates.py)

简介

本指南面向数据库管理员与后端开发，系统讲解本项目的数据库初始化、表结构创建、数据迁移与版本管理、备份与恢复策略、性能优化、监控与连接池配置、事务管理最佳实践以及安全与审计配置。项目采用 SQLAlchemy 异步 ORM 与 Alembic 迁移工具，结合 PostgreSQL 数据库，提供从开发到生产的完整数据库生命周期管理方案。

项目结构

数据库相关能力主要分布在以下模块：

配置与连接：应用配置与数据库连接池参数、异步引擎与会话工厂
模型定义：统一的 ORM 基类与完整的业务模型（科室、员工、指标、考核、工资、用户、计划、模板、菜单等）
初始化脚本：数据库表创建、基础数据与模板数据初始化
迁移工具：Alembic 版本化迁移、离线/在线迁移执行
辅助脚本：菜单表创建、计划表创建、指标模板初始化、字段迁移

graph TB
subgraph "配置与连接"
CFG["配置模块<br/>settings.DATABASE_URL 等"]
ENG["异步引擎与会话工厂"]
end
subgraph "模型层"
MODELS["ORM 模型定义<br/>Department/Staff/Indicator 等"]
end
subgraph "初始化与脚本"
INIT_DB["初始化脚本<br/>创建表与基础数据"]
INIT_TPL["模板初始化脚本"]
MIGRATE["字段迁移脚本"]
CREATE_MENU["菜单表创建脚本"]
CREATE_PLAN["计划表创建脚本"]
end
subgraph "迁移工具"
ALEMBIC_INI["Alembic 配置"]
ALEMBIC_ENV["Alembic 环境配置"]
V001["版本 001 初始表"]
V002["版本 002 模板与字段"]
end
CFG --> ENG
ENG --> MODELS
MODELS --> INIT_DB
MODELS --> INIT_TPL
MODELS --> MIGRATE
MODELS --> CREATE_MENU
MODELS --> CREATE_PLAN
ALEMBIC_INI --> ALEMBIC_ENV
ALEMBIC_ENV --> V001
ALEMBIC_ENV --> V002

图表来源

章节来源

核心组件

数据库连接与会话
- 异步引擎与会话工厂：通过配置模块提供的数据库 URL 创建异步引擎，并生成异步会话工厂；提供依赖注入式会话获取函数，自动提交、回滚与关闭
- 连接池参数：在配置模块中定义连接池大小与溢出参数，确保高并发下的稳定性
模型与索引
- 统一的 DeclarativeBase 基类，所有业务模型继承该基类
- 多表建立复合索引与约束，覆盖常用查询条件与外键关系
Alembic 迁移
- 离线/在线迁移：支持离线模式与异步在线模式，适配不同部署场景
- 版本化迁移：初始版本创建核心表，后续版本扩展模板与字段
初始化与脚本
- 表创建与基础数据：批量创建表并插入示例数据
- 模板与指标：按模板文档初始化指标与模板关联
- 字段迁移：向现有表动态添加新字段，兼容历史版本

章节来源

架构总览

数据库层围绕“配置 → 引擎/会话 → 模型 → 迁移/脚本”的主干展开，形成清晰的职责边界与可演进的版本化管理。

graph TB
CFG["配置模块<br/>DATABASE_URL/DATABASE_POOL_SIZE 等"]
ENGINE["异步引擎"]
SESSION["异步会话工厂"]
BASE["ORM 基类 Base"]
MODELS["业务模型集合"]
ALEMBIC["Alembic 迁移"]
SCRIPTS["初始化与维护脚本"]
CFG --> ENGINE
ENGINE --> SESSION
SESSION --> MODELS
BASE --> MODELS
ALEMBIC --> MODELS
SCRIPTS --> MODELS

图表来源

详细组件分析

数据库初始化与表结构创建

初始化流程
- 使用异步引擎在连接上下文中一次性创建所有表
- 插入基础数据（科室、员工、指标、管理员），避免重复初始化
表结构要点
- 主键自增、唯一约束、外键关系明确
- 常用查询列建立索引，如科室类型、员工状态、考核周期、模板类型等
- 约束保证数据完整性，如指标权重正数约束

sequenceDiagram
participant CLI as "命令行"
participant INIT as "初始化脚本"
participant ENGINE as "异步引擎"
participant MODELS as "ORM 模型"
participant DB as "数据库"
CLI->>INIT : 调用初始化入口
INIT->>ENGINE : 获取连接
INIT->>MODELS : create_all()
MODELS->>DB : 创建表与索引
INIT->>DB : 插入基础数据
DB-->>INIT : 返回结果
INIT-->>CLI : 输出完成信息

图表来源

章节来源

Alembic 数据库迁移工具

配置与环境
- Alembic 配置文件指定脚本位置、日志级别与数据库 URL
- 环境配置加载应用配置与模型元数据，支持离线与在线迁移
版本管理
- 初始版本：创建核心业务表与索引
- 模板版本：新增指标模板表与关联表，向指标表添加多字段
回滚与增量更新
- 每个版本提供升级与降级逻辑，确保可逆演进
- 新增字段采用条件判断，避免重复迁移失败

flowchart TD
START(["开始"]) --> CHECK_CFG["读取 Alembic 配置"]
CHECK_CFG --> LOAD_META["加载模型元数据"]
LOAD_META --> MODE{"迁移模式？"}
MODE --> |离线| OFFLINE["离线迁移<br/>直接写入 SQL"]
MODE --> |在线| ONLINE["在线迁移<br/>异步连接执行"]
OFFLINE --> RUN_MIGR["执行迁移"]
ONLINE --> RUN_MIGR
RUN_MIGR --> DONE(["结束"])

图表来源

章节来源

数据模型与索引设计

模型关系
- 部门与员工一对多、员工与考核/工资一对一多关联
- 考核记录与明细、指标与模板的多对多通过中间表实现
索引策略
- 针对高频过滤与连接字段建立复合索引，提升查询性能
- 外键字段与状态字段建立索引，加速筛选与排序
约束与校验
- 指标权重正数约束，保证业务合理性
- 唯一约束用于编码与用户名等关键字段

erDiagram
DEPARTMENTS ||--o{ STAFF : "拥有"
STAFF ||--o{ ASSESSMENTS : "被考核"
STAFF ||--o{ SALARY_RECORDS : "产生工资"
INDICATORS ||--o{ ASSESSMENT_DETAILS : "被评估"
ASSESSMENTS ||--o{ ASSESSMENT_DETAILS : "包含"
INDICATOR_TEMPLATES ||--o{ TEMPLATE_INDICATORS : "包含"
INDICATORS ||--o{ TEMPLATE_INDICATORS : "关联"

图表来源

章节来源

backend/app/models/models.py

模板与指标初始化策略

模板初始化
- 依据文档模板创建通用、手术、医技、行政、后勤五类模板
- 模板与指标通过中间表建立关联，支持分类与权重配置
指标初始化
- 按平衡计分卡维度与科室类型拆分指标集合
- 支持字段扩展（目标值、单位、计算方法、扣分标准、数据来源、适用科室类型、一票否决等）

sequenceDiagram
participant CLI as "命令行"
participant INIT as "模板初始化脚本"
participant DB as "数据库"
participant MODELS as "ORM 模型"
CLI->>INIT : 调用初始化入口
INIT->>DB : 查询是否存在指标
DB-->>INIT : 返回空/存在
alt 不存在
INIT->>MODELS : 创建指标
INIT->>MODELS : 创建模板
INIT->>MODELS : 关联模板与指标
INIT->>DB : 提交事务
else 已存在
INIT-->>CLI : 跳过初始化
end
INIT-->>CLI : 输出完成信息

图表来源

章节来源

字段迁移与增量更新

字段迁移脚本
- 向指标表动态添加平衡计分卡维度、目标单位、考核方法、扣分标准、数据来源、适用科室类型、一票否决等字段
- 采用条件判断避免重复添加导致迁移失败
与 Alembic 的配合
- Alembic 版本 002 同样实现字段添加逻辑，两者可互补使用

flowchart TD
START(["开始"]) --> CONNECT["连接数据库"]
CONNECT --> ADD_COL["逐个添加字段"]
ADD_COL --> CHECK{"字段是否存在？"}
CHECK --> |是| SKIP["跳过该字段"]
CHECK --> |否| DO_ADD["执行添加"]
SKIP --> NEXT["下一个字段"]
DO_ADD --> NEXT
NEXT --> DONE(["结束"])

图表来源

章节来源

连接池与事务管理

连接池配置
- 在配置模块中设置连接池大小与溢出参数，满足高并发请求
事务管理
- 会话工厂在依赖注入中自动提交或回滚异常，finally 关闭会话，确保资源释放
并发与一致性
- 异步引擎与会话配合，避免阻塞；外键与索引设计减少锁竞争

章节来源

依赖关系分析

组件耦合
- 模型层依赖配置模块提供的数据库 URL，迁移工具依赖模型元数据
- 初始化脚本与模板脚本依赖模型与会话工厂
外部依赖
- Alembic 依赖 SQLAlchemy 异步引擎
- 运行时依赖 PostgreSQL 数据库

graph LR
CONFIG["配置模块"] --> ENGINE["异步引擎"]
ENGINE --> SESSION["异步会话"]
SESSION --> MODELS["ORM 模型"]
MODELS --> INIT["初始化脚本"]
MODELS --> SCRIPTS["模板/迁移脚本"]
ALEMBIC_INI["Alembic 配置"] --> ALEMBIC_ENV["Alembic 环境"]
ALEMBIC_ENV --> MODELS

图表来源

章节来源

性能考虑

索引设计
- 为常用过滤字段（如科室类型、员工状态、考核周期、模板类型、用户名等）建立复合索引
- 对外键字段与排序字段建立索引，减少全表扫描
查询优化
- 使用关系查询时注意惰性加载与联结策略，避免 N+1 查询
- 对大表进行分页查询，限制返回字段
连接池优化
- 合理设置连接池大小与溢出参数，避免连接争用
- 在高并发场景下启用异步 I/O，减少阻塞
数据建模
- 将 JSON 字段用于灵活配置（如模板维度权重、适用科室类型），但需谨慎查询与索引策略

章节来源

故障排查指南

迁移失败
- 检查 Alembic 配置文件中的数据库 URL 是否正确
- 确认模型元数据已正确加载，版本文件命名与依赖关系无误
- 在线迁移需确保异步连接可用，必要时切换为离线迁移验证
字段迁移冲突
- 使用条件判断避免重复添加字段；若 Alembic 与脚本同时执行，建议统一由 Alembic 管理
初始化数据重复
- 初始化脚本中包含存在性检查，避免重复插入；如出现异常，清理缓存或重新执行
连接池耗尽
- 检查连接池参数与并发请求量，适当增大池大小或优化查询
权限问题
- 确保数据库用户具备创建表、索引与修改表结构的权限

章节来源

结论

本项目通过配置驱动的异步数据库连接、完善的模型与索引设计、版本化的 Alembic 迁移与多类初始化脚本，构建了可演进、可维护、高性能的数据库管理方案。遵循本文的迁移策略、性能优化与安全配置建议，可在生产环境中稳定运行并持续演进。

附录

数据库备份与恢复流程

备份
- 使用数据库自带工具进行逻辑或物理备份，定期归档
- 在迁移前执行备份，确保可回滚
恢复
- 从最近备份点恢复，结合 Alembic 迁移补全到最新版本
- 验证关键表与索引完整性，执行回归测试

数据迁移策略

渐进式迁移
- 先迁移结构（表、索引、约束），再迁移数据（基础数据、模板、指标）
回滚策略
- 使用 Alembic 降级到上一版本，配合备份快速恢复
兼容性
- 新增字段采用条件判断，避免破坏现有数据

监控指标与连接池配置

监控指标
- 连接池利用率、活跃连接数、等待队列长度、慢查询数量
连接池配置
- 根据并发峰值与响应时间调整池大小与超时参数

事务管理最佳实践

会话生命周期
- 依赖注入中自动提交或回滚，finally 关闭会话
事务粒度
- 将原子性要求高的操作放在同一事务中，避免长事务

安全配置与审计

安全配置
- 最小权限原则，仅授予所需 DDL/DML 权限
- 使用强口令与 TLS 加密传输
审计日志
- 记录关键 DDL 操作与重要 DML 变更，便于追溯与合规

18 KiB Raw Blame History Unescape Escape

数据库管理

目录

简介

项目结构

核心组件

架构总览

详细组件分析

数据库初始化与表结构创建

Alembic 数据库迁移工具

数据模型与索引设计

模板与指标初始化策略

字段迁移与增量更新

连接池与事务管理

依赖关系分析

性能考虑

故障排查指南

结论

附录

数据库备份与恢复流程

数据迁移策略

监控指标与连接池配置

事务管理最佳实践

安全配置与审计

18 KiB

Raw Blame History