企业官网建设流程全解析

ToolJet 自定义用户组（Custom Groups）完整指南：创建、删除、复制与权限继承机制

【免费下载链接】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

自定义用户组（Custom Groups）是 ToolJet 工作区内实现精细化权限管理（RBAC）的核心手段。本文基于 ToolJet 官方文档与仓库源码，系统讲解自定义组的创建、删除、复制操作，以及"组 + 角色"权限继承与自动升降级的底层规则，帮助你按团队、按业务线为成员精确划分可访问的应用与数据源。

在 ToolJet 中，权限控制由"用户角色"与"用户组"共同承担：Admin、Builder、End-user 等默认角色定义了基础能力，而自定义组则允许管理员针对具体资源（如某个 HR 应用、某个销售数据源）单独授权。文档原文以 HR 与 Sales 两个团队为例：当两个团队各自只需要访问与本团队相关的应用时，管理员只需创建名为 HR、Sales 的自定义组，再通过**精细访问控制（Granular Access Control）**为每组勾选对应应用即可，参见 Access Control 指南。

前置条件：角色要求与功能可用性

执行组管理操作前，需要明确两个约束：

1. 角色要求：创建、删除、复制自定义组均要求当前用户具备Admin（管理员）角色。在 用户角色 体系中，只有 Admin 拥有对工作区结构与成员的管理权限。
2. 功能可用性：自定义组属于受许可证（License）控制的功能。从前端实现看，创建按钮被LicenseTooltip包裹，当许可证无效时按钮被禁用并提示 "Custom groups are not available in your plan"；相关逻辑位于 ManageGroupPermissionsPage.jsx（isFeatureEnabled、featureAccess分别控制可用性与提示文案）。

另外需要注意的是，系统内置的Admin、Builder、End-user是默认组（default groups），它们不能被删除——前端代码通过isDefaultGroup判断（组名匹配end-user/admin/builder时禁用删除按钮并显示 "Cannot delete default group" 提示，见 ManageGroupPermissionsPage.jsx）。自定义组则在界面中以独立的CUSTOM GROUPS分区展示，与上方USER ROLE分区的默认角色组区分开。

创建自定义用户组

操作角色：Admin

创建流程如下：

1. 点击仪表盘左下角的设置图标（⚙️）。
2. 进入Workspace Settings>Groups（Groups 即用户组管理页）。
   • 示例 URL：https://app.corp.com/nexus/workspace-settings/groups
3. 点击+ Create new group。
4. 输入组名，点击Create Group完成创建。

创建成功后，新组会出现在 CUSTOM GROUPS 列表中，随后即可参照 Access Control 指南为其配置权限。

组名校验规则（源码级细节）：前端在 ManageGroupPermissionsPage.jsx 中对组名做了如下约束，这些规则在实际操作中值得留意：

• 最长 50 个字符，超出部分会被截断（value.slice(0, 50)）；
• 只允许字母、数字、下划线（_）、连字符（-）和空格，正则表达式为/^[a-zA-Z0-9_ -]+$/，不符合时提示 "Group name can only contain letters, numbers, underscores, hyphens and spaces"；
• 组名必须唯一，与已有组重名时保存按钮会被禁用（"Group name must be unique and max 50 characters"）。

删除自定义用户组

操作角色：Admin

1. 点击仪表盘左下角的设置图标（⚙️）。
2. 进入Workspace Settings>Groups。
3. 点击目标组右侧的 kebab 菜单（⋮）。
4. 选择Delete，在弹出的确认对话框中确认操作。

删除前会弹出ConfirmDialog二次确认，确认文案为 "This group will be permanently deleted. Do you want to continue?"（见 ManageGroupPermissionsPage.jsx），点击确认后调用后端接口完成删除。

重要限制：如上文所述，默认组（Admin / Builder / End-user）无法删除，删除操作仅适用于自定义组。删除自定义组是不可逆的，删除后该组内所有成员将失去经由该组获得的所有权限。

复制用户组（Duplicate Group）

复制功能用于快速复用已有的权限结构，是批量搭建团队权限时的效率工具。

操作角色：Admin

1. 点击仪表盘左下角的设置图标（⚙️）。
2. 进入Workspace Settings>Groups。
3. 点击目标组右侧的 kebab 菜单（⋮）。
4. 选择Duplicate，在弹出的对话框中勾选需要一并复制的组内容。
5. 点击Duplicate，系统会基于原组创建一个新组并带上所选内容。

可复制的组内容（复刻对话框中的勾选项，对应前端 BaseManageGroupPermissions.jsx）：

勾选项的可视范围与版本有关：在社区版（CE）中仅开放部分选项，如 ManageGroupPermissionsPage.jsx 中GROUP_DUPLICATE_OPTIONS = { addPermission: true, addApps: true, addUsers: true }，其余项由groupDuplicateOption按版本注入。所有勾选项均未勾选时，Duplicate 按钮会被禁用（allFalse判断）。

后端实现原理：复制操作对应 server/src/modules/group-permissions/service.ts 中的duplicateGroup方法，整个过程在数据库事务（dbTransactionWrap）内完成：

1. 查询原组信息并深拷贝为新组记录；
2. 若勾选addPermission，复制组级权限；
3. 若勾选addUsers，将原组全部成员以{ userId, groupId }映射批量写入GroupUsers表；
4. 若勾选addApps，遍历原组所有type == ResourceType.APP的精细权限，先复制权限主体（duplicateGranularPermissions），再复制其下资源级授权（duplicateResourcePermissions）；
5. 通过licenseUserService.validateUser校验许可证后返回新组。

复制完成后新组名沿用原组名，成功后前端会提示 "Group duplicated successfully!" 并自动选中新组，方便立即进入配置。

继承与覆盖规则（Inheritance and Overrides）

这是自定义组体系中最重要的行为准则，文档明确了以下 4 条规则：

• 权限叠加：用户自动继承其所属角色（Role）以及其加入的所有自定义组（Custom Groups）的权限。
• 自动升级：当用户被加入一个权限高于其当前角色的自定义组时，系统会自动将其用户角色升级到与之匹配的更高访问级别。
• 自动降级移除：当用户角色被降级到更低权限时，系统会自动将其从那些提供了高于新角色权限的自定义组中移除。
• 取最高权限：当用户同时属于多个组时，最终生效的是任意一个组所授予的最高级别权限（而不是取交集或平均值）。

理解这四条规则，可以推导出以下实践要点：

• 自定义组本质上是"角色之上的叠加层"，它可以向下细分（如把 End-user 再分为"仅看 HR 应用"与"仅看 Sales 应用"），也可以向上提权（如给某 Builder 临时开放数据源 Configure 权限）。
• 由于"自动升级"与"自动移除"机制的存在，组内成员的层级是动态维护的——管理员在调整用户角色或组成员关系时，无需手动逐一同步，系统会在相应服务端逻辑中完成一致性的收敛。
• 当同一用户既被授予较高角色的组、又被降级时，规则 3 与规则 4 配合保证了"角色降级必然连带移除高权限组"，避免出现角色已降级但组权限仍残留的权限泄漏窗口。

与 Access Control 的衔接：在自定义组上配置权限

自定义组本身只是一层"容器"，真正的权限内容在Groups 页面的两个 Tab中配置：

1. Permissions（组级权限）：对整类资源做粗粒度授权，主要包括：

2. Granular access（精细访问控制）：对单个资源做细粒度授权，支持"所有资源"或"自定义选择"两种范围：

• Apps：Edit（可编辑/构建所选应用，适合 Builder）或View（仅查看已发布版本，适合 End-user），并支持Hide from dashboard（从仪表盘隐藏、仅 URL 可访问）；
• Data Sources：Configure（可查看并编辑数据源配置，适合管理员）或Build with（可在应用/工作流中使用该数据源创建查询，适合开发者）；
• 切换Granular accessTab 后点击+ Add permission，选择资源类型（App / Data source）、命名并配置权限后点击Add即可完成授权。

完整配置步骤与权限含义说明见 Access Control，该文档同时指出：精细访问控制必须通过自定义组来配置，这正是自定义组在 RBAC 体系中不可替代的原因。

从资源模型看，前端 constants.js 将可授权的资源类型枚举为app（应用）、data_source（数据源）、workflow（工作流）、folder（应用文件夹）、module（模块）、workflow_folder、module_folder七类，对应后端granular_permissions与各类group_*关联表，权限配置的覆盖面随着版本迭代持续扩展。

源码级验证：一组操作对应的完整调用链

为便于开发者深入源码验证，这里汇总本文涉及操作的核心实现位置：

值得注意的工程细节：创建、删除、复制等操作都通过RequestContext.setLocals写入审计日志（Audit Logs），这意味着工作区管理员可以在审计记录中追溯每一次组变更的操作用户、资源与时间，满足企业内部合规审计需求。

总结

自定义用户组是 ToolJet 权限体系中连接"角色"与"具体资源"的桥梁：

• 创建 / 删除 / 复制三个高频操作都集中在Workspace Settings > Groups，仅限 Admin 操作，且复制功能可在秒级内复刻成员、权限与应用授权；
• 继承与覆盖规则保证了权限模型的一致性与安全性：权限叠加取最高值、角色升级自动同步、角色降级自动清理高权限组，无需手工干预；
• 结合Access Control的 Permissions 与 Granular access 两个维度，管理员可以精确回答"谁能建应用""谁能看销售报表""谁能配置数据库连接"等问题。

无论是按团队隔离应用（HR / Sales 场景）、按项目搭建临时协作组，还是为外部协作者划定最小权限范围，自定义组都是首选的管理手段。更多权限细节可继续阅读 Access Control 与 用户角色 两篇文档。

【免费下载链接】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