DataOps-platform/docs/runbooks/kestra-dual-run-and-rollback.md

Kestra 双轨迁移与回切运行手册

适用范围

本手册用于把单个 DataFlow 从 n8n 正式执行逐步迁移到 Kestra。迁移是逐流程、 逐环境进行的，不允许一次性改变全局正式引擎。

四种受控状态如下：

1. n8n_primary：n8n 是唯一正式引擎。
2. n8n_primary_kestra_shadow：n8n 正式执行，Kestra 只读或写入隔离目标。
3. kestra_primary_n8n_standby：Kestra 正式执行，n8n 保留为可回切目标。
4. kestra_primary：仅在统一退役门禁独立批准后允许进入。

状态只能沿相邻路径前进或回退，禁止从 n8n_primary 直接跳到 kestra_primary。

迁移前准备

• 使用 scripts/inventory_n8n_workflows.py 取得目标环境的实时资产清单。空的本地 清单不能替代生产清单。
• 导出一个目标 Workflow，并建立 n8n 节点到 DataOps 数据源 UID 的显式映射。 映射中不得包含密码、连接串或 API Key。
• 使用 app.commands.migrate_n8n_workflow 生成 WorkflowSpec、SchedulePlan 和 阻断报告。命令只转换，不部署。
• 未支持的社区节点、脚本节点和不能证明幂等性的写节点必须人工改造；转换器不会 生成任意脚本作为降级方案。
• 为写流程声明影子 Schema、表或对象键前缀。只读流程使用 read_only 隔离策略。

影子运行与对账

同一次双跑必须使用不可变的同一输入快照，并记录 SHA-256 输入摘要。n8n 仍是 唯一正式写入引擎，Kestra 只能：

• 只读执行；或
• 写入预先声明的隔离目标。

每次执行用 app.commands.reconcile_dual_run 对账以下指标：

• 状态、行数、主键摘要、内容摘要和异常数；
• 预先声明的聚合值；
• 执行耗时和资源消耗。

对账文件只包含有界指标和摘要，不保存业务原始行。状态、行数、主键摘要、内容 摘要和异常数不能配置为忽略项。非确定性时间戳或资源波动只能通过显式路径和数值 容差处理。

批次顺序和门禁

迁移顺序固定为：

1. 只读、低频、无下游依赖；
2. 幂等分区写；
3. 多节点核心流程；
4. 高风险写、长任务和特殊节点。

进入一个批次前，资产清单、WorkflowSpec、策略、回滚目标、规定次数的影子运行、 一次失败恢复、对账、连接预算、峰值并发和 SLA 必须全部通过。任一门禁缺失即 失败关闭。

切换

1. 调用切换服务创建带幂等键的切换请求。
2. 数据库在同一事务中写入 workflow_cutover_operations、把迁移状态标记为 transition_pending，并写入 workflow.engine.cutover.requested Outbox 事件。
3. 消费者先停用目标 n8n Workflow，再启用 Kestra Flow。
4. 成功后把流程状态提交为 kestra_primary_n8n_standby。
5. Kestra 激活失败时立即重新激活 n8n，并把操作记录为 rolled_back。原始异常 和引擎响应不会进入审计，只记录安全原因码与有界状态。

不得在数据库事务中发起 n8n 或 Kestra HTTP 请求。

观察期

观察期必须达到流程预先声明的时长，并且满足：

• 没有未解释差异、重复写入或关键 SLA 违约；
• 自动暂停、有限重试和回切至少演练一次；
• n8n 保持 Standby，且没有未授权外部修改；
• 没有实际回切请求。

观察期未结束或出现任一事件时，不允许推进下一批或退役 n8n。

显式回切

1. 确认当前状态是 kestra_primary_n8n_standby。
2. 使用新的幂等键提交回切。
3. 系统先停用 Kestra，再重新激活 n8n。
4. 数据库状态返回 n8n_primary_kestra_shadow。
5. 检查 n8n 已激活、Kestra 已禁用、Outbox 无重复事件，并重新执行针对性对账。

若引擎状态不明确，暂停该流程，不允许同时启用两个正式写入引擎。