限制和权限
提示
Preview status 预览状态
n8n packages 处于 Preview 阶段。这些限制和要求可能会在未来版本中发生变化。
本页说明 package 导出和导入所受的约束,包括大小上限、license 功能、API key scope 和可观测性。
Package 大小限制
四个环境变量用于限制可接受的导入内容,防止体积很小的 archive 解压后变得极大:
| Variable | 默认值 | 限制内容 |
|---|---|---|
N8N_IMPORT_MAX_UNCOMPRESSED_BYTES |
314572800(300 MiB) |
Archive 中所有文件的未压缩总大小,在读取 archive 时检查 |
N8N_IMPORT_MAX_ENTRY_BYTES |
5242880(5 MiB) |
任意单个文件的未压缩大小 |
N8N_IMPORT_MAX_ENTRIES |
5000 |
Archive 中的 entry 数量,包括 directory |
N8N_IMPORT_MAX_PATH_LENGTH |
1024 |
任意 entry path 的字符长度 |
超过任一限制都会返回 400,并指出触发的限制。
警告
Upload 本身另受 N8N_PAYLOAD_SIZE_MAX 限制。该变量默认为 16 MiB,并非 packages 专用。此限制作用于压缩文件,因此通常最先触发:只有未压缩后达到 300 MiB、压缩后仍小于 16 MiB 的 package 才会触及 300 MiB 上限。
导入大型 packages 时,请先提高 N8N_PAYLOAD_SIZE_MAX。只提高导入限制不会产生作用。Upload 超过上限会返回 413。
Import request 还受一些不可配置的限制:每个 request 只能包含一个文件,每个 option field 最大 64 KB,这也是 --bindings 值的实际上限。
Export 对每组 ID 的上限为 300,workflow、agent、folder 和 project ID 分别计数。请参阅选择要导出的内容。
Archive 验证
除大小限制外,n8n 还会拒绝结构不符合 package 要求的 archive;以下情况均返回 400:
manifest.json必须是 archive 中的第一个文件。- Entry path 只能使用字母、数字、
.、_、/和-,因此包含非 ASCII path 的 archive 会被拒绝。 - Path 必须是相对路径、不能跳出 package root,并且必须唯一。
- Entry 必须是文件或 directory。Symlink 和 hardlink 会被拒绝。
packageFormatVersion必须完全匹配。请参阅版本兼容性。
Manifest 未引用的文件会被忽略,但仍计入大小和 entry 限制。
License 功能
Packages 本身不需要 license 功能。该功能适用于所有 plan 和 edition 的 n8n Cloud 与自托管 n8n,export 也完全不需要 license 功能。
Import 会检查两个 license 功能,并且只检查实际要执行的操作:
- Folders:当 import 实际创建或移除 folder 时需要。Folder package 始终需要此功能,即使其中的 folder 已存在于 target 中也是如此。
- Variables:仅当 import 实际会创建或覆盖 variable 时需要。如果 package 中的 variables 都能在 target 上解析,就不会写入任何 variable,因此既不需要 license,也不需要 variable scope。
导入 project package 还需要支持 team projects 的 license。
缺少 license 功能会返回 403,并指出所需功能。
Packages 只能通过 n8n API 使用,因此实例必须启用 API。要阻止 package 移入或移出实例,可以禁用 public API,或不要签发带有 workflow:export、agent:export、project:export、workflow:import 和 agent:import scope 的 API key。
API key scopes API key 范围
Package endpoint 使用 API key 进行身份验证,import 会归属于该 key 的用户。
Export 导出
| Scope | 需要条件 |
|---|---|
workflow:export |
指定 workflow 或 folder ID 时。Folder 使用 workflow scope |
agent:export |
指定 agent ID 时 |
project:export |
指定 project ID 时,也涵盖这些 project 中的 agents |
variable:list |
打包 variable value,且工作流至少引用一个 variable 时 |
Import 导入
| Scope | 需要条件 |
|---|---|
workflow:import |
Package 包含 workflow 时 |
folder:create 和 folder:update |
Package 是 folder package 时。Project package 只需要 folder:create,并且仅在 import 实际创建 folder 时需要 |
workflow:delete |
Import 归档或恢复现有 workflow、folder conflict policy overwrite 实际移除 workflow,或 --deleted-workflow-ids 指定了 workflow 时 |
folder:delete |
直接设置或通过 --project-conflict-policy=overwrite 设置的 folder conflict policy overwrite 实际移除 folder 时 |
workflow:activate |
Import 计划发布 workflow 时,包括在默认的 --publishing-policy=preserve-published-state 下重新发布 |
workflow:deactivate |
Import 计划在 --publishing-policy=match-source 或 unpublish-all 下取消发布 workflow 时 |
project:create |
Import 实际创建 project 时 |
project:update |
Import 在 --project-conflict-policy=overwrite 下实际更改 project 详情时 |
credential:create |
Import 在 --credential-missing-mode=create-with-values 下实际创建 credential 时 |
credential:update |
Import 在 --credential-conflict-policy=overwrite 下实际更改 credential 时 |
dataTable:create |
Package 引用 data table,且 --data-table-missing-mode 为 create 时 |
dataTable:update |
导入通过 --data-table-schema-conflict-policy=overwrite 或 overwrite-non-destructive 实际更改数据表时 |
variable:create |
Import 实际创建 variable 时 |
variable:update |
Import 实际覆盖 variable 时 |
tag:create |
Import 实际创建 tag 时 |
tag:update |
Import 实际重命名或协调 tag 时 |
包含 agents 的 import 还需要 agent 和 skill scope,具体取决于它创建、更新和发布的内容。
从 project package 导入选定内容时,适用相同的 scope。
大多数 scope 根据 import 实际要写入的内容判断,因此,如果 package 中的 tag 或 variable 都已在 target 上匹配,就不需要 tag 或 variable scope。例外是 workflow:import、用于 --deleted-workflow-ids 的 workflow:delete、folder package 所需的 folder scope,以及 workflow 或 folder package 所需的 dataTable:create。这些 scope 根据 package 声明的内容和你传入的选项判断,因此即使每个引用的 table 都已存在,workflow 或 folder package 仍需要 dataTable:create。
Member role 的 API key 不能导入会创建 project 或更改其详情的 project package,因为 project:create 和 project:update 是 owner 和 admin scope。Member 可以拥有这些表中的其他所有 scope。
API key scope 是在你自身权限之上检查的,而不是取代自身权限。Export 时只能获取你有权读取的内容,因此 n8n 会检查你对每个 workflow、folder、project 和 credential 的访问权限。Import 时会检查你对 target project 的写入权限。你无权读取的 credential 会记录为 requirement,而不会打包,因此即使只能看到实例的一部分,生成的 package 也会明确指出 target 必须提供什么。
如果你的角色不允许创建 tag,或创建、更改 data table,n8n 会报告 blocking issue,而不是 403。缺少 API key scope 则返回 403。请参阅导入被拒绝的原因。
Variable 限制
实例可容纳的 variable 数量有上限,global 和 project-scoped variables 会合并计数。如果 import 将创建的新 variables 会超出限制,n8n 会在写入任何内容前拒绝导入。Issue 会指出限制、剩余容量、import 所需数量,以及涉及的 variables。
只有新 variable 才计入限制。覆盖现有 variable 不会消耗剩余容量,因为该 variable 已经计入限制。n8n 还会按 import 实际创建的内容计数,因此 package 中多个 projects 需要的同一个 global variable 只计一次。
Events 事件
两项操作都会在 log streaming 和 telemetry path 上发出事件,便于审计谁移动了哪些内容。
| Event | 发出条件 |
|---|---|
n8n.audit.n8n-package.export.success |
Export 成功 |
n8n.audit.n8n-package.export.failed |
Export 失败 |
n8n.audit.n8n-package.import.success |
Import 成功 |
n8n.audit.n8n-package.import.failed |
Import 失败 |
让 log streaming destination 订阅全部四个事件,即可跟踪所有移入或移出实例的 package。Log streaming event 会携带 entity ID,对应的 telemetry event 则携带每种 entity 的数量。Failure event 会将原因分类为 access-denied、entity-not-found、blocked 或 validation。
有关各 event payload 包含的内容,请参阅 export 页面和 import 页面中的 Events 章节与 Events 章节。
后续阅读
- 导出 package和导入 package:了解这些限制所适用的选项。
- 导入的工作原理:了解 license 和 scope 检查如何纳入 import 流程。