ToolJet 在 AWS ECS 上的完整部署指南：任务定义、环境变量、ToolJet Database 与 Workflows 调度配置

ToolJet 在 AWS ECS 上的完整部署指南：任务定义、环境变量、ToolJet Database 与 Workflows 调度配置

【免费下载链接】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 官方 ECS 部署文档为主体，系统讲解如何通过 CloudFormation 模板、ECS Fargate 任务定义与服务编排，在 Amazon ECS 上完整部署 ToolJet 应用及其依赖组件（PostgreSQL、Redis、PostgREST、Temporal），并深入解读容器启动命令、健康检查端点与关键环境变量背后的源码实现。读完本文，你将能够独立完成 ToolJet 的 ECS 集群搭建、应用负载均衡接入、ToolJet Database 启用以及 Workflow 定时调度的容器化配置。

部署前准备：理解 ToolJet 在 ECS 上的组件依赖

在动手之前，需要先明确 ToolJet 自托管架构在 ECS 上依赖哪些基础服务。从部署文档与仓库入口脚本可以确认，一个可用的 ToolJet ECS 部署至少由以下几部分组成：

:::info 关键事实 ToolJet 的 PostgreSQL 数据库需要手动预先搭建，ECS 部署不会自动创建它。数据库相关的连接参数通过环境变量注入容器。 :::

使用 CloudFormation 模板快速起步

官方为 ECS 部署提供了两套 CloudFormation 模板，可根据自身情况选择：

一键部署所有服务（适合全新环境）：

curl -LO https://tooljet-deployments.s3.us-west-1.amazonaws.com/cloudformation/Cloudfomation-template-one-click.yml

集成到现有 VPC 或已有服务（适合已有基础设施的场景）：

curl -LO https://tooljet-deployments.s3.us-west-1.amazonaws.com/cloudformation/Cloudformation-deploy.yml

第二套模板专为"已有 ECS 服务 / 已有 VPC"的情况设计，可以无缝将 ToolJet 接入你现有的网络拓扑，避免资源重复创建。

:::note 模板只是起点。部署文档明确指出：上述配置仅为模板，你可以根据自身需要自由调整任务定义中的资源参数与环境变量。下文的分步配置即以此为基础展开。 :::

部署 Redis 服务

Redis 用于 ToolJet 的多人在线协同编辑（multiplayer editing）与后台任务（background jobs）。如果已有现成的 Redis 实例（自建或托管），可以直接复用；否则在 ECS 集群中按以下步骤创建：

1. 创建任务定义（Task definition），family 命名为redis，启动类型选择AWS Fargate，操作系统选择Linux/X86_64，网络模式为awsvpc。
2. 添加容器与镜像：容器名称redis，镜像标签务必使用Redis 6.x 系列（例如redis:6.2，见 docs/static/img/setup/ecs/ecs-2.png），端口映射为容器端口6379/ TCP 协议。
3. 创建服务：将 Redis 服务部署到与 ToolJet 应用相同的 ECS 集群中，并启用 Public IP，以便 ToolJet 容器通过公网地址访问（详见下文REDIS_HOST配置）。

部署完成后，记录 Redis 任务的公网 IP，它将在 ToolJet 容器环境变量中以REDIS_HOST的形式被引用。

部署 ToolJet 应用

ToolJet 应用的部署是整个流程的核心，分为"数据库准备 → 负载均衡 → 任务定义 → 服务创建"四个阶段。

第 1 步：准备 PostgreSQL 数据库

ToolJet 使用 PostgreSQL 作为持久化存储，保存用户与应用相关数据。你可以使用 RDS、Aurora 或自建实例，只需保证 ECS 任务可以网络访问到它，并准备好如下连接信息：主机、端口、库名、用户名与密码。

仓库佐证：部署镜像的入口脚本 docker/LTS/ee/ee-entrypoint.sh 在容器启动时会使用wait-for-it.sh等待PG_HOST:PG_PORT（默认 5432）就绪，再继续执行数据库初始化，因此数据库必须在容器启动前可访问。

第 2 步：创建目标组与 Application Load Balancer

创建目标组与应用负载均衡器（ALB），将外部流量路由到 ToolJet 容器。具体操作可参考 AWS 官方文档。需要注意：

• 健康检查端点：ToolJet 服务端暴露了/api/health，请将其配置为 ALB 健康检查路径。
• 源码佐证：健康检查路由定义在 server/src/modules/app/controller.ts，AppController同时响应GET /health与GET /api/health，返回服务健康状态；该路径也被显式排除在 CSRF Origin 校验（server/src/helpers/bootstrap.helper.ts）与 OTEL 埋点（server/src/modules/logging/constant.ts）之外，说明它是专供探活使用的轻量端点。

第 3 步：创建 ToolJet 任务定义

在预配置好的集群上创建任务定义，关键参数如下：

1. 兼容性：选择Fargate作为启动类型。
2. IAM 角色与操作系统：配置任务角色/执行角色（如ecsTaskExecutionRole），操作系统家族选择Linux。
3. 任务大小：选择3GB 内存 + 1 vCPU（见 docs/static/img/setup/ecs/ecs-4.png）。
4. 容器配置：
   • 容器名称：例如ToolJet；
   • 镜像：tooljet/tooljet:ee-latest（如升级到 LTS 则为tooljet/tooljet:ee-lts-latest）；
   • 端口映射：容器端口3000，协议TCP（见 docs/static/img/setup/ecs/ecs-5.png）。

环境变量配置：最小必需集

以下环境变量是 ToolJet 部署的必需项，建议敏感信息使用 AWS Secrets Manager 存储（参考 AWS 敏感数据文档），或将 env 文件存放在 S3 桶中通过任务定义引用（见 docs/static/img/setup/ecs/ecs-6.png）：

生成密钥的推荐方式（需要本机安装openssl）：

# LOCKBOX_MASTER_KEY：32 字节十六进制 openssl rand -hex 32 # SECRET_KEY_BASE：64 字节十六进制 openssl rand -hex 64

源码佐证：这两个密钥的用途与位数要求记录在 docs/docs/setup/env-vars.md：LOCKBOX_MASTER_KEY用于 lockbox 加密数据源凭据，SECRET_KEY_BASE用于加密会话 Cookie，二者缺一不可。

Redis 环境变量：若按上文步骤创建了 Redis 服务，还需在 ToolJet 容器中追加：

REDIS_HOST=<public ip of redis task> REDIS_PORT=6379 REDIS_USER=default REDIS_PASSWORD=

仓库佐证：入口脚本 docker/LTS/ee/ee-entrypoint.sh 会检查REDIS_HOST——若为空或为localhost则在容器内启动内置 Redis；否则视为外部 Redis，并通过wait-for-it.sh校验连通性后才继续启动。因此在 ECS 上指向独立 Redis 任务时，必须正确填写REDIS_HOST。

完整的环境变量参考（含 PostgreSQL 连接串DATABASE_URL、PG_PORT、CHECK_FOR_UPDATES、SMTP、SSO、会话过期时间等可选配置）见 docs/docs/setup/env-vars.md。

启动命令与日志配置

在容器配置中：

• 勾选Use log collection（推荐接入 CloudWatch Logs，日志组如/ecs/ToolJet）；
• Docker configuration的 Command 填写npm, run, start:prod（见 docs/static/img/setup/ecs/ecs-8.png）。

源码佐证：start:prod在 server/package.json 中定义为NODE_ENV=production node dist/src/main，即以生产模式启动 NestJS 服务端。容器启动时入口脚本还会依次执行等待数据库就绪、数据库创建与迁移等初始化步骤（docker/LTS/ee/ee-entrypoint.sh 中的db:setup:prod，其内部对应 server/package.json 的db:create:prod && db:migrate:prod）。

第 4 步：创建服务并接入负载均衡

1. 选择之前创建的集群，启动类型选择Fargate；
2. 设置服务名称（如ToolJet），起始任务数建议设为 2（保证高可用，见 docs/static/img/setup/ecs/ecs-10.png），其余保持默认；
3. 进入网络配置：选择指定的VPC、子网与安全组。务必确保安全组允许对任务 3000 端口的入站流量（见 docs/static/img/setup/ecs/ecs-11.png）；
4. 由于数据库迁移在容器启动时执行，请将Health check grace period 设置为 900 秒，给首次启动留出足够的迁移时间；
5. 选择 Application Load Balancer 选项，将目标组指定为第 2 步创建的 Target Group，健康检查端点会自动填充为/api/health。

:::info 容器首次启动包含建库、迁移、等待依赖服务就绪等多个阶段，耗时会明显长于常规探活周期。900 秒的宽限期是官方推荐的保守值，可根据实际迁移耗时调整。 :::

部署 ToolJet Database（PostgREST）

ToolJet Database 是 ToolJet 内置的数据库功能，其查询能力由PostgREST服务提供。从 ToolJet 3.0 起，部署 ToolJet Database 为强制要求，否则迁移可能失败。相关升级说明参见：

• ToolJet 3.0 自托管迁移指南
• Cloud 迁移指南
• ToolJet Database 功能介绍

PostgREST 的 ECS 部署步骤如下：

1. 创建任务定义，添加容器，镜像为postgrest/postgrest:v12.2.0，端口映射容器端口3001/ TCP（见 docs/static/img/setup/ecs/ecs-13.png）。

2. 配置环境变量：PostgREST 需要如下环境变量（详见 env-vars 文档的 PostgREST 章节）：

3. 创建服务：确保 PostgREST 与 ToolJet 应用位于同一集群；
4. 指定服务名称，其余设置保持默认；
5. 网络连通性：确保 PostgREST 服务与 ToolJet 应用处于同一个 VPC，并确认 ToolJet 应用安全组中放行了3001 端口的入站流量。注意：PostgREST 需要启用 Public IP。

最后，回到 ToolJet 部署，按 env-vars 文档的 Enable ToolJet Database 章节 更新以下环境变量并重新应用变更：

启用 Workflow Scheduling（Workflows 定时调度）

ToolJet Workflows 允许用户通过可视化、基于节点的界面设计和执行复杂的数据驱动自动化任务。要启用 Workflow 的定时调度，需要在 ToolJet 应用同一任务定义（task definition family）下追加两个容器：Worker 容器与Temporal server 容器。

Worker 容器

• 镜像使用tooljet/tooljet:ee-latest，并继承 ToolJet 应用容器的全部环境变量；
• 设置以下环境变量以激活调度能力：

WORKFLOW_WORKER=true ENABLE_WORKFLOW_SCHEDULING=true TOOLJET_WORKFLOWS_TEMPORAL_NAMESPACE=default TEMPORAL_SERVER_ADDRESS=<Temporal_Server_Address>

• 在 Docker configuration 的 containers 页签中，将 Command 设置为npm, run, worker:prod（见 docs/static/img/setup/ecs/ecs-tooljet-worker.png）。

源码佐证：worker:prod在 server/package.json 中定义为WORKER=true NODE_ENV=production node dist/src/main。服务端模块只在WORKER=true时才注册 BullMQ 任务处理器与调度引导逻辑（见 server/src/modules/workflows/module.ts 与 server/src/modules/app-history/module.ts 的注释），说明 Worker 容器本质上是以 Worker 模式运行的服务端。另外，ENABLE_WORKFLOW_SCHEDULING是服务端对外暴露配置的白名单变量之一（server/src/modules/configs/service.ts）。

Temporal server 容器

1. 镜像使用temporalio/auto-setup:1.25.1，并在App protocol 中选择 GRPC（端口映射 7233，见 docs/static/img/setup/ecs/ecs-temporal.png）；
2. 为 Temporal 容器添加如下环境变量（示例值见 docs/static/img/setup/ecs/ecs-temporal-env.png）：

DB=postgres12 DB_PORT=5432 POSTGRES_PWD=temporal POSTGRES_SEEDS=temporal-postgresql POSTGRES_USER=temporal

说明：temporalio/auto-setup会自动完成 Temporal 数据库的 schema 初始化，上述变量用于指定其连接的后端 PostgreSQL。生产环境请替换为实际的数据库地址与凭据。

升级到最新 LTS 版本

ToolJet 每 3～5 个月发布新的 LTS 版本，每个 LTS 版本的生命周期至少 18 个月。LTS 镜像标签遵循LTS-前缀 + 版本号的命名约定，例如tooljet/tooljet:ee-lts-latest。新安装可直接使用最新版本，无需执行本节步骤。

升级前必须满足以下前提：

• 务必在升级前对数据库做完整备份，防止数据丢失；
• 版本低于 v2.23.0-ee2.10.2 的用户，必须先升级到该版本，然后才能继续升级到 LTS 版本。

常见问题排查要点

结合本文涉及的源码，梳理几个部署常见问题的排查方向：

小结

本文基于 docs/docs/setup/ecs.md 梳理了 ToolJet 在 Amazon ECS（Fargate）上的完整部署路径：从 CloudFormation 快速起步，到 Redis、ToolJet 应用、PostgREST（ToolJet Database）与 Temporal（Workflow 调度）四大容器的任务定义与服务编排，并结合 server/package.json、docker/LTS/ee/ee-entrypoint.sh 与 server/src/modules/app/controller.ts 等源码验证了启动命令、健康检查端点与 Worker 模式的底层实现。官方模板只是起点，理解每个环境变量的含义与容器间的网络依赖关系，才能根据业务规模与安全要求灵活调整任务定义，构建稳定可扩展的 ToolJet 生产环境。

【免费下载链接】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