ToolJet 贡献者 Docker 本地开发环境搭建全指南：从 Compose 一键启动到断点调试

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 是一个前后端分离的复杂工程serverNestJS 后端、frontendReact 客户端、plugins数据源插件包外加 PostgreSQL、Redis、PostgREST 等基础设施服务。如果手工安装需要同时配置 Node.js 22、PostgreSQL 13、Redis 7、PostgREST v12.2.0 以及 Oracle Instant Client 等系统级依赖极易出现环境不一致。Docker Compose 是官方推荐的本地开发方式——仓库根目录的 docker-compose.yaml 一次性定义了全部 6 个服务并且通过卷挂载实现代码热重载。其服务拓扑如下服务名镜像 / 构建来源对外端口作用clientdocker/client.Dockerfile.dev8082React 前端 dev serverwebpackserverdocker/server.Dockerfile.dev3000NestJS 后端 APIpluginsdocker/plugins.Dockerfile.dev无数据源插件构建与监听postgrespostgres:135432主数据库与 ToolJet Databaseredisredis:7-alpine6379缓存 / 队列postgrestpostgrest/postgrest:v12.2.03001→3000ToolJet Database 的 REST 网关后端服务之间通过 Compose 内部网络互通REDIS_HOSTredis、PG_HOSTpostgres、PGRST_HOSTpostgrest无需手动配置主机名。前置条件安装最新版本的docker与docker compose官方安装指南见 Docker Desktop 与 Docker Compose 官方文档仓库文档 docker.md 中附有官方链接。Windows 用户建议使用 Docker Desktop WSL2并且务必在 WSL2 终端内执行后续所有命令同时注意.env文件的行尾必须是LFWindows 默认的 CRLF 会导致容器内读取异常。六步搭建本地开发环境1. Fork 并克隆仓库进入 ToolJet 的 GitHub 仓库页面点击Fork按钮把仓库复制到自己的账号下然后克隆到本地git clone https://github.com/your-username/ToolJet.git2. 从示例文件创建.envcp ./deploy/docker/.env.internal.example .env模板文件位于 deploy/docker/.env.internal.example。它按功能分组给出了开发环境所需的核心变量基础TOOLJET_HOST默认http://localhost:8082、LOCKBOX_MASTER_KEY、SECRET_KEY_BASE数据库PG_DBtooljet_production、PG_USERpostgres、PG_HOSTpostgresql、PG_PASS以及 ToolJet Database 专用的TOOLJET_DB、TOOLJET_DB_USER、TOOLJET_DB_HOST、TOOLJET_DB_PASSPostgRESTPGRST_DB_URI、PGRST_HOSTpostgrest、PGRST_JWT_SECRET功能开关CHECK_FOR_UPDATES、DISABLE_TOOLJET_TELEMETRY、COMMENT_FEATURE_ENABLE、ENABLE_MULTIPLAYER_EDITINGtrueSSO / 邮件 / 可观测性Google OAuth、SMTP、Sentry 等可选配置留空即可。各变量的完整含义与取值范围可查阅 环境变量参考文档。3. 用脚本自动生成密钥与密码chmod x ./deploy/docker/internal.sh ./deploy/docker/internal.sh脚本 deploy/docker/internal.sh 会安全地回写.env自动补齐 5 类敏感值变量生成方式用途LOCKBOX_MASTER_KEYopenssl rand -hex 32凭据加密的 lockbox 主密钥SECRET_KEY_BASEopenssl rand -hex 64应用会话与签名密钥PGRST_JWT_SECRETopenssl rand -hex 32PostgREST JWT 认证密钥PG_PASS/TOOLJET_DB_PASSopenssl rand -base64 12处理后取 16 位PostgreSQL 密码PGRST_DB_URI用生成的密码拼装postgres://postgres:passpostgresql/tooljet_dbPostgREST 连接串脚本具有幂等性检测到变量已存在时会跳过并打印提示不会覆盖已有配置可安全重复执行。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-devSQL Server 驱动依赖、Oracle Instant Client含LD_LIBRARY_PATH配置等数据库客户端依赖并设置NODE_OPTIONS--max-old-space-size4096规避 webpack/TypeScript 编译时的堆内存溢出。client 镜像则把frontend/node_modules/.bin加入PATH并同样设置了 4096MB 堆上限。第二步在plugins容器内执行build:plugins生成数据源插件产物供 server/client 容器挂载使用。5. 启动 ToolJetdocker compose up启动后前端通过 docker-compose.yaml 将宿主机8082映射到 client 容器因此访问http://localhost:8082即可打开 ToolJet 界面。server 容器的entrypointdocker/dev-entrypoint.sh在启动时自动完成一系列初始化通过wait-for-it.sh等待 PostgreSQL默认postgres:5432、Redisredis:6379、PostgRESTpostgrest:3000就绪检查并自动创建tooljet_production主库与tooljet_dbToolJet Database两个数据库按构建产物是否存在自动执行npm run db:setup开发模式即db:createdb: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_ENVtest下执行对应server/package.json中的db:create与db:migrate脚本docker compose run --rm -e NODE_ENVtest server npm run db:create docker compose run --rm -e NODE_ENVtest server npm run db:migrate运行全部单元测试docker compose run --rm server npm run --prefix server test运行 e2e 测试对应server/package.json中的test:e2e内部执行scripts/run-e2e.shdocker 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 ClientpreLaunchTask先拉起 client 容器然后以 Chrome 调试器附加到http://127.0.0.1:8082webRoot指向frontend源码Docker Debug ServerpreLaunchTask先拉起 server 容器再通过docker调试平台附加到容器内9229端口并完成localRoot${workspaceRoot}/server与remoteRoot/app/server的源码映射sourceMaps已开启。手动启动调试模式也可以不使用 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 installserver/frontend/plugins 三套依赖与插件构建属正常现象后续增量启动会快得多。端口冲突8082client、3000server、5432postgres、6379redis、3001postgrest、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.mdCompose 主配置docker-compose.yaml调试覆盖配置docker-compose-debug.yamlserver 端 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），仅供参考