问题说明

本文用于排查 ZCenter 启动或升级期间的 Flyway 数据库迁移失败问题。

现象

• ZCenter 启动或升级时数据库迁移失败。
• 迁移过程出现 checksum mismatch、表已存在或版本号冲突等错误。

适用环境

• 产品线：ZVF
• 组件：ZCenter
• 版本：5.1.0

可能原因

• 已执行的迁移脚本被修改，导致校验和不一致。
• 上一次迁移中断后残留数据表，重试时提示表已存在。
• 新增迁移脚本的版本号未严格递增，与已执行版本冲突。

ZCenter 使用 Flyway 管理数据库版本，迁移脚本命名规则为 V{version}__schema.sql。

排查步骤

1. 检查校验失败

• 检查项：确认错误中是否包含 checksum mismatch。
• 处理方式：修复被修改的脚本，使其与数据库记录一致。
• 限制：仅在开发环境可以清空 flyway_schema_history 表后重新执行迁移。

2. 检查残留表

• 检查项：确认错误是否提示目标表已经存在。
• 处理方式：手动清理迁移中断后残留的表，再重新执行迁移。

3. 检查迁移脚本版本号

• 检查项：确认新增迁移脚本的版本号是否与已执行版本冲突。
• 处理方式：确保新脚本版本号严格递增。

4. 核对 Flyway 配置

相关 Flyway 配置如下：

flyway:
  validate-on-migrate: false
  placeholder-replacement: false

补充信息

• 排查时记录失败的迁移脚本名称、Flyway 错误信息和 flyway_schema_history 表中的对应记录。