对接 n8n

按下面顺序操作即可完成接入。一套独立部署的 n8n 对应管理后台 一条 n8n 类型集成平台，请勿混用不同 n8n 地址下的同步条目。

一、在 n8n 中获取 API Key（第一步）

本系统通过 n8n 的 Public API（/api/v1）拉取工作流与执行信息，因此需要先在 n8n 里创建密钥。

1. 使用具备管理权限的账号登录您的 n8n（自建或云端实例均可）。
2. 打开 设置（Settings）。不同版本入口可能为右上角头像菜单、侧边栏齿轮图标等，以您当前界面为准。
3. 进入 API（部分版本显示为 n8n API，或在「个人设置 / Personal」下）。
4. 点击 创建 API Key（或 Create），生成后 立即复制 并妥善保存；关闭弹窗后可能无法再次查看完整密钥。
5. 将 Key 粘贴到下文「管理后台 → 集成平台 → 鉴权」中。不要把 Key 发给无关人员或写入公开文档。

n8n 中打开 API 设置页并创建/展示 API Key 的位置。

二、在管理后台添加 n8n 集成平台

1. 登录 管理后台，侧栏进入 平台管理 → API平台（常见路径：/admin/platform）。
2. 新建一条平台：选择 n8n 类型（或带 n8n 的预设），填写 平台名称 等基础信息，保持 启用。
3. 在 环境变量 中新增一项：名称 填 baseURL，值 填 n8n 根地址，例如 https://n8n.example.com。末尾不要多写斜杠。
4. 在 鉴权 中填写上一步复制的 API Key（与 n8n「API」页生成的密钥一致）。
5. 保存。未保存前页面底部 Webhook 相关区域会提示先保存；保存成功后才会出现 「从 n8n 同步」 等按钮。

集成平台编辑页：类型为 n8n、baseURL、鉴权 API Key、保存按钮。

三、同步 Webhook、测试并绑定到应用

1. 打开 该条 n8n 平台的编辑页，滚动到底部 「Webhook 工作流列表」，点击 「从 n8n 同步」：会拉取当前 n8n 中 已激活 且含 Webhook 节点的工作流。「刷新列表」 仅刷新表格，不会重新全量拉取。

Webhook 工作流列表：从 n8n 同步、刷新列表。

2. 在列表中点击某条的 「详情」。若提示与 n8n 工作流版本不一致，请先回到列表执行 「从 n8n 同步」。
3. 在 Webhook 入参 中填写 JSON 对象（打开详情时通常会预填示例），点击 「测试 Webhook」。
   说明：后台认定 可封装 依赖的是 通过正式 Webhook 路径成功执行的一次运行；仅在 n8n 编辑器里对单个节点点「测试」不会让后台变为可封装。

详情弹窗：入参、测试 Webhook、执行结果。

4. 当 应用封装 为 可封装 时，可点击 「创建 n8n 应用」 进入工作流编辑并保存发布；也可在 工作流 / 应用管理 中新建 n8n 类型应用，在步骤里选择 「Webhook 接口（已同步）」 下 可封装 的条目。

四、n8n 工作流配置要点（必看）

以下均在 n8n 画布 中配置。不满足时，后台可能长期 未就绪，或前台任务无法正常结束。

4.1 Webhook 与激活

• 工作流中必须有 Webhook 节点。 选择
  • 「Webhook」节点 的 Respond 选择 「Using 'Respond to Webhook' Node」
  • 「Webhook」节点后面接一个 「Respond to Webhook」节点
  • 「Respond to Webhook」节点配置
    • Respond With : JSON
    • Response Body :
         {
            "executionId": {{ $execution.id }}
         }
      

    
• 工作流必须在 n8n 中为 已发布（Published），否则不会出现在后台同步列表中。

4.2 图片、音视频、文件等产出

若要给前台返回图片、音视频或文件，请在 n8n 里把结果整理成 可以写进返回内容里的形式（例如 可访问的网页链接、Base64 或 data URL），不要把 n8n 内部的「文件对象」原样当作最终结果传出。

• 优先：上传到 对象存储（如 S3 或兼容 S3 的 OSS） 后，在流程里拼出 浏览器能打开的完整 https 链接，再写入 Webhook 的返回或后续节点。
  • 示例
  • 上传OSS
  • 拼接文件链接
  • 封装应用，对应的产出节点配置
• 备选：用 Extract from File → Move File to Base64 String 等转成 Base64。Base64 体积大，可能影响后台记录与超时，仍建议能用链接就用链接。