## 01、痛点

最近我们团队在发布季就踩了三个坑：本地开发好好的，测试环境少了一张订单扩展表；两个同事都从主分支拉出 V10，合并后 Flyway 直接报校验和不匹配；生产发布时才临时补迁移脚本，结果应用先起来，连不上新字段。我是老李。这些问题不是 Flyway 本身有多难，而是我们一直把数据库迁移当成发布前顺手执行的 SQL，没有像管理代码一样管理它。

典型场景可以画成这样：

```
开发A：V10__add_avatar.sql  →  提交 feature/a
开发B：V10__add_nickname.sql → 提交 feature/b
        ↓ 合并主干
Flyway schema_history 出现两个 V10
        ↓
生产库结构 ≠ 测试库结构 ≠ 本地库结构
```

手工执行迁移最大的问题是：脚本不可重复、顺序不可追溯、环境不可复现。dev、test、staging、prod 四个环境，往往会因为人工执行时间差、执行顺序不同，慢慢变成四套不同的数据库。等发现时，通常是在生产事故前夜。

## 02、是什么

Flyway 是一个数据库迁移工具，核心思想是把数据库结构变更固化为版本化的脚本。脚本按约定命名，例如 V1__init.sql、V2__add_order.sql，按版本号顺序执行。每次执行后，会在数据库中写入 schema_history 表，记录版本号、脚本名、校验和、执行时间。校验和是对脚本内容计算出的哈希值，用于判断已执行脚本是否被修改。

它的执行链可以简单画成：

```
V1__init.sql
   ↓
V2__add_order.sql
   ↓
V3__modify_user.sql
   ↓
schema_history
┌─────────────┬──────────────┬───────────┐
│ version     │ script        │ checksum  │
├─────────────┼──────────────┼───────────┤
│ 1           │ V1__init.sql  │ 8f3a...   │
│ 2           │ V2__add_order │ b2e1...   │
│ 3           │ V3__modify_user│ c71d...  │
└─────────────┴──────────────┴───────────┘
```

Flyway 在 Spring Boot 项目中可以自动装配。启动时默认执行 migrate，如果发现已执行脚本的内容变化，会抛出校验和不匹配错误，阻止应用启动。这个机制不复杂，但足以避免“改了老脚本而不自知”。

多环境下，Flyway 的差异不在工具本身，而在连接地址、目标库、执行策略。dev 环境可以是本地内存库或本地容器库；test 环境通常指向 Docker Compose 拉起的独立测试库；prod 环境则指向生产主库，执行前需要额外审批和备份。

## 03、为什么

现在讲这件事，是因为团队协作方式变了。应用已经容器化、服务化，代码合并到主分支后，数据库迁移脚本也必须跟着代码一起流转。如果迁移还停留在手工阶段，就会成为整个交付链路的短板。

多环境 Flyway 配置至少带来四个收益：

第一，环境可复现。任何人从 Git 拉下代码，切换到对应 Profile，就能在相同结构的数据库上启动应用。第二，变更可追踪。每个 DDL、DML 都有版本号，出问题时可以快速定位是哪个脚本引入。第三，校验前置。在 CI 中跑 validate 和全量 migrate，能把坏脚本挡在合并之前，而不是等到生产。第四，发布可控。生产环境不再默认自动 migrate，而是拆成审批、执行、验证三个阶段。

可以用一张简单图表示：

```
代码变更 → SQL 变更 → 同一个版本号
   ↓           ↓
分支合并 → 迁移脚本合并
   ↓           ↓
CI 校验  → 临时库全量迁移
   ↓           ↓
测试环境自动 migrate
   ↓
生产审批评审 → 受控 migrate → 应用发布
```

所以，多环境配置不是“给每个环境改个数据库地址”那么简单，而是要把迁移纳入和代码一致的工程流程中。

## 04、架构

整体方案可以拆成四层：配置层、执行层、校验层、交付层。

配置层负责区分不同环境的连接和参数。Spring Boot 中可以使用 application-dev.yml、application-test.yml、application-prod.yml，配合公共 application.yml。每个文件里只放该环境必要的差异，比如 dev 用本地 PostgreSQL，test 用 Docker Compose 暴露的端口，prod 只放占位配置，连接信息由发布平台注入。

执行层负责实际运行迁移。本地开发可以随应用启动自动 migrate；测试环境可以在应用启动前让 Flyway 先执行，也可以单独运行命令；生产环境建议使用专门的发布步骤执行 migrate，应用随后再启动。

校验层是 CI 的一部分。CI 中跑 flyway validate，检查已提交脚本和 schema_history 是否一致；再启动一个临时空库，从零执行全量迁移，验证所有脚本可运行。这个动作成本很低，但能发现语法错误、版本重复、脚本顺序错误。

交付层是“代码 + SQL + 审核 + 发布”的统一流水线。SQL 脚本跟代码同库存放、同审同发布。生产执行前有人工审批，执行中有窗口记录，执行后有验证和回滚预案。

架构图可以这样画：

```
┌────────────────────────────────────────────┐
│                  Git 仓库                    │
│  src/main/resources/db/migration/           │
│  application-dev.yml / test.yml / prod.yml  │
└────────────────┬───────────────────────────┘
                 │ 提交 / 合并
                 ▼
┌────────────────────────────────────────────┐
│               CI 校验层                     │
│  flyway validate + 临时库全量 migrate       │
└────────────────┬───────────────────────────┘
                 │ 通过
                 ▼
┌────────────────────────────────────────────┐
│            测试环境                         │
│  Docker Compose 独立数据库 → 自动 migrate   │
│  应用集成测试                               │
└────────────────┬───────────────────────────┘
                 │ 审批
                 ▼
┌────────────────────────────────────────────┐
│            生产环境                         │
│  备份 → 受控 migrate → 应用发布 → 验证      │
└────────────────────────────────────────────┘
```

这个架构并不重，关键是职责清晰：日常开发用自动化，生产发布用受控化，CI 用前置拦截。

## 05、实战

下面按实践顺序走一遍。整体步骤可以先看一眼：

```
5.1 配置 → 5.2 测试库 → 5.3 模拟分支 → 5.4 解决冲突 → 5.5 CI 校验 → 5.6 全量迁移 → 5.7 完整流水线
```

### 5.1 建立多环境配置

公共 application.yml 中只保留 Flyway 默认位置等不变项：

```
spring:
  flyway:
    locations: classpath:db/migration
    baseline-on-migrate: false
```

application-dev.yml：

```
spring:
  datasource:
    url: jdbc:postgresql://localhost:5432/app_dev
    username: dev
    password: dev
  flyway:
    enabled: true
```

application-test.yml：

```
spring:
  datasource:
    url: jdbc:postgresql://localhost:5433/app_test
    username: flyway
    password: flyway
  flyway:
    enabled: true
    clean-disabled: false
```

application-prod.yml：

```
spring:
  datasource:
    url: ${DB_URL}
    username: ${DB_USER}
    password: ${DB_PASSWORD}
  flyway:
    enabled: false
```

生产配置里把 flyway.enabled 设为 false，表示应用启动时不自动 migrate，由发布流水线单独执行。这样应用启动顺序更可控。

### 5.2 Docker Compose 独立测试数据库

在 docker-compose-test.yml 里定义测试库和应用：

```
version: '3.9'
services:
  db-test:
    image: postgres:16-alpine
    environment:
      POSTGRES_DB: app_test
      POSTGRES_USER: flyway
      POSTGRES_PASSWORD: flyway
    ports:
      - '5433:5432'
    healthcheck:
      test: ['CMD-SHELL', 'pg_isready -U flyway -d app_test']
      interval: 5s
      timeout: 5s
      retries: 10

  app-test:
    build: .
    depends_on:
      db-test:
        condition: service_healthy
    environment:
      SPRING_PROFILES_ACTIVE: test
```

应用容器通过 depends_on 的 condition 等待数据库健康，避免“应用先起、迁移失败”。如果在本地运行，也可以只启动 db-test，再手动执行 migrate。

### 5.3 模拟两个开发分支同时创建 V10

假设主分支已有 V9。两个开发分别从主分支拉出：

```
feature/a：创建 V10__add_avatar.sql
feature/b：创建 V10__add_nickname.sql
```

合并时就会冲突。冲突的本质是 Flyway 以版本号为唯一标识，两个脚本都想占用 V10，但内容和校验和不同。合并后如果保留两个 V10，Flyway 的 validate 会直接失败或行为不可预期。

### 5.4 合并分支并解决版本冲突

解决方式不是强行保留两个 V10，而是重新分配版本号。将其中一个改为 V10，另一个改为 V11。如果两个功能是并列的小变更，也可以用 V10.1 和 V10.2 这样的点分版本，前提是团队统一规范。

合并后结构：

```
V9__add_audit.sql
V10__add_avatar.sql
V11__add_nickname.sql
```

注意，一旦某个版本已经在测试库或生产库执行过，就不要修改该脚本内容，否则校验和会对不上。需要变更时，新建一个更高版本的脚本。Flyway 的 out-of-order 某些场景能帮上忙，但不应作为默认策略，因为它会掩盖版本依赖问题。

### 5.5 在 CI 中增加 Flyway validate 和临时库迁移

以 GitHub Actions 为示例，可以在 jobs 里使用 PostgreSQL 服务容器：

```
jobs:
  migration-check:
    runs-on: ubuntu-latest
    services:
      postgres:
        image: postgres:16-alpine
        env:
          POSTGRES_DB: ci_db
          POSTGRES_USER: ci
          POSTGRES_PASSWORD: ci
        ports:
          - 5432:5432
        options: >-
          --health-cmd 'pg_isready -U ci -d ci_db'
          --health-interval 5s
          --health-timeout 5s
          --health-retries 10
    steps:
      - uses: actions/checkout@v4
      - name: Set up JDK
        uses: actions/setup-java@v4
        with:
          distribution: temurin
          java-version: 21
      - name: Run validate and migrate on empty DB
        env:
          SPRING_DATASOURCE_URL: jdbc:postgresql://localhost:5432/ci_db
          SPRING_DATASOURCE_USERNAME: ci
          SPRING_DATASOURCE_PASSWORD: ci
          SPRING_FLYWAY_ENABLED: true
        run: |
          mvn flyway:validate
          mvn flyway:migrate
```

在空库上先 validate 再 migrate，可以同时检查命名规范、版本顺序和脚本可执行性。因为每次 CI 都从空库开始，不会有历史状态干扰。

GitLab CI 或 Jenkins 也是同样思路：准备一个临时数据库实例，执行 validate 和 migrate，然后在任务结束时丢弃。

### 5.6 构建临时数据库执行全量 Migration

除了在 CI 中直接启动服务容器，还可以用 Testcontainers 在测试阶段拉起数据库：在集成测试里运行 flyway.migrate，然后执行应用测试。这样等于每一轮都从零构建一次数据库，保证新脚本能从 V1 走到 Vn 不中断。

测试类可以简化为：

```
@Test
void fullMigrationCanRun() {
    Flyway flyway = Flyway.configure()
            .dataSource(dataSource)
            .load();
    flyway.migrate();
}
```

这个测试成本低，但能捕获脚本里偶然破坏历史版本的情况。

### 5.7 完整流水线设计

最终流水线可以串成七步：

```
提交代码
  → CI 校验（静态检查 + Flyway validate + 临时库全量 migrate）
  → 测试库升级（自动 migrate）
  → 应用测试（集成 / 回归）
  → 生产审批（人工确认迁移窗口和数据备份）
  → 生产 Migration（受控执行）
  → 应用发布（滚动 / 蓝绿）
```

其中，测试环境可以配置成每次部署自动 migrate，生产环境则由迁移任务单独执行。生产执行前必须备份，执行后先做 smoke test，再发布应用。一旦迁移失败，应有回滚脚本或恢复备份的预案。

## 06、洞见

第一，测试环境自动 migrate 与生产受控 migrate 有本质区别。测试环境追求反馈速度，自动 migrate 可以让问题尽早暴露，但前提是 CI 已经做过校验。生产环境追求稳定性，任何默认自动行为都是风险。生产中 migrate 应该像数据库变更窗口一样，有审批、有备份、有记录、有回滚。

第二，版本号是迁移的契约。多人协作时，V10 冲突不是因为 Flyway 笨，而是因为版本号被当成随意数字。可以在团队规范中明确：版本号由功能分支统一分配；合并冲突时保留一个版本，另一个顺延；已执行的脚本永不修改。

第三，校验和是一张安全网。它让“改了老脚本”无处可藏。不要用 repair 随便清理校验和，除非你清楚知道自己在做什么。repair 是修正错误，不是绕过错误。

第四，迁移脚本与代码同源同审。迁移脚本放在 Git 仓库，参与代码评审。评审代码时顺便看 SQL：有没有破坏性 DDL？有没有锁表风险？有没有数据回填顺序？这些都比事后补救便宜。

第五，环境隔离不等于结构隔离。dev/test/prod 数据库内容可以不同，但结构必须一致。结构一致性由 Flyway 的版本链保证，而不是靠人工同步。测试环境自动 migrate 时，结构来自同一条版本链，生产环境执行同一条版本链，这样才能保证一致性。

第六，CI 验证的是“能不能跑通”，生产审批验证的是“该不该现在跑”。两者不能互相替代。前者用自动化拦截明显错误，后者用人的判断控制业务风险。

```
测试环境：自动 migrate → 快速暴露问题
生产环境：受控 migrate → 稳定压倒一切
CI 校验：空库全量迁移 → 确保脚本可执行
审批发布：人工判断窗口 → 控制业务风险
```

## 07、行动

如果你们团队刚开始做 Flyway 治理，可以按三个阶段推进。

第一阶段，先把配置和目录统一。建立 application-dev.yml、application-test.yml、application-prod.yml，迁移脚本统一放到 db/migration。本地启动前先确认数据库健康，优先使用 Docker Compose。

第二阶段，把校验放进 CI。每个合并请求都跑 flyway validate 和空库全量 migrate。测试环境迁移改为自动执行，但确保每次执行前有结构备份或可快速重建。

第三阶段，把生产迁移纳入审批。设计迁移工单，写明版本范围、涉及表、预计耗时、备份策略、回滚方案。生产 migrate 和应用发布拆成两步，应用启动时不再默认迁移。

路线图可以画成：

```
第 1 周：配置 + 目录 + Compose
   ↓
第 2-4 周：CI 校验 + 测试环境自动 migrate
   ↓
第 1-2 月：生产审批 + 受控 migrate + 回滚演练
```

不要一口吃成胖子。先把“脚本版本化”和“CI 校验”跑顺，再推进生产受控。

## 08、小结

迁移脚本不是附属于代码的 SQL，而是数据库的代码。把它当代码管理，版本冲突、环境漂移、发布混乱都会自然消退。工具本身并不复杂，复杂的是协作和流程。Flyway 给了我们版本、校验和、多环境参数，剩下的就是团队约定和自动化落地。别等生产出事才想起迁移。

```
迁移脚本 → 版本控制 → CI 校验 → 受控发布
```

## 09、链接与概念说明

**概念澄清**

- Flyway 命令：migrate 执行未应用的脚本；validate 检查已应用脚本的一致性；info 查看版本状态；repair 修复 schema_history 中的校验和不一致；baseline 为已有库设置基线版本，适用于存量项目接入。
- Checksum：脚本内容的哈希，任何修改都会导致不一致。
- Out-of-order：允许乱序执行迁移，但不建议作为默认策略。
- Placeholder：迁移脚本中的占位符，可通过配置注入环境相关值。
- Spring Boot Profile：用 application-{profile}.yml 区分环境配置，激活使用 spring.profiles.active。
- Docker Compose healthcheck：让容器等待数据库就绪后再启动应用，避免顺序问题。
- Testcontainers：在测试环境中启动临时数据库容器，适合全量迁移验证。

```
validate（校验） ← → migrate（迁移）
info（查看）   ← → repair（修复）
baseline（基线） → 存量项目接入
```

**延伸阅读方向**

- Flyway 官方文档：docs.flywaydb.org
- Spring Boot 数据迁移章节：spring.io 参考手册
- Docker Compose depends_on 与 healthcheck：docker docs
- Git 分支模型：git-scm.com/book
- CI 服务容器：GitHub Actions / GitLab CI / Jenkins 文档

这些资料适合在落地过程中对照查阅，不展开。

最近我们团队在发布季就踩了三个坑：本地开发好好的，测试环境少了一张订单扩展表；两个同事都从主分支拉出 V10，合并后 Flyway 直接报校验和不匹配；生产发布时才临时补迁移脚本，结果应用先起来，连不上新字段。我是老李。这些问题不是 Flyway 本身有多难，而是我们一直把数据库迁移当成发布前顺手执行的 SQL，没有像管理代码一样管理它。

《Spring Boot Flyway 实战手册》第4招 多环境与 CI/CD——让数据库变更进入标准发布流水线

用一套可复现、可校验、可审批的数据库迁移流水线，解决多环境漂移、V10 冲突和 CI 漏检问题。

架构师

数据库

后端

开发工具

数据库迁移需纳入代码级管理，通过Flyway多环境配置实现版本化控制、CI校验与受控发布，解决环境漂移、版本冲突和发布混乱问题，确保开发测试生产环境结构一致，降低上线风险。

数据备份

数据迁移

集成测试

代码解释

PostgreSQL

容器

Docker

2026上云采购 | AI焕新·智启新局

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

《Spring Boot Flyway 实战手册》第4招 多环境与 CI/CD——让数据库变更进入标准发布流水线-腾讯云开发者社区-腾讯云

《Spring Boot Flyway 实战手册》第4招多环境与 CI/CD——让数据库变更进入标准发布流水线

《Spring Boot Flyway 实战手册》第4招多环境与 CI/CD——让数据库变更进入标准发布流水线

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐

《Spring Boot Flyway 实战手册》第4招 多环境与 CI/CD——让数据库变更进入标准发布流水线

《Spring Boot Flyway 实战手册》第4招 多环境与 CI/CD——让数据库变更进入标准发布流水线

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐

《Spring Boot Flyway 实战手册》第4招多环境与 CI/CD——让数据库变更进入标准发布流水线

《Spring Boot Flyway 实战手册》第4招多环境与 CI/CD——让数据库变更进入标准发布流水线