DM-ROW 接口文档

Appearance

数据迁移与版本管理 ​

**本文引用的文件** - [device.sql](file://docs/ddl/device.sql) - [store.sql](file://docs/ddl/store.sql) - [workflow.sql](file://docs/ddl/workflow.sql) - [application.yml（设备服务）](file://lemes-cloud/lemes-business-devicemate/lemes-service-dm-device/lemes-service-dm-device-server/src/main/resources/application.yml) - [application.yml（仓储服务）](file://lemes-cloud/lemes-business-devicemate/lemes-service-dm-store/lemes-service-dm-store-server/src/main/resources/application.yml) - [application.yml（工作流服务）](file://lemes-cloud/lemes-business-devicemate/lemes-service-dm-workflow/lemes-service-dm-workflow-server/src/main/resources/application.yml) - [application.yml（作业执行器）](file://lemes-job-devicemate/lemes-job-devicemate-executor/src/main/resources/application.yml) - [FrameworkController.java](file://lemes-cloud/lemes-framework/lemes-framework-datasource/src/main/java/com/lenovo/lemes/datasource/api/FrameworkController.java) - [DataBaseAdapterService.java](file://lemes-cloud/lemes-framework/lemes-framework-datasource/src/main/java/com/lenovo/lemes/datasource/adapter/DataBaseAdapterService.java) - [DynamicDbName.java](file://lemes-cloud/lemes-framework/lemes-framework-datasource/src/main/java/com/lenovo/lemes/datasource/constants/DynamicDbName.java) - [pom.xml（仓储公共模块）](file://lemes-cloud/lemes-business-devicemate/lemes-service-dm-store/lemes-service-dm-store-common/pom.xml)

目录 ​

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

简介 ​

本文件面向 DeviceMate 项目的数据库迁移与版本管理，系统化梳理版本号命名规范、升级顺序与回滚机制；明确 DDL 变更、DML 初始化与数据转换脚本的组织方式与编写规范；制定增量迁移与全量迁移的选择策略及迁移窗口、数据锁定策略、风险控制措施；给出字段新增/修改/删除的兼容性方案；提供 Flyway、Liquibase 等迁移工具的集成建议；总结生产环境迁移最佳实践（灰度发布、影子表迁移、在线 DDL 变更）；并为 DBA 和运维人员提供可执行的操作手册。

项目结构 ​

DeviceMate 采用多模块微服务架构，数据库层面包含设备、仓储、工作流三大域的 DDL 定义与 Liquibase 版本控制表。动态数据源框架支持多租户/多数据库路由，便于在不同环境与租户间隔离与统一治理。

图表来源

章节来源

核心组件 ​

  • 数据库 DDL 脚本：分别覆盖设备、仓储、工作流域的表结构与索引定义，作为“事实来源”用于全量初始化与对比基线。
  • Liquibase 版本控制表：工作流域包含标准 Liquibase 控制表，表明该域已启用 Liquibase 进行版本管理。
  • 动态数据源框架：提供多数据源路由、数据库类型识别与安全输出能力，支撑多租户与多数据库场景。
  • 服务配置：各服务通过 application.yml 配置数据源与连接池参数，确保迁移过程中的连接稳定性。

章节来源

架构总览 ​

迁移架构围绕“脚本驱动 + 版本控制 + 动态路由”的模式展开：DDL 脚本作为基线，Liquibase 管理增量版本；动态数据源在运行时按租户/库路由到目标数据库，保证迁移与业务访问的隔离与安全。

图表来源

详细组件分析 ​

数据库版本管理策略 ​

  • 版本号命名规范
    • 建议采用“YYYYMMDD-序号”或“主版本.次版本.修订号”格式，结合业务域前缀（如 device_、store_、workflow_），确保全局唯一且可排序。
    • 对于 Liquibase，沿用其标准变更集 ID 规范，配合 contexts/labels 区分环境与功能域。
  • 升级顺序
    • 先基础设施（共享库、公共表）、后业务域；先底层表（维度/字典）、后事实表；先非关键域、后关键域。
    • 同一域内按依赖关系排序：先无外键依赖的表，再有外键依赖的表。
  • 回滚机制
    • 使用 Liquibase 回滚到指定标签（tag）或变更集；对 DDL 变更保留逆向 SQL（drop/alter）。
    • 对关键变更采用“影子表+切换”策略，失败时快速切回原表，降低停机风险。

章节来源

数据迁移脚本组织方式 ​

  • DDL 变更脚本
    • 统一存放于 docs/ddl 下，按域拆分（device.sql、store.sql、workflow.sql），包含序列、表、索引、注释等。
    • 命名规范：domain_YYYYMMDD_description.sql；变更需具备幂等性与可逆性。
  • DML 初始化脚本
    • 用于字典、默认配置、初始权限等，建议与 DDL 分离，独立维护版本。
  • 数据转换脚本
    • 针对字段重命名/拆分/合并、编码映射、历史数据清洗，应包含备份、断点续跑与校验步骤。

章节来源

增量迁移与全量迁移选择策略 ​

  • 增量迁移（推荐）
    • 适用于已有生产库，优先使用 Liquibase 管理版本；每次变更提交到受控分支，经评审后合并。
    • 迁移窗口：选择低峰时段，预留 20%-30% 宽裕时间；对长事务表采用只读快照或影子表。
  • 全量迁移
    • 新环境初始化或重大重构时采用；基于 DDL 脚本一次性创建，随后执行 DML 初始化。
  • 数据锁定策略
    • 尽量避免长事务锁；对大表采用分批处理、分区扫描、临时索引等手段。
  • 风险控制
    • 变更前置：评审、压测、备份、回滚预案；变更中：监控、告警、人工确认；变更后：一致性校验、回归测试。

章节来源

数据兼容性处理 ​

  • 字段新增
    • 默认值设计需考虑历史数据；添加非空字段需分步：先加可空列、填充默认值、再改为非空。
  • 字段修改
    • 优先使用 ALTER COLUMN 的在线变更（视数据库支持）；若需重建表，采用影子表+切换。
  • 字段删除
    • 保留至少一个版本的兼容读取；对强依赖字段，先提供替代字段与迁移路径。

章节来源

迁移工具链集成方案 ​

  • Liquibase（推荐）
    • 在工作流域已存在 Liquibase 控制表，建议在其他域同样启用；通过 changelog 文件管理版本，支持 contexts/labels 与回滚标签。
    • 与 Spring Boot 集成：在 application.yml 中配置参数（如 changeLog、分环境 contexts），启动即自动执行。
  • Flyway（可选）
    • 适合简单线性演进场景；与 Liquibase 类似，通过 SQL 脚本管理版本，支持 baseline 与回滚。
  • 自动化与 CI/CD
    • 在流水线中加入“迁移预检查（幂等性、依赖校验）—执行迁移—健康检查—回滚演练”环节。

章节来源

生产环境迁移最佳实践 ​

  • 灰度发布
    • 先在小范围租户/库验证，逐步扩大；通过动态数据源按租户路由，实现无感切换。
  • 影子表迁移
    • 新旧表并存，增量同步，校验一致后切换；失败时快速回切。
  • 在线 DDL 变更
    • 优先使用数据库支持的在线变更；对不支持的场景，采用影子表+批量迁移。
  • 监控与告警
    • 关注迁移耗时、锁等待、慢查询、连接池使用率；设置阈值告警与自动回滚。

章节来源

DBA 与运维操作手册 ​

  • 准备阶段
    • 备份当前生产库；准备回滚脚本与影子表方案；确定迁移窗口与回滚触发条件。
  • 执行迁移
    • 在低峰期执行；对关键表先做只读快照或影子表；使用 Liquibase/Flyway 执行变更；实时监控。
  • 验证与收尾
    • 校验数据一致性、索引完整性、慢查询；清理临时对象；更新版本标签；归档日志。
  • 常见问题
    • 迁移卡住：检查锁等待、慢查询、连接池耗尽；必要时终止长事务或回滚。
    • 数据不一致：比对关键指标，定位差异表，重跑增量同步或局部回放。

章节来源

依赖关系分析 ​

  • 仓储公共模块排除了 Liquibase 依赖，避免与服务端 Liquibase 配置冲突；建议在服务端统一启用 Liquibase 并集中管理版本。
  • 动态数据源框架提供数据库类型识别与安全输出，迁移过程中可用于差异化处理（如 MySQL/PG 的语法差异）。

图表来源

章节来源

性能考量 ​

  • 迁移窗口规划：预留 20%-30% 宽裕时间，避免与业务高峰期重叠。
  • 锁定策略：优先使用在线 DDL 与影子表；对长事务表采用只读快照或分批处理。
  • 监控指标：迁移耗时、锁等待、慢查询、连接池使用率、磁盘 IO 与网络带宽。
  • 回滚成本：提前准备回滚脚本与影子表切换方案，确保能在分钟级内回滚。

故障排查指南 ​

  • 迁移失败
    • 检查 Liquibase 控制表状态与变更集执行记录；核对数据库连接、权限与字符集。
  • 数据不一致
    • 对比关键表的数据量、索引与约束；定位差异表后重跑增量同步。
  • 连接池耗尽
    • 调整连接池参数（最大连接数、超时时间）；减少一次性大事务。
  • 数据源问题
    • 通过动态数据源控制器列出可用数据源，确认路由正确性与主从配置。

章节来源

结论 ​

DeviceMate 的数据库迁移与版本管理应坚持“脚本驱动 + 版本控制 + 动态路由”的原则。工作流域已采用 Liquibase，建议在其他域推广统一的版本管理策略；通过 DDL 脚本与 Liquibase 双轨并行，确保全量与增量迁移的可控性与可追溯性；结合动态数据源框架与灰度发布、影子表迁移等手段，实现生产级的零停机与高可靠。

附录 ​

  • 参考文件清单
    • DDL 脚本：docs/ddl/device.sql、docs/ddl/store.sql、docs/ddl/workflow.sql
    • 服务配置：lemes-business-devicemate/*/src/main/resources/application.yml
    • 框架组件：lemes-framework-datasource 下的控制器、适配器与常量
    • 仓储公共模块依赖：lemes-service-dm-store-common/pom.xml