企业官网建设流程全解析

在 OpenShift 上部署 ToolJet 3.0：从 YAML 导入到 ToolJet Database 的完整指南

【免费下载链接】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 3.0 LTS 官方部署文档为主体，讲解如何在 Red Hat OpenShift 集群上完整部署 ToolJet：从手工准备 PostgreSQL 数据库、生成安全密钥、通过开发者控制台导入部署与服务 YAML，到建立应用与数据库的拓扑连线，再到配置 ToolJet Database 与 PostgREST 的必备环境变量，最后介绍升级到最新 LTS 版本的前置条件。读完本文，你将掌握一套可复现、可运维的 OpenShift 部署方案，并能处理多 Pod 场景下的 Redis 外部化、自签名证书挂载等关键细节。

部署前须知：先准备 PostgreSQL，再谈 Redis

OpenShift 上的 ToolJet 部署有几个前置依赖，官方文档在开头就做了明确交代：

• PostgreSQL 必须手动准备：ToolJet 使用 PostgreSQL 作为持久化存储，用于保存用户、应用、数据源等核心数据。OpenShift 部署不会替你创建这套主数据库，需要先在集群内（或集群外）准备好一个可用的 PostgreSQL 实例。
• Redis 内置与外部化的取舍：ToolJet 自带内置 Redis，用于多人协同编辑（multiplayer editing）和后台任务（background jobs）。但在多 Pod（multi-pod）部署下，官方建议改用外部 Redis 实例，否则各个 Pod 之间无法共享协同编辑与任务队列状态。

这一点的背景也可以在仓库中找到印证：deploy/openshift/deployment.yaml 中replicas: 2，即默认就是双副本滚动更新（RollingUpdate）部署，因此多 Pod 场景是 OpenShift 部署的常态，外部 Redis 基本属于必选项。

第一步：配置核心环境变量

主数据库与安全密钥

在部署前，需要在 .env 文件中准备以下变量：

TOOLJET_HOST=<Endpoint url> LOCKBOX_MASTER_KEY=<generate using openssl rand -hex 32> SECRET_KEY_BASE=<generate using openssl rand -hex 64> PG_USER=<username> PG_HOST=<postgresql-instance-ip> PG_PASS=<password> PG_DB=tooljet_production

各变量的作用如下（依据 setup/env-vars.md）：

• TOOLJET_HOST：ToolJet 对外可访问的公开 URL（例如https://app.tooljet.ai），所有回调、链接与请求分发都依赖它。
• LOCKBOX_MASTER_KEY：32 字节十六进制字符串，用于加密数据源凭据（datasource credentials），用openssl rand -hex 32生成。
• SECRET_KEY_BASE：64 字节十六进制字符串，用于加密会话 Cookie，用openssl rand -hex 64生成。
• PG_USER/PG_HOST/PG_PASS/PG_DB：PostgreSQL 的用户名、主机地址、密码与数据库名。文档示例使用tooljet_production作为数据库名。
• PG_PORT：PostgreSQL 端口，默认5432，需要时另行指定。

更多环境变量请查阅 环境变量文档，其中还包含DATABASE_URL连接串格式（如postgres://PG_USER:PG_PASS@PG_HOST:5432/PG_DB?sslmode=disable）、PG_DB_OWNER=false（关闭自动建库与扩展创建）、REDIS_HOST/REDIS_PORT/REDIS_USER/REDIS_PASSWORD（外部 Redis v6.2）等可选项。

ToolJet AI 特性白名单

:::warning 要启用 ToolJet 部署中的 AI 功能，必须将https://api-gateway.tooljet.ai加入白名单。 :::

如果部署环境启用了网络策略、出口防火墙或代理白名单，请务必放行该域名，否则 AI 相关能力将无法工作。

第二步：通过开发者控制台导入 YAML

登录并进入 +Add

登录 OpenShift 开发者（Developer）仪表盘后，点击+Add标签页，选择Import YAML，从本地导入 YAML 文件。

:::note 当一次性输入一个或多个文件时，使用---分隔每个定义（manifest）。 :::

导入 deployment.yaml

将下面的命令输出的内容复制粘贴到在线编辑器中：

curl -LO https://tooljet-deployments.s3.us-west-1.amazonaws.com/openshift/deployment.yaml

说明：该命令用于获取官方发布的 OpenShift 部署清单；仓库中 deploy/openshift/deployment.yaml 提供了同结构的可参考版本。

导入 service.yaml

继续将下面的文件内容粘贴到在线编辑器中（多个文件之间用---分隔）：

curl -LO https://tooljet-deployments.s3.us-west-1.amazonaws.com/openshift/service.yaml

仓库中对应的 deploy/openshift/service.yaml 定义了一个名为tooljet-server的LoadBalancer类型 Service，监听 TCP 443 端口并转发到容器的 3000 端口，selector 为component: tooljet，与应用 Deployment 的标签保持一致。

如上图所示，在 "Import YAML" 编辑器中粘贴全部 YAML 内容后，点击Create按钮创建资源。

从 OpenShift 清单看部署细节

结合 deploy/openshift/deployment.yaml 可以更完整地理解这套清单的实际行为：

• 镜像与启动命令：使用tooljet/tooljet-ce:latest，imagePullPolicy: Always，容器启动参数为["npm", "run", "start:prod"]，即直接以生产模式启动 ToolJet 服务端。
• 资源配额：limits为内存 2000Mi、CPU 2000m；requests为内存 1000Mi、CPU 1000m。
• 就绪探针：readinessProbe 通过 HTTP GET 访问/api/health（端口 3000），initialDelaySeconds: 10、periodSeconds: 5、failureThreshold: 6，只有健康检查通过后流量才会接入。
• 凭据注入方式：PG_HOST、PG_USER、PG_PASS、PG_DB、LOCKBOX_MASTER_KEY、SECRET_KEY_BASE、TOOLJET_HOST均通过secretKeyRef从名为server的 Secret 中读取（对应 key 为pg_host、pg_user、pg_password、pg_db、lockbox_key、secret_key_base、tj_host），而不是明文写在 YAML 里。
• OpenShift 专属适配：DEPLOYMENT_PLATFORM=openshift标记部署平台；同时设置HOME=/home/appuser，注释明确说明"需要在 OpenShift 平台为任意用户（arbitrary user）定义 HOME 目录，npm 命令才能正常工作"——这是 OpenShift 随机 UID 安全模型下的常见适配。
• ToolJet Database 相关占位：清单中已预留TOOLJET_DB、TOOLJET_DB_USER、TOOLJET_DB_HOST、TOOLJET_DB_PASS、PGRST_HOST、PGRST_JWT_SECRET等变量，值为replace_with_*占位符，部署前必须替换为真实值（详见下文"ToolJet Database"章节）。

自签名证书场景

:::info 如果 ToolJet 需要连接自签名 HTTPS 端点，请确保设置NODE_EXTRA_CA_CERTS环境变量为包含证书的绝对路径。可以利用 Kubernetes Secret 将证书文件挂载到容器中。 :::

在启用 mTLS 或使用自建 CA 的内部服务（如私有数据源、内部 API）时，这是保证 TLS 握手成功的关键配置。

第三步：在拓扑视图中建立连接

创建完成后，导航到Topology标签页，使用可视化连接器在tooljet-deployment与postgresql之间建立连接，如下图所示。

拓扑视图中tooljet-deployment（Deployment）与postgresql（DeploymentConfig）之间的连线即代表二者建立的依赖关系，后续滚动更新、流量路由都会依据该拓扑关系进行。

ToolJet Database 与 PostgREST：3.0 起为强制要求

为什么必须部署

从 ToolJet 3.0 开始，部署 ToolJet Database 是强制要求，否则迁移（migration）可能会中断。ToolJet Database 是 ToolJet 托管的数据库，用于更快地构建应用并轻松管理数据，具体能力可参考 ToolJet Database 文档。同时建议阅读 ToolJet 3.0 自托管升级指南，了解本次大版本涉及的破坏性变更（如动态组件名引用受限、查询与组件同名映射拆分、属性面板变量访问规则收紧、废弃组件移除等）。

必填环境变量

设置 ToolJet Database 时，以下环境变量为必填：

TOOLJET_DB= TOOLJET_DB_HOST= TOOLJET_DB_USER= TOOLJET_DB_PASS=

其中TOOLJET_DB为默认数据库名（文档示例为tooljet_db），TOOLJET_DB_HOST为数据库主机，TOOLJET_DB_USER为用户名，TOOLJET_DB_PASS为密码。补充说明：TOOLJET_DB_PORT也可用于指定端口（默认 5432）；生产部署中，TOOLJET_DB指定的数据库会在服务端启动过程中自动创建。

PostgREST 必填变量

PostgREST 用于将数据库以 REST API 形式暴露给 ToolJet，同样有以下必填环境变量：

:::tip 如果安装了 openssl，可以运行openssl rand -hex 32生成PGRST_JWT_SECRET的值。如果未指定该参数，PostgREST 将拒绝所有认证请求。:::

PGRST_HOST=localhost:3001 PGRST_LOG_LEVEL=info PGRST_DB_PRE_CONFIG=postgrest.pre_config PGRST_SERVER_PORT=3001 PGRST_DB_URI= PGRST_JWT_SECRET=

各变量要点：

• PGRST_DB_URI：必需，数据库连接串，PostgREST 靠它暴露数据库为 REST API，必须显式设置。
• PGRST_JWT_SECRET：JWT 密钥，缺失时 PostgREST 拒绝认证。
• PGRST_LOG_LEVEL=info：日志级别。
• PGRST_DB_PRE_CONFIG=postgrest.pre_config：预配置 schema。
• PGRST_HOST/PGRST_SERVER_PORT：PostgREST 服务监听地址与端口（示例为localhost:3001）。

仓库中的 deploy/kubernetes/postgrest.yaml 展示了 PostgREST 的完整部署形态：使用postgrest/postgrest:v12.0.2镜像，容器端口 3000，PGRST_DB_URI与PGRST_JWT_SECRET通过 Secretserver注入（key 为pgrst_db_uri），并配套一个tooljet-postgrest-service对外暴露服务——OpenShift 部署可参照该结构规划 PostgREST 与 ToolJet 主服务的网络连通。

PGRST_DB_URI 格式

PGRST_DB_URI的格式如下：

PGRST_DB_URI=postgres://TOOLJET_DB_USER:TOOLJET_DB_PASS@TOOLJET_DB_HOST:5432/TOOLJET_DB

即postgres://<TOOLJET_DB_USER>:<TOOLJET_DB_PASS>@<TOOLJET_DB_HOST>:5432/<TOOLJET_DB>。请确保：

• 用户名和密码与 PostgREST 数据库用户的凭据一致；
• 主机名正确（若使用 Docker Compose 内置 PostgreSQL，则为postgres）；
• 端口为 PostgreSQL 端口（默认5432）；
• 数据库名为 PostgREST 使用的数据库（示例为tooljet_db）。

:::warning务必在 ToolJet 部署之前正确完成上述配置，并且这些环境变量必须设置在 ToolJet 部署所在的同一环境中。若配置缺失或错位，迁移步骤将可能中断，部署无法正常完成。 :::

升级到最新 LTS 版本

新 LTS 版本大约每 3~5 个月发布一次，每个版本的生命周期（end-of-life）至少为 18 个月。要查看最新 LTS 版本，可访问 ToolJet Docker Hub 的 tags 页面；LTS 标签遵循LTS-前缀加版本号的命名约定，例如tooljet/tooljet:ee-lts-latest。

• 如果是全新安装，直接使用最新版本即可，无需执行本升级流程。
• 升级前必须满足以下前置条件：
  • 务必对数据库做全面备份，防止升级过程造成数据丢失；
  • 版本早于v2.23.0-ee2.10.2的用户，必须先升级到该版本，再继续升级到 LTS 版本。

常见问题与运维要点

• 多 Pod 一致性：OpenShift 清单默认replicas: 2，多人协同编辑依赖的 Redis 状态必须外部化，否则各副本间的协同会话与后台任务会相互干扰。
• Secret 优先：主库凭据与安全密钥应存放在 OpenShift Secret（如server）中，通过secretKeyRef注入，避免明文出现在 Deployment YAML 中；ToolJet Database 的占位变量（replace_with_*）在部署前必须替换为真实值。
• 自签名证书：内部服务使用自签名 HTTPS 时，务必通过NODE_EXTRA_CA_CERTS指向挂载的证书文件，并借助 Kubernetes Secret 完成证书注入。
• 健康检查：就绪探针以/api/health为判定依据，若该接口持续失败（默认 6 次探测），Pod 将不会进入就绪状态，流量也不会被路由过去。
• 升级节奏：LTS 生命周期至少 18 个月，升级前先备份数据库，并确认版本是否低于 v2.23.0-ee2.10.2 这一升级门槛。

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