企业官网建设流程全解析

ToolJet 版本管理与发布指南：使用 App Version Manager 实现应用版本控制与生产发布

【免费下载链接】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 的Versioning and Release（版本管理与发布）功能展开，介绍如何在 App Builder 中通过右上角的App Version Manager创建、重命名、删除应用版本，以及如何将选定版本发布（Release）到生产环境、交付给最终用户。读完本文，你将掌握 ToolJet 应用的多版本协作工作流：多个开发者各自基于独立版本迭代、互不覆盖；理解 DRAFT / PUBLISHED / RELEASED 三种版本状态在前后端的行为差异，以及"未发布就公开"和"已发布版本被锁定编辑"这两条关键安全约束背后的实现原理。文中操作步骤以 versioning-and-release.md 为骨架，并结合 frontend 与 server 的源码进行纵深解读。

什么是版本管理与发布

ToolJet 的版本管理（Versioning）让多个开发者可以在同一个应用上各自保存自己的版本。每个开发者可以在自己的版本上独立修改页面、组件、数据查询和事件处理，从而避免互相覆盖对方的工作——这在多人协作开发一个内部工具或业务应用时尤为关键。

发布（Release）则是把某个版本正式"定稿"并推送到生产环境的过程：发布后，最终用户通过应用公开访问链接看到的就是该发布版本的内容，而不是构建器中尚未定稿的草稿。

从数据模型上看，每个应用版本在数据库中对应app_versions表中的一行记录（见 app_version.entity.ts），版本名称与应用分支共同构成唯一约束（@Unique(['name', 'branchId'])）。版本有三个状态枚举（AppVersionStatus）：

前端版本下拉列表正是依据这些状态来渲染标签：草稿显示黄色的Draft标签，已发布的版本在列表中显示为绿色，已发布（Released）版本显示绿色Released标签（相关逻辑见 VersionDropdownItem.jsx）。

版本管理入口：App Version Manager

所有版本操作都集中在 App Builder 工具栏右上角的App Version Manager（应用版本管理器）中。它显示当前正在编辑的版本名称，点击后展开下拉列表，列出该应用已创建的所有版本，并支持：

• 切换当前编辑的版本；
• 创建新版本；
• 重命名版本；
• 删除版本；
• 发布版本（Release）。

前端对应组件为 VersionManagerDropdown.jsx，它通过useVersionManagerStore与全局 Store 联动，负责版本列表的懒加载（打开下拉时才拉取）、环境筛选、Git 同步状态展示等。后端则通过 REST API 提供版本数据：GET /api/apps/:id/versions获取版本列表、PUT /api/apps/:id/versions/:versionId更新版本等（见 controller.v2.ts）。

从源码看，版本列表返回时会标记第一个版本为isCurrentEditingVersion（当前编辑版本），并针对 Git 分支型版本（AppVersionType.BRANCH）把内部 UUID 名称替换为人类可读的分支名（见 service.ts），保证下拉列表与导出弹窗中显示一致。

创建新版本

创建版本的操作路径如下：

1. 打开工具栏中的App Version Manager，点击下拉按钮，查看该应用已创建的所有版本（已发布（Released）的版本名称以绿色显示）。
2. 点击下拉列表底部的Create new version按钮，弹出创建弹窗。
3. 在弹窗中填写Version Name（版本名称）。
4. 在Create version from下拉框中选择新版本的来源版本：它会列出该应用已有的所有版本，选择其中一个作为新版本的基线；如果不选择，ToolJet 会自动选用最后创建的版本作为基线。
5. 点击Create new Version按钮完成创建。

创建版本的底层逻辑

从前端看，创建版本弹窗由 CreateVersionModal.jsx 渲染（内部委托给通用的BaseCreateVersionModal）。从后端看，创建版本的核心实现在VersionService.createVersion（见 service.ts）及其下层工具类：

• 新版本会克隆来源版本的内容（页面、组件、数据查询、事件等），而不是从空白开始，这正是"Create version from"的含义；
• 克隆过程会复制来源版本对应的页面与事件定义（见 create.service.ts 中对versionFromId的处理）；
• 在启用了 Git 同步且为单分支模式的工作区中，创建草稿会触发"替换既有草稿"（replaceDraftVersion）的原子操作，而不是无限堆积多个草稿（见 service.ts）。

重命名版本

如果需要对已有版本改名：

1. 打开App Version Manager，展开版本列表；
2. 找到要重命名的版本，点击版本名称旁边的重命名（编辑）按钮（铅笔图标）；
3. 在弹出的模态框中输入新的版本名称并确认。

需要特别注意的是：并非所有版本都可以随意改名。后端在更新版本时有明确的保护逻辑——如果版本状态不是DRAFT（即已保存的版本），尝试修改其名称或描述会被拒绝并抛出BadRequestException（"Cannot edit name or description of a saved version."），相关校验见 service.ts。也就是说，只有草稿版本允许重命名，已保存/已发布的版本名称是受保护的，前端也只在草稿版本上显示"Edit details"菜单项（见 VersionDropdownItem.jsx）。

删除版本

删除版本同样在App Version Manager中完成：

1. 展开版本下拉列表，找到要删除的版本；
2. 点击该版本右侧的删除图标（垃圾桶）；
3. 确认删除。

删除操作的细节从源码中可以确认：

• 前端删除流程会先弹出ConfirmDialog确认框；若启用了 Git 同步且版本已同步到远端，确认文案会明确指出该版本也会从 Git 中删除且无法恢复，按钮变为 "Delete and commit"（见 VersionManagerDropdown.jsx）；
• 后端删除接口由VersionService.deleteVersion实现，删除时会记录审计日志（包含被删版本 id 与名称），见 service.ts；
• 若删除的模块版本仍被其他应用引用，前端会弹出 "Dependent apps found!" 的警告框并阻止删除（见 VersionManagerDropdown.jsx）；
• Git 同步开启时，最后一个已同步草稿不允许被删除（后端有镜像守卫逻辑，前端会先提示 "Cannot delete the last draft version while git sync is enabled"）。

发布版本（Release）

发布（Release）是将应用正式推送至生产环境的操作。发布之后，用户通过应用的公开链接访问到的即为此版本。

发布操作步骤

1. 打开App Version Manager，从下拉列表中选择要发布的版本（只有状态为已保存的版本才可发布，纯草稿不能直接发布）；
2. 点击右上角的Release按钮；
3. 在弹出的确认对话框中点击Release，确认发布当前版本。

发布权限与前置条件（源码级解读）

前端对 Release / Promote 按钮的显隐有严格判定（见 VersionDropdownItem.jsx）：

• 草稿版本（DRAFT）不显示发布按钮——必须先保存为版本；
• 已发布的版本（PUBLISHED）在 CE（社区版）中可直接 Release；
• 在启用多环境（multi-environment）的版本中，版本需要先逐级Promote（提升）到生产环境（priority = 3）后，才能在生产环境执行 Release；
• 已经发布（Released）的版本不会重复显示发布按钮。

后端promoteVersion实现了环境逐级提升：只有当版本当前所在环境与请求的环境一致时，才能将其提升到优先级更高的下一环境；同时后端明确拒绝提升草稿（"You cannot promote a draft version. Please save the version before promoting."），详见 service.ts。发布后，前端会根据releasedVersionId在版本列表中渲染绿色 Released 标签（见 VersionDropdownItem.jsx）。

两条关键安全约束

官方文档在发布章节以警示框（caution）的形式强调了两条重要约束，这两条约束也都能在后端代码中得到印证：

约束一：未发布就公开 = 预览模式

当应用被设为Public（公开）但尚未发布任何版本时，其行为等同于预览（preview）：通过公开应用 URL 加载的版本，就是当前 App Builder 中正在加载的版本。也就是说，任何人都能看到构建器当前打开的那份内容——这对协作团队意味着，在应用定稿前要谨慎开启公开访问，避免把未完成的半成品暴露给外部用户。

约束二：已发布版本禁止直接编辑

为防止误把未完成的应用发布出去，ToolJet 在已发布（Released）版本上会冻结编辑器：如果你想修改已发布版本的内容，系统会提示你先创建一个新版本，编辑已发布版本本身会被阻止。

这一机制在后端有明确实现：VersionService.getVersion在返回版本数据时，若检测到版本状态为PUBLISHED，会设置shouldFreezeEditor = true（见 service.ts），前端收到该标志后即进入编辑器只读状态。同理，在启用了多环境许可证的工作区中，当前环境优先级大于 1（即非开发环境）时编辑器同样会被冻结（见 service.ts）。这一设计确保了生产内容永远只能通过"新建版本 → 修改 → 发布"的受控流程变更。

版本管理的最佳实践

结合文档操作路径与源码约束，可以总结出以下可落地的协作实践：

1. 一开发者一版本：多人协作时，每个成员基于"Create version from"各自创建独立版本，互不干扰；后端在非 Git 工作区允许多个草稿并存，进一步降低了协作摩擦。
2. 先保存、再发布：草稿（DRAFT）既不能发布也不能直接提升环境，任何变更进入生产前都必须先执行保存（Save version）生成PUBLISHED版本。
3. 发布即定稿：RELEASED版本内容被冻结，后续迭代一律新建版本——这既是安全约束，也是可追溯的变更记录。
4. 公开访问与发布状态联动：在应用尚未 Release 前保持非公开，避免公开 URL 暴露构建器中的当前版本。
5. 结合 Git 同步使用：启用了 Git 同步的工作区中，版本与 Git tag 一一对应，可下拉远端版本（Pull）、识别未同步版本，删除已同步版本会连同 Git tag 一并提交删除（相关 UI 逻辑见 VersionManagerDropdown.jsx）。

结语

ToolJet 的版本管理与发布机制，为低代码应用的多人协作与生产交付提供了一条清晰的路径：DRAFT（草稿）→ PUBLISHED（已保存）→ RELEASED（已发布）的三态流转配合"已发布版本冻结编辑"的硬约束，既保证了开发自由度，又守住了生产安全底线。无论你是个人开发者还是团队协作，善用 App Version Manager 都能让应用的每次迭代都处于可控、可追溯的状态。

【免费下载链接】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