scripts/migration/MIGRATION_TEST.md

AxonHub 迁移测试脚本

自动化测试数据库版本升级迁移的脚本。

概述

migration-test.sh 脚本用于验证 AxonHub 的数据库迁移功能。它会自动下载指定发布标签的二进制文件，初始化数据库，然后使用当前分支的代码执行迁移，并可选地运行 E2E 测试来验证数据的完整性。

快速开始

# SQLite（默认，无需 Docker）
./scripts/migration/migration-test.sh v0.1.0

# MySQL（需要 Docker）
./scripts/migration/migration-test.sh v0.1.0 --db-type mysql

# PostgreSQL（需要 Docker）
./scripts/migration/migration-test.sh v0.1.0 --db-type postgres

# 测试所有数据库
./scripts/migration/test-migration-all-dbs.sh v0.1.0

前置条件

• Go 环境: 脚本需要编译当前分支代码，确保已安装 Go。
• SQLite (默认): 无需额外依赖。
• MySQL: 需要安装并运行 Docker，端口 13306 未被占用。
• PostgreSQL: 需要安装并运行 Docker，端口 15432 未被占用。
• 工具: 需要 unzip 用于解压下载的二进制文件。

功能特性

1. 自动下载和缓存二进制文件 - 从 GitHub Releases 下载指定 tag 的可执行文件，并缓存到本地。
2. 测试版本升级 - 支持从任意 tag 版本迁移到当前分支最新代码。
3. 多数据库支持 - 支持 SQLite、MySQL、PostgreSQL 数据库的迁移测试。
4. 生成迁移计划 - 自动生成包含初始化和迁移步骤的 JSON 计划。
5. E2E 测试验证 - 迁移完成后自动运行 E2E 测试验证数据完整性。
6. 配置一致性 - 使用与 e2e-test.sh 相同的配置，确保测试环境一致。

命令行参数

参数	说明
from-tag	(必需) 要测试迁移的起始 Git tag（例如：v0.1.0）
--db-type TYPE	数据库类型: sqlite, mysql, postgres (默认: sqlite)
--skip-download	如果缓存中已存在二进制文件，跳过下载直接使用
--skip-e2e	迁移后跳过运行 E2E 测试
--keep-artifacts	测试完成后保留工作目录（日志、数据库文件等）
--keep-db	测试完成后保留数据库容器（仅限 MySQL/PostgreSQL）
-h, --help	显示帮助信息

常用示例

• 保留数据库容器以供手动检查:

  ./scripts/migration-test.sh v0.1.0 --db-type mysql --keep-db
  

• 跳过 E2E 测试仅验证迁移过程:

  ./scripts/migration-test.sh v0.1.0 --skip-e2e
  

• 使用缓存的二进制文件并保留测试产物:

  ./scripts/migration-test.sh v0.1.0 --skip-download --keep-artifacts
  

数据库配置与连接

MySQL

• 容器名称: axonhub-migration-mysql
• 端口: 13306
• 数据库/用户/密码: axonhub_test / axonhub / axonhub_test
• 连接命令: docker exec -it axonhub-migration-mysql mysql -u axonhub -paxonhub_test axonhub_test

PostgreSQL

• 容器名称: axonhub-migration-postgres
• 端口: 15432
• 数据库/用户/密码: axonhub_test / axonhub / axonhub_test
• 连接命令: docker exec -it axonhub-migration-postgres psql -U axonhub -d axonhub_test

SQLite

• 数据库文件: scripts/migration/migration-test/work/migration-test.db
• 查看命令: sqlite3 scripts/migration/migration-test/work/migration-test.db

批量测试

migration-test-all.sh 脚本可以测试多个版本在所有支持的数据库上的迁移：

# 测试最近 3 个版本在所有数据库上的迁移
./scripts/migration/migration-test-all.sh

# 测试指定版本在 SQLite 上的迁移
./scripts/migration/migration-test-all.sh --tags v0.1.0,v0.2.0 --db-type sqlite

工作流程

1. 检测系统架构 - 自动检测操作系统和 CPU 架构（linux/darwin, amd64/arm64）。
2. 设置数据库环境 - 根据指定类型设置 SQLite 文件或 Docker 容器。
3. 下载/缓存旧版本二进制 - 从 GitHub 下载指定版本的可执行文件。
4. 构建当前版本 - 编译当前分支的最新代码。
5. 生成迁移计划 - 创建包含版本信息的 migration-plan.json。
6. 初始化数据库 - 使用旧版本二进制初始化数据库结构。
7. 执行迁移 - 使用当前分支版本运行数据库迁移。
8. 运行 E2E 测试 - 验证迁移后的数据库功能是否正常（可选）。
9. 清理 - 清理临时文件和容器（可选保留）。

目录结构

scripts/
├── migration-test.sh           # 主脚本
├── migration-test/             # 测试工作根目录
│   ├── cache/                  # 二进制文件缓存
│   │   └── v0.1.0/
│   │       └── axonhub         # 缓存的 v0.1.0 二进制
│   └── work/                   # 工作目录（测试后默认清理）
│       ├── axonhub-current     # 当前分支编译的二进制
│       ├── migration-test.db   # 测试数据库（SQLite）
│       ├── migration-test.log  # 测试详细日志
│       └── migration-plan.json # 迁移步骤计划

故障排查

• Docker 未运行: 请确保 Docker Desktop 或守护进程已启动。
• 端口占用: 确保 8099 (Server), 13306 (MySQL), 15432 (Postgres) 端口未被占用。
• 下载失败/限流: 设置 GITHUB_TOKEN 环境变量以避免 GitHub API 速率限制。
• 查看详细日志: 实时查看日志：tail -f scripts/migration-test/work/migration-test.log。

CI/CD 集成

GitHub Actions 示例

jobs:
  migration-test:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        db-type: [sqlite, mysql, postgres]
        from-version: [v0.1.0, v0.2.0]
    steps:
      - uses: actions/checkout@v3
      - name: Set up Go
        uses: actions/setup-go@v4
        with:
          go-version: '1.21'
      - name: Run migration test
        run: |
          ./scripts/migration-test.sh ${{ matrix.from-version }} \
            --db-type ${{ matrix.db-type }}

与其他脚本的关系

• e2e-test.sh - 运行完整的 E2E 测试套件。
• e2e-backend.sh - 管理 E2E 测试后端服务器。
• migration-test.sh - 测试单个版本的数据库迁移。
• migration-test-all.sh - 批量测试多个版本的迁移。