For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt, and this page is available as Markdown at /operations/migration-v3-to-v4.md.
  • 简体中文
  • 从 Yearning v3 停机迁移实战

    公测版本迁移提醒(Public Beta)

    Yearning v4.0 目前仍处于 公测阶段(Public Beta)。请务必先使用 v3 生产 MySQL 的脱敏/克隆副本完整演练一遍 preflight -> dry-run -> apply -> verify 并核对业务流转,切勿在未演练前直接对生产 v3 实例执行割接。

    Yearning v4 将元数据库从旧版 MySQL 迁移为全新 PostgreSQL 领域模型。为彻底杜绝双写漂移与权限误映射,v4 采用 停机迁移 → Dry-Run → 管理员人工确认映射 → Apply → 全量核验 的显式流程。

    1. 迁移前必须满足的 4 个前提

    1. 停止旧版 Yearning v3 服务:禁止迁移期间产生新工单或双写。
    2. 结清全部在途任务:旧库中不能有未闭环的活动工单或未完成定时任务(否则报 5001 MIGRATION_ACTIVE_WORK_EXISTS 阻断)。
    3. 备份旧 MySQL 数据库:保存完整的 mysqldump 备份及校验和。
    4. 准备好空白 PostgreSQL 14–18 目标库与 v4 keyring.json:记下 keyring.json 里的 deployment_id 和 payload 密钥的 key_id、key_base64。

    2. 编写完整 migration-config.json

    注意以下两个关键字段:

    • source.legacy_secret_key:填入旧版 v3 conf.toml 中 16 位 General.SecretKey 的引用(环境变量或 0600 文件,严禁命令行传参),迁移器将自动完成 旧 AES-128-CBC 解密 → v4 AES-256-GCM 重加密。
    • encryption.deployment_id:必须与目标环境 keyring.json 中的 deployment_id 完全一致,否则密文 AAD 校验会失败导致运行时无法解密。
    {
      "source": {
        "host": "old-mysql.internal.example.com",
        "port": 3306,
        "database": "Yearning",
        "username": "yearning_v3_readonly",
        "password": { "environment": "LEGACY_MYSQL_PASSWORD" },
        "legacy_secret_key": { "file": "/run/secrets/v3-secret-key" },
        "tls": {
          "mode": "verify_full",
          "server_name": "old-mysql.internal.example.com",
          "ca_file": "/etc/yearning/tls/mysql-ca.pem"
        }
      },
      "target": {
        "host": "new-pg.internal.example.com",
        "port": 5432,
        "database": "yearning_v4",
        "username": "yearning_migrator",
        "password": { "environment": "TARGET_PG_PASSWORD" },
        "tls": {
          "mode": "verify_full",
          "server_name": "new-pg.internal.example.com",
          "ca_file": "/etc/yearning/tls/pg-ca.pem"
        }
      },
      "encryption": {
        "key_id": "prod-k1-payload",
        "key": { "file": "/run/secrets/v4-payload-key-base64" },
        "deployment_id": "yearning-prod-01"
      },
      "source_timezone": "Asia/Shanghai",
      "batch_rows": 1000
    }

    3. 六步完成停机切换

    export LEGACY_MYSQL_PASSWORD="OLD_MYSQL_READONLY_PASS"
    export TARGET_PG_PASSWORD="NEW_PG_MIGRATOR_PASS"
    
    # 步骤 1:在空白 PostgreSQL 上初始化 v4 Schema 与列目录
    ./yearning migrate preflight --config migration-config.json
    ./yearning migrate apply \
      --config migration-config.json \
      --migrations-dir ./db/migrations \
      --catalog ./api/contracts/postgresql-column-catalog.json
    ./yearning migrate verify --config migration-config.json
    
    # 步骤 2:启动临时迁移审查工作台并引导内置 admin(默认仅监听本机 127.0.0.1:9100)
    ./yearning serve --migration-mode \
      --config migration-config.json \
      --bootstrap-admin-password-file /run/secrets/admin-password &
    
    # 步骤 3:执行 Dry-Run,生成脱敏审计报告与候选权限映射(获得 <run_uuid>)
    ./yearning migrate dry-run \
      --config migration-config.json \
      --report-dir /var/lib/yearning/migration-reports

    步骤 4:人工审查与批准权限映射

    1. 浏览器访问 http://127.0.0.1:9100(若在 Kubernetes 集群内运行,先执行 kubectl port-forward svc/yearning-migration-review 9100:9100 -n yearning),使用刚才引导的 admin 账号登录。
    2. 逐项核对 v3 迁移生成的用户、数据源、审批流程与权限组候选映射(如果某数据源未提供 legacy_secret_key 导致密码被隔离,界面会明确标注)。
    3. 全部候选确认无误后,在确认框输入短语 APPROVE <run_uuid> 提交批准。

    步骤 5 & 6:正式写入与全量抽样解密核验

    # 步骤 5:绑定已批准的 run_uuid 执行正式数据迁移
    ./yearning migrate apply \
      --config migration-config.json \
      --run-id <approved_run_uuid>
    
    # 步骤 6:全量核验行数、谱系(Lineage)、逻辑引用以及运行时 AAD 抽样解密
    ./yearning migrate verify \
      --config migration-config.json \
      --run-id <approved_run_uuid> \
      --report-dir /var/lib/yearning/migration-reports

    确认输出 all_passed=true 且 legacy_migration_runs.state = verified 后:

    1. 立即终止 --migration-mode 审查进程(K8s 环境将 yearning-migration-review 缩容为 0 或删除)。
    2. 为目标库执行 db/roles/grants.sql,然后启动正式的 yearning serve 控制面切流。

    4. 迁移失败时的唯一合法恢复方式

    禁止在失败目标库上续跑

    migrate apply migrate apply 失败或收到两次 SIGTERM 后,目标库处于半写入作废态,再次对同一失败 run_id 执行 apply 会被 CLI 直接以退出码 5 拒绝。切勿手工删表修数据后硬上线!

    正确恢复命令:

    # 1. 销毁失败的 PostgreSQL 目标库并重建空库
    psql "$PG_ADMIN_DSN" -c 'DROP DATABASE yearning_v4;'
    psql "$PG_ADMIN_DSN" -c 'CREATE DATABASE yearning_v4 OWNER yearning_schema_owner;'
    
    # 2. 修正配置或源数据问题后,从「步骤 1」完整重新跑一遍 Preflight -> Dry-Run -> 批准 -> Apply -> Verify