企业官网建设流程全解析

ToolJet 数据源（Data Sources）指南：工作区级连接、默认数据源、权限控制与旧版作用域迁移

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

数据源（Data Sources）是 ToolJet 中把外部数据（数据库、REST API、云存储、第三方服务等）接入工作区的统一连接层：连接一旦在工作区建立，即可被该工作区下所有应用共享复用。本文以官方 Data Sources: Overview 文档为主线，完整梳理数据源的概念模型、连接步骤、默认数据源、用户组权限，以及 ToolJet 2.3.0 之前旧版本应用数据源的作用域迁移流程，并结合本仓库server与frontend源码对底层模型进行印证，帮助读者既会操作、也懂原理。

数据源是什么：从“应用内连接”到“工作区级共享”

ToolJet 中的数据源负责从数据库、外部 API 或各类服务中拉取数据、向其推送数据。其核心设计在于连接粒度是工作区（Workspace）级别：一次连接建立后，该工作区中的任意应用（App）都能复用，而无需在每个应用里重复配置。

这一点可以从服务端实体与模块文档中得到印证。server侧的数据源模块（见>类别关键标识说明（来自源码模块文档）全局数据源 Global Data Sourcescope = 'global'工作区级连接，跨应用共享，受细粒度权限管控，是常规形态应用级数据源 App-Level Data Sourcescope = 'local'旧版遗留的应用内连接（UI 称为 app-level），可通过作用域变更迁移为 global，模块本身不再新建 local 数据源示例数据源 Sample Data Sourcetype = 'sample'自动创建、指向共享sample_db的 Postgres 数据源，不可删除，列表接口会隐藏其配置静态/默认数据源 Static/Defaulttype = 'static'kind 限定在restapi、runjs、runpy、tooljetdb、workflows，每个工作区存在一行{kind}default，无用户可编辑配置

这些枚举在 constants/index.ts 中被集中定义：DataSourceTypes = { STATIC, DEFAULT, SAMPLE }、DataSourceScopes = { LOCAL, GLOBAL }。而 data_source.entity.ts 中的data_sources表实体则记录了每个连接的物理字段：name、kind（连接器标识，即插件名）、type（static/default/sample）、scope（枚举local/global，默认local）、organization_id、plugin_id、app_version_id等。也就是说，一次数据源连接本质上是挂在某个组织（工作区）下的资源记录，再通过关联表与用户组、应用、环境产生关系。

注意：Data Sources 页面仅在 ToolJet 2.3.0 及以上版本可用。在 2.3.0 之前的版本中，数据源连接是直接在应用内部建立的，本文最后一部分会专门说明这类应用的迁移路径。

连接数据源：把新连接加入工作区

在 ToolJet 中连接一个数据源有两种入口，但殊途同归——最终都落在工作区级的数据源管理上。官方文档给出的流程如下：

入口一：从查询面板进入。从 Dashboard 新建一个应用后，在底部查询面板中点击+ Add new按钮；随后同样会进入数据源选择界面。

入口二：从 Dashboard 侧边栏直接进入 Data Sources 页面。这是更直接的方式，无需先建应用。

进入 Data Sources 页面后：

1. 页面左侧按类别展示可用的数据源，包括Databases（数据库）、APIs（接口）、Cloud Storages（云存储）以及各类plugins（插件/市场插件）。点击某个类别即可查看该类下的数据源列表。
2. 鼠标悬停到想要接入的数据源上时，会出现Add按钮；点击后将所选数据源接入工作区。
3. 数据源加入后，需要填写连接配置信息（如主机地址、端口、凭据、认证方式等）。

   针对付费套餐（paid plans）：必须完成配置填写与保存，该连接才能跨 多环境 可用——即配置是按环境保存的。

4. 配置完成后回到 Dashboard 新建应用，新添加的数据源会出现在查询面板的Available data sources区域中。无论是已有应用还是新应用，都可以使用该连接。
5. 最后即可基于该数据源创建查询（Query）。当同一个数据源下建立了多个连接时，在查询中可以切换使用同一数据源的不同连接。

源码视角：连接、环境与加密配置

从实现上看，上述第 3 步“填写并保存配置”并不只是存一个 JSON。根据 />

在源码层面，这四类默认数据源属于前文提到的Static/Default 数据源：它们的 kind 由常量DefaultDataSourceKinds定义。需要留意的是，当前仓库 constants/index.ts 中该常量实际包含五种 kind：

export const DefaultDataSourceKinds: DefaultDataSourceKind[] = ['restapi', 'runjs', 'runpy', 'tooljetdb', 'workflows'];

即除官方文档中列出的 RestAPI、Run JavaScript（runjs）、Run Python（runpy）、ToolJet Database（tooljetdb）之外，源码层面还把workflows一并纳入静态默认数据源机制。这些默认数据源在每个工作区存在一行固定的{kind}default记录，属于系统内置、无用户可编辑配置的静态资源（可对照 AGENTS.md 中的描述）。如果你在界面上还看到“Sample data sources（示例数据源）”，那是另一套机制：由SampleDataSourceService自动创建并指向共享sample_db的 Postgres 示例源（参考 sample-ds.service.ts 与 sample-data-sources.md），每个环境都会被写入，且不可被删除。

数据源的用户组权限：谁能建、谁能删、谁能看、谁能改

数据源是工作区共享资源，因此 ToolJet 对其权限做了区分管理。修改数据源权限是 Admin 与 Super Admin 的专属权利。配置入口位于Workspace Settings → Groups Settings（工作区设置 → 组设置）。

官方文档给出了两组权限维度，下面完整列出。

维度一：数据源的创建与删除

维度二：对已授权数据源的查看与编辑

源码视角：权限如何生效

从服务端实现看，这套权限并不只是 UI 上的按钮显隐。server/src/modules/data-sources/repository.ts中的allGlobalDS()是经过权限过滤的全局数据源列表查询（按scope = 'global'过滤，并 JOIN 数据源组权限等关联表）；ability/FeatureAbilityFactory则依据细粒度的GLOBAL_DATA_SOURCE权限（如isAllConfigurable、usableDataSourcesId）生成 CASL 规则，决定当前用户在接口层面能列出、能配置哪些数据源。数据源与用户组的绑定关系同样落库在实体中，例如 data_source_group_permission.entity.ts 与 data_sources_group_permissions.entity.ts。需要说明的是，根据模块文档，这类细粒度数据源权限属于 license 门控能力（granular permissions 需要相应授权），实际可用范围请以你所部署版本/套餐为准。

结论：“可创建/删除数据源”与“可查看/编辑某个数据源的配置”是两套正交的权限。前者决定用户能否在工作区层面增删连接，后者决定用户能否使用某个已被授权给本组的连接，以及能否更新其凭据。两者都由管理员在组设置中为各用户组配置。

旧版本应用的数据源作用域迁移（ToolJet 2.3.0 之前）

在 ToolJet 2.3.0 之前的版本里，数据源连接是在单个应用内部建立的（即前文源码中scope = 'local'的 App-Level 数据源）。为了向后兼容，ToolJet 提供了把这类“应用内数据源”转换为“全局数据源”的迁移能力。官方文档给出的操作如下：

1. 打开使用 2.3.0 之前版本创建的应用，在App Builder 的左侧边栏可以看到数据源管理器（data source manager）。
2. 在已连接数据源旁边找到更多操作菜单（kebab menu），从中选择change scope（更改作用域）。
3. 作用域切换为 global（全局）后，左侧边栏的数据源管理器会被移除；该数据源出现在**查询面板的 Available data sources（可用数据源）**区域。此后，你可以直接在Dashboard 的 Data Sources 页面对该连接进行配置。

对应地，迁移后该数据源就升级为工作区级全局数据源，可被工作区中的其他应用复用。

源码视角：作用域迁移是单向的

作用域变更在服务端对应POST :id/scope路由与changeScope服务方法：

• controller.ts 注册了@Post(':id/scope')端点并调用dataSourcesService.changeScope(dataSourceId, user)；
• service.ts 实现changeScope，其能力（SCOPE_CHANGE）被登记在 constants/index.ts 的FEATURE_KEY中，且根据 ability/index.ts 的注释，只有 Builder 角色可以执行作用域变更。

同时需要注意两个限制（参考模块文档）：一是作用域迁移是单向的（local → global），一旦转换为全局数据源便无法再转回应用级；二是存在依赖查询的数据源无法删除（删除前会通过findQueriesLinkedToDatasource校验是否还有查询引用），示例数据源则始终不可删除。如果旧应用中同时存在多处需要整理的本地数据源，可以参阅仓库中的迁移专题文档 local-data-sources-migration.md，了解本地/应用级数据源的完整迁移背景。

小结与进一步阅读

围绕 ToolJet 的数据源机制，可以提炼出三条关键设计：

1. 连接是工作区级资源：以scope、type、kind三个维度建模（global/local、default/sample/static、连接器插件类型），一次配置、全工作区应用共享；
2. 配置与权限分层管理：连接配置按环境加密存储，数据源在使用上受“创建/删除 + 查看/编辑”两套用户组权限约束；
3. 旧版应用可平滑迁移：2.3.0 之前应用内的 local 数据源可通过 change scope 一次性升级为 global，由 Dashboard 统一管理。

若要进一步深入各数据源的使用细节，可继续阅读本仓库中的下列文档：

• ToolJet Database 使用文档
• RestAPI 连接器配置 与 REST API 查询指南
• Run JavaScript Query 与 Run Python Query
• 示例数据源说明
• 应用内数据源迁移专题
• 角色权限与数据源访问控制
• 多环境（multi-environment）配置说明

如果你希望从代码层面进一步了解数据源的完整生命周期（创建/更新时的配置加密、环境写入、OAuth2 授权、分支与版本、连接测试、查询执行等），可直接阅读server侧的 contenteditable="false">【免费下载链接】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