# Kestra 改造 V50–V55 顺序交付与增量验证计划

> 状态：实施序列已确认；必须按 V50 → V55 顺序推进。每个版本只有在本版本
> 增量验证通过并留下验证记录后，才能进入下一版本。

## 1. 版本口径

V50–V55 是 DataOps Platform 的功能交付里程碑，不是 Alembic migration
revision，也不替代 `pyproject.toml` 中的产品语义版本。

仓库已经存在 `20260718_50_datasource_credentials.py`，因此 Kestra 编排相关的
第一条数据库迁移继续使用主计划中的 `20260718_60_workflow_engine_abstraction.py`。
不得为了匹配 V50 名称而重命名已经存在或已经执行的迁移。

## 2. 总体推进规则

```mermaid
flowchart LR
    V50["V50\n迁移基线与引擎无关模型"] --> V51["V51\nKestra 与引擎适配"]
    V51 --> V52["V52\nDataOps Runner 与资源池"]
    V52 --> V53["V53\nContext / Scheduling MCP"]
    V53 --> V54["V54\nAI 调度规划闭环"]
    V54 --> V55["V55\n双轨迁移、切换与有条件退役"]
```

统一规则：

1. 每个版本只实现本版本声明的范围，不提前混入下一版本功能。
2. 每个版本必须先运行新增/修改代码的单元测试，再运行受影响边界的契约或集成测试。
3. 默认不执行全仓库、全前端、全容器验证；按变更影响选择最小充分测试集。
4. 测试失败、迁移不可回滚、秘密泄漏、重复写风险或上一版本退出条件未满足时停止推进。
5. 每个版本保存一份 `docs/validation/kestra-v<version>.md`，记录代码版本、测试命令、
   结果、已知限制和是否允许进入下一版本。
6. V50–V54 始终保留 n8n 正式运行路径；V55 也只有满足退出门槛后才允许移除 n8n。

## 3. 分层验证策略

| 级别 | 内容 | 使用时机 |
|---|---|---|
| L1 变更级 | 新增/修改模块的单元测试、Schema 和静态检查 | 每个版本必跑 |
| L2 边界级 | 相邻模块契约、数据库迁移、MCP/API 合约 | 该版本改变边界时运行 |
| L3 场景级 | 只启动相关容器的集成或冒烟场景 | V51–V55 按范围运行 |
| L4 全量级 | 全部 Python 测试、前端构建、完整本地栈验收 | 不按版本重复执行；仅在 V55 真正下线 n8n 前执行一次 |

出现以下情况可以额外触发 L4，但必须在验证记录中说明原因：

- 修改认证/RBAC、全局数据库会话、应用启动入口或公共响应协议。
- 修改共享基础镜像、Python/Node 版本或全局依赖锁。
- 修改跨越三个以上业务域的公共模块，无法通过 L1–L3 隔离风险。
- 准备生产切换、正式移除 n8n，或发现难以定位的跨模块回归。

代码格式化、文档修改或单一模块变更不得机械触发 L4。

## 4. V50：迁移基线与引擎无关领域模型

### 目标

在不改变生产执行路径的前提下，完成 n8n 资产盘点、WorkflowSpec/SchedulePlan
Schema、通用引擎绑定和迁移审计模型，为后续接入 Kestra 建立稳定契约。

### 实施范围

- 导出不含凭据内容的 n8n Workflow 迁移清单和定义哈希。
- 建立 `app/core/orchestration/` 领域模块。
- 增加通用 `engine_type`、`engine_definition_id`、`engine_revision` 和绑定表。
- 回填现有记录为 `engine_type='n8n'`，保留原有 n8n 字段。
- 建立 WorkflowSpec、SchedulePlan、节点注册表、DAG 和秘密字段校验。
- 维持同一 DataFlow/环境只有一个正式版本和正式引擎。

### 本版本不做

- 不部署 Kestra。
- 不改变 n8n 调度、启停和执行行为。
- 不创建 Runner 或 MCP 服务。
- 不允许 AI 发布或修改工作流。

### 增量验证

L1：

```bash
.venv/bin/python -m pytest -q \
  tests/test_n8n_migration_inventory.py \
  tests/core/orchestration/test_spec.py \
  tests/core/orchestration/test_repository.py \
  tests/core/orchestration/test_policy.py
```

L2：

```bash
.venv/bin/python -m pytest -q \
  tests/test_database_migrations.py \
  tests/test_workflow_version_schema.py \
  tests/test_workflow_repository.py \
  tests/test_workflow_activation.py
```

### 退出门槛

- 全部活跃及近 90 天执行过的 n8n Workflow 均进入盘点或阻塞清单。
- 数据库迁移可升级、可降级，现有 n8n 数据可无损读取。
- 明文秘密、环形 DAG、未知节点、无限重试和无界回填被拒绝。
- n8n 原有正式流程继续运行，行为没有改变。

### 回滚点

回滚新建表和新增字段；DataOps 恢复只读取原有 n8n 映射。不得删除或重写现有
n8n Workflow。

## 5. V51：Kestra OSS、官方 MCP 与引擎适配

### 目标

在本地隔离环境部署固定版本 Kestra OSS 和官方 Python MCP，完成
`N8nAdapter`、`KestraAdapter` 与确定性 Kestra 编译器；n8n 仍是唯一正式引擎。

### 实施范围

- 在 Compose 中增加 Kestra OSS 和官方 MCP，使用独立数据库或 Schema。
- 服务只加入内部网络，关闭不使用和企业版工具组。
- 建立统一引擎生命周期接口。
- 将 WorkflowSpec 确定性编译为默认禁用的 Kestra Flow。
- 验证创建/更新、启停、执行、日志、Pause/Kill、Backfill、Replay、
  Restart 和 Resume 契约。
- 建立 Kestra MCP 工具和参数 Schema 差异检测。

### 本版本不做

- Kestra 不访问业务数据源。
- 不运行生产影子任务。
- 不开放原始 Kestra MCP 给智能体。
- 不改变任何 DataFlow 的正式引擎角色。

### 增量验证

L1/L2：

```bash
.venv/bin/python -m pytest -q \
  tests/test_kestra_local_contract.py \
  tests/core/orchestration/test_engine_contract.py \
  tests/core/orchestration/test_kestra_compiler.py
```

L3 仅启动 PostgreSQL、Kestra 和 MCP：

```bash
docker compose -f deploy/docker/docker-compose.yml up -d postgres kestra kestra-mcp
.venv/bin/python -m pytest -q tests/integration/test_kestra_mcp_contract.py
```

### 退出门槛

- 相同 WorkflowSpec 产生相同 Kestra 定义哈希。
- 新 Flow 和 Schedule Trigger 默认禁用。
- MCP 合约覆盖计划使用的全部写操作，未授权工具不可用。
- Kestra/MCP 停止后，DataOps 与 n8n 原有功能不受影响。

### 回滚点

停止 Kestra/MCP 容器并删除未激活的 Kestra 测试定义；n8n 保持正式执行。

## 6. V52：DataOps Runner 与现有数据库资源池

### 目标

把数据任务执行从 Flask 请求进程解耦到 DataOps Runner，复用现有
`DataSourceConnectionManager`，让 Kestra 只携带数据源 UID 和任务身份。

### 实施范围

- 建立独立 Runner 服务、显式配置和节点注册表。
- 支持首批 `sql.query`、`sql.execute`、受限 `python` 和 `http` 节点。
- 使用短时、单任务绑定、防重放的签名令牌。
- SQL 参数化；查询强制只读，写入必须通过权限和幂等策略。
- Runner 副本、Worker 和连接池参数进入全局连接预算。
- 验证超时、重试、重启、熔断和事务未知状态。

### 本版本不做

- 不让 AI 决定写入权限或幂等性。
- 不把数据库密码或连接串写入 Kestra。
- 不对正式数据目标进行 Kestra 影子写入。

### 增量验证

L1/L2：

```bash
.venv/bin/python -m pytest -q \
  tests/runner \
  tests/core/data_source \
  tests/test_datasource_api_security.py \
  tests/test_datasource_pool_diagnostics.py
```

L3 只验证 Runner 与两个外部测试数据库：

```bash
docker compose -f deploy/docker/docker-compose.yml up -d \
  postgres source-postgres source-mysql runner
.venv/bin/python -m pytest -q \
  tests/integration/test_runner_datasource_pool.py \
  tests/integration/test_datasource_pool_failures.py
```

### 退出门槛

- Kestra 和日志中不存在业务数据库密码、密文或完整连接串。
- 重复任务令牌不会造成重复提交。
- Runner/数据源失败不会影响平台控制库和其他数据源。
- n8n 正式执行路径保持不变。

### 回滚点

停止 Runner 和 Kestra 测试调用；保留现有 Flask 内的数据源连接池路径，不迁移
正式任务。

## 7. V53：DataOps Context MCP 与 Scheduling MCP Gateway

### 目标

建立 AI 可读的业务上下文面和可写的受控调度面，将权限、审计和危险动作限制
放在 DataOps，而不是依赖 Kestra 企业版能力。

### 实施范围

- Context MCP 提供 DataFlow、血缘、SLA、执行历史、数据源能力和池健康。
- Scheduling MCP Gateway 提供候选计划、禁用发布、Canary、推广、暂停、
  有界回填、限次重试和回滚等复合工具。
- 所有工具绑定身份、角色、业务域、环境和 correlation ID。
- 建立参数上限、连接预算、幂等、时间窗口、Prompt injection 和审计策略。
- 禁止直接暴露任意 YAML、删除、状态篡改、KV/文件修改和动态连接配置。

### 本版本不做

- 不接入自主调度 Agent。
- 不允许模型直接调用 Kestra MCP。
- 不推广任何生产 Kestra Flow。

### 增量验证

L1/L2：

```bash
.venv/bin/python -m pytest -q \
  tests/mcp/test_dataops_context_mcp.py \
  tests/mcp/test_scheduling_gateway.py \
  tests/security/test_scheduling_tool_boundaries.py \
  tests/test_permission_matrix.py \
  tests/test_system_auth.py
```

L3 只验证 Gateway → Kestra/MCP → 审计链路：

```bash
.venv/bin/python -m pytest -q \
  tests/integration/test_kestra_mcp_contract.py \
  tests/integration/test_scheduling_gateway_audit.py
```

### 退出门槛

- Viewer、Editor 和调度服务身份只能访问授权业务域和工具。
- 敏感信息、超范围回填、无限重试和未经校验的 YAML 均被拒绝。
- 相同推广请求重复提交保持幂等。
- 日志或元数据中的恶意文本不能改变工具权限和策略。

### 回滚点

撤销智能体身份的 Gateway 访问权限并停止两个 MCP 服务；Kestra 保持禁用版本，
n8n 继续正式运行。

## 8. V54：AI 调度规划、Canary 与恢复闭环

### 目标

让调度智能体通过 DataOps MCP 完成“观察 → 生成候选 → 校验 → 模拟 →
禁用发布 → Canary → 推广建议 → 监控 → 恢复/回滚”的受控闭环。

### 实施范围

- 规划器输出严格的 WorkflowSpec/SchedulePlan 结构，不输出可直接执行的任意 YAML。
- 保存模型、Prompt、Schema、上下文哈希、候选计划、校验和动作结果。
- 建立模型超时、无效输出、工具失败和目标冲突的确定性降级。
- 恢复智能体只允许暂停、降并发、限次重试和回到上一稳定版本。
- 选择 1–2 个只读、低频流程执行 Kestra Canary；n8n 仍为正式引擎。

### 本版本不做

- 不让 AI 自动执行高风险生产写入。
- 不切换正式引擎。
- 不删除、停止或改写 n8n 正式流程。

### 增量验证

L1/L2：

```bash
.venv/bin/python -m pytest -q \
  tests/agent/test_planner_scenarios.py \
  tests/agent/test_recovery_scenarios.py \
  tests/mcp/test_scheduling_gateway.py \
  tests/security/test_scheduling_tool_boundaries.py
```

L3 运行固定 AI 场景和只读 Canary：

```bash
.venv/bin/python -m pytest -q \
  tests/integration/test_agent_kestra_canary.py \
  tests/integration/test_agent_model_offline.py
```

### 退出门槛

- 固定场景全部产生合法计划或安全拒绝。
- 模型不可用时，已发布调度继续运行，平台退化为固定计划。
- Canary 不写正式目标，结果可与 n8n 正式运行对比。
- AI 决策、工具调用和策略结果能够通过 correlation ID 完整追踪。

### 回滚点

禁用调度智能体和所有候选 Kestra Trigger；保留审计记录，n8n 继续正式运行。

## 9. V55：双轨迁移、分批切换与有条件退役 n8n

### 目标

建立结果对账、单流程角色切换和自动回滚机制，按风险批次从
`n8n_primary_kestra_shadow` 切换到 `kestra_primary_n8n_standby`；只有满足统一
退出门槛后，才进入 `kestra_primary` 和 n8n 运行时下线。

### 实施范围

- 实现四种双轨角色和同一环境唯一正式写入引擎约束。
- 影子任务使用只读模式或隔离 Schema/表/对象键。
- 对账行数、主键、聚合值、哈希、异常、耗时和资源消耗。
- 按“只读 → 幂等分区写 → 核心多节点 → 特殊高风险”顺序迁移。
- 每个流程独立执行切换、Kestra 故障和 n8n 回切演练。
- n8n 先停止新建/激活，再进入 Standby，再归档，最后有条件移除运行依赖。

### 增量验证

迁移和角色切换测试：

```bash
.venv/bin/python -m pytest -q \
  tests/integration/test_n8n_kestra_dual_run.py \
  tests/integration/test_workflow_reconciliation.py \
  tests/integration/test_workflow_engine_cutover.py \
  tests/integration/test_workflow_engine_rollback.py
```

每个迁移批次只运行该批流程的对账、SLA、连接预算和故障恢复场景，不重复执行
不相关业务域测试。

只有准备正式移除 n8n 运行依赖时，执行一次 L4：

```bash
.venv/bin/python -m pytest -q
npm --prefix frontend run build
docker compose -f deploy/docker/docker-compose.yml up -d --build
```

完整本地栈随后只执行关键验收路径：登录、数据源健康、一个只读流程、一个幂等
写流程、失败恢复、回填、回滚和 n8n 已归档不可再激活。L4 通过不代表自动批准
下线，仍需满足下述退出门槛。

### 退出门槛

- 所有生产 n8n Workflow 已迁移、归档或有正式保留说明。
- 所有正式 DataFlow 已使用 Kestra，且不存在未解释的双轨差异。
- 关键流程经过完整业务周期和至少一次故障恢复/回滚演练。
- n8n Standby 观察期内没有实际回切需求。
- 模型离线、Kestra/Runner 重启和单数据源故障均不破坏生产状态。
- 没有 Webhook、前端入口、脚本或外部系统继续依赖 n8n。
- 完整归档和唯一一次最终 L4 验证通过。

若任一条件未满足，V55 可以以 `kestra_primary_n8n_standby` 状态完成阶段性交付，
但不得宣称 n8n 已经下线。

### 回滚点

单流程回滚到 `n8n_primary` 或上一稳定 Kestra 版本。已经移除 n8n 运行容器后，
只能依据 V55 下线前归档和恢复演练执行独立恢复变更，不允许在故障现场临时重建
未知版本。

## 10. 版本验证记录模板

每个版本完成时创建对应验证记录：

```markdown
# Kestra V5x 验证记录

- 代码版本：
- 验证日期：
- 变更范围：
- 执行的 L1/L2/L3 测试：
- 未执行的测试及原因：
- 测试结果：
- 数据迁移升级/降级结果：
- 安全与秘密检查结果：
- 已知限制：
- 回滚点：
- 结论：允许/不允许进入 V5(x+1)
```

验证记录必须明确列出“未执行的测试及原因”，避免把增量验证描述成全量通过。

## 11. 与主实施计划的映射

| 交付版本 | 主计划 Task |
|---|---|
| V50 | Task 0–1 |
| V51 | Task 2–3 |
| V52 | Task 4 |
| V53 | Task 5–6 |
| V54 | Task 7 + 首批只读 Canary |
| V55 | Task 8–10 |

详细文件清单和技术边界继续以
[Kestra AI-first Data Factory 双轨改造实施计划](2026-07-18-kestra-ai-first-data-factory-migration.md)
为准；本文件是实施顺序和验证范围的执行入口。