ToolJet 3.0 自托管升级迁移指南从 v2.50.0-LTS 到 v3.0.0 的破坏性变更与实战改造【免费下载链接】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 官方文档《ToolJet 3.0 Migration Guide Self-Hosted》编写聚焦自托管用户如何从v2.50.0-LTS升级到v3.0.0-ee-lts当前为预发布/beta 版本完整覆盖升级前置条件、全部破坏性变更动态组件引用、组件与查询同名、属性面板变量访问规则、多页面组件命名、废弃功能移除、响应元数据格式以及系统级变更ToolJet Database 与 PostgREST 部署并附上仓库源码级佐证帮助你在升级前完成应用审查、改造与回归测试。升级前必读为什么 3.0 需要一次有计划的迁移ToolJet 3.0 是一个新的主版本major version包含若干破坏性变更breaking changes意味着升级后部分既有应用可能需要调整才能继续正常工作。与常规小版本平滑升级不同从 v2.50.0-LTS 升级到 v3.0.0 之前必须提前审查并改造应用。官方在升级前给出了两条核心建议提前排查废弃功能审查现有应用中对已废弃特性的使用情况尤其是文档中列出的废弃组件与数据源类型提前处理可以显著减少升级时的工作量建立测试流程对于复杂应用建议在升级后建立完整的测试流程确保应用功能符合预期。以下各节将逐一说明你需要检查的变更点、需要执行的动作以及推荐的新写法。升级步骤与前置条件前置条件清单⚠️ 必做在尝试升级到 ToolJet 3.0 之前请确认满足以下三项条件前置条件说明数据库备份对数据库执行完整备份升级涉及数据迁移一旦出错可回滚应用审查按本文列出的破坏性/废弃特性清单逐项检查应用测试环境先在非生产环境测试环境中完成升级演练执行升级更换 Docker 镜像升级动作本身非常简单——将 Docker 镜像更新为tooljet/tooljet:v3.0.0-ee-lts:::warning 当前版本为beta 预发布版本务必先在非生产环境中充分测试再考虑生产环境。 :::破坏性变更一动态输入限制Dynamic Input Restrictions变更内容升级到 3.0 后不再允许动态变更对组件名的引用。此前可以通过运行时变量拼接组件名的写法在 3.0 中将被禁止。需要执行的动作审查应用中所有动态组件名引用必要时进行重构将所有动态组件引用替换为静态引用修改完成后逐一测试所有组件交互。不再支持的写法示例以下三种模式在 3.0 中均不再支持// 1. 使用变量构造组件名 —— 不再生效 {{components[variables.componentNameVariable].value}} // 2. 动态拼接组件名 —— 不被支持 {{components[textinput components.tabs1.currentTab].value}} // 3. 动态访问嵌套属性 —— 不允许 {{components.table1[components.textinput1.value]}}推荐的新写法改用静态引用即可{{components.textinput1.value}} {{components.table1.selectedRow}} {{queries.query1.data}}源码佐证从仓库前端结构看组件引用系统建立在frontend/src/AppBuilder/WidgetManager等模块之上组件与查询统一经由components.*/queries.*命名空间在表达式中解析。3.0 收紧为仅支持静态键访问意味着表达式解析器不再接受先算变量、再取组件的两段式寻址——这本质上是通过限制运行时反射来换取更可预测的依赖分析例如为后续跨页面组件唯一性约束、依赖追踪做准备。破坏性变更二组件与查询同名问题Component and Query Naming变更内容在v2.50.0-LTS 时代组件与查询共用一张全局的 ID→名称映射表而在 3.0 中这张映射被拆分为两套独立体系因此升级过程中如果某个组件引用了同名查询映射关系可能断裂。:::note 此问题仅出现在升级过程中。一旦应用在 ToolJet 3.0 上正常运行后组件与查询使用相同名称将不再有任何问题。 :::需要执行的动作审查应用中是否存在查询与组件同名的情况临时重命名组件或查询确保名称唯一记录所有被重命名的组件/查询以便升级后按需还原重命名后测试受影响组件与查询。典型场景假设一个名为userData的表格组件引用了一个同样名为userData的查询那么在升级过程中这条引用关系可能被破坏。建议在升级前应用一个临时唯一化命名策略例如给查询加前缀升级完成后、确认运行正常后再通过文档化记录还原命名即可平滑绕开这一升级期限制。破坏性变更三属性面板变量访问规则Property Panel Logic变更内容3.0 调整了在**属性面板Property Panel**中访问变量、检查变量是否存在的语法规则对于components/queries/page关键字关键字之后至少需要两个键例如components.textinput1.value对于variables关键字关键字之后至少需要一个键例如variables.name。需要执行的动作审查所有属性面板中的变量检查逻辑将现有的变量存在性检查写法更新为推荐格式移除所有不支持的逻辑模式更新后测试所有使用了变量检查的组件。支持的访问格式// 支持的格式 components.textinput1.value components?.textinput1?.value components[textinput1].value queries.restapi1.data page.variables.name variables[name] variables.name不再支持的存在性检查写法// 不再支持 {{name in variables}} {{Object.keys(variables).includes(name)}} {{variables.hasOwnProperty(name)}} // 推荐的存在性检查方式 {{variables[name] ?? false}}:::caution 这些变更可能影响应用与变量、组件的交互方式。更新后务必进行全面测试。 :::语义解读旧写法name in variables、Object.keys(...)等本质上是运行时对象自省reflection而 3.0 要求表达式在编译期可静态分析。{{variables[name] ?? false}}之所以成为推荐写法是因为它同时做到了两件事以静态下标访问变量、用空值合并运算符??在变量不存在时安全回退到false既满足新语法约束又保持了存在性判断的语义。破坏性变更四多页面组件命名Multi-Page Component Names变更内容当多个页面存在同名组件且该组件与查询关联时查询只在最初关联组件的那个页面上正常工作。典型场景应用有page1与page2两个页面各有一个名为textinput1的组件在page1中创建了一个关联textinput1的查询该查询只在page1上正常工作切到page2后即使页面上存在同名组件查询也不会按预期工作。需要执行的动作审查多页面应用中是否存在同名组件重命名组件确保跨页面名称唯一或修改查询改用**查询参数query parameters**而不是直接引用组件记录所有组件名称变更测试受影响的页面及其交互。当前限制与后续规划官方明确表示构建多页面应用时强烈建议所有页面使用唯一组件名以避免查询绑定出现问题同时团队计划在后续版本中增加跨页面强制组件名唯一的功能。破坏性变更五废弃功能移除Removal of Deprecated Features5.1 Kanban Board 旧组件旧的、已废弃的Kanban Board组件在升级后将完全失效。未更新的应用在升级后会直接崩溃、无法使用。需要执行的动作立即识别应用中所有旧的Kanban Board组件使用新的Kanban组件重建看板将数据与配置迁移到新组件删除旧的 Kanban Board 组件更新所有连接到旧看板的查询或工作流全面测试确保功能完整保留。:::caution 3.0 升级后包含旧 Kanban Board 组件的应用将崩溃且不可用。请在升级前将旧组件的所有实例替换为新 Kanban 组件。 :::源码佐证仓库前端保留了新旧两套组件实现可作为识别依据旧组件frontend/src/AppBuilder/Widgets/KanbanBoard/KanbanBoard.jsx对应kanbanBoard.js组件定义见 frontend/src/AppBuilder/WidgetManager/widgets/kanbanBoard.js新组件frontend/src/AppBuilder/Widgets/Kanban/Kanban.jsx对应 frontend/src/AppBuilder/WidgetManager/widgets/kanban.js。应用编辑器的组件面板与WidgetManager按组件定义注册表工作迁移时只需把旧组件实例替换为新组件定义、再迁移数据绑定即可。5.2 本地数据源Local Data Sources从 ToolJet 3.0.0 起本地数据源Local Data Sources被彻底移除此前版本已标记废弃。升级后连接到本地数据源的查询将显示本地数据源不再受支持的错误信息。需要执行的动作升级前识别应用中所有本地数据源迁移为全局工作区数据源Workspace Data Sources更新所有使用这些数据源的查询与组件迁移后测试所有受影响的组件与查询。升级后的迁移补救若未提前迁移如果升级前未完成迁移升级后查询会显示错误。可按以下步骤补救详细指南见 Local Data Sources Migration Guide识别报错查询在应用 Query Manager 中找到显示本地数据源错误信息的查询这类查询只显示错误、其余内容被隐藏创建新数据源进入 Data Sources 部分创建同类型的新数据源例如原先用 PostgreSQL 本地数据源就创建 PostgreSQL 数据源填写正确的连接信息并保存重连查询打开报错查询在Source字段的下拉框中选择刚创建的同类型数据源查询即恢复可用测试查询运行每个更新后的查询确认一切正常。5.3 工作区变量Workspace Variables工作区变量Workspace Variables已标记废弃3.0 中需要迁移为工作区常量Workspace Constants。需要执行的动作识别应用中所有工作区变量替换为工作区常量更新所有使用这些变量的组件与查询为新常量配置合适的基于角色的访问权限迁移后测试所有受影响功能。为什么用工作区常量工作区常量只在服务端解析安全级别高可以按角色授予用户创建、更新、删除工作区常量的权限。默认情况下工作区管理员拥有工作区常量的全部访问权限。语法对比与迁移示例类型语法示例解析位置工作区变量旧%%client.psql_host%%客户端变量、%%server.psql_host%%服务端变量客户端 / 服务端工作区常量新{{constants.psql_host}}仅服务端具体迁移步骤详见 Workspace Variables Migration Guide进入 ToolJet 工作区设置Workspace Settings选择Workspace Constants标签页点击Create New Constant按钮在抽屉中输入名称与值点击Add Constant保存为所有工作区变量重复上述步骤在应用与数据源中把%%client.xxx%%替换为{{constants.xxx}}、把%%server.xxx%%替换为{{constants.xxx}}全部替换并测试通过后在 Workspace Variables 标签页中删除已废弃的工作区变量。破坏性变更六响应头与元数据Response Headers and Metadata变更内容3.0 为所有数据源引入了统一的metadata能力用于暴露请求/响应的附加信息。此前只有REST API和GraphQL数据源可以访问响应头。需要执行的动作识别所有访问响应头response headers的代码更新为新的 metadata 格式测试所有受影响的查询与组件。语法迁移对照旧写法仅在 REST API / GraphQL 上可用{{queries.queryName.responseHeaders}}新写法所有数据源通用{{queries.queryName.metadata}}metadata对象包含请求与响应的详细信息请求 URL、方法、请求头、参数、响应状态码、响应头等。完整的 metadata 结构示例与属性访问方式见 Metadata and Cookies 文档。源码佐证服务端在查询执行完成后统一组装 metadata。在 server/src/modules/data-queries/util.service.ts 中可以看到查询结果会合并执行状态的响应元数据result[metadata] { ...(result[metadata] || {}), ...queryStatus.getResponseMetadata(), };同时仅当forwardRestCookies开启且数据源类型为restapi、结果含responseHeaders时才会把响应 Cookie 写回客户端setCookiesBackToClient接口定义见 server/src/modules/data-queries/interfaces/IUtilService.ts。这也解释了为什么旧格式responseHeaders需要统一收编进metadata3.0 把所有数据源restapi、grpcv2 等的请求/响应细节统一挂到metadata命名空间下旧字段随之废弃。元数据示例以 REST API 为例{{queries.queryName.metadata}}的结构大致如下完整示例见 metadata-and-cookies.md{ request: { url: https://dummyjson.com/users, method: GET, headers: { user-agent: ... }, params: {} }, response: { statusCode: 200, headers: { content-type: application/json; charsetutf-8 } } }:::info 访问含连字符的 metadata 属性时请使用括号bracket写法例如{{queries.restapi1.metadata.request.headers[user-agent]}}或{{queries.restapi1.metadata.request.headers.user-agent}}。 :::系统变更ToolJet Database 与 PostgRESTToolJet Database 在 3.0 中成为核心依赖core requirement。要使用 ToolJet Database需要部署 PostgREST 服务器用于查询 ToolJet Database。需要配置的环境变量部署 PostgREST 与启用 ToolJet Database 所需的核心环境变量如下详见 环境变量文档变量说明TOOLJET_DBToolJet Database 名称默认值为tooljet_dbTOOLJET_DB_HOSTToolJet Database 主机TOOLJET_DB_USERToolJet Database 用户名TOOLJET_DB_PASSToolJet Database 密码TOOLJET_DB_PORTToolJet Database 端口PGRST_JWT_SECRET用于认证的 JWT 密钥客户端提供PGRST_HOSTPostgREST 数据库主机PGRST_DB_PRE_CONFIGpostgrest.pre_config:::tip 所有生产部署方案中TOOLJET_DB提供的数据库名会在服务端启动过程中自动创建如需手动触发可在 ToolJet server 上执行npm run db:create。 ::::::info 若使用 DB 连接串且连接不支持 SSL请使用如下格式的TOOLJET_DB_URLpostgres://username:passwordhostname:port/database_name?sslmodedisable:::仓库中的 docker-compose.yaml、deploy/docker/docker-compose.yaml 以及 deploy/kubernetes/postgrest.yaml 等部署清单可作为自托管环境中编排 PostgREST 服务、配置上述环境变量的直接参考。升级检查清单速查检查项动作新写法/目标动态组件名引用改为静态引用{{components.textinput1.value}}组件与查询同名升级前临时唯一化命名升级后可还原属性面板变量存在性检查替换旧自省写法{{variables[name] ?? false}}多页面同名组件跨页面唯一命名或改用查询参数唯一组件名旧 Kanban Board 组件迁移到新 Kanban 组件frontend/src/AppBuilder/Widgets/Kanban/Kanban.jsx本地数据源迁移为工作区全局数据源见 local-data-sources-migration.md工作区变量迁移为工作区常量{{constants.xxx}}响应头访问改用统一 metadata{{queries.name.metadata}}ToolJet Database / PostgREST部署 PostgREST 并配置环境变量见 env-vars.md帮助与支持加入 ToolJet Slack 社区获取帮助如果发现了 Bug可以在 ToolJet 的 GitHub 仓库提交 issue详见仓库根目录的 README.md 与 SECURITY.md 中关于问题反馈与安全披露的说明。结语ToolJet 3.0 的升级并非换镜像那么简单动态组件引用的禁用、组件与查询映射拆分、属性面板变量访问规则收紧、多页面组件命名约束、废弃组件旧 Kanban Board与废弃数据能力本地数据源、工作区变量的移除以及响应元数据格式的统一都需要在升级前逐一审查与改造。建议严格按照本文清单备份数据库 → 审查应用 → 测试环境演练 → 执行升级 → 回归测试并在升级窗口内预留足够的改造与验证时间确保自托管环境平滑过渡到 3.0。【免费下载链接】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），仅供参考