n8n 自动化

通过 REST API 控制 n8n 工作流自动化平台。

配置

设置以下环境变量（或将其保存在 .n8n-api-config 文件中）：

export N8N_API_URL="https://your-instance.app.n8n.cloud/api/v1"  # 或 http://localhost:5678/api/v1
export N8N_API_KEY="your-api-key-here"

生成 API 密钥：进入 n8n 设置 → n8n API → 创建 API 密钥。

快速参考

所有请求均需在请求头中携带 X-N8N-API-KEY 进行身份验证。

列出工作流

curl -s -H "X-N8N-API-KEY: $N8N_API_KEY" "$N8N_API_URL/workflows" | jq '.data[] | {id, name, active}'

获取工作流详情

curl -s -H "X-N8N-API-KEY: $N8N_API_KEY" "$N8N_API_URL/workflows/{id}"

启用/停用工作流

# 启用
curl -s -X PATCH -H "X-N8N-API-KEY: $N8N_API_KEY" 
  -H "Content-Type: application/json" 
  -d '{"active": true}' "$N8N_API_URL/workflows/{id}"

# 停用
curl -s -X PATCH -H "X-N8N-API-KEY: $N8N_API_KEY" 
  -H "Content-Type: application/json" 
  -d '{"active": false}' "$N8N_API_URL/workflows/{id}"

触发工作流（通过 Webhook）

# 生产环境 Webhook
curl -s -X POST "$N8N_API_URL/../webhook/{webhook-path}" 
  -H "Content-Type: application/json" 
  -d '{"key": "value"}'

# 测试 Webhook
curl -s -X POST "$N8N_API_URL/../webhook-test/{webhook-path}" 
  -H "Content-Type: application/json" 
  -d '{"key": "value"}'

列出执行记录

# 最近的所有执行记录
curl -s -H "X-N8N-API-KEY: $N8N_API_KEY" "$N8N_API_URL/executions?limit=10" | jq '.data[] | {id, workflowId, status, startedAt}'

# 仅失败的执行记录
curl -s -H "X-N8N-API-KEY: $N8N_API_KEY" "$N8N_API_URL/executions?status=error&limit=5"

# 指定工作流的执行记录
curl -s -H "X-N8N-API-KEY: $N8N_API_KEY" "$N8N_API_URL/executions?workflowId={id}&limit=10"

获取执行详情

curl -s -H "X-N8N-API-KEY: $N8N_API_KEY" "$N8N_API_URL/executions/{id}"

创建工作流（从 JSON 文件）

curl -s -X POST -H "X-N8N-API-KEY: $N8N_API_KEY" 
  -H "Content-Type: application/json" 
  -d @workflow.json "$N8N_API_URL/workflows"

删除工作流

curl -s -X DELETE -H "X-N8N-API-KEY: $N8N_API_KEY" "$N8N_API_URL/workflows/{id}"

常见模式

健康检查（定期运行）

列出启用中的工作流，检查最近执行是否存在错误，并报告状态：

# 统计启用中的工作流数量
ACTIVE=$(curl -s -H "X-N8N-API-KEY: $N8N_API_KEY" "$N8N_API_URL/workflows?active=true" | jq '.data | length')

# 统计过去 24 小时内失败的执行次数
FAILED=$(curl -s -H "X-N8N-API-KEY: $N8N_API_KEY" "$N8N_API_URL/executions?status=error&limit=100" | jq '[.data[] | select(.startedAt > (now - 86400 | todate))] | length')

echo "启用中的工作流数：$ACTIVE | 过去 24 小时失败数：$FAILED"

调试失败的执行

1. 列出失败的执行记录 → 获取执行 ID
2. 获取该执行的详细信息 → 定位失败的节点
3. 检查该节点的参数和输入数据
4. 根据错误消息建议修复方案

工作流摘要

解析工作流 JSON，汇总其触发类型、节点数量、已连接的应用以及调度配置。

API 端点参考

完整端点文档请参阅 references/api-endpoints.md。

提示

• 在非企业版计划中，API 密钥拥有全部访问权限
• 速率限制因计划而异（云托管版有配额限制；自托管版无限制）
• Webhook URL 与 API URL 相互独立（调用 Webhook 无需提供认证请求头）
• 可使用 ?active=true 或 ?active=false 参数对工作流列表进行筛选
• 执行数据可能依据 n8n 的保留策略被自动清理