n8n 工作流集成指南

本文档介绍如何配置 n8n 与 KKMusic 系统的集成，实现自动化事件通知和工作流处理。

一、概述

KKMusic 支持两种 n8n 集成模式：

1. 事件推送模式 - 系统主动向 n8n 推送事件（Job 状态、内容发布等）
2. 工作流触发模式 - 系统调用 n8n 执行 AI 任务（音乐生成、图像增强等）

二、前置要求

• n8n 实例（本地或云端），推荐版本 1.0+
• n8n 需开启 Webhook 功能
• 网络可达（后端能访问 n8n Webhook URL）

n8n 部署方式

# Docker 部署（推荐）
docker run -d \
  --name n8n \
  -p 5678:5678 \
  -v n8n_data:/home/node/.n8n \
  n8nio/n8n

# 或使用 npm
npm install -g n8n
n8n start

三、环境变量配置

在 backend/.env 中添加：

# n8n 事件通知配置
N8N_EVENT_WEBHOOK_URL=http://localhost:5678/webhook/system-events
N8N_WEBHOOK_SECRET=your_secret_key_here
N8N_ENABLE_NOTIFICATIONS=true
N8N_NOTIFICATION_TIMEOUT=5000

# n8n 工作流触发配置（现有）
N8N_WEBHOOK_URL=http://localhost:5678/webhook
CALLBACK_BASE_URL=http://localhost:3001

四、事件类型

KKMusic 会推送以下系统事件：

事件类型	说明	触发时机
job.status.changed	作业状态变化	Job 创建、处理、完成、失败
job.completed	作业完成	草稿生成成功
job.failed	作业失败	任何步骤失败
content.created	内容创建	新内容条目创建
content.published	内容发布	内容状态变为"已发布"
content.draft.ready	草稿就绪	剪映草稿导出完成
task.completed	任务完成	拍摄任务完成
task.asset.uploaded	素材上传	新素材上传入库
subscription.expiring	订阅即将到期	订阅剩余 7/3/1 天
user.daily.summary	每日概要	每日 9:00 推送

事件负载示例

{
  "event": "job.completed",
  "timestamp": "2024-01-15T10:30:00.000Z",
  "data": {
    "jobId": "uuid-xxx",
    "type": "draft_generation",
    "result": {
      "draftPath": "/path/to/draft"
    },
    "projectId": "project-123",
    "userId": "user-456"
  },
  "meta": {
    "source": "kkmusic-backend",
    "version": "1.0.0"
  }
}

五、n8n 工作流配置

5.1 创建系统事件接收工作流

1. 在 n8n 中创建新工作流

2. 添加 Webhook 节点：

   • HTTP Method: POST
   • Path: system-events（与环境变量对应）
   • Response Mode: Immediately

3. 添加 Switch 节点，根据事件类型分支：

   条件: {{ $json.event }}
   - job.failed -> 告警通知
   - content.published -> 社交同步
   - subscription.expiring -> 邮件提醒

5.2 Job 失败告警工作流

[Webhook] -> [Switch: job.failed] -> [钉钉/企业微信] -> [邮件备份]

钉钉机器人节点配置：

{
  "msgtype": "markdown",
  "markdown": {
    "title": "⚠️ 作业处理失败",
    "text": "### 作业失败告警\n\n- **作业ID**: {{ $json.data.jobId }}\n- **错误**: {{ $json.data.error }}\n- **时间**: {{ $json.timestamp }}\n\n[查看详情](http://your-domain/studio/jobs/{{ $json.data.jobId }})"
  }
}

5.3 内容发布同步工作流

[Webhook: content.published] -> [HTTP Request: 平台同步] -> [数据库记录]

5.4 订阅提醒工作流

[Webhook: subscription.expiring] -> [If: daysRemaining <= 3] -> [发送邮件]

六、安全配置

Webhook 签名验证

每个请求头包含签名：

• X-Webhook-Signature: HMAC-SHA256 签名
• X-Timestamp: 请求时间戳
• X-Event-Type: 事件类型

验证示例（n8n Function 节点）：

const crypto = require('crypto');
const secret = 'your_secret_key_here';

const payload = JSON.stringify($input.item.json);
const signature = $input.item.headers['x-webhook-signature'];

const expectedSignature = crypto
  .createHmac('sha256', secret)
  .update(payload)
  .digest('hex');

if (signature !== expectedSignature) {
  throw new Error('Invalid signature');
}

return $input.item;

七、测试接口

后端提供测试端点，用于验证 n8n 连接：

# 测试事件通知连接
curl -X POST http://localhost:3001/api/webhooks/test-notification \
  -H "Content-Type: application/json" \
  -d '{"event": "test.connection"}'

八、故障排查

常见问题

1. 事件未收到

   • 检查 N8N_ENABLE_NOTIFICATIONS 是否为 true
   • 确认 n8n Webhook URL 可访问
   • 查看后端日志 [EventNotification]

2. 签名验证失败

   • 确保 N8N_WEBHOOK_SECRET 两端一致
   • 检查 payload 是否被中间件修改

3. 超时错误

   • 增加 N8N_NOTIFICATION_TIMEOUT 值
   • 检查网络延迟

日志查看

# 后端日志
grep "EventNotification" backend.log

# 查看队列状态
curl http://localhost:3001/api/webhooks/notification-status

九、高级配置

事件过滤

可在代码中配置只推送特定事件：

// backend/config/n8n.js
module.exports = {
  enabledEvents: [
    'job.failed',
    'content.published',
    'subscription.expiring'
  ]
};

批量推送

对于高频事件，可配置批量推送：

N8N_BATCH_SIZE=10
N8N_BATCH_INTERVAL=5000  // ms

十、相关资源

• n8n 官方文档
• Webhook 节点文档
• KKMusic API 文档