ToolJet 用户角色（User Roles）详解：RBAC 权限模型与工作区角色管理实战-港品优选

ToolJet 用户角色（User Roles）详解：RBAC 权限模型与工作区角色管理实战

【免费下载链接】ToolJetOpen-source foundation of ToolJet AI - the enterprise app generation platform for internal tools, dashboards, business applications, workflows and AI agents. Build visually, from a prompt, or from Claude Code, Codex and Cursor over MCP 🚀项目地址: https://gitcode.com/GitHub_Trending/to/ToolJet

导读

本文围绕 ToolJet 开源低代码平台的用户角色（User Roles）机制展开，深入解析工作区（Workspace）级别的三种默认角色 —— Admin（管理员）、Builder（构建者）、End-user（终端用户）—— 各自的职责边界与资源权限矩阵，并给出管理员如何在Workspace Settings > Users中修改用户角色的完整操作步骤。读者将掌握 ToolJet RBAC 的权限分层原理、默认角色在源码中的真实定义，以及如何在日常运维中安全地变更用户角色。

一、ToolJet 的 RBAC：角色、组与权限的三层模型

ToolJet 通过基于角色的访问控制（RBAC）体系来管理应用、数据源、文件夹、工作区常量/变量等资源的安全与访问。其权限体系可以拆解为三个层面：

用户角色（User Roles）：系统预置的角色，决定用户在某一工作区内的基准权限；
自定义组（Custom Groups）：支持更细粒度的权限控制，可将用户按团队或职责分组并赋予特定权限；
资源级权限（Granular Access Control）：对单个应用、数据源等资源设置 View / Edit / Configure 等具体权限。

角色与组共同参与用户的权限判定，而用户角色还会被纳入许可（Licensing）与计费的考量范围。从源码结构看，用户角色与自定义组共用同一套组权限（Group Permissions）机制，默认角色本质上是系统预置的、不可删除的默认组。三者关系可参考配套文档：access-control.md 与 custom-groups.md。

二、三种默认用户角色（Default User Roles）

ToolJet 在工作区级别预置了三种默认用户角色，权限逐级递减：

角色	定位	核心职责
Admin	工作区管理员	管理设置、控制用户权限、监督整体功能，拥有全部资源的完整访问权
Builder	应用构建者	负责应用的创建、定制与配置，权限可被精细配置
End-user	终端用户	消费最终应用，执行任务或达成业务目标；只能查看和使用被授权访问的已发布应用

源码中的角色定义

这三种角色的定义可以在服务端源码 server/src/modules/group-permissions/constants/index.ts 中找到，它们被定义为枚举USER_ROLE与三个默认组对象：

export enum USER_ROLE { END_USER = 'end-user', ADMIN = 'admin', BUILDER = 'builder', }

其中DEFAULT_GROUP_PERMISSIONS定义了各角色的全局开关型权限（如appCreate、dataSourceCreate、folderCreate、appPromote、appRelease等），DEFAULT_RESOURCE_PERMISSIONS则定义了角色在各类资源（App、Data Source、Folder、Workflow、Module 等）上的默认动作权限。此外，server/src/modules/ability/constants.ts 中的DEFAULT_USER_PERMISSIONS为每个用户维护了isAdmin、isBuilder、isEndUser三个角色标志位，以及各资源的细粒度权限列表，是后端进行权限判定的基础数据。

注：工作区级角色之上还存在实例级的 Super Admin（超级管理员）概念，二者作用域不同，可参考 super-admin.md。

三、各角色的权限矩阵（Permissions for User Roles）

默认情况下，Admin 拥有工作区级别的全部权限；End-user 只能查看并使用被授权访问的已发布应用；Builder 的权限则可以被管理员按需配置。三种角色的基准权限矩阵如下：

资源	权限	Admin	Builder	End User
Apps	Create/Update/Delete	✅	可配置	❌
View	✅	可配置	可配置
Data sources	Create/Update/Delete	✅	可配置	❌
Folder	Create/Update/Delete	✅	可配置	❌
Workspace constants/variables	Create/Update/Delete	✅	可配置	❌

从源码印证默认权限差异

对照 DEFAULT_GROUP_PERMISSIONS 可以看出三个角色的默认差异：

Admin / Builder：appCreate、appDelete、folderCreate、folderDelete、dataSourceCreate、dataSourceDelete、orgConstantCRUD、appPromote、appRelease等开关均为true，且都带isBuilderLevel: true标志；
End-user：上述所有开关均为false，isBuilderLevel也为false，即默认没有任何创建/删除类权限。

而在资源默认权限DEFAULT_RESOURCE_PERMISSIONS中，三者的差异更加明显：

Admin：可编辑 App（canEdit: true），可访问 Development / Staging / Production / Released 全部环境（canAccessDevelopment/Staging/Production/Released均为true），数据源可配置（canConfigure: true）；
Builder：可编辑 App，默认可访问 Development、Staging 与 Released 环境，但Production 环境默认为false（canAccessProduction: false），数据源同样可配置；
End-user：App 默认可查看（canView: true），但不可编辑（canEdit: false），仅可访问 Released（已发布）环境，其余环境均不可访问。

这一设计清晰地体现了 "构建者管开发、终端用户只用成品" 的权限隔离思路。

四、管理用户角色：修改用户角色的完整步骤

修改用户角色需要Admin权限，操作路径为工作区管理后台：

点击仪表盘左下角的设置图标（⚙️）；
进入Workspace settings > Users（示例 URL：https://app.corp.com/nexus/workspace-settings/users）；
在用户列表中找到需要调整角色的用户，点击该行末尾的kebab 菜单（⋮）；
点击Edit user details，右侧将弹出用户详情面板；
在User groups下拉框中更新该用户的角色；
点击面板底部的Update按钮；
阅读并接受弹出窗口中的警告，点击Continue确认；
确认后，该用户的角色即完成更新。

角色变更背后的权限联动

从服务端实现看，角色变更并非孤立的用户字段更新。在 server/src/modules/users/repositories/repository.ts 中，用户与角色/组通过user.userGroups关联表关联，后端会按group.name（如USER_ROLE.ADMIN）与organizationId查询并判定用户的有效角色集合（roles: USER_ROLE[]）。因此：

修改用户角色实际上是在调整该用户与默认组/自定义组的隶属关系；
当用户被加入权限更高的自定义组时，其角色会被自动提升（见 custom-groups.md 中的 "Inheritance and Overrides" 规则）；
当用户角色被降级到更低权限时，系统会将其从提供更高权限的自定义组中自动移除，避免越权残留。

这就是第 7 步警告弹窗存在的意义：角色变更可能连带影响用户所属的自定义组，需要管理员二次确认。

五、权限的继承与叠加规则

理解角色权限，还需要掌握权限的叠加逻辑：

用户同时继承所属角色与所属自定义组的权限；
当用户属于多个组时，取任意一组中授予的最高权限（取并集）；
用户拥有资源的创建权并创建该资源后，自动成为资源 Owner，默认获得该资源的全部相关权限（例如创建了数据源 A 的用户，默认拥有数据源 A 的 Configure 与 Build 权限），该规则在 access-control.md 中有明确说明。

六、与其他权限文档的衔接

用户角色是 ToolJet 权限体系的入口，后续深入阅读建议：

访问控制：access-control.md —— 讲解 Apps / Data Sources / Folder / Workspace 常量的创建与删除权限配置，以及 Granular Access Control（粒度级访问控制）的 Edit / View / Configure / Build with 等资源级权限；
自定义组：custom-groups.md —— 讲解如何创建、删除、复制自定义组，以及权限的继承与覆盖规则；
超级管理员：super-admin.md —— 讲解实例级 Super Admin 与工作区级角色（Admin/Builder/End-user）的区别。

小结

ToolJet 的用户角色体系以 Admin、Builder、End-user 三种默认角色为骨架，配合自定义组与粒度级资源权限，构成了一套完整、可伸缩的工作区访问控制方案。管理员既可以通过Workspace Settings > Users快速调整单个用户的角色，也可以通过自定义组实现按团队、按应用的精细授权。理解默认角色的权限边界（尤其是 Builder 默认不可访问 Production 环境、End-user 仅可访问 Released 环境），是安全治理工作区权限的第一步。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析