从 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 个前提
- 停止旧版 Yearning v3 服务:禁止迁移期间产生新工单或双写。
- 结清全部在途任务:旧库中不能有未闭环的活动工单或未完成定时任务(否则报
5001 MIGRATION_ACTIVE_WORK_EXISTS阻断)。 - 备份旧 MySQL 数据库:保存完整的
mysqldump备份及校验和。 - 准备好空白 PostgreSQL 14–18 目标库与 v4
keyring.json:记下keyring.json里的deployment_id和payload密钥的key_id、key_base64。
2. 编写完整 migration-config.json
注意以下两个关键字段:
source.legacy_secret_key:填入旧版 v3conf.toml中 16 位General.SecretKey的引用(环境变量或0600文件,严禁命令行传参),迁移器将自动完成 旧 AES-128-CBC 解密 → v4 AES-256-GCM 重加密。encryption.deployment_id:必须与目标环境keyring.json中的deployment_id完全一致,否则密文 AAD 校验会失败导致运行时无法解密。
3. 六步完成停机切换
步骤 4:人工审查与批准权限映射
- 浏览器访问
http://127.0.0.1:9100(若在 Kubernetes 集群内运行,先执行kubectl port-forward svc/yearning-migration-review 9100:9100 -n yearning),使用刚才引导的admin账号登录。 - 逐项核对 v3 迁移生成的用户、数据源、审批流程与权限组候选映射(如果某数据源未提供
legacy_secret_key导致密码被隔离,界面会明确标注)。 - 全部候选确认无误后,在确认框输入短语
APPROVE <run_uuid>提交批准。
步骤 5 & 6:正式写入与全量抽样解密核验
确认输出 all_passed=true 且 legacy_migration_runs.state = verified 后:
- 立即终止
--migration-mode审查进程(K8s 环境将yearning-migration-review缩容为 0 或删除)。 - 为目标库执行
db/roles/grants.sql,然后启动正式的yearning serve控制面切流。
4. 迁移失败时的唯一合法恢复方式
禁止在失败目标库上续跑
migrate apply
migrate apply 失败或收到两次 SIGTERM 后,目标库处于半写入作废态,再次对同一失败 run_id 执行 apply 会被 CLI 直接以退出码 5 拒绝。切勿手工删表修数据后硬上线!
正确恢复命令: