企业官网建设流程全解析

ToolJet 访问控制（Access Control）完全指南：从资源级权限到细粒度（Granular）权限配置

【免费下载链接】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 作为企业级内部工具与应用构建平台，其访问控制体系决定了谁能创建、删除、查看和编辑工作区内的应用（Apps）与数据源（Data Sources）等核心资源。本文基于官方文档并结合作品仓库中的服务端源码实现，系统讲解 ToolJet 的两层访问控制模型——资源级权限（Permissions）与细粒度访问控制（Granular Access Control），涵盖完整配置步骤、权限含义、底层数据模型与验证逻辑，帮助你在自托管或云端实例上落地精确、安全的多团队权限治理方案。

访问控制概述

ToolJet 的访问控制以「用户组（Group）」为授权单元。管理员把用户划分到不同的组，再为每个组配置不同资源的权限，从而实现"组内共享、组间隔离"的管理目标。整体上可以分为两个层次：

1. 资源级权限（Permissions）：面向应用、数据源、文件夹、工作区常量/变量等资源，配置创建（Create）与删除（Delete）等粗粒度操作权限。
2. 细粒度访问控制（Granular Access Control）：面向单个或多个具体的应用、数据源实例，配置查看（View）、编辑（Edit）、配置（Configure）、构建（Build with）等精细权限。

值得注意的是，ToolJet 的细粒度访问控制必须依托于自定义组（Custom Groups）才能生效，默认内置组无法直接使用该能力，详见下文。

资源级权限（Permissions）

资源级权限控制的是"用户组能否在工作区内新建或删除某类资源"。这些权限面向整类资源生效，属于粗粒度授权。

支持的资源与权限矩阵

说明：查看（view）与编辑（edit）类权限并不在资源级权限中配置，而是通过下文介绍的细粒度访问控制进行设置。

资源创建者的默认所有权

这里有一个容易被忽略但非常重要的规则：

:::info 资源所有者规则 如果用户拥有 Create 权限并创建了一个资源，那么该用户自动成为该资源的所有者，默认获得与该资源相关的全部权限。 例如：用户创建了数据源 A，则默认拥有对数据源 A 的 Configure（配置）与 Build with（构建）访问权限。 :::

这条规则在底层代码中同样有印证——细粒度权限的创建逻辑（server/src/modules/group-permissions/services/granular-permissions.service.ts）在create流程中通过validateGranularPermissionCreateOperation校验组属性，并将资源权限与用户身份绑定，资源创建者自然获得对资源的完整控制权。

配置步骤

配置资源级权限需要Admin（管理员）角色，操作路径如下：

1. 点击仪表盘（Dashboard）左下角的设置图标（⚙️）。
2. 进入Workspace Settings（工作区设置）>Groups（组）。
   • 示例 URL：https://app.corp.com/nexus/workspace-settings/groups
3. 选择需要配置权限的组。
4. 切换到Permissions（权限）选项卡，勾选/配置所需的权限项（如 Create、Delete 等）。

完成配置后，该组内的所有用户即获得对应资源的创建、删除或更新能力。

细粒度访问控制（Granular Access Control）

细粒度访问控制是 ToolJet 权限体系的核心亮点：它允许你将访问权限精确到具体资源实例——例如只让 HR 组访问 HR 相关的 3 个应用，而不影响工作区内的其他应用。

细粒度权限的适用范围当前聚焦于Apps（应用）与Data sources（数据源）。它支持两种授予模式：

• 面向全部资源：将权限授予所有应用或所有数据源（包括未来新建的资源）。
• 面向指定资源：仅将权限授予你勾选的特定资源。

要使用细粒度访问控制，需要先创建自定义组。可参考 自定义组指南 完成组的创建。

应用的细粒度权限

针对应用，细粒度权限提供以下选项：

• Edit（编辑）：授予对所选中应用的编辑权限。拥有该权限的用户可以构建（build）或编辑（edit）被授权的应用。此权限应分配给构建者（Builders）或开发者（Developers）。
• View（查看）：拥有查看权限的用户可以查看所选应用的已发布版本（released version），并使用这些应用执行任务。该权限不允许用户编辑或修改应用，应分配给终端用户（End users）或消费方（Consumers）。
• Hide from dashboard（从仪表盘隐藏）：将所选应用从仪表盘中隐藏，使其仅能通过 URL 被拥有 View 权限的用户访问；拥有 Edit 权限的用户始终可以在仪表盘上看到该应用。
• All apps（所有应用）：将所选访问权限（Edit 或 View）授予工作区内的所有应用，包括之后新建的应用。
• Custom（自定义）：仅将所选访问权限（Edit 或 View）授予指定的应用。

从源码层面看，应用类细粒度权限的动作模型非常完整。在 server/src/modules/group-permissions/types/granular_permissions.ts 中，CreateAppsPermissionsObject定义了：

canEdit —— 是否可编辑 canView —— 是否可查看 hideFromDashboard —— 是否从仪表盘隐藏 canAccessDevelopment —— 是否可访问开发（Development）环境 canAccessStaging —— 是否可访问预发布（Staging）环境 canAccessProduction —— 是否可访问生产（Production）环境 canAccessReleased —— 是否可访问已发布版本 appType —— 应用类型（普通应用 / 工作流等） resourcesToAdd —— 具体授权的资源 ID 列表

也就是说，"Edit / View / Hide from dashboard" 在底层分别映射为canEdit、canView、hideFromDashboard布尔字段；而"All apps"与"Custom"两种模式则由isAll标志与resourcesToAdd（资源 ID 数组）共同表达——当isAll=true时授权面向全部资源，为false时则逐个罗列被授权的应用 ID。这为权限的审计与编程化管理提供了清晰的落点。

数据源的细粒度权限

针对数据源，细粒度权限提供以下选项：

• Configure（配置）：组内用户可以访问并编辑所选数据源的配置详情（如连接地址、凭证等敏感信息）。此权限应授予需要配置数据源的Admin 管理员用户。
• Build with（构建使用）：组内用户可以在应用（Apps）与工作流（Workflows）中使用所选数据源来创建查询（queries）。此权限应授予负责为应用或工作流编写查询的构建者（Builders）或开发者（Developers）。
• All data sources（所有数据源）：将所选访问权限（Configure 或 Build with）授予工作区内的所有数据源，包括之后新建的数据源。
• Custom（自定义）：仅将所选访问权限（Configure 或 Build with）授予指定的数据源。

在源码层，数据源权限的动作由DataSourcesGroupPermissionsActions描述（server/src/modules/group-permissions/types/granular_permissions.ts）：

canConfigure —— 对应 Configure（配置） canUse —— 对应 Build with（构建使用） canRunQuery —— 是否可运行查询（可选扩展）

其中canUse表示"可以在应用中构建查询使用该数据源"，canRunQuery则进一步控制是否允许执行查询——从实现细节上看，ToolJet 将"使用数据源建查询"与"运行查询"拆分为两个可独立控制的维度，便于在不同信任级别的用户之间做更细的授权。

细粒度权限的配置步骤

配置细粒度访问权限同样需要Admin（管理员）角色：

1. 点击仪表盘左下角的设置图标（⚙️）。
2. 进入Workspace Settings>Groups。
   • 示例 URL：https://app.corp.com/nexus/workspace-settings/groups
3. 选择需要配置细粒度访问权限的组。
4. 切换到Granular access（细粒度访问）选项卡，点击+ Add permission（添加权限）按钮。
5. 根据需求选择资源类型（Apps / Data source），为权限命名，配置所需权限项，点击弹窗底部的Add完成创建。

细粒度权限的底层数据模型

细粒度权限在后端并非一个简单的标志位，而是一组相互关联的实体。核心实体为GranularPermissions（对应数据库表granular_permissions），其定义见 server/src/entities/granular_permissions.entity.ts：

• id：UUID 主键；
• groupId：关联的用户组 ID；
• name：权限名称（非空，即你在界面中为权限填写的名字）；
• type：资源类型枚举（ResourceType），区分 App、Data source、Workflow、Folder、Module 等；
• isAll：是否面向全部资源（默认true）——这正是界面中"All apps / All data sources"与"Custom"两种模式的持久化差异；
• createdAt/updatedAt：创建与更新时间戳。

同时，该实体通过一对一关系（OneToOne，级联删除）挂载了三张明细表：

• AppsGroupPermissions（应用组权限）
• DataSourcesGroupPermissions（数据源组权限）
• FoldersGroupPermissions（文件夹组权限）

从这种"主表 + 类型化明细表"的设计可以看出，ToolJet 的细粒度权限是可扩展的：主表只记录"哪一组、什么类型、是否覆盖全部资源"，而具体到每个资源实例的canEdit、canView、hideFromDashboard等动作位则落在各自类型的明细表中。新增资源类型（如工作流 Workflows、模块 Modules）时无需改动主表结构，只需新增对应的明细实体即可。

此外，在权限创建的服务端入口GranularPermissionsService.create（server/src/modules/group-permissions/services/granular-permissions.service.ts）中可以看到完整的事务性流程：

1. 校验目标组确实属于当前组织（organizationId）；
2. 通过validateGranularPermissionCreateOperation校验操作合法性（如是否允许在该组上创建细粒度权限）；
3. 在数据库事务（dbTransactionWrap）内创建权限主记录与资源明细记录；
4. 通过licenseUserService.validateUser校验当前实例/许可证下的用户数上限；
5. 写入审计日志（Audit Logs），记录操作人、组织、资源 ID 与权限名称。

该流程体现了权限变更的安全边界：任何细粒度权限的增删都必须经过组织归属校验与许可证校验，并且全程留痕（审计日志），便于企业合规审计。

与自定义组的配合：继承与覆盖规则

细粒度访问控制必须建立在自定义组之上。在 自定义组指南 中，ToolJet 明确了以下继承与覆盖（Inheritance and Overrides）规则，它们同样适用于细粒度权限的解析结果：

• 用户继承其角色（Role）以及其所属所有自定义组的权限；
• 当用户被加入一个权限高于其当前角色的自定义组时，其用户角色会被自动升级以匹配更高的访问级别；
• 当用户的角色被降级到权限更低时，其会被自动移出那些提供高于新角色允许权限的自定义组；
• 当用户属于多个组时，其实际获得的权限取任意一个组所授予的最高级别权限。

这意味着细粒度权限的最终效果遵循"权限取并集、高者优先"的原则，管理员在规划组结构时应当注意避免无意的权限扩散——例如给某个组成员授予了某个应用的 View 权限，同时又让另一个更高权限的组包含同一成员，则该成员实际能以更高的权限访问该应用。

权限规划最佳实践

结合文档与源码实现，可以总结出以下在 ToolJet 中落地访问控制的建议：

1. 按团队/职能拆分自定义组：例如 HR、Sales、Finance，或者 Builder、End User，避免将所有用户放入单一组导致权限无法细分。
2. 构建者与终端用户分离：将应用的 Edit（构建/编辑）权限只授予 Builder/Developer 组；将 View（查看已发布版本）权限授予终端用户组，从源头杜绝非构建人员改动应用。
3. 数据源权限遵循最小化原则：Configure（可编辑连接配置与凭证）只授予需要管理数据连接的 Admin；普通构建者仅授予 Build with 即可；若存在仅需读数据的场景，可利用canRunQuery维度进一步收敛"运行查询"的权限。
4. 善用 All 与 Custom 的取舍：对于全工作区共享的资源（如公共数据源）使用"All data sources"模式，避免资源增长后频繁补授权；对于敏感或部门专属资源务必使用"Custom"模式逐一授权。
5. 利用"Hide from dashboard"控制可见性：需要将应用以 URL 形式分发给外部或低频用户时，可对该应用勾选"从仪表盘隐藏"，仅保留 View 权限入口。
6. 借助审计日志治理权限变更：由于细粒度权限创建/更新操作会写入审计日志，建议管理员定期回看日志，追踪"谁在何时为哪个组授予了哪些资源的权限"，防止权限漂移。

总结

ToolJet 的访问控制体系是一条清晰的"两层授权"链路：资源级权限（Permissions）负责粗粒度的 Create / Delete / Update 操作授权，细粒度访问控制（Granular Access Control）负责精确到单个应用、数据源实例的 View / Edit / Configure / Build with 授权。二者共同作用，配合自定义组的继承与覆盖规则，可以在同一个工作区内实现多团队、多角色的隔离与协作。

从实现角度，细粒度权限通过granular_permissions主表 + 类型化明细表（Apps / DataSources / Folders）持久化，由 granular-permissions.service.ts 在事务中完成创建并写入审计日志；isAll字段与resourcesToAdd数组则精确对应界面上"All / Custom"两种授权模式。掌握这些底层细节，可以帮助你在实际部署中更准确地预测权限行为，构建既灵活又可审计的企业级访问控制策略。

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