使用节点类型策略控制节点可用性
节点类型策略用于决定用户可以在整个实例或单个项目中使用哪些节点。
提示
Preview status 预览状态
节点类型策略处于 Preview 阶段,未来版本中可能会发生变化。请避免在生产环境中依赖此功能。
提示
Feature availability 功能可用性
以下版本提供节点类型策略:
- n8n Cloud: Enterprise
- 自托管: Enterprise
节点类型策略从 n8n 2.45.0 开始可用。
实例 Owner 或 Admin 设置实例策略。然后,项目 Admin 可以进一步限制自己的项目。你可以使用 n8n public API 管理策略。
节点类型策略的工作原理
策略包含一个规则列表和一个默认操作。
每条规则包含:
id:规则名称,在策略中必须唯一。当规则阻止某个节点时,n8n 会报告此 ID。action:allow、deny或delegate。只有实例策略接受delegate。selector:规则匹配的节点。
选择器通过以下两种方式之一匹配节点:
| 选择器 | 匹配项 | 示例 |
|---|---|---|
{ "kind": "name", "value": "<node-type>" } |
按精确名称匹配一个节点类型。 | n8n-nodes-base.executeCommand |
{ "kind": "package", "value": "<package-name>" } |
匹配 package 中的每个节点。 | n8n-nodes-base、@n8n/n8n-nodes-langchain |
n8n 按顺序检查规则,并使用第一条匹配的规则。如果没有规则匹配,n8n 会使用策略的 defaultAction。
要查找节点的类型名称,请在画布上选中该节点并复制它。将其粘贴到文本编辑器中,然后查看 type 字段。
name 规则也会匹配该节点的 tool 版本。例如,针对 n8n-nodes-base.gmail 的规则也会阻止 AI agent 使用的 Gmail Tool。
实例策略和项目策略如何组合
n8n 先评估实例策略,再评估项目策略:
| 实例判定 | 结果 |
|---|---|
deny |
节点被阻止。项目无法再次允许它。 |
allow |
由项目策略决定。项目只能进一步收紧限制。 |
delegate |
除非项目中存在显式的 allow 规则,否则节点会被阻止。项目的 defaultAction 不算显式允许。 |
对于默认应阻止、但项目 Admin 可以在自己项目中启用的节点,请使用 delegate。只有实例策略接受 delegate。
如果没有任何策略,则所有节点均可用。
使用策略可以按项目阻止节点,同时仍将其保留为已安装状态。在自托管实例上,可以使用 NODES_EXCLUDE 从整个实例中移除节点。
使用 API 设置策略
身份验证和权限
在 X-N8N-API-KEY 请求头中发送 API key。该 key 需要 nodeTypePolicy:manage scope。请参阅创建 API key。
| 端点 | 可以调用的角色 |
|---|---|
GET 和 PUT /api/v1/node-type-policies/instance |
实例 Owner 和 Admin |
GET 和 PUT /api/v1/node-type-policies/projects/<project-id> |
实例 Owner 和 Admin,以及该项目的 Admin |
要查找项目 ID,请在 n8n 中打开该项目。ID 是 URL 中 /projects/ 后面的部分。
读取、修改,然后写入策略
每个策略都有一个 version。PUT 必须发送你上次读取到的版本。这样可以防止两个 Admin 相互覆盖对方的更改。
要更改策略:
从未设置过的策略会返回 version: 0,因此第一次 PUT 应发送 0。如果在你读取后有人更改了策略,n8n 会返回 409 Conflict。请重新读取策略并重试。
如果某个 scope 附加了多个策略,或者其策略与另一个 scope 共享,PUT 也会返回 409 Conflict。在这种情况下,请更新共享策略或该 scope 的 attachments。请参阅在多个 scope 之间共享一个策略。
PUT 会替换策略中的所有规则。要添加一条规则,请同时发送现有规则和新规则。
示例:阻止整个实例中的节点
以下实例策略会阻止 Execute Command 节点,并允许项目 Admin 为自己的项目启用 SSH 节点。请使用当前 version,通过 PUT /node-type-policies/instance 发送:
{
"version": 0,
"defaultAction": "allow",
"rules": [
{
"id": "block-execute-command",
"action": "deny",
"selector": { "kind": "name", "value": "n8n-nodes-base.executeCommand" }
},
{
"id": "ssh-on-request",
"action": "delegate",
"selector": { "kind": "name", "value": "n8n-nodes-base.ssh" }
}
]
}
响应会返回保存后的策略及其新 version。响应还可能包含 warnings,列出已被前面规则覆盖的规则。n8n 永远不会执行这些规则。更改会在大约一秒内生效。
示例:在一个项目中启用委派的节点
上面的实例策略委派了 SSH 节点。以下项目策略会在一个项目中启用该节点。请使用当前 version,通过 PUT /node-type-policies/projects/<project-id> 发送:
{
"version": 0,
"defaultAction": "allow",
"rules": [
{
"id": "allow-ssh",
"action": "allow",
"selector": { "kind": "name", "value": "n8n-nodes-base.ssh" }
}
]
}
必须包含 allow 规则。项目的 defaultAction: allow 不会启用已委派的节点。
在多个 scope 之间共享一个策略
通过 /node-type-policies/policies 和 /node-type-policies/scopes/<scope-id>/attachments 端点,实例 Admin 可以在多个项目中复用同一组规则。大多数设置不需要使用这些端点。对 attachments 端点发出 GET 请求,会返回已附加的策略以及 PUT 所需的 version。详情请参阅端点参考。
节点在编辑器中被阻止时用户会看到什么
当节点在项目中被阻止时,该项目中的用户会看到:
- Nodes panel 节点面板: 浏览时不会显示被阻止的节点。它们仍会出现在搜索结果末尾,并带有锁定图标。用户无法添加这些节点。
- Canvas 画布: 工作流中已有的被阻止节点会显示受限标签。
- Node details 节点详情: 参数为只读。用户可以联系实例 Admin 或替换该节点。
- Publish and run 发布和运行: n8n 会拒绝操作,并显示一条消息,其中列出每个被阻止的节点及用于在工作流中找到它的链接。如果保存操作添加了被阻止的节点,n8n 也会以相同方式拒绝保存。
节点在 agents 中被阻止时用户会看到什么
- Tool picker 工具选择器: 被阻止的节点会显示在列表末尾并带有锁定图标。用户无法添加这些节点。Chat Hub tools 的行为相同。
- Chat 聊天: n8n 会拒绝对被阻止 tool 的调用,并将该步骤标记为受限。Agent 会告诉用户它无法执行的操作。
- Save and publish 保存和发布: n8n 会拒绝保存添加了被阻止 tool 的 agent,也会拒绝发布使用该 tool 的 agent。
- AI builders AI 构建器: Agent Builder 可以建议被阻止的节点,但 n8n 随后会拒绝保存。n8n Assistant 也同样如此,其企业就绪程度为 Limited enterprise readiness。
已使用被阻止节点的工作流
新策略不会更改现有工作流,但会限制用户可以对这些工作流执行的操作:
| 操作 | 结果 |
|---|---|
| 打开并编辑 | 允许。 |
| 保存 | 只要保存操作没有添加新的被阻止节点类型,即允许保存。 |
| 发布 | 拒绝。 |
| 运行(包括通过触发器运行或作为子工作流运行) | 拒绝。n8n 会将此次运行记录为失败的执行。 |
| 移动到另一个项目 | 根据目标项目的策略进行检查。 |
已发布的工作流会保持已发布状态,但在你允许该节点或从工作流中移除该节点之前,其执行会失败。
禁用的节点仍会计入检查。用户不能先以禁用状态添加被阻止的节点,再稍后启用它。
限制
- 尚无 Settings 页面: 目前只能通过 public API 管理策略。未来计划提供 Settings 页面。
- 不支持通配符:
name规则只匹配一个精确的节点类型。要匹配多个节点,请使用package规则。 package规则要求已安装该 package: 如果 package 尚未安装,n8n 会拒绝针对它的package规则。name规则没有此限制,因此你可以在任何人安装 community node 之前将其阻止。- 没有节点可豁免: 如果策略默认拒绝,它也会阻止 Manual Trigger 和 Sticky Note 等节点。请为用户需要的每个节点添加
allow规则。 - 并非数据边界: 阻止节点不会阻止其背后的服务。用户仍然可以通过 HTTP Request 或 Code 节点访问相同的 API。在自托管实例上,要让 n8n 完全不加载某个节点,请使用
NODES_EXCLUDE。 - Source control pulls 源代码控制拉取: n8n 会跳过使用被阻止节点的已拉取工作流,并在拉取结果中报告该工作流。在你允许该节点或将其移除之前,Git 中和 n8n 中的工作流会保持不同。
- 节点参数内的子工作流: n8n 不会检查在另一个节点的参数中定义的子工作流所包含的节点。