ToolJet 在 Kubernetes 上部署实战：从 PostgreSQL 准备、Secret 配置到 PostgREST 与 LTS 升级

发布时间：2026/9/12 1:04:35来源：尧图网络

ToolJet 在 Kubernetes 上部署实战从 PostgreSQL 准备、Secret 配置到 PostgREST 与 LTS 升级【免费下载链接】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 官方 Kubernetes 部署文档见 docs/versioned_docs/version-2.50.0-LTS/setup/kubernetes.md为主体结合仓库内 deploy/kubernetes 目录下的真实清单文件完整讲解在任意 Kubernetes 集群上部署 ToolJet 的全流程包括外部 PostgreSQL 数据库的准备、serverSecret 的创建、Deployment 与 Service 的配置、ToolJet Database 所需的 PostgREST 部署以及从旧版本升级到最新 LTS 版本的前置条件。读完本文你将获得一份可直接落地、可复制运行的 Kubernetes 部署清单并理解每个核心环境变量与清单字段背后的实际作用。一、部署前置条件手动准备 PostgreSQL 数据库ToolJet 使用 PostgreSQL 作为持久化存储用于保存用户、应用定义等核心数据。官方明确表示只支持 PostgreSQL不计划支持 MySQL 等其他数据库因此部署的第一步是在集群外部或集群内手动准备一个可用的 PostgreSQL 实例。推荐使用云厂商托管的 PostgreSQL 服务EKS 场景推荐 RDSAKS 场景推荐 Azure Database for PostgreSQLGKE 场景推荐 Cloud SQL具体的最低数据库版本等要求可参考系统要求文档中的 Database Software 部分由于 ToolJet 容器自身不做数据库初始化托管请务必确认数据库已创建好、网络可达能被集群内 Pod 访问并记录下主机、端口、库名、用户名与密码供后续 Secret 配置使用。二、创建名为server的 Kubernetes SecretToolJet 要求将敏感配置通过名为server的 Kubernetes Secret 注入到容器中。官方要求的核心变量共 10 个环境变量用途说明TOOLJET_DBToolJet Database内部数据库的数据库名TOOLJET_DB_HOSTToolJet Database 的主机地址TOOLJET_DB_USERToolJet Database 的用户名TOOLJET_DB_PASSToolJet Database 的密码PG_HOSTToolJet 主存储 PostgreSQL 的主机地址PG_DBToolJet 主存储 PostgreSQL 的数据库名PG_USERToolJet 主存储 PostgreSQL 的用户名PG_PASSToolJet 主存储 PostgreSQL 的密码SECRET_KEY_BASE用于会话/令牌签名的基础密钥务必使用强随机值LOCKBOX_KEY用于数据加密的密钥对应部署清单中的LOCKBOX_MASTER_KEY完整的环境变量说明与更多可选配置项如TOOLJET_HOST、ENABLE_TOOLJET_DB、PGRST_*系列等请查阅环境变量参考。一种创建方式如下--from-literal仅用于示意生产环境建议使用--from-file或外部 Secret 管理工具避免密钥进入 shell 历史kubectl create secret generic server \ --from-literalpg_hostpostgres-host \ --from-literalpg_dbpostgres-db \ --from-literalpg_userpostgres-user \ --from-literalpg_passwordpostgres-password \ --from-literalsecret_key_baserandom-string \ --from-literallockbox_keyrandom-string \ --from-literaltj_hosthttps://your-tooljet-domain \ --from-literalpgrst_db_uripostgres-connection-uri-for-tooljet-db \ --from-literaltooljet_db_user... \ --from-literaltooljet_db_pass...注意 Secret 的key 名称必须与 Deployment 清单中secretKeyRef.key完全对应。仓库中的 deploy/kubernetes/deployment.yaml 实际引用的小写键名为pg_host、pg_user、pg_password、pg_db、lockbox_key、secret_key_base、tj_host、pgrst_db_uri等创建 Secret 时请按下表对齐否则 Pod 会因取不到环境变量而启动失败。三、创建 ToolJet Deployment官方提供的部署清单模板可直接下载后应用kubectl apply -f deploy/kubernetes/deployment.yaml3.1 清单字段逐项解析仓库中 deploy/kubernetes/deployment.yaml 的默认模板包含以下关键配置可直接对照调整副本与更新策略replicas: 2采用RollingUpdatemaxUnavailable: 1、maxSurge: 1保证滚动升级过程中始终有实例可用镜像tooljet/tooljet-ce:latest社区版imagePullPolicy: Always确保每次拉取最新镜像企业版EE请替换为tooljet/tooljet:EE-LTS-*系列 tag启动命令args: [npm, run, start:prod]即容器以生产模式启动服务端私有镜像仓库若使用私有镜像需提前创建docker-secret并配置imagePullSecrets资源配额limits为内存 2000Mi、CPU 2000mrequests为内存 1000Mi、CPU 1000m——这是官方模板的参考值生产环境应根据实际负载调整GKE 模板中则为 1000Mi/500m端口容器监听3000端口ToolJet 服务端默认端口就绪探针对/api/health发起 HTTP GETinitialDelaySeconds: 10、periodSeconds: 5、failureThreshold: 6——这意味着服务只有在健康检查通过后才会被纳入 Service 流量可用于后续排查启动问题环境变量来源大部分敏感变量通过secretKeyRef从serverSecret 注入非敏感变量如DEPLOYMENT_PLATFORM: k8s、TOOLJET_DB: tooljet_db则直接以字面量写入。3.2 必须修改的占位符清单中预留了以下占位值应用前务必替换为你的实际配置replace_with_tooljet_db_user、replace_with_tooljet_db_host、replace_with_tooljet_db_passToolJet Database 的凭据replace_with_postgrest_hostPostgREST 服务的地址见下文第五节replace_jwt_secret_herePostgREST 的 JWT 密钥TOOLJET_HOST通过 Secret 的tj_host键注入需设为你的对外访问域名如https://tooljet.your-domain.com。重要提示官方明确说明该模板只是起点不一定适合生产环境。请下载清单后按需修改副本数、资源配额与环境变量再执行kubectl apply。四、验证部署状态并创建 Service4.1 验证 Pod 是否正常运行kubectl get pods等待 Pod 进入Running且READY 1/1状态若 Pod 一直未就绪可通过kubectl logs pod-name查看启动日志结合就绪探针的/api/health路径确认服务端是否成功连接数据库并完成迁移。4.2 创建 Service 对外暴露服务官方提供了基于 AWS 负载均衡器的 Service 模板kubectl apply -f deploy/kubernetes/service.yaml仓库中的 deploy/kubernetes/service.yaml 采用LoadBalancer类型将集群内3000端口映射为443端口对外提供 HTTPS 访问并通过注解挂载 AWS ACM 证书service.beta.kubernetes.io/aws-load-balancer-ssl-cert: certificate-arn指定 SSL 证书 ARNservice.beta.kubernetes.io/aws-load-balancer-backend-protocol: http后端走 HTTPselector: component: tooljet与 Deployment 的 Pod 标签对应。不同云厂商的差异Service 的创建方式因云厂商而异仓库为各大平台都准备了现成清单EKS直接使用上述 AWS LoadBalancer 模板详见 deploy/kubernetes/service.yamlAKS使用 deploy/kubernetes/AKS/service.yaml其中包含 Azure 专用的azure-load-balancer-resource-group、azure-dns-label-name注解与loadBalancerIP字段通过kubectl apply -f deployment.yaml,service.yaml一并应用GKE需要依次准备 GKE/certificate.yaml托管 SSL 证书、GKE/service.yamlNodePort 型tj-service8080→3000和 GKE/ingress.yamlIngress 绑定全局静态 IPtj-static-ip与托管证书将tooljet.your-domain.com路由到 Service并先通过gcloud compute addresses create tj-static-ip --global预留静态 IP再执行kubectl apply -f certificate.yaml,deployment.yaml,service.yaml,ingress.yamlGKE 托管证书的签发可能需要几分钟请耐心等待。4.3 拆分部署前端客户端可选如果你希望把 ToolJet 的 Web 客户端单独托管在 Firebase、Netlify 等静态托管服务上而不是与后端一起部署可以参考仓库文档 setup 目录下的部署入口了解客户端单独部署的配置方式。五、处理自签名 HTTPS 证书如果 ToolJet 需要连接使用自签名 HTTPS 证书的端点例如自建数据源、内部 API请务必设置NODE_EXTRA_CA_CERTS环境变量指向包含证书的绝对路径。在 Kubernetes 中通常的做法是将证书文件放入 Secret通过volumeMounts挂载到容器内的固定路径在 Deployment 的env中设置NODE_EXTRA_CA_CERTS/path/to/ca-cert.crt。这样 Node.js 运行时才会信任该自签名证书避免请求被 TLS 校验拦截。六、启用 ToolJet Database部署 PostgRESTToolJet Database 是 ToolJet 内置的数据库功能。要使用它必须额外部署一个PostgREST服务它负责以 REST 接口方式查询 ToolJet Database。相关环境变量的完整配置请参考环境变量参考中的 ToolJet Database 章节。6.1 部署 PostgRESTkubectl apply -f deploy/kubernetes/postgrest.yaml仓库中的 deploy/kubernetes/postgrest.yaml 是一个组合清单包含Deploymenttooljet-postgrest镜像postgrest/postgrest:v12.0.2监听3000端口单副本滚动更新PGRST_DB_URI从 Secret 的pgrst_db_uri键读取 PostgreSQL 连接串PGRST_JWT_SECRETJWT 签名密钥注意该模板中此值同样引用pgrst_db_uri键生产环境建议为pgrst_jwt_secret单独配置独立键避免与连接串混用PGRST_LOG_LEVEL: info、PGRST_DB_PRE_CONFIG: postgrest.pre_config。Servicetooljet-postgrest-serviceNodePort类型80端口转发到容器的3000端口供 ToolJet 服务端在集群内访问。6.2 更新 ToolJet DeploymentPostgREST 就绪后需要在 ToolJet 的 Deployment 中补充以下环境变量并重新 applyTOOLJET_DB、TOOLJET_DB_HOST、TOOLJET_DB_USER、TOOLJET_DB_PASSToolJet Database 的库与凭据PGRST_HOSTPostgREST 服务的集群内地址如tooljet-postgrest-service.default.svc.cluster.local或直接使用 Service 名PGRST_JWT_SECRET与 PostgREST 配置一致的 JWT 密钥同时将ENABLE_TOOLJET_DB设为trueGKE 模板中该变量以注释形式预留取消注释即可。七、升级到最新 LTS 版本ToolJet 每 35 个月发布一个新的 LTS 版本且每个 LTS 版本的生命周期end-of-life至少为 18 个月。LTS 镜像 tag 遵循LTS-前缀的命名规范例如tooljet/tooljet:EE-LTS-latest。如果是全新安装直接使用最新版本镜像即可本升级指南不适用。升级到最新 LTS 版本前必须满足两个前置条件完整备份数据库升级过程可能涉及数据迁移务必在操作前对 PostgreSQL 做全量备份防止数据丢失版本跳跃限制低于v2.23.0-ee2.10.2的旧版本必须先升级到 v2.23.0-ee2.10.2再继续升级到目标 LTS 版本不能跨版本直接跳升。更详细的升级步骤请参考专门的升级到 LTS 指南。八、小结与故障排查要点一次完整的 Kubernetes 部署路径可概括为准备 PostgreSQL → 创建serverSecret → apply Deployment → 验证 Pod → 创建 Service/Ingress → 可选部署 PostgREST 启用 ToolJet Database。基于仓库清单可以归纳出几个常见问题的排查方向Pod 一直未就绪检查serverSecret 的键名是否与清单secretKeyRef完全一致pg_host、pg_user、pg_password、pg_db、lockbox_key、secret_key_base等确认 PostgreSQL 是否可达、账号权限是否足够执行迁移健康检查失败就绪探针固定探测/api/health见 deploy/kubernetes/deployment.yaml若该接口无响应多半是服务端启动阶段异常通过kubectl logs查看应用日志外部访问不通确认 Service 的selector与 Deployment 的 Pod 标签component: tooljet匹配云厂商 LB/Ingress 的证书与域名是否正确绑定。各云平台EKS/AKS/GKE的完整差异化清单均可在仓库 deploy/kubernetes 目录下找到按需取用并修改占位值即可。【免费下载链接】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），仅供参考

网站建设高端定制企业官网