ToolJet 数据源（Data Sources）完全指南：从连接到共享、权限与底层实现

ToolJet 是一个用于构建内部工具、仪表盘、业务应用、工作流与 AI Agent 的企业级应用生成平台。数据源（Data Sources）是其中的核心概念之一：它让应用能够从数据库、外部 API 或各类服务中拉取数据，也能将数据推送回这些系统。本文将完整讲解 ToolJet 数据源的类型划分、数据源管理器的用法、添加与配置流程、默认数据源、作用域（local/global）以及基于用户组的权限体系，并结合本仓库的源码（实体定义、服务层、权限守卫）剖析其底层实现，让你既会"用"也能"懂"。

什么是 ToolJet 数据源

数据源（Data Source）是 ToolJet 应用与世界交互的桥梁。官方概念文档将其定义为：

Data sources are pivotal as they enable us to fetch and send data to and from different sources including databases, external APIs, or services.

翻译过来即是：数据源使我们能够从数据库、外部 API 或服务等不同来源获取数据并发送数据。一旦某个数据源在工作空间内完成配置，它就可以被该工作空间内的所有应用共享——这是 ToolJet 数据源体系最重要的设计原则之一：连接一次，处处可用。

在 ToolJet 的运行时链路中，数据源并不直接执行查询，而是作为**连接定义（connection definition）**存在：它保存了目标系统的类型（kind）、凭证与连接选项，供查询（Query）在执行时引用。这一点可以从本仓库的数据源实体中清晰地看到，下文"源码级原理"一节会展开说明。

数据源的类型与数据源管理器

除了 ToolJet 自带的**内置数据库（ToolJet Database）**之外，ToolJet 还支持大量外部数据源，大致可以分为三大类：

• 数据库（Databases）：如 PostgreSQL、MySQL、MongoDB、Redis、Snowflake、BigQuery、ClickHouse 等；
• 外部 API（External APIs）：如 REST API、GraphQL、OpenAPI 等；
• 服务（Services）：如 Slack、Stripe、SendGrid、Twilio、Google Sheets、S3 等 SaaS 与云服务。

为统一管理这些连接，ToolJet 提供了数据源管理器（Data Source Manager）。它的打开方式非常简单：在 App Builder（应用构建器） 的左侧边栏中，点击 Data Sources 按钮即可打开。

从源码结构看，前端的数据源管理能力分布在 frontend/src/AppBuilder 的多个模块中，例如 LeftSidebar/leftSidebarConstants.js 定义了侧边栏的菜单项，QueryManager/Components/DataSourcePicker.jsx 与 DataSourceSelect.jsx 负责查询面板中数据源的选择与切换，而 _stores/slices/dataSourceSlice.js 则管理了数据源在全局状态中的存储。

添加并配置一个数据源

在 ToolJet 中添加数据源的体验"就像填写一张表单一样简单"。标准流程如下：

1. 点击 App Builder 左侧边栏中的 Data Sources 按钮，打开数据源管理器；
2. 浏览或搜索目标数据源；
3. 将鼠标悬停在目标数据源上，点击出现的 Add 按钮；
4. 在弹出的表单中填入连接所需的凭证（如主机地址、端口、用户名、密码、API Key 等）。

在 Dashboard（仪表盘）侧，也可以从左侧边栏直接进入 Data Sources 页面完成同样的操作。该页面在 ToolJet 2.3.0 及以上版本可用，页面左侧按类别列出数据源（Databases、APIs、Cloud Storages、plugins 等），点击某一类别即可看到可用的数据源列表，悬停后同样出现 Add 按钮。

数据源添加完成后，还需要填写配置信息以建立连接。需要注意：在付费计划中，必须完成配置的录入与保存，数据源才能跨多个环境（multiple environments）使用。

随后回到 Dashboard 新建应用，刚刚添加的数据源会出现在查询面板（Query Panel）的 Available data sources 区域中，既可用于新建应用，也可用于已有应用。若同一数据源建立了多条连接，在创建查询时还可以在同一数据源的不同连接之间切换。

关于所有兼容数据源及其详细配置说明，请参阅仓库中的 Datasource Catalog（数据源目录），其中按类别收录了全部数据源的设置指南；对应插件源码与清单则分布在 plugins/packages（核心数据源）与 marketplace/plugins（市场插件）目录下，例如 postgresql、mysql、restapi、slack、stripe、openai 等。

每个应用默认内置的四个数据源

在 ToolJet 的每个应用中，默认就会提供 4 个开箱即用的数据源，无需任何额外配置：

数据源	用途	仓库文档
ToolJet Database	ToolJet 内置数据库，开箱即用的数据存储	tooljet-db/tooljet-database.md
RestAPI	通过 REST 协议调用任意 HTTP 接口	data-sources/restapi.md
Run JavaScript Query	在应用内直接运行 JavaScript 逻辑	data-sources/run-js.md
Run Python Query	在应用内直接运行 Python 逻辑	data-sources/run-py.md

这 4 个默认数据源保证了每个新建应用都能立即"跑起来"：既可以直接读写内置数据库，也可以通过 REST API 对接外部系统，还能用 JS/Python 做数据处理与转换，再配合查询与动作（Actions）编排出完整的业务逻辑。

数据源的作用域：local 与 global

理解作用域（Scope）是掌握 ToolJet 数据源模型的关键。从本仓库的数据源实体定义 server/src/entities/data_source.entity.ts 可以看到：

@Column({ type: 'enum', enumName: 'scope', enum: ['local', 'global'], default: 'local' })
scope: string;

每个数据源都有 scope 字段，取值为：

• local（本地）：数据源连接只存在于创建它的那个应用版本内，属于旧版本 ToolJet（2.3.0 之前）的默认行为；
• global（全局）：数据源提升为工作空间级共享连接，可被该工作空间下的所有应用复用。

旧版本应用的迁移：把 local 改为 global

对于在 ToolJet 2.3.0 之前版本创建的应用，数据源连接是在单个应用内部建立的。为保持向后兼容，ToolJet 提供了修改数据源作用域的能力，将其升级为全局数据源：

1. 在 App Builder 的左侧边栏中，可以看到该应用的数据源管理器；
2. 将鼠标悬停在已连接的数据源旁，打开 kebab 菜单（⋮），选择 change scope（修改作用域）；
3. 修改为 global 后，左侧边栏中的数据源管理器会消失，该数据源会出现在查询面板的 Global Data Sources（全局数据源）之下；
4. 此后，你可以从 Dashboard 的 Data Sources 页面对该数据源进行统一配置与维护。

这一设计也解释了为何 Dashboard 侧的 Data Sources 页面在 2.3.0 版本才引入——它正是为了承接从"应用内管理"向"工作空间级管理"演进后的新形态。

数据源权限：谁可以创建、删除、查看与编辑

数据源权限的配置权限仅保留给工作空间内的 Admins（管理员）和 Super Admins（超级管理员）。配置入口为：Workspace Settings（工作空间设置）→ Groups Settings（组设置）。

权限分为两个维度：

维度一：工作空间内数据源的创建与删除

权限	说明
Just Create（仅创建）	可添加新数据源并修改已有数据源；悬停已连接数据源时不会出现删除按钮
Just Delete（仅删除）	可从工作空间移除已连接的数据源；悬停已连接数据源时会显示删除按钮
Both Create and Delete（创建与删除）	既能添加新数据源，也能移除已连接的数据源
Neither Create nor Delete（两者皆无）	无法从 Dashboard 访问 Data Sources 页面；若尝试通过 URL 直接访问，会弹出错误提示（error toast）

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

权限	说明
View（查看）	用户组可以连接其被授权的数据源，但不能更新这些数据源的凭证
Edit（编辑）	用户组可以更新已授权数据源的凭证

在源码层面，这套权限体系由 server/src/modules/data-sources/ability 中的能力（ability）定义与 guard.ts 守卫共同实施，服务层在返回数据源列表时也会通过 userPermissions 过滤用户可访问的连接（见下文 allGlobalDS 调用）。

源码级原理：数据源在后端是如何建模与查询的

实体模型

数据源的核心实体定义在 server/src/entities/data_source.entity.ts，对应数据库表 data_sources。除 scope 外，它还包含以下关键字段：

• id：UUID 主键；
• name：数据源名称；
• kind：数据源类别（如 database、api、workflows 等，用于区分默认数据源类型）；
• type：枚举类型，取值为 STATIC、DEFAULT、SAMPLE，默认 DEFAULT——其中 SAMPLE 对应 ToolJet 自带的示例数据源（如 Sample Database）；
• plugin_id：关联到具体的插件（Plugin）实体，插件携带该数据源的图标、manifest（清单）与 operations（操作定义）；
• organization_id：所属工作空间（org）ID；
• is_dummy：是否为占位/虚拟数据源；
• 关联关系：通过 data_source_group_permissions 关联用户组权限，通过 dataSourceVersions 支持按版本管理连接配置，通过 dataQueries 反向关联基于该数据源创建的所有查询。

特别值得注意的是 @AfterLoad() 钩子与 apps 的多对多关联，它体现了数据源与"应用版本"的绑定历史；而 dataSourceVersions（数据源版本实体 data_source_version.entity.ts）则支撑了 Git 同步/分支场景下不同分支拥有独立连接配置的能力。

服务层

服务层实现位于 server/src/modules/data-sources/service.ts 的 DataSourcesService，其职责包括：

• getForApp：返回当前应用可用的数据源。它通过 dataSourcesRepository.allGlobalDS(...) 按用户的权限与组织 ID 过滤全局数据源；当 shouldIncludeWorkflows 为 false 时，还会把 kind 为 workflows 的默认数据源从结果中剔除；
• getAll：返回 Data Sources 页面所需的完整数据源列表，支持按 environmentId（环境）、branchId（分支）筛选，并且只会返回 DEFAULT 与 SAMPLE 类型的数据源；对于插件型数据源，会解析其 iconFile、manifestFile、operationsFile（在迁移后这些文件内容以二进制形式存储，见 1735689600000-MigrateJsBundleContentToBinary.ts），对于 openapi 类型则单独解构 options 中的 spec 字段。

从这些实现可以看到：数据源是"工作空间级 + 插件驱动 + 权限过滤"的共享资源——前端拿到的数据源列表，实际是服务端基于用户权限、所属组织、当前环境/分支三重维度过滤后的结果。

插件机制

不同类型的数据源在 ToolJet 中统一由**插件（Plugin）**承载。每个插件包（见 plugins/packages 与 marketplace/plugins）都包含：

• manifest 清单：声明数据源类型、支持的认证方式与连接选项（schema）；
• operations 定义：声明该数据源支持的操作（如查询、测试连接）；
• 前后端入口：分别用于在构建器中渲染配置表单（前端）与在服务端执行连接/查询（后端）。

服务端的 services/plugin-selector.service.ts 负责根据数据源的 plugin 信息选择对应的插件实现，而 util.service.ts 提供参数解析等通用能力。也就是说，新增一种数据源本质上是新增一个插件包，这正是 ToolJet 数据源生态能够快速扩展的根本原因。

小结

回顾全文，ToolJet 数据源体系可以概括为四个要点：

1. 一次配置、处处共享：数据源在工作空间级管理，配置完成后可被该工作空间的所有应用复用；
2. 类型丰富、插件驱动：内置数据库之外，数据库、API、云存储与各类服务均由插件承载，可在 Datasource Catalog 中按需选用并查看配置说明；
3. 作用域可控：local 与 global 两种作用域，配合旧版本应用的 "change scope" 迁移能力，让历史应用也能平滑升级到共享数据源模型；
4. 权限精细：Admins/Super Admins 可按用户组授予"创建/删除"与"查看/编辑"两类权限，由后端能力守卫在数据源列表查询时强制执行。

无论是构建一个简单的内部工具，还是对接企业核心系统的工作流应用，理解数据源的类型、作用域与权限模型，都是高效使用 ToolJet 的第一步。