N8N 集成

通过 Orchestrator 的 External 类型集成 n8n 工作流,实现企业业务流程自动化和第三方系统集成。

什么是 n8n

n8n 是一个开源的工作流自动化平台,支持:

🔄 工作流自动化: 连接300+应用和服务
🔌 Webhook 触发: 接收外部事件触发流程
🛠️ 自定义节点: JavaScript/Python 编写自定义逻辑
📊 数据转换: 灵活的数据处理和映射

集成架构

用户消息
  ↓
Application (企业微信/Web)
  ↓
Orchestrator (External 类型)
  ↓
N8N Adapter
  ↓
N8N Webhook
  ↓
工作流执行
  ↓
响应返回

应用场景

1. 表单数据处理

场景: 用户发送的消息自动转换为表单提交

用户: "申请3天年假，从12月1日到12月3日"
  ↓
n8n 工作流:
  1. 解析消息提取信息
  2. 调用 OA 系统 API 提交申请
  3. 返回申请单号
  ↓
回复: "年假申请已提交，申请单号: #12345"

2. 多系统数据同步

场景: 消息内容同步到多个业务系统

用户: "更新客户联系方式..."
  ↓
n8n 工作流:
  1. 调用 CRM API 更新客户信息
  2. 同步到 ERP 系统
  3. 发送邮件通知相关人员
  ↓
回复: "客户信息已更新并同步"

3. 智能通知分发

场景: 根据消息内容智能分发通知

用户: "生产线设备异常..."
  ↓
n8n 工作流:
  1. 分析异常严重程度
  2. 通知维修团队 (企业微信 + 短信)
  3. 创建工单
  4. 记录到数据库
  ↓
回复: "已通知维修团队，工单号: #789"

配置步骤

1. 在 n8n 中创建工作流

创建 Webhook 触发器:

登录 n8n 管理界面
创建新工作流
添加 Webhook 节点作为触发器:
- HTTP Method: POST
- Path: 自定义 (如 /sira-webhook)
- Response Mode: When Last Node Finishes

配置工作流:

Webhook 触发
  ↓
[可选] 数据提取
  ↓
业务逻辑处理
  ↓
第三方 API 调用
  ↓
响应生成
  ↓
返回结果

获取 Webhook URL:

启动工作流
复制 Webhook URL
格式: https://n8n.example.com/webhook/sira-webhook

2. 创建 Orchestrator

进入 Orchestrator 管理:

导航到 Agent System → 编排器 → 创建编排器
填写基础信息:
- 名称: n8n_workflow
- 显示名称: N8N 工作流
- 描述: 功能说明

选择编排类型:

类型: External
外部系统: N8N

3. 配置 N8N 参数

必填参数

字段	说明	示例
Webhook URL	n8n Webhook 地址	`https://n8n.example.com/webhook/sira-webhook`

可选参数

字段	说明	默认值
API Key	n8n API 密钥 (如需认证)	无
Timeout	请求超时时间 (秒)	60

API Key 配置 (如果 n8n 启用了认证):

json

{
  "api_base_url": "https://n8n.example.com/webhook/sira-webhook",
  "api_key": "your-n8n-api-key"
}

4. 保存并测试

点击创建保存 Orchestrator
创建 Agent (可使用任意 LLM 模型,不会被实际调用)
创建 Application 绑定该 Orchestrator
发送测试消息验证集成

N8N 工作流开发

接收数据格式

Sira AI 发送给 n8n Webhook 的数据格式:

json

{
  "message": "用户消息内容",
  "session_id": "会话ID",
  "context": {
    "user_id": "用户ID",
    "organization_id": "组织ID",
    "platform": "wework",
    "timestamp": "2025-10-14T12:00:00Z"
  }
}

在 n8n 中访问数据:

javascript

// 用户消息
{{ $json.message }}

// 会话 ID
{{ $json.session_id }}

// 用户 ID
{{ $json.context.user_id }}

返回数据格式

n8n Webhook 可以返回多种格式,Sira AI 会自动提取响应:

格式 1: 简单字符串

json

"处理成功"

格式 2: 标准对象

json

{
  "response": "处理成功，工单号: #123"
}

格式 3: 多字段对象

json

{
  "message": "处理完成",
  "data": {
    "order_id": "12345",
    "status": "pending"
  }
}

支持的响应字段 (按优先级):

response
message
text
output
data (转为字符串)

工作流示例

示例 1: 表单提交

Webhook (接收)
  ↓
Code Node (提取信息)
  输入: {{ $json.message }}
  代码:
    const message = $input.item.json.message;
    const match = message.match(/申请(\d+)天.*从(.+)到(.+)/);
    return {
      days: match[1],
      start_date: match[2],
      end_date: match[3],
      user_id: $input.item.json.context.user_id
    };
  ↓
HTTP Request (调用 OA API)
  Method: POST
  URL: https://oa.example.com/api/leave
  Body:
    {
      "user_id": "{{ $json.user_id }}",
      "days": {{ $json.days }},
      "start_date": "{{ $json.start_date }}",
      "end_date": "{{ $json.end_date }}"
    }
  ↓
Set Node (生成响应)
  response: "年假申请已提交，申请单号: {{ $json.order_id }}"
  ↓
Respond to Webhook (返回结果)

示例 2: 智能通知

Webhook (接收)
  ↓
IF Node (严重程度判断)
  条件: {{ $json.message.includes('紧急') }}
  ↓
  是 → Send SMS (短信通知)
  否 → Send WeWork (企业微信通知)
  ↓
Create Ticket (创建工单)
  ↓
Log to Database (记录日志)
  ↓
Respond to Webhook (返回工单号)

认证配置

API Key 认证

n8n 中启用认证:

在 Webhook 节点中选择 Header Auth
设置认证头名称: X-N8N-API-KEY
生成 API Key

Sira AI 中配置:

json

{
  "api_base_url": "https://n8n.example.com/webhook/sira-webhook",
  "api_key": "your-generated-api-key"
}

请求头格式:

X-N8N-API-KEY: your-generated-api-key
Content-Type: application/json

无需认证

如果 n8n Webhook 在内网或已有其他安全措施:

json

{
  "api_base_url": "https://n8n.example.com/webhook/sira-webhook"
}

错误处理

N8N 工作流中的错误处理

方式 1: Error Trigger Node

Main Workflow
  ↓ (出错)
Error Trigger
  ↓
Send Alert (通知管理员)
  ↓
Return Error Response

方式 2: Try-Catch 模式

IF Node (检查条件)
  ↓ 失败
  Set Node (设置错误响应)
    response: "处理失败: {{ $json.error }}"

Sira AI 中的错误处理

当 n8n Webhook 返回错误时:

HTTP 错误 (4xx, 5xx):

响应: "工作流执行失败，请稍后重试"

超时错误:

响应: "工作流处理超时，请检查系统状态"

自定义错误响应: n8n 中返回错误信息:

json

{
  "response": "处理失败: 系统繁忙"
}

高级配置

异步工作流

场景: 工作流处理时间较长

方案: 立即返回,异步通知结果

Webhook (接收)
  ↓
Respond to Webhook (立即响应)
  response: "已收到请求，处理中..."
  ↓
[分支] 异步处理
  ↓
长时间任务
  ↓
HTTP Request (回调通知)
  URL: Sira AI 回调接口

多工作流路由

场景: 根据消息类型调用不同工作流

方案: 在 n8n 主工作流中实现路由

Webhook (接收)
  ↓
Switch Node (消息分类)
  - 包含"申请" → 调用审批工作流
  - 包含"报修" → 调用维修工作流
  - 包含"查询" → 调用查询工作流
  - 默认 → 通用处理

数据持久化

场景: 保存会话数据

方案: 使用 Redis 或数据库节点

Webhook (接收)
  ↓
Redis Get (获取历史数据)
  Key: session:{{ $json.session_id }}
  ↓
业务处理 (结合历史数据)
  ↓
Redis Set (保存新数据)
  Key: session:{{ $json.session_id }}
  Value: {{ $json }}
  TTL: 86400 (24小时)
  ↓
返回响应

监控和调试

N8N 执行日志

在 n8n 界面查看工作流执行历史
查看每个节点的输入/输出
检查错误信息和堆栈

Sira AI 日志

系统设置 → 日志管理
筛选 Orchestrator ID
查看请求和响应详情
分析错误和性能

常见调试问题

问题: Webhook 无响应

排查:

检查 n8n 工作流是否激活
确认 Webhook URL 正确
测试 Webhook 是否可访问: curl -X POST https://n8n.example.com/webhook/test

问题: 返回数据格式错误

排查:

在 n8n 中查看 Respond to Webhook 节点输出
确保返回 JSON 或字符串
检查响应字段名是否支持

问题: 超时错误

解决:

增加 Orchestrator 的 timeout 配置
优化 n8n 工作流性能
考虑使用异步模式

最佳实践

性能优化

快速响应:
- 工作流控制在30秒内完成
- 复杂任务使用异步模式
- 避免不必要的节点
并行处理:
- 使用 Split In Batches 节点批处理
- 独立任务使用并行分支
- 合理设置并发限制

错误处理

友好错误消息:
- 不要直接返回技术错误信息
- 提供用户友好的提示
- 包含问题解决建议
重试机制:
- 对临时性错误实现重试
- 设置合理的重试次数 (3次)
- 指数退避策略

安全性

认证保护:
- 生产环境启用 API Key
- 定期轮换密钥
- 使用 HTTPS
数据验证:
- 验证输入数据格式
- 过滤敏感信息
- 防止 SQL 注入等攻击
访问控制:
- 限制 Webhook IP 白名单
- 最小权限原则
- 审计日志

常见问题

配置相关

Q: Webhook URL 如何获取?

在 n8n 中创建 Webhook 节点
激活工作流
复制 Production URL

Q: 支持哪些认证方式?

A: 目前支持 API Key 认证 (通过 X-N8N-API-KEY header)

Q: 可以调用多个 n8n 工作流吗?

A: 可以创建多个 Orchestrator,每个对应一个 n8n Webhook

功能相关

Q: 支持流式响应吗?

A: n8n 不支持流式响应,只能等待工作流完成后返回完整结果

Q: 如何传递额外数据给 n8n?

A: 数据在 context 字段中,在 n8n 中通过 {{ $json.context.xxx }} 访问

Q: 工作流执行失败如何通知用户?

在 n8n 中捕获错误并返回友好消息
或者在 Sira AI 中显示默认错误提示

性能相关

Q: 工作流执行很慢怎么办?

优化 n8n 工作流节点
使用异步模式
增加 timeout 配置

Q: 如何处理大量并发请求?

n8n 配置横向扩展
使用消息队列缓冲
实施限流策略

下一步

Dify 集成 - 集成 Dify AI 应用
创建 Orchestrator - Orchestrator 完整教程
创建 Application - 创建应用绑定 Orchestrator
n8n 官方文档 - n8n 详细文档

N8N 集成 ​

什么是 n8n ​

集成架构 ​

应用场景 ​

1. 表单数据处理 ​

2. 多系统数据同步 ​

3. 智能通知分发 ​

配置步骤 ​

1. 在 n8n 中创建工作流 ​

2. 创建 Orchestrator ​

3. 配置 N8N 参数 ​

必填参数 ​

可选参数 ​

4. 保存并测试 ​

N8N 工作流开发 ​

接收数据格式 ​

返回数据格式 ​

工作流示例 ​

示例 1: 表单提交 ​

示例 2: 智能通知 ​

认证配置 ​

API Key 认证 ​

无需认证 ​

错误处理 ​

N8N 工作流中的错误处理 ​

Sira AI 中的错误处理 ​

高级配置 ​

异步工作流 ​

多工作流路由 ​

数据持久化 ​

监控和调试 ​

N8N 执行日志 ​

Sira AI 日志 ​

常见调试问题 ​

最佳实践 ​

性能优化 ​

错误处理 ​

安全性 ​

常见问题 ​

配置相关 ​

功能相关 ​

性能相关 ​

下一步 ​

N8N 集成

什么是 n8n

集成架构

应用场景

1. 表单数据处理

2. 多系统数据同步

3. 智能通知分发

配置步骤

1. 在 n8n 中创建工作流

2. 创建 Orchestrator

3. 配置 N8N 参数

必填参数

可选参数

4. 保存并测试

N8N 工作流开发

接收数据格式

返回数据格式

工作流示例

示例 1: 表单提交

示例 2: 智能通知

认证配置

API Key 认证

无需认证

错误处理

N8N 工作流中的错误处理

Sira AI 中的错误处理

高级配置

异步工作流

多工作流路由

数据持久化

监控和调试

N8N 执行日志

Sira AI 日志

常见调试问题

最佳实践

性能优化

错误处理

安全性

常见问题

配置相关

功能相关

性能相关

下一步