ToolJet 数据源接入完全指南从添加数据源到加密存储与连接验证【免费下载链接】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 中数据源Data Source是连接应用与外部数据库、API、云存储及 AI 服务的桥梁。本指南以官方教程《Adding a data source》为骨架完整讲解如何在应用构建器中添加数据源、填写凭据、验证连接并保存配置同时结合仓库源码深入剖析 ToolJet 的加密存储机制与连接测试调用链。读完本文你将掌握 ToolJet 数据源添加的完整实操流程并理解其底层实现原理。核心前提数据源是应用级别App Level的资源在开始添加数据源之前需要先明确一个关键概念数据源在应用级别创建而不是工作区Workspace级别。这意味着每个 ToolJet 应用拥有自己独立的数据源列表。同一个 PostgreSQL 数据库如果要在两个不同的应用中使用需要分别在这两个应用中各添加一次。这一设计保证了应用之间的配置隔离——修改一个应用的数据库连接配置不会影响其他应用。从源码结构看数据源确实与具体的应用版本App Version和环境Environment绑定DataSourceManager.jsx 中创建数据源时会同时携带app_id、app_version_id与environment_id参数由后端 util.service.ts 持久化到数据源版本与环境的关联表中从实现层面印证了数据源隶属于应用这一设计。第一步打开 Datasource Manager 并点击 Add datasource在 ToolJet 应用构建器App Builder中**Datasource Manager数据源管理器**位于左侧边栏。添加新数据源的入口非常直观打开目标应用进入应用构建器在左侧边栏中找到Datasource Manager点击Add datasource按钮。点击后界面会弹出数据源选择面板等待你选择希望添加的数据源类型。数据源的类型分组从 DataSourceComponents/index.js 的源码可以看到内置数据源会按照 manifest插件清单中声明的type字段被自动归类到不同分组分组判定条件manifesttype典型示例Databases数据库databasePostgreSQL、MySQL、MongoDB、Snowflake 等APIs接口apiREST API、GraphQL、gRPC、OpenAPI 等Cloud Storages云存储cloud-storageAWS S3、GCS、MinIO 等AI人工智能服务aiOpenAI、Gemini、Anthropic 等Plugins插件由已安装的市场插件动态加载由 pluginsService.findAll() 从服务端获取此外面板中还会展示常用数据源Commonly Used Data Sources快捷入口并支持关键词搜索过滤。如果没找到想要的数据源面板底部还提供了 Suggest建议入口可以将你需要的集成反馈给团队。第二步选择数据源并填写凭据以 PostgreSQL 为例本教程以PostgreSQL为例。在数据源列表中选中 PostgreSQL 后界面会展开一个凭据填写表单你需要提供 PostgreSQL 数据库的连接信息。PostgreSQL 连接参数详解PostgreSQL 数据源的表单结构由插件 manifest 文件 plugins/packages/postgresql/lib/manifest.json 定义。该文件使用 JSON SchemaJSON-Schema draft 2020-12描述所有配置项、默认值、校验规则与 UI 交互方式。核心参数如下参数说明默认值是否必填connection_type连接方式手动填参数manual或使用连接串stringmanual是host数据库主机地址localhost是manual 模式port数据库端口5432是manual 模式database数据库名称—否username数据库用户名—是manual 模式password数据库密码—否但通常需要ssl_enabled是否启用 SSL/TLS 加密连接true否ssl_certificate证书类型ca_certificate/self_signed/nonenone启用 SSL 时必填ca_cert/client_key/client_cert/root_cert对应 CA 证书、客户端密钥、客户端证书、根证书内容—视证书类型而定connection_string编码后的连接串string 模式形如postgres://username:passwordhostname:port/database?sslmoderequire—string 模式必填allow_dynamic_connection_parameters是否允许在查询运行时动态覆盖 host 与 databasefalse否ssh_enabled是否通过 SSH 隧道连接enabled/disableddisabled否ssh_host/ssh_port/ssh_usernameSSH 服务器地址、端口默认22、用户名—启用 SSH 时必填ssh_auth_typeSSH 认证方式private_key/passwordprivate_key启用 SSH 时必填ssh_private_key/ssh_password/ssh_passphraseSSH 私钥、密码、口令—视认证方式而定两种连接方式根据 manifest 中的allOf条件约束逻辑PostgreSQL 支持两种连接方式手动连接Manual connection逐项填写 host、port、database、username、password 等字段连接串Connection string直接在connection_string字段中粘贴编码后的连接串例如postgres://admin:p%40sswordlocalhost:5432/my%23db。注意特殊字符需要使用 URL 编码例如编码为%40、#编码为%23。密码字段支持 Secret 引用manifest 中密码字段的help_text标注为Supports secrets (e.g.,{{secrets.db_password}})即密码等敏感字段可以直接引用工作区环境变量Secrets例如{{secrets.db_password}}从而避免在数据源配置中硬编码明文密码。后端在连接测试与执行查询时会通过 resolveValue() 将{{constants|secrets|globals.server.*}}占位符解析为实际值。第三步理解加密字段的底层机制原文档指出标记为encrypted的字段会在保存到 ToolJet 数据库之前进行加密。这是数据源安全模型的核心值得深入理解其实现。哪些字段会被加密以 PostgreSQL 插件为例manifest 中tj:encrypted数组明确列出了所有需要加密的字段tj:encrypted: [ password, ca_cert, client_key, client_cert, root_cert, connection_string, ssh_private_key, ssh_password, ssh_passphrase ]可见所有敏感凭据类字段——数据库密码、各类证书私钥、连接串、SSH 凭据——都会被加密存储。加密存储的实现方式从服务端源码 util.service.ts 的parseOptionsForCreate()方法可以看出加密并不是简单地对值做对称加密后存回 options而是采用凭据隔离存储方案前端将表单中每个字段连同encrypted标记一起提交服务端遍历选项对标记为encrypted的字段调用CredentialService.create(value)将明文存入独立的credentials凭据表由加密服务负责加解密数据源的 options JSON 中只保留{ credential_id: id, encrypted: true }不再保存任何明文或密文值。服务端 AGENTS.md 中对此有明确描述Options are encrypted at rest: values markedencryptedare stored in thecredentialstable viaCredentialsService; the options JSON keeps only{ credential_id, encrypted: true }. Decryption happens inparseSourceOptionsat query/test time only.——即解密只发生在查询执行或连接测试的瞬间列表 API 永远不返回解密后的值。这种设计的价值在于即使数据源 options 被意外导出例如通过 Git 同步泄露的也只是凭据 ID 而非真实密码真实凭据始终安全地存放在加密的 credentials 表中。第四步设置数据源名称每个数据源的名称在应用内必须是唯一的App 级别唯一且名称可以随时修改。在新建数据源时名称默认取自所选数据源类型如PostgreSQL点击表单顶部的数据源名称即可编辑如果名称留空前端会提示The name of datasource should not be empty见 DataSourceManager.jsx 的createDataSource()逻辑保存时后端还会通过generateUniqueName()与ensureUniqueActiveNameForUpdate()见 util.service.ts保证同一应用/版本内名称唯一避免多个同类型数据源重名导致查询歧义。建议为数据源取一个语义化名称例如prod-postgres、analytics-db因为在后续创建查询时你需要在查询编辑器中通过这个名称选择要操作的数据源。第五步Test Connection 验证连接填写完凭据后点击Test Connection按钮验证连接是否可用。文档提示验证可能需要花费一点时间请耐心等待。前端如何发起测试测试连接由前端组件 TestConnection.jsx 实现点击按钮后按钮文案变为 Testing connection... 并进入禁用态前端组装请求体{ kind, options, plugin_id, environment_id, dataSourceId }调用datasourceService.test()若后端返回status: ok弹出 Test connection verified 成功提示若失败则弹出 Test connection could not be verified 并触发onConnectionTestFailed回调展示错误详情。后端如何执行测试服务端testConnection的实现位于 util.service.ts 的testConnection()方法调用链为controller.testConnection()→dataSourcesService.testConnection()→dataSourcesUtilService.testConnection()→ 插件服务实例的testConnection(sourceOptions)。关键步骤包括解析常量与 Secrets遍历 options将{{constants.xxx}}、{{secrets.xxx}}、{{globals.server.*}}占位符替换为真实值解析凭据对于带credential_id的加密字段调用credentialService.getValue(credentialId)解密得到真实密码调用插件连接测试通过插件服务选择器pluginsServiceSelector.getService()拿到对应数据源类型的服务实例并调用其testConnection()结果归一化如果插件未实现testConnection方法会抛出NotImplementedException任何异常都会被捕获并转换为{ status: failed, message: ... }结构返回给前端展示。这也解释了为什么不同数据源插件的测试行为不同——连接测试的底层逻辑完全由各插件自己的testConnection()实现可在plugins/packages/*/lib中查看各插件源码。第六步保存数据源连接验证通过后点击保存Save按钮完成数据源的创建。保存时名称、kind类型、插件 ID、options、app_id、app_version_id、environment_id、scope 等参数会被一并提交后端parseOptionsForCreate()会对加密字段执行凭据隔离存储见上文第三步保存成功后前端会弹出 Data Source Added 成功提示新数据源立即出现在 Datasource Manager 列表中可供当前应用创建查询使用。云端部署的注意事项IP 白名单:::tip 提示 如果你使用的是ToolJet Cloud且你的数据源数据库/API不对公网开放请在创建数据源时显示的提示中将 ToolJet 的 IP 地址加入白名单。 :::这是因为 ToolJet Cloud 托管在云端其服务器需要通过公网访问你的数据源。如果数据源位于防火墙或安全组之后必须放行 ToolJet 展示的出口 IP否则Test Connection与查询执行都会因网络不通而失败。自托管Self-hosted部署则不存在此问题——ToolJet 与数据源通常位于同一内网可直接访问。添加完成后的下一步数据源保存成功后它就成为当前应用内查询Query的数据后端在应用构建器中打开Query Manager查询管理器选择刚添加的数据源例如prod-postgres编写 SQL 查询或其他操作PostgreSQL 支持查询、插入、更新、删除等操作将查询结果绑定到页面上的表格、图表等组件完成应用搭建。总结添加数据源是使用 ToolJet 构建内部工具的第一步也是连接数据世界的关键环节。回顾本文核心要点作用域数据源是应用级别的资源每个应用独立维护自己的数据源列表入口应用构建器左侧边栏的 Datasource Manager →Add datasource类型丰富数据库、API、云存储、AI 服务与市场插件分类清晰支持搜索凭据填写以 PostgreSQL 为例支持手动配置与连接串两种方式并支持 SSL 证书、SSH 隧道与 Secrets 引用等高级配置加密存储标记为encrypted的字段由CredentialsService存入独立凭据表options 中仅保留credential_id解密只发生在测试与查询执行的瞬间连接验证Test Connection会解析常量与凭据后调用对应插件服务实例的testConnection()完成真实连通性测试云环境ToolJet Cloud 用户需将 ToolJet 出口 IP 加入数据源白名单。掌握这些步骤与原理你就能安全、高效地为任何 ToolJet 应用接入所需的数据源为后续的查询开发与界面搭建打下坚实基础。【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考