ToolJet Helm 图表部署指南：Kubernetes 集群安装、values 参数与数据库初始化详解

本文基于 ToolJet 仓库中的 Helm 部署文档 deploy/helm/README.md，完整讲解如何通过 Helm v3 将 ToolJet 社区版（CE）安装到 Kubernetes 集群：从 Chart 依赖、helm install 操作步骤，到 values.yaml 中应用资源配置、HPA 伸缩阈值、Secret 凭据与内置 PostgreSQL 子图表的逐项说明，并结合模板源码（Deployment/Service/Secret/HPA）分析各参数如何最终作用于容器运行时。读完本文，你能够独立完成一次可登录的 ToolJet Helm 部署，并理解每个关键配置项背后的实现。

Chart 概览与依赖结构

该 Chart 位于仓库的 deploy/helm/ 目录下，deploy/helm/README.md 明确指出：这是一个相对基础（rudimentary）的部署方案，并自带一个内置的 PostgreSQL 服务器。Chart 的元信息定义在 deploy/helm/Chart.yaml 中：

apiVersion: v2
name: tooljet
description: none

type: application
version: 1.2.2
appVersion: "v1.2.2"

dependencies:
- name: postgresql
  version: "11.1.3"
  repository: "https://charts.bitnami.com/bitnami"

关键点：

• version: 1.2.2 是 Chart 版本，appVersion: "v1.2.2" 是应用镜像版本，两者会直接用于拼装容器镜像 tag（后文 Deployment 模板中可见 tooljet/tooljet-ce:{{ .Chart.AppVersion }}）；
• 唯一的子依赖是 Bitnami 官方仓库的 postgresql 11.1.3 Chart，因此首次安装前必须先执行 helm dependency update 拉取该子图表包；deploy/helm/Chart.lock 中记录了依赖的 digest（sha256:e743082c...）与生成时间，用于锁定依赖版本。

模板目录 deploy/helm/templates/tooljet/ 下共四个清单文件，分别对应四个 Kubernetes 资源：

模板文件	资源类型	作用
deployment.yaml	Deployment	运行 ToolJet 服务容器，注入数据库与密钥环境变量
service.yaml	Service	在集群内暴露 3000 端口
secret.yaml	Secret	存放数据库凭据与加密主密钥
hpa.yaml	HorizontalPodAutoscaler	按 CPU/内存阈值自动伸缩副本数

安装步骤（继承官方文档的完整操作流）

按照 deploy/helm/README.md 的官方步骤，完整安装流程共 5 步：

第 1 步：克隆仓库并进入 Helm 目录

# 克隆 ToolJet 仓库后进入本 Chart 所在目录
cd deploy/helm

第 2 步：更新 Chart 依赖

helm dependency update

该命令会按 Chart.yaml 的 dependencies 声明从 Bitnami 仓库拉取 postgresql 11.1.3 子图表。

第 3 步（推荐但可选）：修改 values.yaml 中的配置

官方文档建议至少修改 values.yaml 中的用户名、密码与持久化（persistence）等值。各参数的详细说明见下文「values.yaml 关键参数」一节。

第 4 步：执行安装

helm install -n $NAMESPACE --create-namespace $RELEASE .

其中 $NAMESPACE 与 $RELEASE 需替换为你自己的命名空间与 release 名称。命名参数 --create-namespace 会在命名空间不存在时自动创建。

第 5 步：初始化（seed）数据库

官方文档特别强调：安装完成后数据库尚未被 seed。需要进入 tooljet Pod，在 /app 目录下执行：

# 进入 tooljet Pod 的 shell
kubectl exec -it <tooljet-pod> -n $NAMESPACE -- bash
# 在容器内的 /app 目录下执行
cd /app
npm run db:seed

seed 完成后即可用文档给出的默认账号登录：

• 用户名：[e-mail]
• 密码：password

这组默认凭据并非写在 Helm 模板里，而是来自服务器端的 seed 脚本。从源码看，server/scripts/seeds.ts 中定义了 SEED_DEFAULTS（email: '[e-mail]'、password: 'password'、workspaceName: 'My workspace'），并且支持通过环境变量 SEED_EMAIL、SEED_PASSWORD、SEED_FIRST_NAME、SEED_LAST_NAME、SEED_WORKSPACE 覆盖默认值。也就是说，如果你不想使用文档中的默认账号，可以在 Deployment 中注入这些环境变量再执行 seed。npm run db:seed 本身对应 server/package.json 中的脚本定义：ts-node -r tsconfig-paths/register --transpile-only ./scripts/seeds.ts。

values.yaml 关键参数逐项说明

deploy/helm/values.yaml 的结构分两大块：apps.tooljet（ToolJet 应用本体）和 postgresql（内置数据库子图表）。以下按原文档中的取值逐条说明，并补充模板中的实际消费位置。

apps.tooljet：服务、资源与密钥

apps:
  tooljet:
    service:
      type: ClusterIP
      host: "http://localhost"
    deployment:
      resources:
        requests:
          memory: 1024Mi
          cpu: 1
        limits:
          memory: 2048Mi
          cpu: 2
    hpa:
      min: 1
      max: 1
      threshold:
        cpu: 0.75
        ram: 768Mi
    secret:
      name: tooljet-server
      data:
        pg_user: "postgresql"
        pg_password: "postgresql"
        pg_db: "tooljet"
        lockbox_key: "0123456789ABCDEF"
        secret_key_base: "0123456789ABCDEF"

各参数与模板中的映射关系：

• service.type（默认 ClusterIP）与 service.host：service.type 直接渲染进 service.yaml 的 spec.type，端口固定为 3000/TCP；service.host 则以环境变量 TOOLJET_HOST 的形式注入容器，用于服务端生成对外可访问的应用 URL（在集群内使用时通常要改为你的实际域名或 Ingress 地址）。
• deployment.resources.requests/limits：渲染进 deployment.yaml 的 resources 段，默认请求 1 CPU / 1024Mi 内存，上限 2 CPU / 2048Mi 内存。注意 Node 服务端在镜像内设置了 NODE_OPTIONS=--max-old-space-size=4096（见 docker/server.Dockerfile），所以 limits 内存若调低需留意 V8 堆与容器内存的匹配关系。
• hpa.min / hpa.max：当前默认均为 1，即事实上的固定单副本；hpa.threshold.cpu: 0.75 与 hpa.threshold.ram: 768Mi 是伸缩触发阈值，渲染进 hpa.yaml 的 targetAverageValue。
• secret.name（默认 tooljet-server）：Secret 的名称，Deployment 通过它引用数据库凭据与密钥。
• secret.data 五个键是整组最关键的安全凭据：
  • pg_user / pg_password / pg_db：数据库连接三元组，必须与下方 postgresql.auth 及库名保持一致（默认用户名 postgresql、库名 tooljet）；
  • lockbox_key / secret_key_base：服务端加密主密钥与会话密钥，默认值为 16 位十六进制占位串，生产环境务必替换为随机生成的 16 进制字符串（README 中"Patch the values (usernames & passwords, persistence, ...)"即主要指这里）。

secret.yaml 模板将这五个值通过 b64enc 编码后写入 Opaque Secret：

data:
  pg_user: {{ .Values.apps.tooljet.secret.data.pg_user | b64enc | quote }}
  pg_password: {{ .Values.apps.tooljet.secret.data.pg_password | b64enc | quote }}
  pg_db: {{ .Values.apps.tooljet.secret.data.pg_db | b64enc | quote }}
  lockbox_key: {{ .Values.apps.tooljet.secret.data.lockbox_key | b64enc | quote }}
  secret_key_base: {{ .Values.apps.tooljet.secret.data.secret_key_base | b64enc | quote }}

这意味着凭据以明文写在 values.yaml 中，由 Helm 负责编码落盘——生产环境建议改用外部密钥管理方案覆盖，而不要在 values 文件中提交真实密码。

postgresql：内置数据库子图表

postgresql:
  enabled: true
  postgresqlExtendedConf:
    maxConnections: 1024
  replication:
    enabled: false
  auth:
    # postgresPassword: "postgres"
    username: "postgresql"
    password: "postgresql"
  primary:
    persistence:
      enabled: true
      size: 8Gi
      storageClass: ""

这些值透传给 Bitnami PostgreSQL 子图表：

• enabled: true 启用内置数据库；置为 false 时需自行提供 PG 端点，并将 PG_HOST 等变量改为外部实例（对应修改 deployment.yaml 中渲染的服务地址）；
• postgresqlExtendedConf.maxConnections: 1024：通过自定义 postgresql.conf 片段把最大连接数从 Bitnami 默认值提升到 1024，这是 ToolJet 这类连接密集型服务端在单库场景下常见的调优点；
• replication.enabled: false：不搭建主从复制，符合该 Chart "rudimentary" 的定位；
• auth.username / auth.password：数据库超级用户凭据，必须与 apps.tooljet.secret.data.pg_user / pg_password 一致，否则 ToolJet 无法连接数据库；
• primary.persistence：默认开启，容量 8Gi，storageClass: "" 表示使用集群默认 StorageClass。自建集群若无默认 StorageClass，需要在此显式指定，否则 PostgreSQL Pod 会卡在 PVC 未绑定状态。

Deployment 模板：镜像、探针与环境变量

deploy/helm/templates/tooljet/deployment.yaml 是理解运行时行为的核心，关键片段如下：

containers:
  - name: tooljet
    image: "tooljet/tooljet-ce:{{ .Chart.AppVersion }}"
    imagePullPolicy: IfNotPresent
    args: ["npm", "run", "start:prod"]
    ports:
      - containerPort: 3000

• 镜像 tag 直接取自 Chart.yaml 的 appVersion，即当前为 tooljet/tooljet-ce:v1.2.2。升级应用版本时需要同步更新 Chart 元信息与镜像来源；
• 容器以 npm run start:prod 启动。对照 server/package.json，该脚本等价于 NODE_ENV=production node dist/src/main，即直接运行 NestJS 编译产物；镜像的构建流程（Node 22 构建 + debian:12-slim 运行层、WORKDIR /app）见 docker/server.Dockerfile，这也解释了 README 中 seed 操作为什么是在容器的 /app 目录下执行。

健康检查探针配置在 deployment.yaml：

readinessProbe:
  httpGet:
    port: 3000
    path: /api/health
  successThreshold: 1
  initialDelaySeconds: 10
  periodSeconds: 5
  failureThreshold: 6

即每 5 秒请求一次 /api/health，初始延迟 10 秒，连续 6 次失败则标记为未就绪（约 40 秒的容忍窗口）。

环境变量注入是"values 参数 → 运行时行为"的最后一环（deployment.yaml）：

环境变量	取值来源	说明
TOOLJET_HOST	apps.tooljet.service.host	对外访问地址，用于拼接应用链接
PG_HOST	{{ .Release.Name }}-postgresql	拼接 release 前缀 + 内置 PG 服务名，因此它与 helm install 时用的 $RELEASE 强耦合
PG_USER / PG_PASS / PG_DB	Secret（pg_user/pg_password/pg_db）	数据库连接三元组，经 secretKeyRef 注入
LOCKBOX_MASTER_KEY	Secret（lockbox_key）	数据加密主密钥
SECRET_KEY_BASE	Secret（secret_key_base）	会话密钥
DEPLOYMENT_PLATFORM	固定值 k8s:helm	标识部署平台，服务端据此区分运行环境

从源码结构看，PG_HOST 使用 .Release.Name 拼接 Bitnami PostgreSQL 的服务名，因此同一个命名空间内重复安装时务必保持 release 名一致，否则会出现 PG 服务寻址失败。

Service 与 HPA 模板

• service.yaml 是最薄的清单：type 取自 values（默认 ClusterIP），暴露 3000 端口并选择 app: tooljet 标签的 Pod。若需从集群外访问，可把 service.type 改为 NodePort/LoadBalancer，或自行叠加 Ingress 资源（本 Chart 未包含 Ingress 模板）；
• hpa.yaml 使用 autoscaling/v2beta1 API，目标为同名的 tooljet Deployment，同时以 CPU（targetAverageValue: 0.75）与内存（768Mi）两个 Resource 指标驱动伸缩，副本数在 min~max（默认 1~1）之间。需要留意的是：autoscaling/v2beta1 属于较旧的 HPA API，在较新的 Kubernetes 集群版本中该 API 已被移除，因此在 1.25 之后的集群上部署前，建议先验证节点端点对该 API 的可用性，必要时评估升级到 autoscaling/v2 的等价写法（此为对模板 API 版本的适用性提示，非当前仓库已实现的修改）。

验证与后续检查清单

部署完成并按 README 执行 db:seed 后，可按以下顺序验证：

1. kubectl get pods -n $NAMESPACE：确认 tooljet 与 $RELEASE-postgresql 两组 Pod 均就绪（readiness 探针即 /api/health，未就绪说明健康检查未通过）；
2. kubectl port-forward 或临时修改 Service 类型后访问 http://<host>/:3000，使用 [e-mail] / password（或你通过 SEED_* 环境变量自定义的凭据）登录；
3. 检查 values.yaml 中 lockbox_key、secret_key_base、数据库密码、持久化容量是否已按生产要求替换——README 明确将这一步列为"推荐但可选"，但对生产部署而言它是必要项。

小结

ToolJet 官方的 Helm 部署方案用"一张最小化应用模板 + 一个 Bitnami PostgreSQL 子图表"实现了集群内一键安装：Chart.yaml 锁定版本与依赖，values.yaml 集中管理资源、HPA 与凭据，四个模板文件把参数渲染为 Deployment/Service/Secret/HPA 资源，最终由 npm run db:seed 完成数据库初始化并产出默认账号。理解 secret.data 与 postgresql.auth 的对应关系、PG_HOST 与 release 名的耦合、以及 TOOLJET_HOST 的作用，是把这个"基础版"部署改造为生产可用部署的三个关键点。