MJ N8N Workflow Promote

Stage 1 — DEV 环境测试

1.1 启动 DEV 环境

docker compose up -d

访问 n8n UI：http://localhost:5678

1.2 验证清单

逐项检查以下内容：

• 工作流出现在 n8n UI 中（名称正确，DEV- 前缀）
• 凭据已绑定（Postgres-MJ-DataWarehouse 显示为已连接）
• API 连通性（手动执行 HTTP Request 节点，返回 200）
• 手动完整执行（Trigger → 全流程无报错）
• 输出格式正确（通知消息内容、日志格式）
• 错误分支验证（模拟异常输入，IF FALSE 分支正常处理）
• 环境变量正确（日志中显示 environment: "dev"）
• 标签正确（env:dev, trigger:*, domain:*）

1.3 触发方式测试指引

根据工作流触发类型选择对应测试方式：

DBTrigger 测试示例：

-- 根据工作流监听的表和 schema 插入测试数据
INSERT INTO ops_ods.ods_data_quality_validator (raw_payload, created_at)
VALUES ('{"test": true}'::jsonb, NOW());

Webhook 测试示例：

curl -X POST http://localhost:5678/webhook/{path} \
  -H "Content-Type: application/json" \
  -d '{"test": true}'

Stage 2 — TEST 环境晋升

2.1 晋升前置条件

所有条件必须满足后才能晋升到 TEST：

• DEV 连续成功执行 >= 3 次
• DEV 稳定运行 >= 3 天
• 零执行失败（排除已知外部因素）
• 性能基线已建立（执行时间在预期范围内）
• PR 代码审查已通过
• 文档完整（README.md + CHANGELOG.md）

2.2 晋升执行步骤

1. 确认配置：检查 _config/test.yaml 中的 trigger 配置正确
2. 渲染 TEST 工作流：

   uv run python scripts/render_n8n_workflows.py test
   

3. 验证渲染结果：

   uv run python scripts/render_n8n_workflows.py --verify test
   

4. 导入到 TEST n8n 实例：将渲染后的 JSON 通过 n8n UI 导入
5. 绑定凭据：在 TEST 环境中绑定 Postgres-MJ-DataWarehouse 凭据
6. 手动冒烟测试：执行一次完整工作流，确认无错误
7. 激活工作流：确认无误后在 n8n UI 中设为 Active

2.3 TEST 环境 Docker 命令

docker compose -f docker-compose.yml -f docker-compose.test.yml up -d

Stage 3 — PRODUCTION 生产部署

3.1 部署前检查清单

• TEST 环境验证全部通过
• production.yaml 配置已确认（特别是 Webhook URL 不是占位符）
• 回滚方案已准备（当前 PROD 工作流已导出备份）
• 团队已通知
• 部署时间窗口已确认（建议非高峰时段）

3.2 部署执行步骤

1. 渲染 PROD 工作流：

   uv run python scripts/render_n8n_workflows.py production
   

2. 验证渲染结果：

   uv run python scripts/render_n8n_workflows.py --verify production
   

3. 备份当前 PROD 工作流：从 n8n UI 导出当前版本（JSON 文件保存备用）
4. 导入渲染后的 JSON：通过 n8n UI 导入到 PROD n8n 实例
5. 创建/绑定凭据：PROD 凭据手动管理，确认 Postgres-MJ-DataWarehouse 已绑定
6. 手动冒烟测试：执行一次完整工作流，确认无错误
7. 激活工作流：确认无误后在 n8n UI 中设为 Active

3.3 PRODUCTION 环境 Docker 命令

docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d

3.4 即时验证（部署后 30 分钟内）

• 工作流状态为 Active
• 首次执行成功（等待触发或手动执行）
• 无错误日志
• 下游系统正常接收数据/通知
• 通知正常送达（WeChat 群消息确认）

3.5 观测期验证（部署后 24 小时）

• 执行次数符合预期频率
• 执行时间在正常范围
• 无资源泄漏（内存/连接数稳定）
• 通知正常送达
• 无异常告警

Rollback Strategy（回滚策略）

回滚触发条件

以下任一条件触发回滚：

• 连续 3+ 次执行失败
• 执行时间超过正常值 3 倍
• 数据错误（输出数据不正确）
• 下游系统报告异常

回滚执行步骤

1. 立即停用工作流：n8n UI → 将工作流设为 Inactive
2. 通知团队：通过 WeChat/Slack 通知相关人员
3. 恢复备份版本：从之前导出的 JSON 文件重新导入到 n8n
4. 重新绑定凭据：确认 Postgres-MJ-DataWarehouse 凭据已绑定
5. 激活恢复的版本：在 n8n UI 中设为 Active
6. 验证恢复后的执行：手动触发或等待自动触发，确认执行成功
7. 记录回滚事件：更新 CHANGELOG.md（记录回滚原因和时间）

回滚决策树

执行失败?
  ├── 单次失败 → 观察下一次
  ├── 2 次失败 → 检查日志，准备回滚
  └── 3+ 次失败 → 立即回滚

执行超时?
  ├── < 2x 正常值 → 监控
  ├── 2-3x 正常值 → 告警 + 准备回滚
  └── > 3x 正常值 → 立即回滚

数据错误?
  └── 任何数据错误 → 立即回滚

Human Intervention Points（人工交互节点）

Output（输出）

每个阶段完成后输出以下摘要：

{Stage}验证完成 / 晋升条件检查完成
  通过项: N / 总项: M
  [如有未通过项列表]
  建议：{next action}

示例：

DEV 环境测试验证完成
  通过项: 8 / 总项: 8
  建议：所有验证通过，可以准备 TEST 环境晋升。使用 /mj-n8n-promote 选择 "TEST 环境晋升" 阶段。

TEST → PROD 晋升条件检查完成
  通过项: 5 / 总项: 6
  未通过:
    - [ ] 文档完整（README.md + CHANGELOG.md）— CHANGELOG.md 尚未更新
  建议：请先更新 CHANGELOG.md，然后重新检查晋升条件。

Reference

• -> promotion-checklist.md — 精简晋升检查清单（快速参考，基于 n8n/_templates/TEMPLATE_WORKFLOW_PROMOTION_CHECKLIST.md 的简化版）
• n8n/_templates/TEMPLATE_WORKFLOW_PROMOTION_CHECKLIST.md — 完整晋升检查清单模板（权威版本）
• docs/infrastructure/n8n/ — n8n 基础设施文档
• n8n/workflows/_config/*.yaml — 环境配置文件
• scripts/render_n8n_workflows.py — 渲染脚本
• docker-compose.yml / docker-compose.test.yml / docker-compose.prod.yml — Docker 环境配置