n8n 中文文档

通过公共 API 以编程方式使用环境

你可以使用公共 API,通过脚本和流水线管理 n8n 环境,无需打开 n8n UI。这样便可自动在实例之间推进更改,例如按计划或在 CI/CD 流水线中将开发实例上的工作移至生产环境。

本页介绍源代码管理 API 端点如何协同工作。本文假设你已将实例连接到 Git,并了解 UI 中的推送和拉取行为。如需了解相关背景,请阅读推送和拉取更改以及在环境之间移动工作。

提示

Feature availability 功能可用性

源代码管理的 status 和 push 端点自 n8n 2.39.0 版本起可用。 * GET /api/v1/source-control/status * POST /api/v1/source-control/push

环境是 Enterprise 功能。

端点

公共 API 提供三种源代码管理操作:

端点 方法 功能
/source-control/status GET 预览实例与 Git 之间任一方向的待处理更改。
/source-control/push POST 提交本地更改并将其推送到已连接的 Git 分支。
/source-control/pull POST 从已连接的 Git 分支获取更改并应用到实例。

push 和 pull 与源代码管理菜单中的 Push 推送和 Pull 拉取按钮执行相同的操作。status 对应 UI 在确认前于推送和拉取弹窗中显示的文件列表。API 将其作为独立端点提供,以便脚本执行与 UI 内联审查相同的操作。

如需完整的请求和响应模式,请参阅端点参考。

身份验证和作用域

每个请求都需要在 X-N8N-API-KEY 标头中发送 API key。在 Enterprise 计划中,你可以将每个 key 的作用域限制到所需的最低权限:

作用域 授予的权限
sourceControl:pull 将更改拉取到实例。
sourceControl:push 将本地更改推送到 Git。
sourceControl:read 读取待处理更改的状态。

通过这种方式设置 key 的作用域,可以强制限定同步方向。对于只能接收更改的生产实例,请为其 key 授予 sourceControl:pull,使其无法推送。如果还希望该 key 在拉取前通过 status 预览传入的更改,请同时添加 sourceControl:read。

先检查状态,再执行操作

不要在不了解更改内容的情况下直接推送。push 需要一个 fileNames 数组,并且只提交其中列出的文件,因此应先调用 status 查看哪些文件符合条件。

步骤如下:

  1. 调用 status 查看符合条件的文件。
  2. 确定要包含的内容:包含所有文件以推送全部更改,或选择部分文件以仅推送部分更改。
  3. 根据所选文件构建 fileNames,仅保留每个文件的 id 和 type。
  4. 使用该数组调用 push。

调用 status 时使用 direction 查询参数,选择要预览的方向:

curl --request GET \
    --location '<YOUR-INSTANCE-URL>/api/v1/source-control/status?direction=push' \
    --header 'X-N8N-API-KEY: <YOUR-API-KEY>'

响应中的每个文件都包含其 id、name、type(例如 workflow 或 credential)和 status(例如 modified 或 new):

{
    "data": [
        {
            "id": "1a2b3c",
            "name": "Daily sales report",
            "type": "workflow",
            "status": "modified",
            "file": "workflows/1a2b3c.json"
        }
    ]
}

从开发环境推进到只读生产环境

这是一种常见设置:在开发实例上进行更改,然后将其推进到只接收更新的生产实例。本例让两个实例共享一个 Git 分支。

为每个实例提供具有相应作用域的 API key:

  • 开发实例的 API key 具有 sourceControl:read 和 sourceControl:push。
  • 生产实例的 API key 具有 sourceControl:read 和 sourceControl:pull。

1. 预览开发环境中的更改。 使用 direction=push 调用 status,查看 n8n 将提交的内容:

curl --request GET \
    --location '<DEV-INSTANCE-URL>/api/v1/source-control/status?direction=push' \
    --header 'X-N8N-API-KEY: <DEV-API-KEY>'

2. 从开发环境推送到 Git。 发送提交消息和要推进的文件,并在 fileNames 中以 id/type 对的形式列出。若要推进全部更改,请包含步骤 1 的 status 响应中的每个文件;若只推进部分更改,则包含文件子集:

curl --request POST \
    --location '<DEV-INSTANCE-URL>/api/v1/source-control/push' \
    --header 'Content-Type: application/json' \
    --header 'X-N8N-API-KEY: <DEV-API-KEY>' \
    --data '{
        "commitMessage": "Promote sales reporting workflows",
        "fileNames": [
            {
                "id": "1a2b3c",
                "type": "workflow"
            }
        ]
    }'

3. 预览生产环境中的更改。 在应用任何更改前,使用 direction=pull 调用 status,查看 n8n 将应用的内容:

curl --request GET \
    --location '<PROD-INSTANCE-URL>/api/v1/source-control/status?direction=pull' \
    --header 'X-N8N-API-KEY: <PROD-API-KEY>'

4. 拉取到生产环境。 生产实例读取同一分支并应用更改。使用 force 接受传入版本,并设置 autoPublish 以在工作流到达时发布它们:

curl --request POST \
    --location '<PROD-INSTANCE-URL>/api/v1/source-control/pull' \
    --header 'Content-Type: application/json' \
    --header 'X-N8N-API-KEY: <PROD-API-KEY>' \
    --data '{
        "force": true,
        "autoPublish": "published"
    }'

autoPublish 参数接受 none(默认值)、published(仅重新发布已在生产环境中发布的工作流)或 all(发布所有拉取的工作流)。有关各模式的更多详情,请参阅推送和拉取更改。

提示

使用多个分支

如果实例使用不同的 Git 分支,则无法直接推进更改。请从开发环境推送到其分支,在 Git 提供商中将该分支合并到生产分支,然后在生产环境中拉取。有关分支模式,请参阅在环境之间移动工作。

定时备份流程

若要定期在 Git 中对实例进行版本管理,请获取所有符合条件的文件,并按计划推送全部内容。可以从 cron 作业、CI 流水线,或使用 Schedule Trigger 的 n8n 工作流运行此流程。

1. 获取所有符合条件的文件。 使用 direction=push 调用 status:

curl --request GET \
    --location '<YOUR-INSTANCE-URL>/api/v1/source-control/status?direction=push' \
    --header 'X-N8N-API-KEY: <YOUR-API-KEY>'

2. 推送完整列表。 将 status 响应返回的每个文件映射为其 id 和 type,并作为 fileNames 传递。与推进流程不同,此作业无人值守,并将 force 设置为 true。这样会跳过冲突检查,并始终以实例的当前状态覆盖分支。每次定时运行前,请确保实例保存的是你需要的版本,否则可能会覆盖 Git 中较新的更改。

curl --request POST \
    --location '<YOUR-INSTANCE-URL>/api/v1/source-control/push' \
    --header 'Content-Type: application/json' \
    --header 'X-N8N-API-KEY: <YOUR-API-KEY>' \
    --data '{
        "commitMessage": "Scheduled backup",
        "force": true,
        "fileNames": [
            {
                "id": "1a2b3c",
                "type": "workflow"
            },
            {
                "id": "4d5e6f",
                "type": "workflow"
            },
            ...
        ]
    }'

处理推送冲突

如果自上次同步以来实例和 Git 都更改了同一个文件,该文件便处于冲突状态。status 会使用 "conflict": true 标记这些文件。如果在未设置 force 的情况下调用 push,且所选文件中有任何文件存在冲突,n8n 会拒绝整个推送并返回 409 响应:

{
    "message": "Push blocked by conflicting files. Pass `force: true` to push anyway.",
    "conflicts": [
        {
            "id": "1a2b3c",
            "name": "Daily sales report",
            "type": "workflow",
            "status": "modified",
            "file": "workflows/1a2b3c.json",
            "conflict": true
        }
    ]
}

若仍要推送,并使用实例版本覆盖 Git 中存在冲突的文件,请将 force 设置为 true:

curl --request POST \
    --location '<YOUR-INSTANCE-URL>/api/v1/source-control/push' \
    --header 'Content-Type: application/json' \
    --header 'X-N8N-API-KEY: <YOUR-API-KEY>' \
    --data '{
        "commitMessage": "Push reviewed workflows only",
        "force": true,
        "fileNames": [
            {
                "id": "1a2b3c",
                "type": "workflow"
            }
        ]
    }'

推送和拉取的内容

API 提交和应用的资源与 UI 相同:工作流、凭证存根、变量存根、数据表模式、项目、文件夹和标签。如需完整列表以及每种资源类型的合并行为,请参阅推送和拉取更改。

相关资源

不想自己部署和维护 n8n?n8ncn 托管 n8n 云服务:开通账号即可使用,不用买服务器;也可以在 n8ncn 工作流库 找现成的中文工作流。