ToolJet 环境变量完全指南：Server、Client 与 PostgREST 的配置详解-酒店常州论坛

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

【免费下载链接】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 是一个开源的低代码应用构建平台，其服务端（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 部署场景还提供了两份精简示例：

deploy/docker/.env.internal.example：内部部署（internal）模式，PG 主机等指向 docker-compose 内部服务名；
deploy/docker/.env.external.example：外部数据库接入模式。

在 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。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析