n8n 中文文档

Package 格式

提示

Preview status 预览状态

n8n packages 处于 Preview 阶段。package 格式在未来版本中可能会发生变化。

n8n package 是 gzip 压缩的 tar 归档。标准工具可以读取它,因此无需 n8n 也能检查其内容:

tar -tzf triage.n8np    # list what's inside
tar -xzf triage.n8np    # extract it

.n8np 扩展名只是一种命名约定。n8n 在导入时不会检查文件名,也接受布局相同的未压缩 tar 文件。

在归档内,每个实体都以独立的小型 JSON 文件存放在自己的目录中,根目录下的 manifest.json 会为所有内容建立索引。manifest.json 必须是归档中的第一个文件,这样 n8n 才能在读取其余内容之前验证 package。

三种 package 形态

形态取决于导出的对象。三种形态携带的文件类型相同,但排列方式不同。

工作流 package

按工作流 ID 导出会得到若干独立工作流,其依赖的所有内容都位于顶层:

triage.n8np
├── manifest.json
├── workflows/
│   ├── triage-inbound-wf7Kq2/
│   │   ├── workflow.json
│   │   └── workflow-metadata.json
│   └── send-email-wf9Zx1/
│       ├── workflow.json
│       └── workflow-metadata.json
├── credentials/
│   └── linear-api-crLin44/
│       └── credential.json
├── variables/
│   └── slackchannelid-vaSl03/
│       └── variable.json
├── data-tables/
│   └── countries-dtCn12/
│       └── data-table.json
└── tags/
    └── prod-tgPr01/
        └── tag.json

每个工作流目录包含两个文件:

  • workflow.json:工作流本身。
  • workflow-metadata.json:导出版本的 ID,以及源实例上已发布版本的 ID(如果有)。导入时会用它来应用发布策略。

文件夹 package

按文件夹 ID 导出会保留文件夹树。文件夹中的工作流位于该文件夹内的 workflows/ 目录中,嵌套文件夹则直接位于父文件夹内,不会重复出现 folders/ 路径段。凭据、变量、数据表和标签仍位于顶层:

in-progress.n8np
├── manifest.json
├── folders/
│   ├── to-production-fdToProd/
│   │   └── folder.json            # an empty folder is just the shell
│   └── in-progress-fdInProg/
│       ├── folder.json
│       ├── workflows/
│       │   └── triage-inbound-wf7Kq2/
│       │       ├── workflow.json
│       │       └── workflow-metadata.json
│       └── nested-fdNest01/
│           ├── folder.json
│           └── workflows/
│               └── playground-wfPlay1/
│                   ├── workflow.json
│                   └── workflow-metadata.json
├── credentials/
│   └── linear-api-crLin44/
│       └── credential.json
└── tags/
    └── prod-tgPr01/
        └── tag.json

项目 package

按项目 ID 导出会增加一层命名空间。一个 package 可以携带多个项目。导出项目拥有的凭据、变量和数据表会嵌套在该项目下。全局内容或由 package 外项目拥有的内容仍位于顶层。标签始终位于顶层,因为标签在 n8n 中是全局的:

team-ligo.n8np
├── manifest.json
├── projects/
│   └── team-ligo-prTeam9/
│       ├── project.json
│       ├── workflows/                    # workflows at the project root
│       │   └── triage-inbound-wf7Kq2/
│       │       ├── workflow.json
│       │       └── workflow-metadata.json
│       ├── folders/
│       │   └── in-progress-fdInProg/
│       │       ├── folder.json
│       │       └── workflows/
│       │           └── send-email-wf9Zx1/
│       │               ├── workflow.json
│       │               └── workflow-metadata.json
│       ├── credentials/                  # owned by this project
│       │   └── linear-api-crLin44/
│       │       └── credential.json
│       ├── variables/                    # scoped to this project
│       │   └── slackchannelid-vaSl03/
│       │       └── variable.json
│       └── data-tables/
│           └── countries-dtCn12/
│               └── data-table.json
├── credentials/                          # a global credential
│   └── shared-smtp-crSmtp1/
│       └── credential.json
├── variables/                            # a global variable
│   └── region-vaRg02/
│       └── variable.json
└── tags/                                 # always global
    └── prod-tgPr01/
        └── tag.json

提示

在项目 package 中,变量所在的位置决定其创建位置。projects/<project-directory>/variables/ 下的变量会在该项目中创建,顶层变量则会在全局创建。因此项目 package 不接受 --variable-parent-policy:布局已经作出了决定。

Agents 和 skills

Agents 与工作流并列存放。在工作流或文件夹 package 中,每个 agent 在顶层 agents/ 下都有一个目录。在项目 package 中,agent 位于其所属项目下的 projects/<project-directory>/agents/ 中。每个 agent 目录包含两个文件:

  • agent.json:agent 的定义,包括其自定义 tools 和计划。
  • agent-metadata.json:导出版本的 ID,以及源实例上已发布版本的 ID(如果有)。导入时会用它来应用发布策略。

导出的 agent 使用的每个 skill 都有自己的目录,其中包含一个 skill.json,保存 skill 的内容以及它是项目 skill 还是实例 skill。如果项目 skill 所属的项目也在 package 中,该 skill 位于该项目下;其他所有 skill 都位于顶层 skills/ 中:

support.n8np
├── manifest.json
├── agents/
│   └── support-triage-agSup01/
│       ├── agent.json
│       └── agent-metadata.json
├── skills/
│   └── refund-policy-skRf01/
│       └── skill.json
└── credentials/
    └── openai-account-crOai01/
        └── credential.json

目录命名

每个实体都有一个名为 <slug>-<id> 的目录:先是实体名称生成的 slug,然后是连字符,最后是实体在源实例上的 ID。生成 slug 时,名称会转换为小写,删除除字母 a 到 z、数字、空白和连字符以外的所有字符,将连续空白和重复的连字符转换为单个连字符,并去掉两端的连字符:

实体名称 ID 目录
Triage inbound wf7Kq2 triage-inbound-wf7Kq2
slackChannelId vaSl03 slackchannelid-vaSl03
Q4 报告 wfQ4r1 q4-wfQ4r1
報告 wfBg02 workflow-wfBg02

最后一行展示了回退规则:如果生成 slug 后没有保留任何字符,n8n 会使用实体类型作为 slug(workflow、agent、skill、folder、project、credential、variable、data-table 或 tag)。由于 ID 是目录名的一部分,名称相同的两个实体仍会获得不同的目录。

目录名是为了方便用户阅读归档。n8n 始终通过 manifest 和 JSON 文件中的 ID 识别实体,而不会使用目录名。

manifest.json

manifest 是一个索引。它会告诉 n8n package 中包含什么,以及目标实例需要提供什么,使导入可以在不读取每个文件的情况下快速失败。

以下三个字段始终存在:

  • packageFormatVersion:package 格式的版本,当前为字符串 "1"。
  • sourceN8nVersion:创建 package 的 n8n 版本。
  • sourceId:创建 package 的实例标识符。

随后是条目列表,每种存在的实体类型对应一个列表:workflows、agents、skills、folders、projects、credentials、dataTables、variables 和 tags。如果某个列表为空,则会完全省略。每个条目都包含相同的三个字段:

  • id:实体在源实例上的 ID。
  • name:实体名称。
  • target:包含实体 JSON 文件的目录,相对于 package 根目录。

工作流条目还包含 isArchived,表示该工作流在源实例上是否已归档。

最后是 requirements,其中列出工作流和 agents 在目标实例上运行所需的内容。它最多包含七个部分。每个条目都有 usedBy,即需要该内容的工作流和 agents,每项格式为 { "kind": "workflow", "id": "<id>" } 或 { "kind": "agent", "id": "<id>" }:

部分 条目结构 说明
credentials { id, name, type, usedBy } 打包的凭据最多只携带其表达式值,因此除非导入根据这些值创建凭据,否则目标实例必须提供该凭据
dataTables { id, name, usedBy } 模式本身位于打包的 data-table.json 中
workflows { id, name, usedBy } 子工作流和错误工作流引用,以及 agent 用作 tools 的工作流。name 为可选字段,因为导出用户可能看不到被引用的工作流
agents { id, name, usedBy } agent 使用的 sub-agents。仅当 sub-agent 位于 package 中时才包含 name
variables { name, usedBy } 仅包含名称,没有 ID,因为 $vars.<name> 在运行时按名称解析
tags { id, name, usedBy } 只有工作流使用标签
nodeTypes { type, typeVersion, usedBy } 工作流和 agents 的节点 tools 使用的每种节点类型和版本。目标实例必须安装所有这些节点,因此可通过该列表判断目标实例能否导入 package。导入时,n8n 会重新生成同一列表,而不是直接信任此处内容

警告

requirements 列出工作流和 agents 需要的内容,这与 package 实际包含的内容并不相同。requirements.workflows 会列出每个静态工作流引用,包括已打包在 package 中的子工作流。导出用户无权读取的凭据会出现在 requirements.credentials 中,但没有对应文件。不要将 requirements 视为归档清单;清单应查看各条目列表。

以下是包含两个工作流的工作流 package 的完整 manifest:

{
    "packageFormatVersion": "1",
    "sourceN8nVersion": "2.34.0",
    "sourceId": "f9e1e962bba26edf357042c12f367dab17f4c63ec368e1f39cbf7ce43c8b9f8b",

    "workflows": [
        { "id": "wf7Kq2", "name": "Triage inbound", "target": "workflows/triage-inbound-wf7Kq2", "isArchived": false },
        { "id": "wf9Zx1", "name": "Send email", "target": "workflows/send-email-wf9Zx1", "isArchived": false }
    ],
    "credentials": [
        { "id": "crLin44", "name": "Linear api", "target": "credentials/linear-api-crLin44" }
    ],
    "dataTables": [
        { "id": "dtCn12", "name": "countries", "target": "data-tables/countries-dtCn12" }
    ],
    "variables": [
        { "id": "vaSl03", "name": "slackChannelId", "target": "variables/slackchannelid-vaSl03" }
    ],
    "tags": [
        { "id": "tgPr01", "name": "prod", "target": "tags/prod-tgPr01" }
    ],

    "requirements": {
        "credentials": [
            { "id": "crLin44", "name": "Linear api", "type": "linearApi", "usedBy": [{ "kind": "workflow", "id": "wf7Kq2" }] }
        ],
        "dataTables": [
            { "id": "dtCn12", "name": "countries", "usedBy": [{ "kind": "workflow", "id": "wf7Kq2" }] }
        ],
        "workflows": [
            { "id": "wf9Zx1", "name": "Send email", "usedBy": [{ "kind": "workflow", "id": "wf7Kq2" }] }
        ],
        "variables": [
            { "name": "slackChannelId", "usedBy": [{ "kind": "workflow", "id": "wf7Kq2" }] }
        ],
        "tags": [
            { "id": "tgPr01", "name": "prod", "usedBy": [{ "kind": "workflow", "id": "wf7Kq2" }] }
        ],
        "nodeTypes": [
            { "type": "n8n-nodes-base.formTrigger", "typeVersion": 2.5, "usedBy": [{ "kind": "workflow", "id": "wf7Kq2" }] },
            { "type": "n8n-nodes-base.linear", "typeVersion": 1, "usedBy": [{ "kind": "workflow", "id": "wf7Kq2" }] },
            { "type": "n8n-nodes-base.executeWorkflow", "typeVersion": 1.2, "usedBy": [{ "kind": "workflow", "id": "wf7Kq2" }] },
            { "type": "n8n-nodes-base.dataTable", "typeVersion": 1, "usedBy": [{ "kind": "workflow", "id": "wf7Kq2" }] },
            { "type": "n8n-nodes-base.emailSend", "typeVersion": 2.1, "usedBy": [{ "kind": "workflow", "id": "wf9Zx1" }] }
        ]
    }
}

data-table.json

每个数据表文件包含该表的模式。行不会随 package 迁移。

{
    "id": "dtCn12",
    "name": "countries",
    "columns": [
        { "id": "dcNm01", "name": "name", "type": "string", "index": 0 },
        { "id": "dcCd02", "name": "code", "type": "string", "index": 1 }
    ]
}
字段 描述
id 表在源实例上的 ID。导入创建的表会保留该 ID
name 表的名称
columns 每列对应一个条目,包含 id、name、type 和 index(列在表中的位置)
columns[].id 列在源实例上的 ID。n8n 2.44.0 之前导出的 package 不包含此字段

列 ID 让导入能够识别重命名的列,从而保留该列的值。n8n 2.44.0 之前导出的 package 不包含列 ID,因此 n8n 按名称匹配列,重命名列会被视为破坏性变更。请参阅数据表。

版本兼容性

packageFormatVersion 当前为 "1"。只有版本完全匹配时,n8n 实例才会导入 package。不存在兼容窗口或迁移路径:声明任何其他版本的 package 都会在写入任何内容之前以 400 被拒绝。

sourceN8nVersion 仅用于记录信息,不会与目标实例进行比较。因此,只要格式版本匹配且目标实例拥有工作流使用的节点类型,package 就可以在运行不同 n8n 版本的实例之间自由迁移。

例外是数据表列 ID。从 n8n 2.44.0 起,导出的数据表包含列 ID;旧实例会以 400 拒绝包含列 ID 的 package。请先升级导入目标实例。

在流水线中比较 packages

归档是确定性的:文件时间戳固定为 Unix 纪元,权限固定,gzip 以可移植模式运行。在同一实例和同一 n8n 版本上对相同内容执行两次导出会生成完全相同的字节,因此你可以在流水线中通过 package 校验和检测变化。

后续阅读

相关资源

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