自定义项目角色(Custom project roles)#

功能可用性

自定义角色可在自托管企业版和云企业版计划中使用。有关计划详情，请参阅 n8n 的定价页面。

可用版本： n8n 1.122.0 版本（发布于 2025 年 11 月 24 日）

从 n8n 版本 2.13.0 起，可使用密钥库范围。

实例角色与项目角色

n8n 有两种类型的角色： * 实例角色（账户类型）：Owner、Admin 和 Member 角色，适用于整个 n8n 实例及所有项目 * 项目角色：适用于特定项目的角色（Admin、Editor、Viewer 以及自定义角色）

自定义角色是项目级别的角色。它们定义单个项目内的权限，而不是整个实例的权限。

自定义项目角色允许你创建具有特定权限的角色，以满足团队的需求。与内置项目角色（管理员、编辑、查看者）不同，自定义角色让你可以对工作流程、凭证和其他项目资源定义详细的访问权限。

🌐 Custom project roles allow you to create roles with specific permissions tailored to your team's needs. Unlike the built-in project roles (Admin, Editor, Viewer), custom roles let you define granular access to workflows, credentials, and other project resources.

创建自定义角色(Create a custom role)#

实例所有者和实例管理员可以创建自定义角色。

🌐 Instance owners and instance admins can create custom roles.

创建自定义角色：

🌐 To create a custom role:

前往设置 > 项目角色。
选择 创建角色。
输入角色名称和可选描述。
为此角色选择权限（范围）:
- 工作流权限：查看、执行、编辑、创建、发布、转让、删除或管理工作流的数据脱敏
- 凭证权限：查看、编辑、创建、共享、取消共享、转移或删除凭证
- 项目权限：查看、编辑或删除项目
- 文件夹权限：查看、编辑、创建、转移或删除文件夹
- 执行权限：显示已编辑的执行数据
- 秘密保险库权限：查看、创建、编辑、删除或同步项目的秘密保险库
- Secrets 权限：在凭据中使用 secrets
- 数据表权限：查看表格、查看行、编辑表格、编辑行、创建或删除表格
- 项目变量权限：查看、编辑、创建或删除项目变量
- 源代码管理：推送到源代码管理
选择 创建角色。

为用户分配自定义角色(Assign a custom role to users)#

项目管理员可以为项目成员分配自定义角色。自定义角色仅适用于分配它们的特定项目。用户在不同项目中可以拥有不同的角色。

🌐 Project admins can assign custom roles to project members. Custom roles apply only within the specific project where they're assigned. A user can have different roles in different projects.

分配自定义角色：

🌐 To assign a custom role:

选择项目。
选择 项目设置。
在 项目成员 下，浏览或搜索用户。
选择用户，然后从下拉菜单中选择自定义角色。
选择保存。

项目级权限

自定义角色权限仅适用于分配该角色的项目。如需在多个项目中授予相同权限，需要在每个项目中单独分配该自定义角色。

编辑自定义角色(Edit a custom role)#

要修改现有的自定义角色：

🌐 To modify an existing custom role:

前往设置 > 项目角色。
找到你想要编辑的自定义角色。
选择 三点菜单 > 编辑。
更新角色名称、描述或权限。
选择 保存更改。

编辑会影响所有分配的用户

对自定义角色的更改会立即影响分配到该角色的所有用户，无论他们所在的项目。如果该角色在多个项目中使用，权限更改将在所有分配了该角色的地方生效。

复制自定义角色(Duplicate a custom role)#

基于现有角色创建新角色：

🌐 To create a new role based on an existing one:

前往设置 > 项目角色。
找到你想要复制的角色。
选择 三点菜单 > 复制。
根据需要修改角色名称和权限。
选择 创建角色。

删除自定义角色(Delete a custom role)#

要删除自定义角色：

🌐 To delete a custom role:

前往设置 > 项目角色。
找到你想要删除的角色。
选择 三点菜单 > 删除。
确认删除。

在删除之前重新分配用户

如果用户被分配到此角色，则必须先将他们重新分配到其他角色，然后才能删除该角色。

权限范围参考(Permission scopes reference)#

自定义角色使用权限范围来定义用户在项目中可以执行的操作。下面的每个范围都对应 项目角色 编辑器中的一个复选框。各部分标题与编辑器的部分名称匹配；范围代码是你在 API 响应和审计日志中会看到的内容。

🌐 Custom roles use permission scopes to define what users can do within a project. Each scope below matches a checkbox in the Project roles editor. The section headings match the editor's section names; the scope codes are what you'll see in API responses and audit logs.

自动授予的权限范围

n8n 会将某些权限范围配对，因此它们不会以独立的复选框出现：

授予 <resource>:read 同时也授予该资源的匹配列表权限范围（例如，workflow:read 授予 workflow:list）。
授予 workflow:publish 同时也授予 workflow:unpublish。

工作流范围(Workflow scopes)#

workflow:create - 创建新工作流
workflow:read - 查看工作流详情
workflow:update - 编辑工作流程
workflow:execute - 执行工作流
workflow:publish - 发布工作流（也授予 workflow:unpublish）
workflow:delete - 删除工作流
workflow:move - 在项目之间转移工作流程
workflow:enableRedaction - 为工作流开启数据屏蔽（参见执行数据屏蔽）
workflow:disableRedaction - 关闭工作流的数据编辑（参见执行数据编辑）

凭据范围(Credential scopes)#

credential:create - 创建新凭据
credential:read - 查看凭证详情
credential:update - 编辑凭据
credential:delete - 删除凭据
credential:move - 在项目之间传输凭据
credential:share - 与其他用户共享凭据
credential:unshare - 移除凭证共享

项目范围(Project scopes)#

project:read - 查看项目详情
project:update - 编辑项目设置
project:delete - 删除项目

文件夹范围(Folder scopes)#

folder:create - 创建新文件夹
folder:read - 查看文件夹内容
folder:update - 重命名文件夹
folder:delete - 删除文件夹
folder:move - 传输文件夹

执行范围(Execution scopes)#

execution:reveal - 显示已编辑的执行数据（参见执行数据编辑）

秘密金库范围(Secret vault scopes)#

范围代码使用 externalSecretsProvider 前缀。角色编辑器将此部分列为 秘密库。

🌐 The scope codes use the externalSecretsProvider prefix. The role editor lists this section as Secrets vaults.

externalSecretsProvider:create - 在项目中创建新的秘密金库
externalSecretsProvider:read - 查看项目中的秘密保险库
externalSecretsProvider:update - 编辑秘密仓库配置
externalSecretsProvider:delete - 从项目中删除秘密金库
externalSecretsProvider:sync - 重新加载保险库的秘密

机密范围(Secrets scope)#

作用域代码使用 externalSecret 前缀。角色编辑器将此部分列为秘密。

🌐 The scope code uses the externalSecret prefix. The role editor lists this section as Secrets.

externalSecret:list - 在凭据中使用秘密

数据表范围(Data table scopes)#

dataTable:create - 创建新数据表
dataTable:read - 查看数据表架构
dataTable:update - 编辑数据表架构
dataTable:delete - 删除数据表
dataTable:readRow - 从数据表中读取行
dataTable:writeRow - 在数据表中插入或更新行

项目变量范围(Project variable scopes)#

projectVariable:create - 创建新变量
projectVariable:read - 查看变量值
projectVariable:update - 编辑变量值
projectVariable:delete - 删除变量

源代码控制范围(Source control scopes)#

sourceControl:push - 将更改推送到源代码管理

常见的自定义角色示例(Common custom role examples)#

这些是你可以为常见用例创建的示例自定义项目角色。请记住，这些角色适用于单个项目内，而不适用于整个 n8n 实例。

🌐 These are example custom project roles you can create for common use cases. Remember that these roles apply within individual projects, not across your entire n8n instance.

工作流开发者(Workflow developer)#

仅处理工作流程的用户角色：

🌐 A role for users who work only with workflows:

workflow:create、workflow:read、workflow:update、workflow:execute、workflow:delete
credential:read（只能查看凭证，但不能编辑）
project:read

凭证管理器(Credential manager)#

管理凭据的用户角色：

🌐 A role for users who manage credentials:

credential:create、credential:read、credential:update、credential:delete、credential:share
workflow:read（查看工作流程以了解凭证使用情况）
project:read

机密用户(Secrets user)#

用于那些在凭据中使用外部秘密但不管理保险库的用户的角色：

🌐 A role for users who use external secrets in credentials but don't manage vaults:

externalSecret:list（在凭证表达式中使用密钥）
credential:create、credential:read、credential:update（使用密钥管理凭证）
workflow:read
project:read

工作流发布者(Workflow publisher)#

一个可以发布工作流但没有完全编辑权限的用户角色：

🌐 A role for users who can publish workflows without full edit access:

workflow:read，workflow:publish
credential:read
project:read

组合作用域

你可以组合任意作用域来创建符合你具体需求的角色。请考虑最小权限原则：只授予用户执行其任务所需的权限。