ToolJet Workspace Constants 与 Secrets 实战指南：环境隔离、加密存储与安全访问

ToolJet Workspace Constants 与 Secrets 实战指南环境隔离、加密存储与安全访问【免费下载链接】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/ToolJetWorkspace Constants工作区常量与 Secrets机密是 ToolJet 中用于维护应用一致性与安全性的核心机制它们在应用运行时保持不变既支持可复用值Global Constants的统一维护也为 API 密钥、数据库凭据等敏感信息提供加密存储。本文基于官方文档与仓库源码完整讲解两类常量的差异、环境级配置、创建与管理流程、{{constants.*}}/{{secrets.*}}引用语法以及从环境变量映射常量的进阶用法帮助你构建安全、可维护、多环境适配的 ToolJet 应用。什么是 Workspace Constants 与 SecretsWorkspace Constants 允许你预先定义一组值在整个工作区的应用之间复用从而保证一致性、便于集中更新并安全地存放敏感信息。工作区常量是工作区级别的它只在其创建所在的工作区内可见其他工作区无法访问。在 ToolJet 中常量分为两种类型Global Constants全局常量存放可复用的普通值例如 API URL、配置项等可在整个工作区的应用中一致使用。它们是在客户端解析的。Secrets机密常量专为 API 密钥、数据库凭据、加密密钥等敏感数据设计的安全存储类型。Secrets 在前端被掩码masked显示并以加密格式存储且是在服务端解析的不会暴露给客户端。注意Secret 常量不能在 RunJS 或 RunPy 查询中使用。从源码实现看常量与机密在服务端以加密形式落库。在 服务层实现 中create方法通过encryptSecret(organizationId, value)将值加密后再写入环境映射而读取时只有明确传入decryptSecretValue标志才解密 Secret 值否则统一返回**********掩码从底层保证了敏感值不泄露。两类常量的特性对照与使用边界特性Global ConstantsSecrets组件App Builder✅❌数据查询Data Queries*✅✅数据源Data Sources✅✅工作流Workflows✅Coming Soon数据库中加密存储✅✅前端掩码显示❌✅客户端解析✅❌服务端解析❌✅命名规范{{constants.constant_name}}{{secrets.secret_name}}使用时的两个关键限制Secret 常量不能用于 RunJS / RunPy 查询——这是出于安全考虑防止敏感值在自定义脚本执行上下文中被读取或外泄。Secret 常量只能作为单一 key 使用不能以组合 keycomposite key的方式使用。前端在解析查询参数时同样做了针对性处理在 queryPanel.js 中代码先匹配{{constants.}}语法并从结果中提取常量名再决定解析逻辑体现了客户端对 Global Constants 的显式支持路径。环境级配置一套常量适配多个环境Workspace Constants 的一大核心能力是环境级配置。你可以为同一个常量或 Secret在 development、staging、production 等不同环境中赋予不同的值。这对管理各环境不同的 API 密钥、数据库凭据、外部服务端点尤其重要。例如你可以为每个环境配置唯一的 API 密钥保证集成与安全性在不同阶段互不干扰。在服务端环境级取值由allEnvironmentConstants/getConstantsForEnvironment方法支撑见 organization-constants/service.ts每个常量通过orgEnvironmentConstantValues与多个环境appEnvironments建立一对多的值映射查询时按environmentId取对应值从而实现了同名常量、按环境取不同值的机制。创建 Workspace Constants创建、更新或删除工作区常量需要Workspace Constants/Variables 权限参见 基于角色的访问控制指南。拥有权限后按以下步骤创建在 ToolJet 仪表盘左侧边栏进入Workspace Constants标签页。 示例 URLhttps://app.corp.com/nexus/workspace-constants点击Create new constant按钮打开配置抽屉。为工作区常量输入名称和值。选择工作区常量的类型Global constant全局常量Secret机密点击Add constant保存。提示常量或 Secret 一旦创建类型便不可更改。如需调整类型只能删除后按目标类型重新创建。服务端创建逻辑见 service.ts 的 create 方法会先在organization_constants表中登记constantName、organizationId与type随后为所有环境建立空值映射最后将加密后的值写入对应环境的orgEnvironmentConstantValues。对基础版用户未启用多环境值会同步写入所有环境保证后续升级企业版时应用可无缝运行。在应用中访问常量在 App Builder 中使用 Global Constants在 App Builder 中所有全局常量都可以在左侧边栏的Inspector中找到直接以{{constants.constant_name}}语法引用即可。在数据源与查询中使用 Global Constants全局常量让你定义一次、处处复用数据源连接表单填写连接参数时直接引用常量便于集中维护与切换。查询管理器中的查询在查询编辑器中使用同样的{{constants.constant_name}}语法。使用 SecretsSecrets 使用{{secrets.secret_name}}语法访问。在数据源与查询中Secret 值在前端始终以掩码形式显示只能在工作区常量的仪表盘中查看真实值。数据源连接表单查询管理器中的查询服务端对两类常量的解析差异在 service.ts 的 getConstantsForEnvironment 中体现得淋漓尽致非 Secret 类型会解密并返回真实值而 Secret 类型无论是否请求解密在前端可访问的接口路径上始终返回secretValue即**********从源头杜绝敏感信息进入网络负载。从环境变量映射 Workspace Constantsv3.5.8-ee-lts 起从版本v3.5.8-ee-lts开始你可以通过环境变量来设置全局常量和 Secret 常量。通过环境变量设置的常量会在名称前带有.env标签如果存在同名常量环境变量设置的版本会优先用于 App Builder而通过 UI 设置的常量会带有duplicate重复标签以示区分。通过 UI 无法编辑或删除由环境变量创建的常量。要新增、更新或删除环境变量中的任何值必须重启容器。设置全局常量设置单个全局常量语法TOOLJET_GLOBAL_CONSTANTS__environment__constant_name示例TOOLJET_GLOBAL_CONSTANTS__development__companyName Corp Pvt. Ltd.批量设置多个全局常量语法TOOLJET_GLOBAL_CONSTANTS__environment {name1: value1, name2: value2}示例TOOLJET_GLOBAL_CONSTANTS__development {company1: corp.com, company2: example.com}设置 Secret 常量设置单个 Secret 常量语法TOOLJET_SECRET_CONSTANTS__environment__constant_name示例TOOLJET_SECRET_CONSTANTS__development__apiKey agdagdagdg批量设置多个 Secret 常量语法TOOLJET_SECRET_CONSTANTS__environment {name1: value1, name2: value2}示例TOOLJET_SECRET_CONSTANTS__development {api_url: https://api.example.com, password: 12345, key: agdagdagdg}从 Workspace Variables 迁移到 Workspace Constants弃用说明ToolJet 中的 Workspace Variables工作区变量已标记为Deprecated弃用将在未来版本中移除。当前版本仍可删除已有变量并在 ToolJet 应用中继续使用它们但不再支持创建和更新变量。请改用Workspace Constants参见 Workspace Constants 完整指南。迁移步骤如下1. 创建对应的 Workspace Constants按照上文 创建 Workspace Constants 的步骤为每个 Workspace Variable 的值创建新的常量。2. 替换应用中的 Workspace Variables进入需要替换的应用或数据源将旧的 Workspace Variables 替换为对应的 Workspace Constants。例如若你有一个客户端变量%%client.pi%%请将其替换为{{constants.pi}}。3. 删除 Workspace Variables在所有变量迁移完成、并对应用进行充分测试后删除旧的 Workspace Variables进入 Workspace Settings 中的 Workspace Variables 标签页。 示例 URLhttps://app.corp.com/nexus/workspace-settings/workspace-variables点击待删除变量旁的删除图标完成移除。常见问题与最佳实践为什么 Secret 不能在前端解析为了安全。Secret 由服务端解析前端请求链路中只出现掩码值**********避免敏感信息进入浏览器与网络负载同时值在数据库中以加密形式存储见 加密服务实现 与 service.ts。常量类型可以修改吗不可以。创建后类型固定需删除重建。环境变量与 UI 常量同名时以谁为准环境变量版本优先UI 版本标记为duplicate且环境变量版常量无法通过 UI 编辑。何时使用哪种常量需要在下游被组件、工作流复用的普通配置用 Global ConstantsAPI 密钥、密码、令牌等敏感信息一律用 Secrets并尽量配合环境级配置实现开发/生产隔离。通过合理运用 Workspace Constants 与 Secrets你可以显著降低配置管理的重复劳动同时以加密存储、服务端解析、前端掩码、环境级取值四重机制保障敏感数据安全让多环境应用开发与运维更加高效可控。【免费下载链接】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），仅供参考