跳到主要内容

数据库配置与Aerich迁移管理文档

概述​

本文档详细说明邮轮穿舱件管理系统后台的数据库配置和Aerich迁移管理流程。系统使用Tortoise ORM作为对象关系映射工具，并通过Aerich进行数据库迁移管理。

数据库配置架构​

配置结构图​

flowchart TD
    A[应用启动] --> B[读取环境变量]
    B --> C[加载.env文件]
    C --> D[Settings类初始化]
    D --> E[读取JSON配置文件]
    E --> F[构建Tortoise配置]
    F --> G[Aerich迁移工具]

核心配置文件​

系统采用分层配置架构，主要配置文件包括：

Tortoise ORM配置详解​

配置加载机制​

系统通过动态加载环境特定的JSON配置文件来构建Tortoise ORM配置：

# [settings.py](git_repository_url/app/core/settings.py#L47-L51)
@computed_field
@property
def tortoise_orm_config_dict(self) -> Dict[str, Any]:
    with open(f".config/{self.env}.database.json", "r") as f:
        return json.load(f)

Aerich配置​

在 pyproject.toml 中配置Aerich工具：

[tool.aerich]
tortoise_orm = "app.tortoise_config.AERICH_CONFIG"
location = "./migrations"
src_folder = "./."

数据库迁移流程​

1. 空数据库初始化​

当数据库为空时，使用以下命令进行初始化：

aerich init-db

执行流程：

  1. 读取 tortoise_config.py 中的AERICH_CONFIG配置
  2. 连接到目标数据库
  3. 创建所有模型对应的数据表
  4. 生成初始迁移记录

2. 模型更新迁移​

当数据模型发生变化时，执行以下迁移流程：

# 生成迁移文件
aerich migrate

# 应用迁移到数据库
aerich upgrade

迁移执行流程图：

sequenceDiagram
    participant D as 开发者
    participant A as Aerich
    participant DB as 数据库
    
    D->>A: aerich migrate
    A->>DB: 对比模型与数据库差异
    DB-->>A: 返回差异信息
    A->>A: 生成迁移文件
    A-->>D: 创建迁移文件成功
    
    D->>A: aerich upgrade
    A->>DB: 执行迁移SQL
    DB-->>A: 迁移完成确认
    A-->>D: 迁移应用成功

数据库表结构​

实体关系图​

erDiagram
    users ||--o{ roles : "拥有"
    users ||--o{ access_log : "创建"
    users ||--o{ ticket : "创建"
    users ||--o{ workpieces : "创建"
    workpieces ||--o{ image_mapping : "关联"
    image_mapping }o--|| image : "引用"
    ticket ||--o{ workpieces : "目标工件"
    
    users {
        int id PK
        string username UK
        string password
        string email UK
        string sms
        string status
        string openid
        bool is_system
        int created_by
        int updated_by
        datetime created_at
        datetime updated_at
    }
    
    roles {
        int id PK
        int user_id FK
        string scope_list
        string scope_group
        int created_by
        int updated_by
        datetime created_at
        datetime updated_at
    }
    
    workpieces {
        int workpiece_id PK
        int workpiece_status
        int inspect_reference
        int maintainance_reference
        int created_by
        int updated_by
        datetime created_at
        datetime updated_at
    }

核心数据表说明​

根据 迁移文件 分析，系统包含以下主要数据表：

用户管理表 (users)​

  • 主键：id (自增整数)
  • 唯一约束：username, email
  • 支持微信OpenID集成
  • 系统用户标识字段

权限角色表 (roles)​

  • 与用户表一对多关系
  • 权限范围管理
  • 权限组分类

工件管理表 (workpieces)​

  • 工件状态跟踪
  • 维护和检测工单引用
  • 生命周期管理

图片映射表 (image_mapping)​

  • 工件与图片关联关系
  • 多对多关系桥接表

迁移依赖关系分析​

模块依赖图​

flowchart TD
    subgraph "配置层"
        A[settings.py]
        B[tortoise_config.py]
        C[pyproject.toml]
    end
    
    subgraph "迁移层"
        D[migrations/]
        E[Aerich工具]
    end
    
    subgraph "模型层"
        F[app/models/]
        G[数据库表]
    end
    
    A --> B
    C --> E
    B --> E
    E --> D
    F --> E
    E --> G

迁移执行依赖​

  1. 配置依赖：Aerich依赖 tortoise_config.py 中的配置
  2. 模型依赖：迁移基于app/models目录下的模型定义
  3. 文件依赖：迁移记录存储在migrations目录
  4. 环境依赖：配置通过环境变量动态加载

最佳实践建议​

迁移操作规范​

  1. 开发环境迁移

    • 每次模型变更后立即执行迁移
    • 测试迁移脚本的正确性
    • 保留迁移历史记录

  2. 生产环境部署

    • 预演迁移脚本
    • 备份数据库
    • 分阶段执行迁移

配置管理​

  1. 环境隔离：使用不同的JSON配置文件管理各环境数据库连接
  2. 安全配置：敏感信息通过环境变量管理
  3. 版本控制：迁移文件纳入版本控制

故障排除​

常见问题​

  1. 迁移失败：检查数据库连接配置和权限
  2. 配置加载错误：验证JSON配置文件格式和路径
  3. 模型冲突：确保模型定义与数据库表结构一致

调试技巧​

  • 使用 aerich migrate --name=description 添加迁移描述
  • 检查迁移文件中的SQL语句是否正确
  • 验证模型字段类型与数据库类型的兼容性

索引​

邮轮穿舱件管理系统采用现代化的数据库迁移管理方案，通过Aerich工具实现了数据库版本控制的自动化。配置架构支持多环境部署，迁移流程确保了数据模型变更的安全性和可追溯性。

关键要点：

  • 分层配置架构支持灵活的环境管理
  • Aerich提供了完整的数据库迁移生命周期管理
  • 实体关系设计支持系统的核心业务需求
  • 迁移依赖关系清晰，便于维护和扩展