ToolJet V2 升级迁移指南：多页面、多环境与可选项功能配置全解析

ToolJet Version 2（V2）是一次面向自托管部署的重要版本升级，带来了多页面应用、多环境支持、Forms 表单组件等核心能力，并引入了需要显式开启的 ToolJet Database 与 Marketplace 两个可选功能。本文基于 ToolJet 2.50.0-LTS 版本的官方迁移指南，完整梳理 V2 的部署升级路径、数据迁移触发机制、可选功能的配置项（以 .env 环境变量为核心）以及版本弃用清单，帮助你在升级前评估改动、升级时一次性配置到位、升级后快速验证新功能是否生效。

V2 带来了什么：核心新特性总览

根据 v2-migration.md 官方迁移指南，ToolJet V2 的主要新特性集中在以下五个方面：

特性	说明	是否需要额外配置
Multi page（多页面）	在单个应用内创建、管理、导航多个页面，一个应用可以承载多样化的功能	否，默认可用
Multi env（多环境）	支持按环境管理数据源连接与配置，便于区分开发、测试、生产	否，默认可用
Forms widget（表单组件）	提供动态表单构建能力，配合 Tabs 组件可实现多页表单	否，默认可用
ToolJet Database	内置数据存储，用类似电子表格的界面维护表数据，开箱即用	是，需 ENABLE_TOOLJET_DB=true（opt-in）
Marketplace	插件市场，可安装自定义数据源插件到工作区	是，需 ENABLE_MARKETPLACE_FEATURE=true（opt-in）

其中，ToolJet Database 与 Marketplace 属于需要显式开启（opt-in）的能力，这也是升级 V2 时唯一需要额外关注的配置变更点。其余三个特性在默认部署中直接可用，无需任何额外配置。

部署升级：默认部署可直接升级，无需额外配置

对于已经按照官方 setup 文档 完成部署的用户，V2 的升级路径非常简单：

无论你此前选择了哪种部署方式（Docker Compose、Kubernetes、ECS、Helm 等），默认配置下都可以直接部署 V2，无需任何额外配置变更。

唯一的例外是上文提到的两个可选功能（ToolJet Database 与 Marketplace），它们需要按照各自的功能文档额外配置。以最常见的 Docker Compose 部署为例，升级流程与全新部署完全一致，仅需更新镜像后重启：

# 1. 拉取最新镜像
docker compose pull

# 2. 重建并后台启动容器
docker-compose up -d

注意：在 Linux 服务器上，docker 命令可能需要 sudo 权限，此时请使用 sudo docker-compose up -d。

仓库中对应 V2 的默认部署模板可以参考 docker-compose-db.yaml（内置 PostgreSQL 的推荐方案），其中 tooljet 服务使用 tooljet/tooljet-ce:latest 镜像，通过 env_file: .env 加载环境变量，并依赖 postgres 与 postgrest 两个服务。

升级时的数据迁移：服务器启动阶段自动完成

V2 升级涉及一批数据迁移（data migrations），这是部署过程中需要特别留意的一点：

由于 V2 的变更需要执行若干数据迁移，首次部署/升级后服务器可能需要一些时间才能就绪并处理 HTTP 请求。该迁移会在服务器启动（server boot）阶段自动触发，无需人工干预。

从源码看，数据迁移的加载逻辑定义在 data-migration-config.ts：TypeORM 连接配置中 migrationsRun: false、migrations: [__dirname + '/data-migrations/**/*{.ts,.js}']，即所有位于 server/data-migrations/ 目录下的迁移脚本都会在服务启动时被自动检测并执行。仓库中该目录包含超过 100 个迁移脚本，例如 1661331234770-RestructureTableColumnSizesAndActionsToHaveAValueKeyThatPointsToItsContents.ts、1668521091918-ChangeDefinitionStructureForMultiPage.ts 等，其中后者正是为多页面特性重写应用定义结构（definition structure）的核心迁移，印证了「V2 数据迁移由服务启动自动触发」这一官方说明。

因此升级 V2 后，请耐心等待服务完全就绪（健康检查通过）再对外提供访问，切勿在迁移执行期间强制重启容器，以免造成数据不一致。

可选功能一：开启 ToolJet Database（内置数据库）

ToolJet Database 是 V2 引入的内置数据存储能力，它仅在 ENABLE_TOOLJET_DB=true 时才会启用。开启该功能需要两部分配置：PostgREST 服务端 + ToolJet 服务端。

依赖组件：PostgREST 服务

PostgREST 是一个独立的 Web 服务器，能将 PostgreSQL 数据库直接转换为可查询的 RESTful API，ToolJet Database 正是基于它实现的。官方文档明确指出：

PostgREST 只与 ToolJet 服务端通信，因此不需要对外暴露公网端口，请勿将其映射到公网。

PostgREST 侧需要配置以下环境变量：

变量	说明
PGRST_JWT_SECRET	用于认证的 JWT 密钥（必填，若未指定，PostgREST 将拒绝所有认证请求）
PGRST_DB_URI	ToolJet 数据库的连接字符串，格式须为 postgres://[USERNAME]:[PASSWORD]@[HOST]:[PORT]/[DATABASE]
PGRST_LOG_LEVEL	日志级别，例如 info

PGRST_JWT_SECRET 与 ToolJet 服务端的 PGRST_JWT_SECRET 必须保持一致。如果安装了 openssl，可以直接用以下命令生成：

openssl rand -hex 32

ToolJet 服务端配置

ToolJet 服务端需要追加以下环境变量：

变量	说明
ENABLE_TOOLJET_DB	true 或 false，功能总开关
TOOLJET_DB	数据库名，默认值为 tooljet_db
TOOLJET_DB_HOST	数据库主机
TOOLJET_DB_USER	数据库用户名
TOOLJET_DB_PASS	数据库密码
TOOLJET_DB_PORT	数据库端口
PGRST_JWT_SECRET	JWT 密钥，须与 PostgREST 侧一致
PGRST_HOST	PostgREST 数据库主机

两点使用提示：

• 自动建库：启用该功能后，TOOLJET_DB 指定的数据库名会在服务器启动过程中自动创建（适用于所有生产部署方式）；若需手动触发，可在 ToolJet 服务端执行 npm run db:create。
• 连接串形式：若希望使用连接字符串且连接不支持 SSL，可使用 TOOLJET_DB_URL，格式为 postgres://username:password@hostname:port/database_name?sslmode=disable。

完整的变量清单与说明同样维护在 env-vars.md 与 tooljet-database.md 中。在 Docker Compose 部署下，PostgREST 容器会以 postgrest/postgrest:v12.0.2 镜像运行，并通过 PGRST_SERVER_PORT=80、PGRST_DB_PRE_CONFIG=postgrest.pre_config 等变量接入（参见 docker-compose-db.yaml）。

功能价值

启用后，ToolJet Database 允许你：在仅组织内可访问的安全数据库中维护数据表；以类电子表格的界面编辑、搜索、过滤、排序数据；像使用任何其他数据源一样快速编写查询构建应用（无需额外搭建）；将数据库 Schema 导出为 JSON 文件；通过主键（Primary Keys） 唯一标识记录、通过外键（Foreign Keys） 建立表间关联并维护引用完整性。

可选功能二：开启 Marketplace（插件市场）

ToolJet Marketplace 允许用户为工作区安装自定义插件（数据源），实现与 ToolJet 的深度集成。它同样是 opt-in 功能，需要显式开启。

启用方式

在 .env 文件中添加：

ENABLE_MARKETPLACE_FEATURE=true

本地运行 ToolJet 时，需要在启动服务器之前先构建好 marketplace，确保所有插件可用。此外还有两个辅助变量：

变量	说明
ENABLE_MARKETPLACE_FEATURE	true 或 false，功能总开关
ENABLE_MARKETPLACE_DEV_MODE	true 或 false，开发者插件调试模式

权限要求：只有管理员（Administrator） 角色可以访问 Marketplace 页面。

使用流程

1. 进入市场：登录后点击仪表盘左下角的设置图标，在菜单中选择 Marketplace。页面包含 Installed（已安装）与 Marketplace（市场）两个标签页。
2. 安装插件：在 Marketplace 标签页浏览可用插件列表，点击插件卡片上的 Install 按钮，安装完成后状态会从 Install 变为 Installed。
3. 使用插件：进入仪表盘的 Data sources（数据源） 标签页，滚动到 Plugins 分组，即可看到所有已安装的 Marketplace 插件，将其配置为数据源使用。

仓库的 marketplace/plugins 目录内置了大量插件包（如 anthropic、openai、github、gmail、salesforce 等），每个插件包都遵循统一的结构（package.json、lib 源码、README.md、icon.svg 等），安装后即可作为新的数据源类型出现在工作区中。更详细的插件开发与安装说明可参考 build-plugin-for-marketplace.md。

弃用项：Docker Compose 自动 SSL 部署被移除

V2 还包含一项明确的弃用声明：

Docker Compose 部署中带自动 SSL（auto SSL）的部署方式已被弃用（deprecated）。

即旧版文档（1.x.x）中「Docker 部署 + 自动 SSL」的组合不再推荐使用。如果你此前依赖该方式提供 HTTPS，升级 V2 前应提前规划替代方案（例如在 Docker Compose 前放置独立的反向代理/负载均衡器来终结 TLS，再以 HTTP 转发到 ToolJet 服务），避免升级后证书自动续期与入口 TLS 中断。

升级前的检查清单

结合 V2 的变更点，升级前建议逐项核对：

1. 确认功能需求：是否需要 ToolJet Database 或 Marketplace？不需要则保持默认关闭，减少配置面与资源占用。
2. 准备环境变量：如需开启可选功能，提前准备好 ENABLE_TOOLJET_DB、TOOLJET_DB_*、PGRST_JWT_SECRET、ENABLE_MARKETPLACE_FEATURE 等变量并写入 .env（参考 env-vars.md）。
3. 生成密钥：使用 openssl rand -hex 32 生成 PGRST_JWT_SECRET（若此前已有则保持一致即可）。
4. 处理弃用项：若当前使用 Docker Compose 自动 SSL 部署，提前切换到外部反向代理方案。
5. 预留迁移窗口：为首次启动的数据迁移预留足够时间，迁移期间不要强制中断服务。
6. 升级后验证：服务就绪后，登录确认多页面应用创建正常、多环境切换可用，并逐一验证已开启的可选功能是否生效。

帮助与支持

升级过程中如遇问题：可加入 ToolJet 的 Slack 社区 寻求帮助，或发送邮件至 [e-mail]；如果确认是 Bug，请在 GitHub Issues 中提交问题反馈。此外，V2 的完整变更细节可通过 ToolJet 官方发布的 changelog 查看（仓库根目录的 update-version.js 等脚本可用于版本管理场景）。

本文涉及的关键参考文件汇总：

• V2 迁移指南原文
• 环境变量参考
• Docker Compose 部署指南
• ToolJet Database 概览
• Marketplace 概览
• 多页面概念说明
• 数据迁移配置
• 内置 PostgreSQL 的 Docker Compose 模板