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

在 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再谈 RedisOpenShift 上的 ToolJet 部署有几个前置依赖官方文档在开头就做了明确交代PostgreSQL 必须手动准备ToolJet 使用 PostgreSQL 作为持久化存储用于保存用户、应用、数据源等核心数据。OpenShift 部署不会替你创建这套主数据库需要先在集群内或集群外准备好一个可用的 PostgreSQL 实例。Redis 内置与外部化的取舍ToolJet 自带内置 Redis用于多人协同编辑multiplayer editing和后台任务background jobs。但在多 Podmulti-pod部署下官方建议改用外部 Redis 实例否则各个 Pod 之间无法共享协同编辑与任务队列状态。这一点的背景也可以在仓库中找到印证deploy/openshift/deployment.yaml 中replicas: 2即默认就是双副本滚动更新RollingUpdate部署因此多 Pod 场景是 OpenShift 部署的常态外部 Redis 基本属于必选项。第一步配置核心环境变量主数据库与安全密钥在部署前需要在 .env 文件中准备以下变量TOOLJET_HOSTEndpoint url LOCKBOX_MASTER_KEYgenerate using openssl rand -hex 32 SECRET_KEY_BASEgenerate using openssl rand -hex 64 PG_USERusername PG_HOSTpostgresql-instance-ip PG_PASSpassword PG_DBtooljet_production各变量的作用如下依据 setup/env-vars.mdTOOLJET_HOSTToolJet 对外可访问的公开 URL例如https://app.tooljet.ai所有回调、链接与请求分发都依赖它。LOCKBOX_MASTER_KEY32 字节十六进制字符串用于加密数据源凭据datasource credentials用openssl rand -hex 32生成。SECRET_KEY_BASE64 字节十六进制字符串用于加密会话 Cookie用openssl rand -hex 64生成。PG_USER/PG_HOST/PG_PASS/PG_DBPostgreSQL 的用户名、主机地址、密码与数据库名。文档示例使用tooljet_production作为数据库名。PG_PORTPostgreSQL 端口默认5432需要时另行指定。更多环境变量请查阅 环境变量文档其中还包含DATABASE_URL连接串格式如postgres://PG_USER:PG_PASSPG_HOST:5432/PG_DB?sslmodedisable、PG_DB_OWNERfalse关闭自动建库与扩展创建、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:latestimagePullPolicy: Always容器启动参数为[npm, run, start:prod]即直接以生产模式启动 ToolJet 服务端。资源配额limits为内存 2000Mi、CPU 2000mrequests为内存 1000Mi、CPU 1000m。就绪探针readinessProbe 通过 HTTP GET 访问/api/health端口 3000initialDelaySeconds: 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_PLATFORMopenshift标记部署平台同时设置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-deploymentDeployment与postgresqlDeploymentConfig之间的连线即代表二者建立的依赖关系后续滚动更新、流量路由都会依据该拓扑关系进行。ToolJet Database 与 PostgREST3.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_dbTOOLJET_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_HOSTlocalhost:3001 PGRST_LOG_LEVELinfo PGRST_DB_PRE_CONFIGpostgrest.pre_config PGRST_SERVER_PORT3001 PGRST_DB_URI PGRST_JWT_SECRET各变量要点PGRST_DB_URI必需数据库连接串PostgREST 靠它暴露数据库为 REST API必须显式设置。PGRST_JWT_SECRETJWT 密钥缺失时 PostgREST 拒绝认证。PGRST_LOG_LEVELinfo日志级别。PGRST_DB_PRE_CONFIGpostgrest.pre_config预配置 schema。PGRST_HOST/PGRST_SERVER_PORTPostgREST 服务监听地址与端口示例为localhost:3001。仓库中的 deploy/kubernetes/postgrest.yaml 展示了 PostgREST 的完整部署形态使用postgrest/postgrest:v12.0.2镜像容器端口 3000PGRST_DB_URI与PGRST_JWT_SECRET通过 Secretserver注入key 为pgrst_db_uri并配套一个tooljet-postgrest-service对外暴露服务——OpenShift 部署可参照该结构规划 PostgREST 与 ToolJet 主服务的网络连通。PGRST_DB_URI 格式PGRST_DB_URI的格式如下PGRST_DB_URIpostgres://TOOLJET_DB_USER:TOOLJET_DB_PASSTOOLJET_DB_HOST:5432/TOOLJET_DB即postgres://TOOLJET_DB_USER:TOOLJET_DB_PASSTOOLJET_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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考