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 部署至少由以下几部分组成组件作用说明PostgreSQLToolJet 的主存储持久化用户、应用、数据源等元数据需要手动预先创建Redis多人在线协同编辑 后台任务ToolJet 依赖 Redis 启用 multiplayer editing 与 background jobsToolJet 应用容器前后端一体服务镜像tooljet/tooljet:ee-latest监听容器端口 3000PostgRESTToolJet 3.0 起强制ToolJet Database 查询层提供 ToolJet Database 的 REST 查询能力监听端口 3001Temporal可选Workflow 调度引擎启用 Workflow Scheduling 时必需Application Load Balancer流量入口将外部流量路由到 ToolJet 容器健康检查指向/api/health:::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 集群中按以下步骤创建创建任务定义Task definitionfamily 命名为redis启动类型选择AWS Fargate操作系统选择Linux/X86_64网络模式为awsvpc。添加容器与镜像容器名称redis镜像标签务必使用Redis 6.x 系列例如redis:6.2见 docs/static/img/setup/ecs/ecs-2.png端口映射为容器端口6379/ TCP 协议。创建服务将 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.tsAppController同时响应GET /health与GET /api/health返回服务健康状态该路径也被显式排除在 CSRF Origin 校验server/src/helpers/bootstrap.helper.ts与 OTEL 埋点server/src/modules/logging/constant.ts之外说明它是专供探活使用的轻量端点。第 3 步创建 ToolJet 任务定义在预配置好的集群上创建任务定义关键参数如下兼容性选择Fargate作为启动类型。IAM 角色与操作系统配置任务角色/执行角色如ecsTaskExecutionRole操作系统家族选择Linux。任务大小选择3GB 内存 1 vCPU见 docs/static/img/setup/ecs/ecs-4.png。容器配置容器名称例如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变量用途TOOLJET_DBToolJet Database 库名默认tooljet_dbTOOLJET_DB_HOSTToolJet Database 数据库主机TOOLJET_DB_USERToolJet Database 用户名TOOLJET_DB_PASSToolJet Database 密码PG_HOSTPostgreSQL 主数据库主机PG_DB主数据库名称PG_USER主数据库用户名PG_PASS主数据库密码SECRET_KEY_BASE用于加密会话 Cookie 的 64 字节十六进制字符串LOCKBOX_MASTER_KEY用于加密数据源凭据的 32 字节十六进制字符串生成密钥的推荐方式需要本机安装openssl# LOCKBOX_MASTER_KEY32 字节十六进制 openssl rand -hex 32 # SECRET_KEY_BASE64 字节十六进制 openssl rand -hex 64源码佐证这两个密钥的用途与位数要求记录在 docs/docs/setup/env-vars.mdLOCKBOX_MASTER_KEY用于 lockbox 加密数据源凭据SECRET_KEY_BASE用于加密会话 Cookie二者缺一不可。Redis 环境变量若按上文步骤创建了 Redis 服务还需在 ToolJet 容器中追加REDIS_HOSTpublic ip of redis task REDIS_PORT6379 REDIS_USERdefault 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/ToolJetDocker configuration的 Command 填写npm, run, start:prod见 docs/static/img/setup/ecs/ecs-8.png。源码佐证start:prod在 server/package.json 中定义为NODE_ENVproduction node dist/src/main即以生产模式启动 NestJS 服务端。容器启动时入口脚本还会依次执行等待数据库就绪、数据库创建与迁移等初始化步骤docker/LTS/ee/ee-entrypoint.sh 中的db:setup:prod其内部对应 server/package.json 的db:create:prod db:migrate:prod。第 4 步创建服务并接入负载均衡选择之前创建的集群启动类型选择Fargate设置服务名称如ToolJet起始任务数建议设为 2保证高可用见 docs/static/img/setup/ecs/ecs-10.png其余保持默认进入网络配置选择指定的VPC、子网与安全组。务必确保安全组允许对任务 3000 端口的入站流量见 docs/static/img/setup/ecs/ecs-11.png由于数据库迁移在容器启动时执行请将Health check grace period 设置为 900 秒给首次启动留出足够的迁移时间选择 Application Load Balancer 选项将目标组指定为第 2 步创建的 Target Group健康检查端点会自动填充为/api/health。:::info 容器首次启动包含建库、迁移、等待依赖服务就绪等多个阶段耗时会明显长于常规探活周期。900 秒的宽限期是官方推荐的保守值可根据实际迁移耗时调整。 :::部署 ToolJet DatabasePostgRESTToolJet Database 是 ToolJet 内置的数据库功能其查询能力由PostgREST服务提供。从 ToolJet 3.0 起部署 ToolJet Database 为强制要求否则迁移可能失败。相关升级说明参见ToolJet 3.0 自托管迁移指南Cloud 迁移指南ToolJet Database 功能介绍PostgREST 的 ECS 部署步骤如下创建任务定义添加容器镜像为postgrest/postgrest:v12.2.0端口映射容器端口3001/ TCP见 docs/static/img/setup/ecs/ecs-13.png。配置环境变量PostgREST 需要如下环境变量详见 env-vars 文档的 PostgREST 章节变量说明PGRST_JWT_SECRET用于认证的 JWT token 密钥可用openssl rand -hex 32生成PGRST_DB_URIToolJet Database 的连接串格式为postgres://[USERNAME]:[PASSWORD][HOST]:[PORT]/[DATABASE]PGRST_LOG_LEVEL日志级别如info创建服务确保 PostgREST 与 ToolJet 应用位于同一集群指定服务名称其余设置保持默认网络连通性确保 PostgREST 服务与 ToolJet 应用处于同一个 VPC并确认 ToolJet 应用安全组中放行了3001 端口的入站流量。注意PostgREST 需要启用 Public IP。最后回到 ToolJet 部署按 env-vars 文档的 Enable ToolJet Database 章节 更新以下环境变量并重新应用变更变量说明TOOLJET_DB默认tooljet_dbTOOLJET_DB_HOST/TOOLJET_DB_USER/TOOLJET_DB_PASS/TOOLJET_DB_PORT数据库连接信息PGRST_JWT_SECRET与 PostgREST 容器保持一致的 JWT 密钥PGRST_HOSTPostgREST 服务地址PGRST_DB_PRE_CONFIGpostgrest.pre_config启用 Workflow SchedulingWorkflows 定时调度ToolJet Workflows 允许用户通过可视化、基于节点的界面设计和执行复杂的数据驱动自动化任务。要启用 Workflow 的定时调度需要在 ToolJet 应用同一任务定义task definition family下追加两个容器Worker 容器与Temporal server 容器。Worker 容器镜像使用tooljet/tooljet:ee-latest并继承 ToolJet 应用容器的全部环境变量设置以下环境变量以激活调度能力WORKFLOW_WORKERtrue ENABLE_WORKFLOW_SCHEDULINGtrue TOOLJET_WORKFLOWS_TEMPORAL_NAMESPACEdefault TEMPORAL_SERVER_ADDRESSTemporal_Server_Address在 Docker configuration 的 containers 页签中将 Command 设置为npm, run, worker:prod见 docs/static/img/setup/ecs/ecs-tooljet-worker.png。源码佐证worker:prod在 server/package.json 中定义为WORKERtrue NODE_ENVproduction node dist/src/main。服务端模块只在WORKERtrue时才注册 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 容器镜像使用temporalio/auto-setup:1.25.1并在App protocol 中选择 GRPC端口映射 7233见 docs/static/img/setup/ecs/ecs-temporal.png为 Temporal 容器添加如下环境变量示例值见 docs/static/img/setup/ecs/ecs-temporal-env.pngDBpostgres12 DB_PORT5432 POSTGRES_PWDtemporal POSTGRES_SEEDStemporal-postgresql POSTGRES_USERtemporal说明temporalio/auto-setup会自动完成 Temporal 数据库的 schema 初始化上述变量用于指定其连接的后端 PostgreSQL。生产环境请替换为实际的数据库地址与凭据。升级到最新 LTS 版本ToolJet 每 35 个月发布新的 LTS 版本每个 LTS 版本的生命周期至少 18 个月。LTS 镜像标签遵循LTS-前缀 版本号的命名约定例如tooljet/tooljet:ee-lts-latest。新安装可直接使用最新版本无需执行本节步骤。升级前必须满足以下前提务必在升级前对数据库做完整备份防止数据丢失版本低于 v2.23.0-ee2.10.2 的用户必须先升级到该版本然后才能继续升级到 LTS 版本。常见问题排查要点结合本文涉及的源码梳理几个部署常见问题的排查方向现象排查方向容器反复重启 / 探活失败确认 PostgreSQL 与 Redis 在wait-for-it.sh的超时窗口内可达确认/api/health已配置为健康检查路径且未修改容器启动命令npm run start:prod数据库迁移失败ToolJet 3.0确认 PostgREST 已部署且TOOLJET_DB*系列变量正确注入3.0 起 ToolJet Database 为迁移前置条件多人在线协同失效检查REDIS_HOST/REDIS_PORT是否指向可访问的 Redis 6.x 实例且 ToolJet 容器与 Redis 任务网络互通Workflow 定时任务不触发确认 Worker 容器命令为npm run worker:prod即WORKERtrue且TEMPORAL_SERVER_ADDRESS指向可访问的 Temporal 服务安全组放行遗漏ToolJet 容器入站放行 3000PostgREST 所在安全组对 ToolJet 放行 3001ALB 目标组指向 ToolJet 的 3000小结本文基于 docs/docs/setup/ecs.md 梳理了 ToolJet 在 Amazon ECSFargate上的完整部署路径从 CloudFormation 快速起步到 Redis、ToolJet 应用、PostgRESTToolJet Database与 TemporalWorkflow 调度四大容器的任务定义与服务编排并结合 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考