ToolJet Workspace Variables 迁移到 Workspace Constants 完整指南

ToolJet Workspace Variables 迁移到 Workspace Constants 完整指南【免费下载链接】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 Variables 曾是 ToolJet 中存储令牌、密钥、API Key 等值的通用机制但在当前版本中已被标记为Deprecated弃用。本篇指南以 ToolJet 3.0.0-LTS 文档为基础结合 server 源码 中 Constants 模块的真实实现系统讲解 Workspace Variables 与 Workspace Constants 的差异、Constants 的两类形态Global Constants 与 Secrets、创建与访问方式、环境级配置以及从 Variables 平滑迁移的完整操作流程。读完本文你将能够独立完成存量应用从旧变量体系到新常量体系的迁移与验证并理解其底层加密与解析机制。Workspace Variables 为何被弃用Workspace variables 过去用于在 ToolJet 中存储诸如令牌tokens、secret keys、API keys 等值。但当前 Workspace variables已被标记为 deprecated表示它将在未来版本中被移除。在当前版本中你仍然可以删除已有的 Workspace Variables在整个 ToolJet 应用中继续使用已存在的变量但创建和更新变量已不再支持。官方建议改用 Workspace Constants本文档即为从 Workspace Variables 迁移到 Workspace Constants 的指南。从底层看Constants 之所以能替代 Variables是因为其数据模型与解析链路更加严格常量定义存储在organization_constants表实体定义见 organization_constants.entity.ts通过(constantName, organizationId, type)唯一约束确保同工作区内常量名与类型不重复每个常量在不同环境下的取值存放在org_environment_constant_values表见 org_environment_constant_values.entity.ts通过(organizationConstantId, environmentId)唯一约束实现一个常量、多环境多值的模型常量类型由OrganizationConstantType枚举控制默认值为GLOBAL。Workspace Constants 是什么Workspace Constants 是预定义值用于在工作区内的多个应用中增强一致性、简化更新流程并安全存储敏感信息。与其他变量不同Constants 只在服务端解析从而避免客户端暴露安全性更高。关键特性工作区隔离Constants 仅在其所属工作区内可用其他工作区无法访问加密存储所有常量与密钥在存入数据库前都会加密为敏感数据提供额外保护层两类形态分为 Global Constants全局常量与 Secret Constants秘密常量。Global Constants全局常量预定义值可在工作区内的应用之间复用适合存放 API URL、配置项等高频使用的值。特点可在组件、数据查询、数据源、工作流中使用在客户端解析Resolved on Client Side在数据库中加密存储但前端不做掩码Masked in Frontend ❌。Secret Constants秘密常量专为存储 API Keys、数据库凭据等敏感信息设计。特点在服务端解析防止暴露给客户端掩码显示前端只显示**********只能在 Workspace Constants 仪表盘中查看真实值可在数据查询与数据源中使用但Secret Constants 不能用于 RunJS 或 RunPy 查询只能作为单一键使用不能以复合键方式使用cant be used in a composite key manner工作流中的支持状态为 Coming Soon。两类常量的特性对比特性Global ConstantsSecrets组件Components✅❌数据查询Data Queries*✅✅数据源Data Sources✅✅工作流Workflows✅Coming Soon数据库中加密✅✅前端掩码❌✅客户端解析✅❌服务端解析❌✅命名约定{{constants.constant_name}}{{secrets.secret_name}}注意Secret Constants 不能用于 RunJS 或 RunPy 查询Secret Constants 只能作为单一键使用不能以复合键方式使用。这一客户端/服务端解析的设计在源码中有直接体现。在 organization-constants/service.ts 的allEnvironmentConstants方法中当常量为SECRET类型且未请求解密时只返回常量名称而不返回任何值即使返回值secret 也会被替换为掩码**********源码第 11 行定义了const secretValue **********只有显式传入decryptSecretValue true时才会通过decryptSecret解密出真实值。这正是Secrets 只能在工作区常量仪表盘中查看这一行为的服务端实现。环境特定配置Environment Specific ConfigurationsToolJet 允许用户为不同环境如 development、staging、production的常量和密钥分配不同值实现环境特定配置。这一能力对管理随环境变化的敏感信息至关重要例如每个环境使用不同的 API Key、数据库凭据或外部服务端点。示例场景为每个环境配置唯一的 API Key确保无缝集成与安全。其底层结构正是前文提到的org_environment_constant_values表每个常量记录通过environmentId关联到具体环境从而做到同一常量在不同环境下取不同的值数据模型见 org_environment_constant_values.entity.ts。创建 Workspace Constants创建、更新或删除工作区常量需要workspace constants/variables 权限详见 Access Control 指南。获得权限后按以下步骤创建从 ToolJet 仪表盘左侧边栏进入Workspace Constants选项卡。 示例 URLhttps://app.corp.com/nexus/workspace-constants点击Create new constant按钮打开配置抽屉。Create New Constant输入工作区常量的名称与值。选择工作区常量类型Global constant全局常量Secret秘密常量点击Add constant按钮保存。:::info 常量或密钥一旦创建其类型无法更改。如需更改类型只能删除后按目标类型重新创建。 :::创建与读取逻辑在服务端由 organization-constants/service.ts 统一实现并通过 controller.ts 暴露 REST 接口模块内的 ability/guard.ts 负责权限校验对应文档所述需要 workspace constants/variables 权限。访问 Workspace Constants使用 Global Constants全局常量使用语法{{constants.constant_name}}访问可用于 App Builder、数据源、数据查询和工作流。在 App Builder 中使用在 App Builder 内可以在左侧边栏的 inspector 元素中找到所有常量。在数据源与查询中使用Global Constants 允许你定义一次值然后在数据源和查询中复用数据源连接表单在连接配置字段中直接引用{{constants.constant_name}}。Query Manager 中的查询在查询参数中引用同一语法。使用 SecretsSecrets 用于安全存储 API Keys、数据库凭据等敏感信息使用语法{{secrets.secret_name}}访问。在数据源与查询中使用在数据源和查询中secret 值在前端会被掩码显示只能在工作区 Constants 仪表盘中查看真实值数据源连接表单Query Manager 中的查询前端掩码行为由服务端返回值决定如前文源码所示普通读取接口对 secret 类型只返回**********只有仪表盘在解密模式下才能获取真实值organization-constants/service.ts。从环境变量映射 Workspace Constants从版本v3.5.8-ee-lts起你可以使用环境变量来设置全局常量与秘密常量。通过环境变量设置的工作区常量会带有一个.env标签。如果出现两个同名常量则通过环境变量设置的那个会在 App Builder 中生效而通过 UI 设置的常量会带有一个duplicate标签。通过 UI 无法编辑或删除由环境变量创建的常量。若要新增、更新或删除环境变量中的任何值必须重启容器。设置 Global Constants设置单个全局常量语法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 Constants设置单个秘密常量语法TOOLJET_SECRET_CONSTANTS__environment__constant_name示例TOOLJET_SECRET_CONSTANTS__development__apiKey agdagdagdg设置多个秘密常量语法TOOLJET_SECRET_CONSTANTS__environment {name1: value1, name2: value2}示例TOOLJET_SECRET_CONSTANTS__development {api_url: https://api.example.com, password : 12345, key : agdagdagdg}环境变量映射常量的解析逻辑位于 organization-constants/services/environment-constants.service.ts该服务在容器启动时读取上述TOOLJET_*_CONSTANTS__*环境变量并同步为工作区常量这解释了为何新增、更新或删除环境变量值后需要重启容器。从 Workspace Variables 迁移到 Workspace Constants迁移的核心思路是为每个 Workspace Variable 创建对应的 Workspace Constant 并填入值然后逐步替换应用中的引用最后删除旧的变量。第一步创建 Workspace Constants按照 创建 Workspace Constants 指南为每个需要迁移的变量创建新的常量并存储对应值。第二步用 Workspace Constants 替换应用中的 Workspace Variables迁移完所有 Workspace Variables 后就可以在应用中将 Workspace Variables 替换为对应的 Workspace Constants导航到需要替换 Workspace Variables 的应用或数据源将 Workspace Variables 替换为对应的 Workspace Constants。替换示例如果有一个客户端 Workspace Variable 为%%client.pi%%将其替换为{{constants.pi}}。替换时注意区分两种语法原 Workspace Variable替换后的 Global Constant替换后的 Secret%%client.name%%{{constants.name}}{{secrets.name}}对于令牌、密钥、数据库凭据等敏感信息建议迁移为 Secret 类型以获得服务端解析与前端掩码保护对于 API URL、配置项等非敏感值迁移为 Global Constant 即可。第三步删除 Workspace Variables在将所有 Workspace Variables 迁移到 Workspace Constants 并充分测试应用后可以删除 Workspace Variables。删除步骤进入 Workspace Settings 中的Workspace Variables选项卡。 示例 URLhttps://app.corp.com/nexus/workspace-settings/workspace-variables点击要删除的 Workspace Variable 旁边的删除图标。迁移检查清单✅ 所有 Variables 已创建为对应 Constants区分 Global 与 Secret 类型✅ 应用中所有%%client.xxx%%、%%server.xxx%%引用已替换为{{constants.xxx}}或{{secrets.xxx}}✅ 涉及 RunJS/RunPy 的查询确认未引用 SecretSecrets 不允许在此类查询中使用✅ 生产环境应用已完整回归测试✅ 删除旧 Variables 前已确认无遗漏引用。迁移后的安全收益完成迁移后你将获得 Variables 时代不具备的安全能力加密存储常量与密钥入库前均加密organization_constants.entity.ts服务端解析Secrets 不经过客户端前端只看到掩码**********organization-constants/service.ts环境隔离每个环境development/staging/production可为同一常量配置不同值org_environment_constant_values.entity.ts环境变量注入通过TOOLJET_GLOBAL_CONSTANTS__*与TOOLJET_SECRET_CONSTANTS__*实现声明式配置environment-constants.service.ts。相关文档Workspace Constants 完整指南Access Control 权限指南【免费下载链接】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），仅供参考