导出 package
提示
Preview status 预览状态
n8n packages 处于 Preview 阶段。导出选项在未来版本中可能会发生变化。
导出操作会写入一个 n8n package,即 .n8np 归档。其中包含你请求的内容,以及这些工作流在目标实例上所需全部内容的引用。导出不会修改源实例。
使用 n8n CLI:
n8n-cli package export --workflow-id=<workflow-id> --output=triage.n8np
或者直接调用端点:
curl -X POST 'https://n8n.example.com/api/v1/n8n-packages/export' \
-H "X-N8N-API-KEY: <your-api-key>" \
-H 'Content-Type: application/json' \
-d '{"workflowIds": ["<workflow-id>"]}' \
-o triage.n8np
有关完整的请求和响应模式,请参阅端点参考中的 N8nPackage 部分。
选择导出内容
至少传入一个 ID。若要指定多个对象,请重复使用标志;不支持以逗号分隔的形式。
# Two workflows
n8n-cli package export --workflow-id=wf7Kq2 --workflow-id=wf9Zx1 --output=triage.n8np
# A folder, and everything nested inside it
n8n-cli package export --folder-id=fdInProg --output=in-progress.n8np
# A workflow and a folder together
n8n-cli package export --workflow-id=wf7Kq2 --folder-id=fdInProg --output=mixed.n8np
# A workflow and an agent together
n8n-cli package export --workflow-id=wf7Kq2 --agent-id=agSup01 --output=support.n8np
# Two whole projects
n8n-cli package export --project-id=prTeam9 --project-id=prOps3 --output=teams.n8np
工作流、agent 和文件夹 ID 可以组合使用。项目 package 的形态不同,因此项目 ID 不能与其中任何一种组合。混合这两组 ID 会返回 400。
文件夹始终会携带其中嵌套的文件夹及其工作流。文件夹和项目导出会排除已归档的工作流,除非设置 --include-archived-workflows=true。按 ID 指定的工作流即使已归档也始终会导出。如果指定的工作流也位于指定的文件夹中,它只会在该文件夹内导出一次。
n8n 将每组 ID 的上限设为 300。此限制按组计算,因此一次导出可以指定 300 个工作流、300 个 agents 和 300 个文件夹。超过上限会返回 400,而 CLI 不会在发送请求前捕获此问题。
空项目只会导出项目 metadata,manifest 中不会包含 workflows 列表。
导出标志
| Flag | 说明 |
|---|---|
--workflow-id, -w |
要包含的工作流 ID。重复使用可导出多个工作流。 |
--agent-id |
要包含的 agent ID。重复使用可导出多个 agents。 |
--folder-id |
要包含的文件夹 ID,以及其中嵌套的所有内容。重复使用可导出多个文件夹。 |
--project-id, -p |
要包含的项目 ID。重复使用可导出多个项目。不能与 --workflow-id、--agent-id 或 --folder-id 组合。 |
--output, -o |
package 的写入文件。默认为当前目录中的 export.n8np。 |
--version-policy |
latest(默认)、published-strict、prefer-published 或 ignore-unpublished。n8n 导出每个工作流和 agent 的哪个版本。请参阅工作流版本。 |
--include-variable-values |
true(默认)或 false。是否打包变量值。请参阅变量值。 |
--include-tags |
true(默认)或 false。是否打包导出工作流上的标签。 |
--include-archived-workflows |
false(默认)或 true。文件夹和项目导出是否包含其中已归档的工作流。 |
--credential-export-policy |
expression-values-only(默认)或 no-values。是否打包通过表达式设置的凭据字段。请参阅凭据值。 |
--dependency-policy |
fail(默认)、include-in-package 或 reference-only。n8n 如何处理 package 所依赖但你未指定的工作流或 agent,例如子工作流、错误工作流或 sub-agent。请参阅工作流依赖项。 |
提示
这里以 kebab-case 显示 n8n-cli package export 标志。--help 会输出等效的 camelCase 名称(--workflowId、--includeTags、--dependencyPolicy),错误消息也会使用这些名称。两种写法均有效。
--output 会覆盖已有文件且不发出警告。导出失败时 n8n 不会写入任何内容,因此失败的运行会保留之前的文件。
工作流依赖项
如果工作流调用子工作流或指定错误工作流,该工作流就是 package 的依赖项。当依赖项不在指定的 ID 集合中时,--dependency-policy 决定 n8n 如何处理。
该策略只适用于工作流和 agents,不影响它们使用的凭据、数据表、变量或标签。agent 的 sub-agents 以及它用作 tools 的工作流也算作依赖项。
| 值 | 行为 |
|---|---|
fail(默认) |
中止导出并列出缺少的内容,最多 20 个 ID |
include-in-package |
遍历依赖关系图,并将缺少的工作流和 agents 添加到 package |
reference-only |
不包含这些对象,并将其记录在 requirements.workflows 或 requirements.agents 中,作为目标实例必须已有的实体 |
fail 和 include-in-package 会沿着整个依赖链处理。 如果工作流 A 调用 B,B 又调用 C,则导出 A 和 B 时仍会因 C 而失败。只有 reference-only 会停在直接引用处,因为它假定被引用的工作流及其依赖项已经一起存在于目标实例。
错误工作流也算作依赖项。 如果工作流在 Settings 设置 > Error workflow 错误工作流 下配置了错误工作流,则默认导出会失败,除非同时包含该错误工作流。例外情况是字面值 DEFAULT 和通过表达式设置的错误工作流,n8n 会忽略它们。
n8n 不会将表达式设置的引用视为依赖项,也不会在导入时重写此类引用。只有静态引用会计入。
日常环境提升场景有两种形式:
# Name the dependency yourself
n8n-cli package export --workflow-id=wf7Kq2 --workflow-id=wf9Zx1 --output=triage.n8np
# Or let n8n work it out
n8n-cli package export --workflow-id=wf7Kq2 \
--dependency-policy=include-in-package \
--output=triage.n8np
警告
导出项目时,include-in-package 可能会引入未请求的项目。由其他项目拥有的依赖项会将该项目的外壳和文件夹链带入归档。CLI 摘要统计的是你指定的项目,而不是归档中的项目,因此发生这种情况时会少报。请解压归档或读取 manifest,查看实际导出的内容。
工作流版本
--version-policy 决定每个工作流的哪个版本随 package 迁移:
| 值 | 行为 |
|---|---|
latest(默认) |
导出当前草稿 |
published-strict |
导出已发布版本。如果某个工作流没有已发布版本,则中止导出,并列出最多 20 个此类工作流 |
prefer-published |
导出已发布版本;对于未发布的工作流,导出其草稿 |
ignore-unpublished |
导出已发布版本,并排除未发布的工作流 |
对于工作流,该策略只决定节点和连接。其名称、设置和标签始终来自当前草稿。该策略也适用于 agents。
已归档的工作流没有已发布版本,因此无论策略如何,它始终导出其草稿。
被 ignore-unpublished 排除的依赖项视为缺失。在 --dependency-policy=fail 或 include-in-package 下,导出会中止;在 reference-only 下,n8n 会将其记录在 manifest 的 requirements 中。
变量值
默认情况下,导出工作流引用的变量会连同其值一起迁移。使用 --include-variable-values=false 时,变量仍会迁移并出现在 manifest 和 requirements.variables 中,但会省略其 value 字段。
关闭变量值会改变导入行为:目标实例会创建一个空变量,而不是填入变量值;这不会阻止变量本身迁移。
打包变量值需要 API key 具有 variable:list 作用域,但仅当导出的工作流引用至少一个变量时才需要。如果缺少该作用域,导出会返回 403,提示添加作用域或设置 --include-variable-values=false。任何可以创建 API key 的角色都能分配 variable:list,因此此处出现 403 表示所用 key 在创建时未包含该作用域。
n8n 会扫描节点参数和工作流设置中的 $vars.NAME、$vars['NAME'] 和 $vars["NAME"] 来查找变量引用。
如果同一 package 中的一个变量名会解析为两个不同变量,导出将被阻止,因为 package 只能携带其中一个。
凭据值
默认情况下,打包的凭据会携带值为 n8n 表达式的字段,例如 ={{ $secrets.apiKey }},以及这些字段所依赖的设置。例如,CA 证书字段只有在启用 SSL 时才会出现在凭据表单中,因此如果它包含表达式,SSL 设置也会一并迁移。你直接输入的其他值(例如主机或密码)永远不会迁移;出于安全原因,OAuth token 也不会迁移。使用 --credential-export-policy=no-values 时,每个凭据文件只包含凭据的 ID、名称和类型。
表达式值让目标实例能够创建一个可用的凭据,并从目标实例自己的存储中读取密钥。要使用这些值,请以 --credential-missing-mode=create-with-values 导入。请参阅凭据。
标签
使用 --include-tags=false 时,不会迁移任何标签数据:导出的工作流不携带标签引用,归档中也没有 tags/ 目录。
这对导入的影响比看起来更大。携带标签列表(包括空列表)的工作流会用该列表完全覆盖目标工作流的标签。完全不含标签列表的工作流则不会改变目标上的标签。因此,--include-tags=false 才是保留目标现有标签的选项。
如果源实例设置了 N8N_WORKFLOW_TAGS_DISABLED=true,无论该标志如何设置,每次导出都会省略标签且不发出警告。
响应包含哪些信息
导出成功时会以 application/gzip 返回归档,并通过 X-N8n-Export-Counts header 提供每种实体的实际数量:
X-N8n-Export-Counts: {"agents":0,"workflows":2,"folders":0,"credentials":1,"dataTables":1,"variables":1,"tags":1}
这些是计算文件夹内容以及自动包含的子工作流和 sub-agents 后,归档中最终各类内容的数量,因此不一定与请求的 ID 数量相符。该 header 没有 projects 键。CLI 会根据它输出摘要。
credentials 统计打包的凭据文件,因此无权读取的凭据会记录为要求,但不会计入数量。variables 统计打包的变量文件,而不是引用的名称。
无论导出了什么,下载文件名始终为 export.n8np。CLI 则会写入 --output 指定的位置。
权限
导出需要 API key 具有以下作用域:
- 指定工作流或文件夹 ID 时,需要
workflow:export。文件夹使用工作流作用域。 - 指定 agent ID 时,需要
agent:export。 - 指定项目 ID 时,需要
project:export,这也涵盖这些项目中的 agents。 - 打包变量值且工作流引用了至少一个变量时,需要
variable:list。
除了 API key 权限外,你只能导出自己有权读取的内容:n8n 在构建 package 时会检查你对每个工作流、agent、文件夹、项目和凭据的访问权限。无权读取的凭据会记录为要求,而不会打包。
导出不需要任何许可证功能。完整矩阵请参阅限制与权限。
错误
| 状态 | 原因 |
|---|---|
400 |
请求的工作流、agent、文件夹或项目不存在,或你无权访问;也可能是混合了不同 ID 组、未传入 ID、某组超过 300 个 ID,或者导出被 --dependency-policy 或 --version-policy=published-strict 阻止 |
403 |
API key 缺少所需作用域 |
实体不存在和无权访问都会返回相同的 400 和相同消息,因此不能使用导出来测试某个 ID 是否存在。导出绝不会返回 404。
错误正文只包含 message。
事件
每次导出都会在日志流和遥测路径上发出事件,以便审计从实例中导出了什么。
| 事件 | 发出时机 |
|---|---|
n8n.audit.n8n-package.export.success |
导出成功 |
n8n.audit.n8n-package.export.failed |
导出失败 |
成功事件包含用户,以及实际进入 package 的 workflowIds、agentIds、folderIds 和 projectIds,因此反映的是文件夹内容和自动包含的依赖项,而不是请求的对象。每个列表仅在非空时出现。
失败事件包含用户、请求的 ID,以及值为 access-denied、entity-not-found、blocked 或 validation 的 reason。
日志流事件包含 ID。遥测事件会发出计数,以保持数据匿名。
后续阅读
- 导入 package:将文件迁移到另一个实例。
- Package 格式:了解归档中的内容。
- 限制与权限:了解大小上限和完整作用域矩阵。