ToolJet 使用 Docker Compose 部署完整指南：内置与外部 PostgreSQL 双方案、备份恢复与 LTS 升级实战-港品优选

ToolJet 使用 Docker Compose 部署完整指南：内置与外部 PostgreSQL 双方案、备份恢复与 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 Docker Compose 部署实战指南。围绕 setup/docker.md 文档展开，覆盖「内置 PostgreSQL 数据库」与「外部托管 PostgreSQL 数据库」两种官方部署模式，并深入讲解.env关键变量、internal.sh/external.sh脚本的密钥生成逻辑、数据库备份与恢复流程，以及升级到最新 LTS 版本的前置要求。读完本文，你将能够在任意 Linux 服务器上独立完成 ToolJet 的生产级 Docker 部署，并掌握后续维护升级的关键操作。

部署架构总览

ToolJet 是一个用于构建内部工具、仪表盘与业务应用的开放源代码平台。其服务端基于 NestJS，客户端为 React 前端，二者在容器中由tooljet/tooljet-ce镜像统一承载，并以npm run start:prod启动（见 deploy/docker/docker-compose-db.yaml）。

ToolJet 的生产部署依赖以下基础设施：

PostgreSQL 数据库：用于存储应用定义、数据源（加密后的）凭据以及用户认证数据；
PostgREST 服务：当启用 ToolJet Database（内置数据存储）时，由它对外提供 RESTful API；
Redis：在 CE 镜像中作为内置 sidecar 由入口脚本自动拉起，用于缓存与会话支撑（见 docker/ce-entrypoint.sh）。

Docker Compose 部署提供两种官方方案，你可以根据是否有现成的托管数据库进行选择：

内置 PostgreSQL（推荐）：Compose 文件中直接编排postgres:13官方镜像，开箱即用；
外部 PostgreSQL：适用于已使用 AWS RDS、Google Cloud SQL 等托管服务的场景，仅需提供数据库连接信息。

两种方案对应的 Compose 文件与初始化脚本均可在仓库的 deploy/docker 目录下找到，下文将逐一展开。

前置条件：安装 Docker 与 Docker Compose

在开始部署前，请先在服务器上安装 Docker Engine 与 Docker Compose。官方安装文档对应：

Docker Engine 安装：https://docs.docker.com/engine/install/
Docker Compose 安装：https://docs.docker.com/compose/install/

两个实用建议（官方文档同样强调）：

为 Docker 配置非 root 运行：参照 https://docs.docker.com/engine/install/linux-postinstall/ 将当前用户加入docker组，避免每次执行都加sudo；
Linux 服务器上的 sudo 场景：如果你的docker命令需要 sudo 权限，将本文中的docker-compose up -d替换为sudo docker-compose up -d即可。

方案一：使用内置 PostgreSQL 数据库（推荐）

1. 下载生产 Compose 文件并创建数据目录

在服务器上执行以下命令，从官方部署源拉取生产环境的 Compose 文件，并将其重命名为标准的docker-compose.yaml，同时创建 PostgreSQL 数据挂载目录：

curl -LO https://tooljet-deployments.s3.us-west-1.amazonaws.com/docker/docker-compose-db.yaml mv docker-compose-db.yaml docker-compose.yaml mkdir postgres_data

该 Compose 文件在仓库中的对应版本为 deploy/docker/docker-compose-db.yaml，其中几个关键编排点值得留意：

服务	说明
`tooljet`	使用`tooljet/tooljet-ce:latest`镜像，`restart: always`保证崩溃自动拉起，通过`env_file: .env`注入配置，映射宿主机`80`端口
`postgres`	使用`postgres:13`官方镜像，容器名取`${PG_HOST}`的值，数据卷以 bind 方式挂载到当前目录下的`postgres_data`
`postgrest`	使用`postgrest/postgrest:v12.0.2`，`depends_on: postgres`保证启动顺序，供 ToolJet Database 使用

注意内置方案的数据卷是 bind mount 到./postgres_data的（见 deploy/docker/docker-compose-db.yaml），这正是第一步需要mkdir postgres_data的原因，目录不存在会导致卷挂载失败。

2. 生成 .env 文件与安全密钥

下载.env模板与初始化脚本，并将模板重命名为.env：

curl -LO https://tooljet-deployments.s3.us-west-1.amazonaws.com/docker/.env.internal.example curl -LO https://tooljet-deployments.s3.us-west-1.amazonaws.com/docker/internal.sh && chmod +x internal.sh mv .env.internal.example .env && ./internal.sh

internal.sh的作用是自动生成一套生产级安全密钥与数据库口令，避免你手动填写易被爆破的弱密码。其源码位于 deploy/docker/internal.sh，核心逻辑如下：

LOCKBOX_MASTER_KEY：通过openssl rand -hex 32生成 32 字节十六进制串。ToolJet 服务端用它加密所有数据源凭据（lockbox 加密体系），对应变量说明见 env-vars.md；
SECRET_KEY_BASE：通过openssl rand -hex 64生成 64 字节十六进制串，用于加密会话 Cookie；
PGRST_JWT_SECRET：通过openssl rand -hex 32生成，供 PostgREST 做 JWT 认证；
PG_PASS/TOOLJET_DB_PASS：通过openssl rand -base64 12 | tr -d '/+' | cut -c1-16生成 16 位随机数据库密码；
PGRST_DB_URI：自动拼接为postgres://postgres:<password>@postgresql/tooljet_db写入.env。

脚本使用awk以幂等方式更新.env：变量已存在则替换，不存在则追加，因此可以安全地重复执行。如果某个密钥已生成，再次运行时会提示 "already exists" 并跳过，避免覆盖已有配置。

如果你希望手工生成这些密钥（例如不用脚本），等价命令为：openssl rand -hex 32（LOCKBOX_MASTER_KEY / PGRST_JWT_SECRET）与openssl rand -hex 64（SECRET_KEY_BASE）。

3. 启动容器

docker-compose up -d

ToolJet 服务端入口脚本 docker/ce-entrypoint.sh 在容器启动时会依次完成：

若检测到 Redis 未运行，则使用内置配置拉起 Redis sidecar；
加载容器内.env（如果存在）；
根据DATABASE_URL是否设置，通过wait-for-it.sh等待 PostgreSQL 就绪（超时 300 秒）；
执行npm run db:setup:prod（生产构建）完成数据库 schema 初始化；
最后exec "$@"启动npm run start:prod主进程。

因此docker-compose up -d后，即使看到容器短暂退出重启，也往往是等待数据库初始化的正常过程，可通过docker-compose logs -f观察日志确认最终状态。

4. 配置 TOOLJET_HOST 与自定义域名（可选）

TOOLJET_HOST是 ToolJet 客户端对外访问的公共 URL，为必填项，可在.env中修改。它既可以是服务器的公网 IPv4 地址，也可以是你绑定的自定义域名：

TOOLJET_HOST=http://12.34.56.78 # 或 TOOLJET_HOST=https://tooljet.yourdomain.com

注意事项：

TOOLJET_HOST必须以http://或https://开头，否则客户端无法正确解析资源路径；
如果使用了自定义域名，请在 DNS 中添加一条指向服务器 IP 的A 记录；
更多可配置环境变量请参考 env-vars.md，例如USER_SESSION_EXPIRY（会话过期时间，默认 2880 分钟即 10 天）、DISABLE_SIGNUPS（限制注册）、CHECK_FOR_UPDATES（更新检查）等。

方案二：使用外部 PostgreSQL 数据库

如果你希望复用 AWS RDS、Google Cloud SQL 等托管 PostgreSQL，或者已有独立维护的数据库实例，选择本方案。区别在于 Compose 文件不再编排postgres服务，仅保留tooljet与可选的postgrest（见 deploy/docker/docker-compose.yaml）。

1. 准备外部数据库

先在云服务商或自建环境中创建一个 PostgreSQL 数据库实例，并确保：

数据库对 ToolJet 服务器可达（安全组 / 防火墙放行对应端口）；
你手头有数据库的用户名、密码、主机名、数据库名四项信息；
该账号具备建库与创建扩展的权限（ToolJet 默认会在启动时基于PG_DB创建数据库并尝试创建 PostgreSQL 扩展；若无法授予 CREATEDB 权限，可设置PG_DB_OWNER=false并手动初始化，见 env-vars.md）。

2. 下载外部数据库版 Compose 文件

curl -LO https://tooljet-deployments.s3.us-west-1.amazonaws.com/docker/docker-compose.yaml

3. 生成 .env 并录入外部数据库凭据

curl -LO https://tooljet-deployments.s3.us-west-1.amazonaws.com/docker/.env.external.example curl -LO https://tooljet-deployments.s3.us-west-1.amazonaws.com/docker/external.sh && chmod +x external.sh mv .env.external.example .env && ./external.sh

与内置方案不同，external.sh（源码见 deploy/docker/external.sh）会交互式提示你输入外部数据库信息：

Enter PostgreSQL database username: Enter PostgreSQL database hostname: Enter PostgreSQL database password: Enter PostgreSQL database name:

脚本随后自动完成三件事：

将输入值写入.env的PG_USER、PG_HOST、PG_PASS、PG_DB；
把 PG 前缀的值同步复制到 ToolJet Database 使用的TOOLJET_DB_USER、TOOLJET_DB_HOST、TOOLJET_DB_PASS；
拼接PGRST_DB_URI=postgres://<user>:<pass>@<host>/tooljet_db写入.env。

注意，外部方案中PG_HOST必须填外部数据库的真实主机名（如db.example.com），而不能像内置方案那样填postgresql这个 Compose 网络内的服务名。

4. 启动容器

docker-compose up -d

5. 自签名 HTTPS 证书场景（可选）

如果 ToolJet 需要连接使用了自签名 HTTPS 证书的端点，请确保在.env中设置NODE_EXTRA_CA_CERTS环境变量，指向包含 CA 证书的 PEM 文件绝对路径（如/ToolJet/ca/cert.pem）。该文件需为 PEM 格式，可包含多张证书，相关说明见 env-vars.md。

关键环境变量速查表

两种方案共用的.env模板位于 deploy/docker/.env.internal.example 与 deploy/docker/.env.external.example，下面汇总部署阶段最关键的变量：

变量	必填	说明
`TOOLJET_HOST`	✅	客户端公共 URL，必须以`http(s)://`开头
`LOCKBOX_MASTER_KEY`	✅	32 字节十六进制串，用于加密数据源凭据
`SECRET_KEY_BASE`	✅	64 字节十六进制串，用于加密会话 Cookie
`PG_HOST`	✅	PostgreSQL 主机；内置方案填`postgresql`
`PG_DB`	✅	数据库名（内置模板默认`tooljet_production`）
`PG_USER`/`PG_PASS`	✅	数据库用户名 / 密码
`TOOLJET_DB_HOST/USER/PASS`	启用 ToolJet DB 时	内置数据存储的连接信息
`PGRST_DB_URI`	启用 ToolJet DB 时	PostgREST 连接串，格式`postgres://user:pass@host/db`
`PGRST_JWT_SECRET`	启用 ToolJet DB 时	PostgREST JWT 密钥；不设置则 PostgREST 拒绝认证请求
`CHECK_FOR_UPDATES`	否	每 24 小时检查更新，设`false`/`0`关闭（默认开启）
`DISABLE_TOOLJET_TELEMETRY`	否	每 24 小时上报用户数遥测，设`true`关闭（默认开启）
`DEPLOYMENT_PLATFORM`	否	标记部署平台，模板中为`docker`
`USER_SESSION_EXPIRY`	否	会话过期时间（分钟），默认`2880`（10 天）

完整变量说明请参阅 env-vars.md，其中还包含 SMTP 邮件、Google OAuth、SSO、Sentry APM、多语言（LANGUAGE）等可选配置。

Docker 备份与恢复（仅限内置 PostgreSQL）

对于内置 PostgreSQL 方案，官方提供了backup-restore.sh一键脚本，同时支持备份与恢复：

curl -LO https://tooljet-deployments.s3.us-west-1.amazonaws.com/docker/backup-restore.sh && chmod +x backup-restore.sh ./backup-restore.sh

运行脚本后会进入交互式菜单，选择备份或恢复操作。备份的本质是对postgres容器中的数据库执行pg_dump导出，恢复则通过psql导入，因此恢复目标环境需要有可用的 PostgreSQL 服务。

建议：无论采用哪种方案，在升级版本或重大变更前，都应对数据库执行一次完整备份。外部 PostgreSQL 方案可直接使用云厂商的快照或pg_dump工具完成备份。

升级到最新 LTS 版本

ToolJet 的 LTS（长期支持）版本大约每 3～5 个月发布一次，每个 LTS 版本的生命周期至少 18 个月。镜像标签遵循LTS-前缀加版本号的命名约定，例如tooljet/tooljet:EE-LTS-latest。

适用范围：本指南仅适用于已部署旧版本的存量安装；如果是全新安装，直接使用最新镜像即可，无需执行升级流程。

升级前置要求

务必先对数据库做完整备份，防止升级过程中数据丢失；
版本门槛：运行版本早于v2.23.0-ee2.10.2的用户，必须先升级到该版本，再继续升级到 LTS 版本，不能跨版本直接跳升。

升级操作要点

升级的核心思路是替换镜像标签后重建容器：

# 1. 先在 .env 或 docker-compose.yaml 中将镜像 tag 更新为目标 LTS 版本 # 2. 拉取新镜像并重建容器 docker-compose pull tooljet docker-compose up -d --remove-orphans

由于 ToolJet 依赖数据库迁移机制（仓库 server/migrations 与 server/data-migrations 中保存了大量历史迁移脚本），新版本首次启动时服务端会自动执行新增迁移。因此升级后请重点观察日志中的迁移执行情况，确认应用正常进入监听状态。若升级过程遇到问题，可借助备份进行回滚恢复。

部署后的验证与排障

完成部署后，建议按以下顺序验证：

访问 Web 界面：浏览器打开TOOLJET_HOST对应的地址（如http://<服务器IP>），应出现 ToolJet 的登录/注册页面；
检查容器状态：docker-compose ps确认tooljet、postgres（内置方案）、postgrest均为运行状态；
查看服务日志：docker-compose logs -f tooljet，确认npm run start:prod成功监听80端口（Compose 中设置了SERVE_CLIENT: "true"，由服务端直接托管前端静态资源）；
首次启动等待：数据库初始化与迁移可能耗时数分钟，期间容器可能显示Restarting，属正常现象。

常见问题速查：

现象	排查方向
容器反复重启	查看日志是否卡在等待 PostgreSQL（`wait-for-it`超时 300 秒），确认`PG_HOST`与端口可达
访问出现 502/404	确认`TOOLJET_HOST`是否以`http(s)://`开头，`SERVE_CLIENT`是否为`true`
ToolJet Database 不可用	确认`ENABLE_TOOLJET_DB`、`PGRST_DB_URI`、`PGRST_JWT_SECRET`均已正确设置
80 端口被占用	修改 deploy/docker/docker-compose-db.yaml 中的端口映射为`8080:80`等自定义端口

小结

本文完整梳理了 ToolJet 基于 Docker Compose 的两种生产部署路径：内置 PostgreSQL 方案适合快速起步（推荐），外部 PostgreSQL 方案适合已有托管数据库的团队；同时给出了密钥生成脚本、环境变量速查、备份恢复以及 LTS 升级的完整操作指引。部署过程中涉及的所有 Compose 编排、初始化脚本与入口逻辑均可直接在仓库的 deploy/docker、docker/ce-entrypoint.sh 与 docker/ce-production.Dockerfile 中查看源码，便于你按需定制自己的部署方案。

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

企业官网建设流程全解析