数据库迁移（Flyway）

概述

系统使用 Flyway 管理数据库版本迁移，确保生产环境数据库 Schema 的版本控制和自动化执行。

环境配置

开发环境（application-dev.yaml）

spring:
  flyway:
    enabled: false  # 开发环境禁用，需手动执行 SQL

生产环境（application-prod.yaml）

spring:
  flyway:
    enabled: true                    # 生产环境启用
    locations: classpath:db/migration # 迁移脚本目录
    baseline-on-migrate: true        # 首次迁移时自动 baseline
    baseline-version: 0              # baseline 版本号
    validate-on-migrate: true        # 迁移前校验

迁移脚本目录

迁移脚本必须放在以下目录：

backend/src/main/resources/db/migration/

命名规范

Flyway 迁移文件命名格式：

V{版本号}__{描述}.sql

• V — 表示版本化迁移（Versioned Migration）
• 版本号 — 必须是递增的数字，如 1, 2, 3, ..., 30
• 双下划线 — 版本号和描述之间用双下划线 __ 分隔
• 描述 — 简短的迁移描述，单词间用下划线分隔

示例

V1__init_schema.sql                          # 初始化建表
V2__add_qq_openid_to_user.sql                # 给用户表添加 QQ openid 字段
V12__add_points_system.sql                    # 添加积分系统
V53__add_seafile_oauth_client.sql             # Seafile OAuth 客户端
V54__add_new_field.sql                        # 新字段示例

现有迁移脚本

系统已有 53 个迁移脚本（V1 ~ V53），按功能分类：

基础初始化

用户与认证

机器人

博客

图床与展示

积分系统

抽奖与投票

数据开放

晚自习与签到

规章与校友

加入页与用户演进

合作社团与外部身份

统一分组与近期功能

新增迁移脚本流程

1. 确定版本号

查看现有最大版本号（当前为 V53），下一个版本号为 V54。

2. 创建迁移文件

# 在正确目录下创建
touch backend/src/main/resources/db/migration/V54__add_new_feature.sql

3. 编写 SQL

-- V54__add_new_feature.sql

-- 添加新字段
ALTER TABLE `club_membership` ADD COLUMN `new_field` VARCHAR(255) DEFAULT NULL COMMENT '新字段说明';

-- 添加新表
CREATE TABLE IF NOT EXISTS `new_table` (
    `id` BIGINT NOT NULL AUTO_INCREMENT,
    `name` VARCHAR(255) NOT NULL,
    `created_at` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
    `updated_at` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
    PRIMARY KEY (`id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;

4. 开发环境手动执行

mysql -u root -p openatom_db < backend/src/main/resources/db/migration/V54__add_new_feature.sql

5. 生产环境自动执行

部署后 Flyway 会自动执行新迁移脚本。

Flyway 兼容策略

系统已有历史数据库首次接入 Flyway 时的处理策略：

1. Baseline：首次接入时 baseline 到版本 0
2. V1 幂等：V1__init_schema.sql 使用 CREATE TABLE IF NOT EXISTS，确保幂等
3. 兜底：SchemaCompatibilityInitializer 在应用层做 Schema 兼容性兜底
4. 持续演进：从 V2 开始按版本号递增

常见问题

迁移校验失败

现象：启动报 Flyway validation failed。

原因：已执行的迁移脚本被修改，导致 checksum 不匹配。

解决：

• 不要修改已执行的迁移脚本
• 如确需修复，使用 flyway repair 命令重置 checksum

迁移版本号冲突

现象：启动报 Flyway duplicate migration version。

解决：确保每个版本号只使用一次，新脚本使用下一个可用版本号。

脚本未执行

现象：新增了 SQL 文件但 Flyway 未执行。

排查：

1. 确认文件在 backend/src/main/resources/db/migration/ 目录下
2. 确认文件名格式为 V{数字}__{描述}.sql（双下划线）
3. 确认 Flyway 已启用（enabled: true）