ToolJet 本地开发环境搭建指南：用 Docker Compose 实现服务编排、热重载与 VSCode 调试-港品优选

ToolJet 本地开发环境搭建指南：用 Docker Compose 实现服务编排、热重载与 VSCode 调试

【免费下载链接】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 讲解如何一键拉起 ToolJet 的前端（client）、后端（server）、插件构建（plugins）、PostgreSQL、Redis 与 PostgREST 全栈服务。读完本文，你将掌握从克隆仓库、生成安全密钥到启动开发容器、运行单元 / e2e 测试，以及在 VSCode 中远程调试 Docker 内 Node.js 服务的完整流程。

适用范围说明：本文流程面向开发 / 贡献场景，若你只是想在本地或服务器上部署运行 ToolJet（自托管），请参照仓库中的 Setup 章节，其中包含 Docker、Kubernetes、Helm 等多种部署路径；如果只是快速体验，可先阅读 Try ToolJet。

前置条件

在开始之前，请确保本机已安装最新版本的docker与docker compose插件（Docker Desktop 自带 compose 子命令，Linux 环境需单独安装 compose plugin）。

Windows 用户特别注意：建议使用 Docker Desktop 的 WSL2 后端，并且所有命令必须在WSL2 终端中执行，而不是 PowerShell 或 CMD。同时，由于 Windows 默认行尾符为 CRLF，从deploy/docker/.env.internal.example复制生成的.env文件需要把行尾符调整为LF，否则环境变量解析会出错。

仓库根目录的 docker-compose.yaml 是本次开发环境的服务编排核心，共定义 6 个服务：plugins、client、server、redis、postgrest、postgres。启动后的端口映射如下：

服务	容器内监听	宿主机映射	作用
client	8082	8082	ToolJet 前端（webpack dev server）
server	3000	3000	ToolJet NestJS 后端 API
postgrest	3000	3001	PostgREST，为 ToolJet Database 提供 REST 接口
postgres	5432	5432	主数据库（服务端数据）
redis	6379	6379	缓存与队列支持

其中server通过depends_on依赖postgres、redis、postgrest，且其容器环境变量中把REDIS_HOST=redis、PG_HOST=postgres、PGRST_HOST=postgrest直接指向 compose 服务名，即容器间通过服务名互联。

本地开发环境搭建步骤

1. Fork 并克隆仓库

以 GitHub 协作模式为例：先进入上游 ToolJet 仓库页面点击Fork按钮，在自己账号下生成一份副本；随后把这份 fork 克隆到本地：

git clone <your-forked-tooljet-repo-url> cd ToolJet

2. 准备 .env 环境变量文件

ToolJet 在启动时需要大量环境变量（数据库连接、加密密钥、SSO 配置等）。本地开发用的是内部（internal）环境模板，将其复制为项目根目录的.env：

cp ./deploy/docker/.env.internal.example .env

模板文件本身位于 deploy/docker/.env.internal.example，其中已预置了TOOLJET_HOST=http://localhost:8082、数据库名、PGRST_HOST=postgrest等开发默认值。更完整的变量说明（含生产部署所需项）可查阅仓库文档 env-vars.md。

3. 用脚本自动填充安全密钥

.env中以下几项属于必须安全随机生成的敏感密钥，逐个手写既不安全也易出错：

LOCKBOX_MASTER_KEY：ToolJet 用于加密数据源凭据等敏感信息的 Lockbox 主密钥；
SECRET_KEY_BASE：用于会话与签名等安全操作的密钥基；
PGRST_JWT_SECRET：PostgREST 签发/校验 JWT 的密钥；
PG_PASS/TOOLJET_DB_PASS：PostgreSQL 用户密码。

官方提供了一个一键填充脚本，直接执行即可：

chmod +x ./deploy/docker/internal.sh && ./deploy/docker/internal.sh

从源码看，deploy/docker/internal.sh 的逻辑非常清晰：先source .env加载现有配置，然后逐一检查上述键值是否为空，为空则调用openssl rand生成并回写.env：

LOCKBOX_MASTER_KEY用openssl rand -hex 32（64 位十六进制）；
SECRET_KEY_BASE用openssl rand -hex 64（128 位十六进制）；
PGRST_JWT_SECRET用openssl rand -hex 32；
PG_PASS与TOOLJET_DB_PASS通过openssl rand -base64 12处理后截取 16 位；
最后根据生成的密码拼接出PGRST_DB_URI并回写。

也就是说，这个脚本是幂等的：若相应键已存在则跳过（打印提示），可安全重复执行。

4. 构建开发镜像并启动

先构建镜像。由于 compose 中的client、server、plugins三个服务都使用仓库根目录作为构建上下文（context: ./），首次构建需要拉取基础镜像并安装 npm 依赖，耗时较长：

docker compose build docker compose run --rm plugins npm run build:plugins

第二条命令以一次性容器方式先构建插件包（plugins）产物，供 server/client 使用。三个开发镜像分别由 docker/client.Dockerfile.dev、docker/server.Dockerfile.dev、docker/plugins.Dockerfile.dev 定义，均基于node:22.15.1-bullseye，并通过NODE_OPTIONS="--max-old-space-size=4096"提高 Node 堆内存上限以避免前端构建、服务编译时内存溢出。

随后启动全部服务：

docker compose up

等 client 的 webpack dev server 与 server 的 NestJS watch 模式就绪后，在浏览器访问http://localhost:8082即可看到 ToolJet 界面，首次访问会引导创建管理员账号。

需要停止开发环境时：

docker compose stop

stop只是暂停容器（数据卷postgres、redis保留），下次docker compose up可快速恢复现场。

代码改动与容器热重载

开发镜像把宿主目录以 volume 方式挂载进容器：

client 挂载./frontend与./plugins，运行npm run --prefix frontend start（webpack dev server）；
server 挂载./server、./plugins以及根目录的.env/.env.test，运行npm run --prefix server start:dev（NestJS watch 模式）。

因此修改前端或后端代码后，对应容器会自动热重载，无需手动重启。但以下两类变更需要额外处理：

涉及数据库迁移或新增 npm 依赖：如果改动包含 TypeORM migration，或在package.json中新增了依赖包，需要重启 server 容器使新代码/依赖生效：
```
docker compose restart server
```
需要为容器内新增系统级依赖：若新增的功能要求安装某个二进制工具或系统库（例如图像处理命令imagemagick），就必须修改 docker/server.Dockerfile.dev，在apt-get install列表中追加依赖，然后重建镜像并重启：
```
docker compose build server docker compose up
```
以文档中的示例为例，改造后的 Dockerfile 大致形态如下（原文档中该示例基于node:18.18.2-buster，请注意当前仓库的 server 开发镜像实际基线为node:22.15.1-bullseye，实践时应以仓库内现有 Dockerfile 为基准，仅追加你需要的 apt 包）：
```
FROM node:22.15.1-bullseye AS builder RUN apt-get update && apt-get install -y \ build-essential \ postgresql-client \ freetds-dev \ libaio1 \ imagemagick RUN mkdir -p /app WORKDIR /app COPY ./server/package.json ./server/package-lock.json ./server/ RUN npm --prefix server install ENV NODE_ENV=development COPY ./server/ ./server/ COPY ./docker/ ./docker/ COPY ./.env ../.env RUN ["chmod", "755", "entrypoint.sh"]
```
保存后依次执行docker compose build server与docker compose up，新容器即包含imagemagick。

在 Docker 中运行测试

测试环境配置来自项目根目录的.env.test文件（与.env相互独立）。先创建并迁移测试数据库：

docker compose run --rm -e NODE_ENV=test server npm run db:create docker compose run --rm -e NODE_ENV=test server npm run db:migrate

这些命令实际对应 server/package.json 中的脚本：db:create调用ts-node ./scripts/create-database.ts，db:migrate依次执行 schema migration（基于 TypeORM CLI）与 data migration。

运行单元测试：

docker compose run --rm server npm run --prefix server test

运行 e2e（端到端）测试：

docker compose run --rm server npm run --prefix server test:e2e

只运行某个特定的单元测试文件：

docker compose run --rm server npm --prefix server run test <path-to-file>

--prefix server的作用是指定 npm 在server/目录下执行脚本（对应源码中的test脚本为NODE_ENV=test ... jest --config jest.config.ts），而<path-to-file>会透传给 Jest 作为匹配路径。

Docker + VSCode 联合调试

仓库为 Docker 开发环境内置了一整套 VSCode 调试配置，无需改动源码即可对容器内的前后端打断点、观察变量。

调试基础设施

.vscode/launch.json：新增了Docker Debug Client与Docker Debug Server两个启动配置，分别用于在容器中调试前端与后端；
.vscode/tasks.json：管理调试场景下的 docker compose 命令任务，可一键以 detached（后台）模式启动 client/server 容器；
docker-compose-debug.yaml：调试用 compose overlay，核心是为server增加宿主机 9229 端口映射，并把启动命令切换为带调试参数的npm run --prefix server start:debug -- --debug 0.0.0.0:9229，使 NestJS 以 Node 调试模式监听 9229。

启动调试会话

以调试模式启动全部服务（基础编排文件 + 调试覆盖文件叠加）：

docker-compose -f docker-compose.yaml -f docker-compose-debug.yaml up --build

随后在 VSCode 中操作：

用 VSCode 打开 ToolJet 项目目录；
点击左侧活动栏的Run and Debug（调试）图标进入调试视图；
在启动配置下拉框中按需选择Docker Debug Server（后端）或Docker Debug Client（前端），点击运行即可挂载调试器。

该方案的价值在于把断点调试能力从宿主机延伸到容器内：你可以在 server 的 NestJS 控制器、服务或拦截器中直接打断点，配合 VSCode 的实时变量检查、调用栈与单步执行定位问题；统一、可版本化的调试配置也让团队成员共享同一套开发体验，降低了新人上手门槛。

常见问题排查

如果在本地启动 ToolJet 过程中遇到构建失败、容器启动异常或数据库连接问题，建议按以下顺序自查：

确认.env必备密钥已生成（重跑./deploy/docker/internal.sh可安全补齐缺失项）；
确认本机 5432/6379/8082/3000 等端口未被其他进程占用；
确认数据库迁移已执行、.env.test已为测试环境正确创建；
若改动涉及 Dockerfile 或 compose 编排，务必执行docker compose build后再up，避免使用陈旧镜像。

若上述排查仍无法解决，可在项目的 GitHub Issues 提交新 issue，或加入 ToolJet 的 Slack 社区获取帮助（反馈时请附上.env脱敏后的配置、docker compose 日志与复现步骤）。

小结

借助仓库自带的 docker-compose.yaml 与三份.env/ Dockerfile 模板，贡献者只需cp + internal.sh + compose up三步即可获得一个带数据库、缓存、REST 网关与前后端热重载的完整开发环境。结合.env.test测试库、docker compose run的测试命令，以及docker-compose-debug.yaml提供的 9229 调试端口，整套工作流覆盖了"写代码 → 热更新 → 自动化测试 → 断点调试"的贡献闭环，可帮助你在不污染本机 Node/PostgreSQL 环境的前提下高效参与 ToolJet 开发。

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

企业官网建设流程全解析