ToolJet 环境变量完全指南:Server、Client 与 PostgREST 的配置详解

原创2026-09-09 21:58:251,976 阅读
文章标签:低代码前端后端企业应用

ToolJet 环境变量完全指南:Server、Client 与 PostgREST 的配置详解

ToolJet 是一个开源的低代码应用构建平台,其服务端(server)与前端客户端(client)在启动时都依赖一组环境变量来获得正确的运行参数。本文以 docs/docs/setup/env-vars.md 为骨架,系统梳理 ToolJet 全部环境变量的含义、默认值与配置要点,并结合仓库中的 .env.example、deploy/docker/.env.internal.example 以及服务端源码(server/src)解释这些变量在底层是如何被消费的。读完本文,你将能独立完成一次自托管 ToolJet 的完整环境配置,并理解每个必填变量缺失时会产生的影响。

环境变量文件从哪来

仓库根目录提供了 .env.example,其头部注释明确说明:

Create .env from this example file and replace values for the environment.

即把 .env.example 复制为 .env 后再逐项填写真实值即可。该示例文件同时提示:测试环境需要单独的 .env.test。此外,Docker 部署场景还提供了两份精简示例:

在 docker-compose 场景下,还需注意 .env.example 中的说明:如需 Enterprise Edition,应在执行 docker-compose up 前设置 TOOLJET_EDITION=ee(默认 ce)。

ToolJet Server 必填环境变量

服务端要能正常启动并对外提供服务,以下四组变量缺一不可。

TOOLJET_HOST(必填)

变量 描述
TOOLJET_HOST ToolJet 客户端的公网地址(例如 https://app.tooljet.com)

该变量被广泛用于服务端生成跳转链接、邮件链接与 API 响应。从源码可以看到它在多个关键位置被读取:server/src/helpers/utils.helper.ts 中的 getTooljetHost() 会回退到 process.env.TOOLJET_HOST,并据此判断当前部署是否使用 HTTPS(TOOLJET_HOST.startsWith('https'),用于 Cookie 的 secure 标记判定);server/src/modules/email/service.ts 则用它拼接邮件中的 ToolJet 地址(会先剥离末尾斜杠)。

LOCKBOX_MASTER_KEY(必填)

ToolJet 服务端使用 Lockbox 机制加密数据源(datasource)凭据,需要设置一个 32 字节的十六进制字符串 作为 LOCKBOX_MASTER_KEY。

底层实现在 server/src/modules/encryption/service.ts:加密使用 aes-256-gcm(nonce 12 字节、附带 16 字节 GCM 认证标签),而实际的列级密钥通过 HKDF 从 LOCKBOX_MASTER_KEY 派生(#computeAttributeKey,哈希算法 sha384),每个表/列使用独立的派生密钥——这是从 Ruby on Rails 时代的 Lockbox gem 迁移到 NestJS 时保留的行为。文件头部的注释还特别提醒:不要修改该函数的签名,因为它被大量数据迁移脚本(如 server/data-migrations/1709618105785-EncryptValuesForExistingOrganizationConstants.ts)依赖。

生成命令:openssl rand -hex 32

SECRET_KEY_BASE(必填)

服务端使用一个 64 字节的十六进制字符串 加密会话 Cookie。

在 server/src/modules/session/module.ts 中,JwtModule.registerAsync 将 SECRET_KEY_BASE 直接作为 JWT 签名密钥(secret: config.get<string>('SECRET_KEY_BASE')),即所有会话 JWT 的签发与校验都依赖该值。更换或丢失它会导致所有已登录用户的会话失效,因此应妥善保管且避免在运行期变更。

生成命令:openssl rand -hex 64

PostgreSQL 数据库配置(必填)

ToolJet 服务端使用 PostgreSQL 作为主数据库:

变量 描述
PG_HOST PostgreSQL 主机
PG_DB 数据库名
PG_USER 用户名
PG_PASS 密码
PG_PORT 端口

这些变量在 server/ormconfig.ts 的 buildConnectionOptions() 中被消费:port 取 +data.PG_PORT || 5432(默认 5432),连接池上限 PG_POOL_MAX 默认 25,并支持 ORM_LOGGING 控制 TypeORM 日志。两点实用说明:

  • docker-compose 场景:PG_HOST 可直接填 postgres(服务名),由 Docker 内部 DNS 解析;
  • 连接串方式:如果使用连接 URL 且数据库不支持 SSL,可用 DATABASE_URL 并写成 postgres://username:password@hostname:port/database_name?sslmode=disable。源码中 dbSslConfig() 会在存在 DATABASE_URL 时自动附加 ssl: { rejectUnauthorized: false }。

ToolJet Server 可选环境变量

禁用数据库与扩展自动创建(可选)

默认情况下 ToolJet 会根据 PG_DB 自动创建数据库,并可能尝试创建 PostgreSQL 扩展(如 pgcrypto,见 server/ormconfig.ts 中的 uuidExtension: 'pgcrypto'),这要求 PG 用户具备 CREATEDB 权限。若无法授予该权限,可将 PG_DB_OWNER 设为 false 关闭自动创建,改为手动建库。

检查更新与遥测(可选)

变量 默认 说明
CHECK_FOR_UPDATES 启用 每 24 小时向 ToolJet 服务器请求最新产品更新,设为 0 可关闭
DISABLE_TOOLJET_TELEMETRY 启用 每 24 小时上报用户计数,设为 true 可关闭

对应实现位于 server/src/modules/meta/service.ts(更新检查)与实例设置常量定义 server/src/modules/instance-settings/constants/index.ts。

评论功能开关(可选)

变量 值
COMMENT_FEATURE_ENABLE true 或 false

控制画布上是否允许添加评论。配置前提是先在设置中启用多人实时编辑(multiplayer editing,对应 .env.example 中的 ENABLE_MULTIPLAYER_EDITING=true)。

Marketplace 插件开发模式(可选)

变量 值
ENABLE_MARKETPLACE_DEV_MODE true 或 false

开启后允许开发者构建(开发调试)Marketplace 插件。

用户会话过期时间(可选)

变量 描述
USER_SESSION_EXPIRY 会话过期时间,单位为分钟;默认 10 天。例如设为 120 即 2 小时

server/src/modules/session/util.service.ts 中通过 configService.get('USER_SESSION_EXPIRY') 读取该值并换算成过期时刻(乘以 60 * 1000 毫秒)写入会话。示例 deploy/docker/.env.internal.example 中给出参考值 2880(2 天)。

ToolJet 数据库(必填)

ToolJet Database 是内置的数据存储能力,通过 PostgREST 对外提供 REST API,其连接参数如下:

变量 说明
TOOLJET_DB 数据库名,默认值 tooljet_db
TOOLJET_DB_HOST 数据库主机
TOOLJET_DB_USER 数据库用户名
TOOLJET_DB_PASS 数据库密码
TOOLJET_DB_PORT 数据库端口
PGRST_JWT_SECRET PostgREST 用于校验 JWT 的密钥
PGRST_HOST PostgREST 主机
PGRST_DB_PRE_CONFIG 对应 postgrest.pre_config(默认值见 .env.example)

要点:

  • 在所有生产部署方案中,TOOLJET_DB 指定的库名会在服务端启动时被用来创建新数据库;也可手动执行 npm run db:create(在 ToolJet server 目录下);
  • 与主库类似,支持连接串变量 TOOLJET_DB_URL,格式 postgres://username:password@hostname:port/database_name?sslmode=disable;
  • 底层连接同样定义于 server/ormconfig.ts 的 buildToolJetDbConnectionOptions(),其中 TOOLJET_DB_PORT 默认 5432,连接池 TOOLJET_DB_PG_POOL_MAX 默认 25,并可通过 TOOLJET_DB_STATEMENT_TIMEOUT(默认 60000ms)控制语句超时。

SERVER_HOST(可选)

当后端(API 服务)部署在独立服务器时,可在此指定主机名作为反向代理目标;不设置时默认值为 server。

HIDE_ACCOUNT_SETUP_LINK(可选)

设为 true 时,管理员在用户管理页面将看不到“账户设置”链接。前提是已配置 SMTP,以便新用户能收到欢迎邮件。

DISABLE_SIGNUPS(可选)

设为 true 可关闭公开注册,仅允许通过邀请加入新用户。注意:注册页面仍会展示,只是无法成功提交表单。该开关仅在多工作区(Multi-Workspace)特性启用时生效(见 .env.example 注释)。服务端由 server/src/modules/onboarding/guards/signup-disable.guard.ts 在注册流程中强制执行。

SERVE_CLIENT 与 SUB_PATH(可选)

  • SERVE_CLIENT:默认未设置,服务端会在 / 端点托管前端客户端;设为 false 可关闭该行为(此时前端需单独构建部署);
  • SUB_PATH:当 ToolJet 部署在域名子路径时设置,必须带尾部 /,且仅在服务端托管前端时生效。

服务端对 SERVE_CLIENT 的消费可见于 server/src/helpers/utils.helper.ts(生产环境下 TOOLJET_SERVER_URL 缺省时按 SERVE_CLIENT !== 'false' 回退),前端构建侧则见 frontend/src/index.ejs 中对 SERVE_CLIENT !== 'false' 的判断。

SMTP 邮件配置(可选)

ToolJet 使用 SMTP 发送邮件(例如向工作区添加新用户时的邀请邮件)。

  • Enterprise Edition:v2.62.0 起必须在 UI 中配置 SMTP(见 docs/docs/setup/env-vars.md 说明),.env 中的 SMTP 变量不再被读取;从 v2.62.0 之前升级时,旧变量会自动映射到 UI 配置中,确认无误后可从 .env 移除;
  • Community Edition:继续使用以下环境变量:
变量 描述
DEFAULT_FROM_EMAIL 发件邮箱(示例默认 hello@tooljet.io)
SMTP_USERNAME 用户名
SMTP_PASSWORD 密码
SMTP_DOMAIN 域名或主机
SMTP_PORT 端口

Slack 与 Google OAuth(可选)

若需以 Slack 作为数据源,需创建 Slack App 并配置:

变量 描述
SLACK_CLIENT_ID Slack App 的 client id
SLACK_CLIENT_SECRET Slack App 的 client secret

若需访问 Google Sheets 等数据源,需在 Google Cloud Console 创建 OAuth 凭据:

变量 描述
GOOGLE_CLIENT_ID client id
GOOGLE_CLIENT_SECRET client secret

Google Maps(可选)

若需要使用 Maps 组件,需创建 Google Maps API key:

变量 描述
GOOGLE_MAPS_API_KEY Google Maps API key

可观测性:APM 与 Sentry(可选)

变量 描述
APM_VENDOR 应用性能监控厂商,目前支持 sentry
SENTRY_DNS Sentry DSN,用于将事件上报到对应项目
SENTRY_DEBUG 是否打印 Sentry 日志,true/false,默认 false
RELEASE_VERSION 设置后,支持按 release 分组的 APM 提供商会跟踪该版本
TOOLJET_SERVER_URL 服务端 URL(如 https://server.tooljet.com),用于 CSP 头与 APM trace 信息

NODE_EXTRA_CA_CERTS(可选)

当需要信任自定义 CA 以建立 HTTPS 连接时,配置该变量指向 PEM 格式的 CA 证书文件绝对路径(如 /ToolJet/ca/cert.pem)。文件需为 PEM 格式,可包含多个证书。

密码重试限制(可选)

默认密码最大重试次数为 5,超过后账户将被锁定:

变量 描述
DISABLE_PASSWORD_RETRY_LIMIT true 时关闭重试次数检查(无限制)
PASSWORD_RETRY_LIMIT 自定义重试上限(默认 5)

实例级 SSO(可选)

变量 描述
SSO_GOOGLE_OAUTH2_CLIENT_ID Google OAuth client id
SSO_GIT_OAUTH2_CLIENT_ID GitHub OAuth client id
SSO_GIT_OAUTH2_CLIENT_SECRET GitHub OAuth client secret
SSO_GIT_OAUTH2_HOST 自托管 GitHub 时的 OAuth 主机名
SSO_ACCEPTED_DOMAINS 支持 SSO 认证的邮箱域名(逗号分隔)
SSO_DISABLE_SIGNUPS 认证用户不存在时禁止其注册

FORWARD_RESTAPI_COOKIES(可选)

默认服务端不会在 REST API 请求中转发 Cookie;设为 true 可开启。该选项仅自托管版本可用。

ToolJet Client 环境变量

当前端客户端单独构建部署时,需要以下变量:

TOOLJET_SERVER_URL(按需必填)

变量 描述
TOOLJET_SERVER_URL ToolJet 服务端 URL(如 https://server.tooljet.com)

frontend/src/index.jsx 中会读取运行时注入的 window.public_config.TOOLJET_SERVER_URL 来确定后端地址,因此前端单独部署时必须正确注入该值。

TOOLJET_SERVER_PORT(可选)

用于本地开发,设置后服务端地址将变为 http://localhost:<TOOLJET_SERVER_PORT>(例如 3000)。

ASSET_PATH(按需必填)

当客户端静态资源需要从其他位置(如 CDN)加载时设置。可以是绝对路径,也可以是相对主 HTML 文件的相对路径,例如 https://app.tooljet.ai/。

SERVE_CLIENT(可选)

默认构建产物设计为随 ToolJet 服务端一同托管;若客户端单独使用,需将 SERVE_CLIENT 设为 false。

PostgREST Server(必填)

PostgREST 是 ToolJet Database 的 REST API 网关,其必填变量:

变量 描述
PGRST_JWT_SECRET 用于校验客户端 JWT 的密钥
PGRST_DB_URI ToolJet 数据库连接串
PGRST_LOG_LEVEL 日志级别,通常为 info

两点硬性要求:

  • PGRST_JWT_SECRET 可用 openssl rand -hex 32 生成;若未指定,PostgREST 将拒绝所有认证请求;
  • PGRST_DB_URI 必须使用格式:postgres://[USERNAME]:[PASSWORD]@[HOST]:[PORT]/[DATABASE]。

如需调整 PostgREST 的其他行为,可参考其官方配置文档(PostgREST configuration)。

审计日志文件路径(可选)

变量 描述
LOG_FILE_PATH 审计日志落盘路径,例如 tooljet/log/tooljet-audit.log

设置后,每次产生新的审计日志都会追加写入该文件(对应后端审计日志模块的落盘能力)。

ToolJet Apps 相关变量

ENABLE_PRIVATE_APP_EMBED(可选)

默认只允许嵌入公开应用;设为 true 后允许嵌入私有 ToolJet 应用。

注意:该选项仅从 ToolJet Enterprise Edition 2.8.0 起、Community/云版本 2.10.0 起可用。

相关的还有 .env.example 中列出的 DISABLE_APP_EMBED(设为 true 时公开与私有应用的嵌入均被禁止)与 ENABLE_CORS(前端与后端分离部署时设为 true)。

配置默认语言(可选)

通过 LANGUAGE 变量可设置 ToolJet 的默认语言:

变量 描述
LANGUAGE 语言代码,例如 fr

支持的语言及代码:English(en)、Français(fr)、Español(es)、Italiano(it)、Bahasa Indonesia(id)、Українська(uk)、Русский(ru)、Deutsch(de)。云版本不支持该设置。

其他值得关注的变量(来自 .env.example)

除文档主线外,仓库根目录 .env.example 还沉淀了一批生产常用变量,补充说明如下:

  • Workflow/Worker:WORKER=true 启用 BullMQ 任务处理与调度加载;TOOLJET_QUEUE_DASH_PASSWORD 为工作流面板密码;TOOLJET_WORKFLOW_SANDBOX_BYPASS=true 可绕过 Python 执行的 nsjail 沙箱(仅限 AWS Fargate、Render 等不支持 SYS_ADMIN 能力的平台,且会失去代码隔离);
  • Redis:REDIS_HOST、REDIS_PORT(默认 6379)、REDIS_USERNAME、REDIS_PASSWORD、REDIS_DB、REDIS_TLS,docker-compose 下 REDIS_HOST 填服务名 redis;
  • SCIM:SCIM_ENABLED、SCIM_BASIC_AUTH_USER、SCIM_BASIC_AUTH_PASS、SCIM_HEADER_AUTH_TOKEN 用于身份供给;
  • Git 对象缓存:DISABLE_GIT_OBJECT_CACHE、GIT_OBJECT_CACHE_TTL_DAYS(默认 14 天)、GIT_OBJECT_CACHE_MAX_GB(默认 2GB)、GIT_OBJECT_CACHE_DIR(默认系统临时目录,K8s 中建议指向持久卷);
  • 日志调优:TRANSACTION_LOGGING_LEVEL(development=trace / production=info / test=error)、CUSTOM_QUERY_LOGGING_LEVEL、SLOW_QUERY_LOGGING_THRESHOLD(默认 1ms);
  • 可观测性:ENABLE_METRICS=true 暴露 Prometheus /metrics 端点;
  • PAT:PAT_SESSION_EXPIRY(分钟)、PAT_EXPIRY(天)控制个人访问令牌有效期。

小结

ToolJet 的部署配置可以概括为一句话:先满足必填项(TOOLJET_HOST、LOCKBOX_MASTER_KEY、SECRET_KEY_BASE、PG 连接、ToolJet DB 与 PostgREST),再按需开启可选能力(SSO、SMTP、OAuth、可观测性、嵌入与本地化)。以仓库 .env.example 为起点复制并逐项填写,对照本文的默认值与格式说明即可避免启动期常见问题。若需验证服务端对这些变量的实际消费方式,可直接查阅 server/src/modules/encryption/service.ts、server/src/modules/session/module.ts 与 server/ormconfig.ts。

登录后查看全文
ToolJet