Flyway 数据库迁移接管与发布规范

1. 目标与边界

Flyway 只负责版本化、可审计的数据库结构变更和确定性基础数据。

• Web 应用不依赖 Flyway，普通启动和服务器重启不会修改数据库。
• ruoyi-migration.jar 是唯一迁移执行入口。
• 新迁移只允许放在 Api/ruoyi-system/src/main/resources/db/migration。
• 接管前脚本归档在 Api/ruoyi-system/src/main/resources/db/legacy-migration，不再修改。
• 临时修数、故障补偿和批量删除不进入 Flyway。
• Flyway clean、baseline-on-migrate 和乱序执行均被禁用。

当前首批受管迁移为：

V20260818_001__merchant_entry_notice.sql
V20260818_002__merchant_penalty_appeal_history.sql

2. 版本与 SQL 规则

文件名必须使用：

VyyyyMMdd_NNN__lower_snake_case.sql

同一日期的 NNN 从 001 递增。迁移一旦提交或在任一共享环境执行，禁止修改、重命名或删除；修正必须创建更高版本。

蓝绿发布共用一个数据库，因此迁移必须遵守 expand-contract：

1. 先新增兼容列、表或索引，新旧代码都能运行。
2. 新代码完成切流并稳定运行后，再停止旧结构写入。
3. 删除旧列、旧表等收缩操作必须放到后续独立版本。

3. 构建与本地命令

构建迁移工具：

cd Api
mvn -pl ruoyi-migration package

迁移工具只从环境变量读取连接信息，密码不会进入命令行参数：

export FLYWAY_URL='jdbc:mysql://127.0.0.1:3306/xiedao_dev?useUnicode=true&characterEncoding=utf8&useSSL=false&serverTimezone=GMT%2B8'
export FLYWAY_USER='xiedao'
export FLYWAY_PASSWORD='数据库密码'

java -jar ruoyi-migration.jar info
java -jar ruoyi-migration.jar validate
java -jar ruoyi-migration.jar migrate

baseline 必须显式携带经审核的版本，例如：

java -jar ruoyi-migration.jar baseline 20260817

4. 首次接管前置审计

候选基线版本是 20260817，因为现有人工迁移归档的最高版本为 V20260817。它不是可以直接执行的默认值，只有确认数据库已包含全部历史变更后才能使用。

分别对 xiedao_dev 和 xiedao_prod 完成以下检查：

1. 使用 mysqldump --no-data --skip-comments --skip-dump-date 导出结构并进行差异比较。
2. 核对部署记录中的历史遗漏，尤其是 xd_rental_order_dispatch 和 xd_car_rental_dispatch 的 is_overdue、overdue_days、overdue_fee_fen 字段。
3. 核对当前应用 Mapper 引用的表和列均存在。
4. 确认库中没有 flyway_schema_history；如果存在，先查清来源，禁止覆盖。
5. 在执行 baseline 前创建全库备份及 SHA-256 文件。

只要开发库和正式库仍有未解释的结构差异，就停止接管。Flyway baseline 只登记历史起点，不会验证历史脚本是否真的执行过。

5. 一次性接管顺序

5.1 开发库

1. 构建 ruoyi-migration.jar，上传到服务器的受限目录。
2. 配置指向 xiedao_dev 的 FLYWAY_URL/USER/PASSWORD。
3. 执行 info，确认没有历史表。
4. 执行 baseline 20260817。
5. 执行 migrate 和 validate，确认两个 V20260818 迁移成功。
6. 在 /opt/xiedao/dev/env.sh 增加：

export FLYWAY_DEPLOY_ENABLED=true

可选连接覆盖项：

export FLYWAY_HOST=127.0.0.1
export FLYWAY_PORT=3306
export FLYWAY_DATABASE=xiedao_dev
export FLYWAY_USER=xiedao

未设置 FLYWAY_PASSWORD 时，发布脚本复用现有 DB_PASSWORD。

5.2 正式库

1. 完成开发库迁移和业务验收。
2. 对 xiedao_prod 创建完整备份并计算 SHA-256。
3. 使用同一个 ruoyi-migration.jar 执行 baseline 20260817。
4. 执行 migrate 和 validate。
5. 在蓝、绿两个 /opt/xiedao/prod/<slot>/env.sh 中增加 FLYWAY_DEPLOY_ENABLED=true。
6. 两个槽位必须使用一致的 Flyway 主机、端口、库名和账号配置。

不要通过启动 Web 服务完成首次 baseline。

6. 发布行为

开发发布产物包含：

• ruoyi-admin.jar
• ruoyi-migration.jar
• 同时记录两个 SHA-256 的 release.env

开发环境开启迁移门禁后，发布顺序是：校验两个 JAR、Flyway validate、Flyway migrate、切换 Web JAR、健康检查。迁移未执行的 release 会记录 MIGRATIONS_PASSED=false，禁止晋级生产。

生产晋级仍在 /opt/xiedao/prod/operation.lock 内串行执行，顺序是：

1. 校验开发 release、Git 状态、测试结果及两个 JAR 的 SHA-256。
2. 使用 mysqldump --single-transaction 创建压缩备份和 SHA-256 文件。
3. 执行 Flyway validate 和 migrate。
4. 切换非流量槽位的 Web JAR并重启、健康检查。
5. Nginx 切流仍由原有 switch-prod 独立完成。

若数据库迁移成功但新应用启动失败，只回滚应用 JAR，数据库不会自动回滚。因此每条生产迁移都必须与旧应用向后兼容。

7. 自动化验证

cd Api
mvn -pl ruoyi-migration test

测试包括：

• 迁移文件命名和重复版本检查。
• 使用 MySQL 8.0 Testcontainers 建立历史库、baseline 到 20260817、执行正式迁移并 validate。

本机没有 Docker 时容器测试会跳过；CI 或发布前验证环境必须提供 Docker，并确认该测试实际执行而不是跳过。