生产环境Spring Boot集成Flyway配置最佳实践及校验异常问题咨询

org.flywaydb.core.api.FlywayException: Validate failed: Migration checksum mismatch for migration version 报错的本质是：已经执行过的Flyway迁移脚本内容被修改，Flyway计算得到的最新校验和与flyway_schema_history系统表中存储的历史校验和不一致，触发的校验拦截。

前置规范：从根源避免校验失败问题 #

• 所有迁移脚本一旦提交并在任何环境执行过，绝对禁止修改、删除、重命名，如果原有脚本逻辑存在错误，只能新增版本号更高的修正脚本迭代调整
• 迁移脚本统一按照V<版本号>__<脚本描述>.sql格式命名，版本号规则需团队全局统一，推荐使用时间戳格式如V202405201430__add_user_mobile_column.sql，避免版本号冲突
• 开发人员提交脚本前必须在本地执行flyway validate命令确认校验通过，再提交到代码仓库进入提测流程
• 禁止在迁移脚本中编写可变逻辑，比如now()、动态读取环境变量等会导致不同环境执行结果不一致的内容，这类逻辑统一放到应用业务层处理

生产环境核心配置规则 #

• 强制开启spring.flyway.clean-disabled=true，彻底禁止Flyway执行清理数据库的操作，避免误操作清空生产数据
• 默认保留spring.flyway.validate-on-migrate=true配置，不要为了临时绕过报错关闭校验逻辑，否则会导致多环境脚本不一致的问题被掩盖，引发更大的线上故障
• 生产环境建议关闭应用启动自动执行迁移的逻辑，改为发布前由运维/DBA手动执行flyway migrate命令，确认迁移执行结果正常后再启动应用，避免应用启动过程中迁移失败导致服务不可用
• 多实例部署的应用不要关闭Flyway默认的分布式锁配置，保证同一时间只有一个实例执行迁移逻辑，避免并发执行导致锁表、脚本重复执行等问题

校验失败应急处理方案（无需重置数据库） #

生产环境出现校验失败时不要直接修改业务数据或者重置数据库，按照以下步骤处理：

• 第一步对比当前版本包内的迁移脚本与历史上已经执行过的版本的差异，确认是脚本被误改，还是多环境同步异常
• 如果确认历史脚本被误改，但修改后的逻辑和生产库已经执行的结果完全一致，不需要调整业务数据，直接执行flyway repair命令即可自动修正flyway_schema_history表中存储的校验和，快速恢复校验
• 如果修改后的脚本逻辑和生产库实际执行结果不一致，不要使用repair命令，新增版本号更高的修正脚本，把生产库的表结构、数据修正到预期状态，执行完成后校验会自动通过

内容的提问来源于stack exchange，提问作者abishkar bhattarai