ToolJet 贡献者 Docker 本地开发环境搭建全指南：从 Compose 一键启动到断点调试
【免费下载链接】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 开发环境搭建指南，覆盖从 fork/克隆仓库、生成环境变量、构建镜像到docker compose up一键启动的完整流程，并深入讲解服务架构（client / server / plugins / postgres / redis / postgrest）、热重载机制、测试运行方式以及基于 VSCode +docker-compose-debug.yaml的容器内断点调试方案。读完本文，你将能在本地独立启动一套可开发的 ToolJet 环境，并具备修改代码、运行单测/e2e 测试与容器调试的完整能力。
注意：本指南面向代码贡献者的本地开发场景。如果你只是想自托管部署 ToolJet，请参考 部署 Setup 文档，那里有面向生产环境的配置说明；如果只是想快速试用，可以按 Try ToolJet 的步骤在本地跑起来。
为什么用 Docker Compose 搭建开发环境
ToolJet 是一个前后端分离的复杂工程：server（NestJS 后端）、frontend（React 客户端）、plugins（数据源插件包），外加 PostgreSQL、Redis、PostgREST 等基础设施服务。如果手工安装，需要同时配置 Node.js 22、PostgreSQL 13、Redis 7、PostgREST v12.2.0 以及 Oracle Instant Client 等系统级依赖，极易出现环境不一致。
Docker Compose 是官方推荐的本地开发方式——仓库根目录的 docker-compose.yaml 一次性定义了全部 6 个服务，并且通过卷挂载实现代码热重载。其服务拓扑如下：
| 服务名 | 镜像 / 构建来源 | 对外端口 | 作用 |
|---|---|---|---|
client | docker/client.Dockerfile.dev | 8082 | React 前端 dev server（webpack） |
server | docker/server.Dockerfile.dev | 3000 | NestJS 后端 API |
plugins | docker/plugins.Dockerfile.dev | 无 | 数据源插件构建与监听 |
postgres | postgres:13 | 5432 | 主数据库与 ToolJet Database |
redis | redis:7-alpine | 6379 | 缓存 / 队列 |
postgrest | postgrest/postgrest:v12.2.0 | 3001→3000 | ToolJet Database 的 REST 网关 |
后端服务之间通过 Compose 内部网络互通（REDIS_HOST=redis、PG_HOST=postgres、PGRST_HOST=postgrest），无需手动配置主机名。
前置条件
- 安装最新版本的
docker与docker compose（官方安装指南见 Docker Desktop 与 Docker Compose 官方文档，仓库文档 docker.md 中附有官方链接）。 - Windows 用户：建议使用 Docker Desktop + WSL2，并且务必在 WSL2 终端内执行后续所有命令；同时注意
.env文件的行尾必须是LF（Windows 默认的 CRLF 会导致容器内读取异常）。
六步搭建本地开发环境
1. Fork 并克隆仓库
进入 ToolJet 的 GitHub 仓库页面点击Fork按钮，把仓库复制到自己的账号下，然后克隆到本地：
git clone https://github.com/<your-username>/ToolJet.git2. 从示例文件创建.env
cp ./deploy/docker/.env.internal.example .env模板文件位于 deploy/docker/.env.internal.example。它按功能分组给出了开发环境所需的核心变量：
- 基础：
TOOLJET_HOST（默认http://localhost:8082）、LOCKBOX_MASTER_KEY、SECRET_KEY_BASE； - 数据库：
PG_DB=tooljet_production、PG_USER=postgres、PG_HOST=postgresql、PG_PASS，以及 ToolJet Database 专用的TOOLJET_DB、TOOLJET_DB_USER、TOOLJET_DB_HOST、TOOLJET_DB_PASS； - PostgREST：
PGRST_DB_URI、PGRST_HOST=postgrest、PGRST_JWT_SECRET； - 功能开关：
CHECK_FOR_UPDATES、DISABLE_TOOLJET_TELEMETRY、COMMENT_FEATURE_ENABLE、ENABLE_MULTIPLAYER_EDITING=true； - SSO / 邮件 / 可观测性：Google OAuth、SMTP、Sentry 等可选配置（留空即可）。
各变量的完整含义与取值范围可查阅 环境变量参考文档。
3. 用脚本自动生成密钥与密码
chmod +x ./deploy/docker/internal.sh && ./deploy/docker/internal.sh脚本 deploy/docker/internal.sh 会安全地回写.env，自动补齐 5 类敏感值：
| 变量 | 生成方式 | 用途 |
|---|---|---|
LOCKBOX_MASTER_KEY | openssl rand -hex 32 | 凭据加密的 lockbox 主密钥 |
SECRET_KEY_BASE | openssl rand -hex 64 | 应用会话与签名密钥 |
PGRST_JWT_SECRET | openssl rand -hex 32 | PostgREST JWT 认证密钥 |
PG_PASS/TOOLJET_DB_PASS | openssl rand -base64 12处理后取 16 位 | PostgreSQL 密码 |
PGRST_DB_URI | 用生成的密码拼装postgres://postgres:<pass>@postgresql/tooljet_db | PostgREST 连接串 |
脚本具有幂等性：检测到变量已存在时会跳过并打印提示，不会覆盖已有配置，可安全重复执行。
4. 构建镜像并编译插件
docker compose build docker compose run --rm plugins npm run build:plugins第一步会分别构建plugins、client、server三个开发镜像。从 docker/server.Dockerfile.dev 可以看到，server 镜像基于node:22.15.1-bullseye，除常规编译工具外还内置了postgresql-client、freetds-dev（SQL Server 驱动依赖）、Oracle Instant Client（含LD_LIBRARY_PATH配置）等数据库客户端依赖，并设置NODE_OPTIONS=--max-old-space-size=4096规避 webpack/TypeScript 编译时的堆内存溢出。client 镜像则把frontend/node_modules/.bin加入PATH并同样设置了 4096MB 堆上限。
第二步在plugins容器内执行build:plugins，生成数据源插件产物，供 server/client 容器挂载使用。
5. 启动 ToolJet
docker compose up启动后，前端通过 docker-compose.yaml 将宿主机8082映射到 client 容器，因此访问http://localhost:8082即可打开 ToolJet 界面。server 容器的entrypoint（docker/dev-entrypoint.sh）在启动时自动完成一系列初始化：
- 通过
wait-for-it.sh等待 PostgreSQL（默认postgres:5432）、Redis（redis:6379）、PostgREST（postgrest:3000）就绪； - 检查并自动创建
tooljet_production（主库）与tooljet_db（ToolJet Database）两个数据库； - 按构建产物是否存在，自动执行
npm run db:setup（开发模式，即db:create+db:migrate）或db:setup:prod； - 最后以
npm run --prefix server start:dev启动 NestJS 开发服务器。
因此首次启动不需要手动执行迁移命令，容器会自举完成建库与迁移。
6. 停止容器
docker compose stop修改代码：热重载与镜像重建策略
docker compose up以卷挂载方式（./server:/app/server:delegated、./frontend:/app/frontend:delegated、./plugins:/app/plugins）把本地源码注入容器，同时用匿名卷隔离容器内的node_modules，避免与宿主机依赖冲突。因此：
- 普通代码改动：server 容器会自动热重载，无需任何手动操作；client 侧由 webpack dev server 负责。
- 涉及数据库迁移或新增 npm 依赖（
package.json变更）：需重启 server 容器使迁移脚本与新依赖生效：docker compose restart server - 需要向容器添加新的二进制或系统库：编辑 docker/server.Dockerfile.dev，在
RUN apt-get update && apt-get install -y ...一行追加包名，然后重建镜像：docker compose build server docker compose up
文档给出了一个典型示例：假设要安装imagemagick，则在 Dockerfile 的apt install列表中追加imagemagick，使其在构建阶段被安装到 server 容器中。以此类推，任何 apt 可用的系统库都可按同样方式注入。
在容器内运行测试
测试配置从项目根目录的.env.test文件读取（该文件也被挂载进 server 容器，见 docker-compose.yaml），与开发环境.env相互隔离。
- 创建并迁移测试数据库（两条命令均在
NODE_ENV=test下执行，对应server/package.json中的db:create与db:migrate脚本）：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 - 运行全部单元测试：
docker compose run --rm server npm run --prefix server test - 运行 e2e 测试（对应
server/package.json中的test:e2e，内部执行scripts/run-e2e.sh）：docker compose run --rm server npm run --prefix server test:e2e - 运行单个单元测试文件：
docker compose run --rm server npm --prefix server run test <path-to-file>
用 VSCode 调试 Docker 容器中的 client / server
仓库为容器调试预置了完整的 VSCode 配置，开箱即用。
基础设施
- Compose 调试覆盖文件：docker-compose-debug.yaml 为
server服务额外映射端口9229:9229，并把启动命令切换为npm run --prefix server start:debug -- --debug 0.0.0.0:9229（对应server/package.json中的start:debug，即nest start --debug --watch），使 Node 进程以调试模式监听 9229 端口。 - VSCode 任务：.vscode/tasks.json 定义了
docker-compose: debug:client与docker-compose: debug:server两个任务，会以 detached 模式、叠加docker-compose-debug.yaml启动对应服务。 - VSCode 启动配置：.vscode/launch.json 提供两个调试配置：
- Docker Debug Client：
preLaunchTask先拉起 client 容器，然后以 Chrome 调试器附加到http://127.0.0.1:8082，webRoot指向frontend源码； - Docker Debug Server：
preLaunchTask先拉起 server 容器，再通过docker调试平台附加到容器内9229端口，并完成localRoot（${workspaceRoot}/server）与remoteRoot（/app/server）的源码映射，sourceMaps已开启。
- Docker Debug Client：
手动启动调试模式
也可以不使用 VSCode，直接在命令行叠加调试配置启动：
docker-compose -f docker-compose.yaml -f docker-compose-debug.yaml up --build操作步骤
- 用 VSCode 打开 ToolJet 仓库根目录；
- 点击左侧活动栏的Run and Debug（调试）图标；
- 在配置下拉框中选择Docker Debug Client或Docker Debug Server；
- 按 F5 启动——VSCode 会自动执行前置任务拉起容器，随后附加调试器，即可在源码中设置断点、实时查看变量、观察调用栈。
这套配置让贡献者无需离开 IDE 就能完成「改代码 → 断点调试 → 修复」的闭环，也降低了团队间调试环境不一致带来的协作成本。
常见问题
- Windows 下容器启动异常：检查
.env行尾是否为 LF（可在 VSCode 右下角或通过sed -i 's/\r$//' .env转换），并确认命令运行在 WSL2 终端中。 - 首次启动较慢：需要依次完成基础镜像拉取、
npm install（server/frontend/plugins 三套依赖）与插件构建，属正常现象；后续增量启动会快得多。 - 端口冲突：
8082（client）、3000（server）、5432（postgres）、6379（redis）、3001（postgrest）、9229（调试）均为对外映射端口，如与本机已有服务冲突，可在docker-compose.yaml或docker-compose-debug.yaml中调整宿主机侧端口。
如果仍无法解决，可在 ToolJet 的 GitHub Issues 提交新问题，或加入官方 Slack 社区寻求帮助（入口见 docker.md 的 Troubleshooting 一节）。
相关资源
- 贡献指南入口：CONTRIBUTING.md、贡献者文档
- 环境变量完整参考：docs/docs/setup/env-vars.md
- 快速试用（非开发模式）：docs/docs/setup/try-tooljet.md
- Compose 主配置：docker-compose.yaml；调试覆盖配置：docker-compose-debug.yaml
- server 端 npm 脚本（
db:create/db:migrate/db:setup/test:e2e/start:debug的定义）：server/package.json
【免费下载链接】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），仅供参考
