从零部署ToolJet：开源低代码平台构建内部工具实战指南

1. 项目概述从零到一用开源低代码平台构建你的第一个内部工具如果你是一名开发者、产品经理或者是一个小团队的负责人大概率遇到过这样的场景业务部门提了一个紧急需求比如需要一个简单的数据看板来监控销售漏斗或者需要一个内部审批流程工具。你评估了一下用传统开发方式从前端页面到后端接口再到数据库设计没个三五天搞不定但业务方希望“明天就能用”。这时候一个能快速搭建、灵活部署并且能连接现有数据源的低代码平台就成了救命稻草。ToolJet 正是为了解决这个问题而生的。它不是一个简单的表单生成器而是一个功能完备的开源低代码应用开发平台。你可以把它理解为一个“可视化编程环境”核心目标是让开发者或有一定技术背景的业务人员能够通过拖拽组件和配置数据源的方式快速构建出功能复杂的内部工具、业务看板和工作流应用。它的社区版CE完全开源你可以免费、无限制地将其部署在自己的服务器上完全掌控数据和代码。而它的商业版本 ToolJet AI则在开源版的基础上增加了AI辅助生成、企业级安全管控和团队协作等高级功能。简单来说ToolJet 试图在“完全定制化开发”和“功能固定的SaaS工具”之间找到一个完美的平衡点。它让你能用比写代码快得多的速度构建出贴合自身业务逻辑、且能与你现有技术栈数据库、API、云服务无缝集成的应用程序。接下来我将以一个真实的“员工请假审批系统”为例带你从零开始深入拆解 ToolJet 的核心能力、部署实操、应用构建心法以及那些官方文档里不会写的“坑”。2. 核心架构与设计思路拆解为什么是 ToolJet在决定采用一个技术栈之前我习惯先理解它的设计哲学和底层架构。这能帮助我判断它是否真的适合我的场景以及在遇到问题时该如何思考。2.1 可视化构建器的本质组件与查询的编排引擎ToolJet 的核心是一个基于 Web 的可视化构建器。但它的强大之处在于它不仅仅是将 UI 组件如表格、按钮、图表拖到画布上那么简单。其底层是一个高效的状态管理和事件驱动系统。每个 UI 组件Widget都拥有自己的属性Properties和可以触发的事件Events。例如一个表格组件有“数据源”、“分页”、“列定义”等属性它也可以有“行被点击”、“筛选条件变化”等事件。而“查询”Queries是 ToolJet 中连接数据与UI的桥梁。一个查询可以是从 PostgreSQL 读取数据也可以是调用一个 REST API甚至是一段 JavaScript 或 Python 代码。整个应用的逻辑就是通过配置“当组件A发生事件X时触发查询Y并将查询结果绑定到组件B的属性Z上”这样的规则链来完成的。这种设计模式非常直观它把传统的“前端请求后端后端处理返回数据前端渲染”的流程抽象成了可视化的配置极大地降低了构建交互式应用的门槛。2.2 数据源连接打通企业数据孤岛的关键ToolJet 官方支持超过80种数据源这几乎是它最核心的竞争力之一。这些数据源大致可以分为几类数据库PostgreSQL, MySQL, MongoDB, Redis, Elasticsearch, Snowflake 等。API支持 REST API 和 GraphQL可以通过配置请求头、参数和身份验证方式轻松连接。云存储AWS S3, Google Cloud Storage, MinIO 等。SaaS 工具Slack, Google Sheets, Stripe, Salesforce 等。内置数据库ToolJet Database。这是一个基于 PostgreSQL 的、可通过界面直接操作的轻量级数据库非常适合存储应用本身的配置数据或简单的业务数据。这里有一个非常重要的设计细节ToolJet 采用了“代理连接”模式。这意味着当你的应用在浏览器中运行时它向数据源发出的请求并不是直接从浏览器发出的而是先发送到 ToolJet 的后端服务器由后端服务器作为代理去请求实际的数据源再将结果返回给前端。注意这种架构带来了两大好处和一点需要注意的地方。好处一是安全性你的数据库连接凭证如用户名密码不会暴露给前端而是保存在相对安全的服务端。好处二是跨域问题迎刃而解因为所有请求都走同源的服务端代理。需要注意的地方是ToolJet 服务端成为了一个关键的性能瓶颈和单点你需要确保它的网络能够顺畅访问你的所有数据源并且其本身要有足够的处理能力。2.3 社区版 vs. AI 企业版如何选择很多人在刚开始接触时会困惑该用哪个版本。我的建议很明确从社区版CE开始。社区版CE已经提供了构建绝大多数内部工具所需的全部核心功能。可视化构建器、60组件、80数据源、多页面应用、基础的团队协作如多人实时编辑、自托管部署这些都是免费的。对于个人开发者、创业公司或大公司内部的一个小团队来说CE 版的功能已经绰绰有余。你完全可以用它搭建出数据仪表盘、CRM 子系统、内部工单系统、运维监控面板等。ToolJet AI企业版主要面向中大型企业解决的是规模化、合规化和智能化的问题。它的核心增值点在于AI 辅助开发用自然语言描述需求AI 生成应用界面或 SQL 查询。这能进一步提升初始搭建速度但对复杂业务逻辑的精准度仍需人工调整。企业级管控细粒度的权限控制RBAC、审计日志、单点登录SSO、SOC2/GDPR 合规支持。当你的工具涉及敏感数据或需要给成百上千的员工使用时这些是必需品。高级部署与协作Git 同步、多环境开发/测试/生产管理、白标定制。这适合将 ToolJet 作为正式开发流程一部分的团队。除非你所在的组织对安全合规有硬性要求或者预算充足希望用 AI 提效否则 CE 版足以满足你 90% 的需求。先基于 CE 版做出一个可用的原型验证价值再考虑升级也不迟。3. 从零部署手把手搭建你的私有化 ToolJet 环境理论说得再多不如动手实践。我强烈推荐使用 Docker 进行部署这是最快捷、依赖问题最少的方式。下面我将以在 Ubuntu 22.04 服务器上部署为例详细讲解每一步。3.1 基础环境准备首先确保你的服务器已经安装了 Docker 和 Docker Compose。ToolJet 的 Docker 镜像已经包含了前端、后端和内置的 PostgreSQL 数据库开箱即用。# 更新系统包列表 sudo apt-get update # 安装 Docker 所需依赖 sudo apt-get install -y apt-transport-https ca-certificates curl software-properties-common # 添加 Docker 官方 GPG 密钥 curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg # 设置稳定版仓库 echo deb [arch$(dpkg --print-architecture) signed-by/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable | sudo tee /etc/apt/sources.list.d/docker.list /dev/null # 安装 Docker Engine sudo apt-get update sudo apt-get install -y docker-ce docker-ce-cli containerd.io # 安装 Docker Compose (以 v2 为例) sudo curl -L https://github.com/docker/compose/releases/download/v2.23.0/docker-compose-$(uname -s)-$(uname -m) -o /usr/local/bin/docker-compose sudo chmod x /usr/local/bin/docker-compose # 验证安装 docker --version docker-compose --version3.2 使用 Docker Compose 一键部署单纯使用docker run命令虽然简单但不利于管理和持久化配置。我推荐使用docker-compose.yml文件来定义服务。创建一个目录比如tooljet并在其中创建docker-compose.yml文件。# docker-compose.yml version: 3.8 services: tooljet: image: tooljet/tooljet-ce:latest # 使用社区版最新镜像生产环境建议指定具体版本号如 v2.10.0 container_name: tooljet_app restart: unless-stopped ports: - 3000:3000 # 将容器的3000端口映射到主机的3000端口 environment: - NODE_ENVproduction - TOOLJET_HOSThttp://localhost:3000 # 你的实际访问地址如果是域名则替换为 https://your-domain.com - TOOLJET_SERVER_URLhttp://localhost:3000 # 同上 - LOCKBOX_MASTER_KEYyour_secure_master_key_here_32_bytes # 重要用于加密必须更换 - SECRET_KEY_BASEyour_secure_secret_key_base_here_64_bytes # 重要用于会话加密必须更换 - DATABASE_URLpostgresql://postgres:postgrestooljet_db:5432/tooljet?pool10 # 连接内置数据库 volumes: - tooljet_storage:/app/storage # 持久化上传的文件 - tooljet_logs:/app/log # 持久化日志 depends_on: - db db: image: postgres:15-alpine container_name: tooljet_db restart: unless-stopped environment: - POSTGRES_USERpostgres - POSTGRES_PASSWORDpostgres - POSTGRES_DBtooljet volumes: - tooljet_pgdata:/var/lib/postgresql/data volumes: tooljet_storage: tooljet_pgdata: tooljet_logs:关键配置解析与避坑指南镜像标签tooljet/tooljet-ce:latest指向最新的社区版。对于生产环境强烈建议不要使用latest标签而应使用具体的版本号如tooljet/tooljet-ce:v2.10.0以避免自动升级带来的意外变更。你可以在 ToolJet 的 GitHub Releases 页面找到稳定版。端口映射我映射到了主机的3000端口。你可以根据实际情况修改比如80:3000如果主机80端口空闲且不想加端口号访问。环境变量这是配置的核心。LOCKBOX_MASTER_KEY和SECRET_KEY_BASE这两个变量至关重要且必须被替换为你自己生成的强随机字符串。它们用于加密数据库中的敏感信息如数据源密码和用户会话。如果使用默认值或不设置将存在严重安全风险。生成命令示例openssl rand -hex 32(生成64字符用于LOCKBOX_MASTER_KEY) 和openssl rand -hex 64(生成128字符用于SECRET_KEY_BASE)。TOOLJET_HOST和TOOLJET_SERVER_URL必须设置为用户访问 ToolJet 时使用的完整 URL包括协议 http/https。如果部署在服务器上并通过域名访问这里应该填https://your-domain.com。填错会导致应用内的重定向、资源加载和 OAuth 回调失败。数据持久化通过volumes将 PostgreSQL 数据、上传的文件和日志挂载到宿主机确保容器重建后数据不丢失。保存好docker-compose.yml文件后在同一个目录下执行# 启动服务 docker-compose up -d # 查看日志确认启动是否成功 docker-compose logs -f tooljet如果一切顺利几分钟后你就可以通过http://你的服务器IP:3000访问 ToolJet 了。首次访问会进入管理员账户注册页面。实操心得在服务器上部署时我强烈建议在 ToolJet 前面加一个反向代理比如 Nginx。这样你可以配置 HTTPS使用 Let‘s Encrypt 免费证书保证通信安全。使用更友好的域名和端口如https://tooljet.yourcompany.com。方便做负载均衡和静态资源缓存。一个简单的 Nginx 配置示例如下server { listen 80; server_name tooljet.yourcompany.com; return 301 https://$server_name$request_uri; } server { listen 443 ssl http2; server_name tooljet.yourcompany.com; ssl_certificate /path/to/your/fullchain.pem; ssl_certificate_key /path/to/your/privkey.pem; location / { proxy_pass http://localhost:3000; # 指向 docker-compose 映射的端口 proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection upgrade; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; proxy_cache_bypass $http_upgrade; } }同时别忘了将docker-compose.yml中的TOOLJET_HOST和TOOLJET_SERVER_URL也改为https://tooljet.yourcompany.com。4. 实战构建一个员工请假审批系统现在我们的 ToolJet 环境已经就绪。让我们来构建一个真实的内部工具一个简单的员工请假审批系统。这个系统将包含以下功能员工提交请假申请表单。管理员在一个看板上查看所有申请表格。管理员可以批准或拒绝申请按钮操作。申请状态实时更新员工能看到审批结果。我们将使用 ToolJet 的内置数据库ToolJet Database来存储数据这样无需额外准备数据库。4.1 数据模型设计首先我们需要设计存储请假申请的数据表。在 ToolJet 中内置数据库的使用非常直观。登录 ToolJet点击左侧导航栏的 “Data Sources” - “Add”。选择 “ToolJet Database”。连接成功后点击 “Create new table”我们创建一张名为leave_applications的表。添加以下字段列id(Integer, Primary Key, Auto Increment) - 主键employee_name(Text) - 员工姓名employee_id(Text) - 工号leave_type(Text) - 假期类型如年假、病假、事假start_date(Date) - 开始日期end_date(Date) - 结束日期reason(Long Text) - 请假事由status(Text) - 状态 (pending,approved,rejected)approved_by(Text) - 审批人created_at(DateTime, Default:now()) - 创建时间4.2 创建应用与页面布局回到首页点击 “Create new application”。给应用起个名字比如 “员工请假系统”。默认会创建一个页面。我们可以规划两个页面员工提交页(/submit): 用于员工填写请假单。审批看板页(/dashboard): 用于管理员审批。点击页面名称旁边的 “” 号创建第二个页面并重命名。4.3 构建员工提交页面切换到submit页面。拖拽组件从右侧组件库中拖拽一个 “Form” 容器到画布中央。Form 容器能自动管理内部输入组件的布局和提交行为。设计表单在 Form 容器内依次拖入以下组件Text Input(重命名为姓名输入框): 绑定变量{{components.姓名输入框.value}}Text Input(重命名为工号输入框): 绑定变量{{components.工号输入框.value}}Dropdown(重命名为假期类型下拉框): 在属性面板的 “Options” 里手动输入年假, 病假, 事假, 调休每行一个选项。绑定变量{{components.假期类型下拉框.value}}Datepicker(两个重命名为开始日期选择器和结束日期选择器): 分别绑定变量。Textarea(重命名为事由输入框): 绑定变量。Button(重命名为提交按钮): 修改按钮文本为 “提交申请”。配置提交查询这是最关键的一步。我们需要在点击“提交按钮”时将表单数据插入数据库。点击画布空白处在右侧查询面板点击 “ Add”。选择数据源为 “ToolJet Database”操作类型选择 “Insert row”。在 “Table” 下拉框中选择我们创建的leave_applications。在 “Row object” 中我们需要构建一个 JSON 对象来映射字段。这里就要用到 ToolJet 的JavaScript 表达式能力了。点击输入框旁的/图标切换到代码模式输入{ employee_name: components.姓名输入框.value, employee_id: components.工号输入框.value, leave_type: components.假期类型下拉框.value, start_date: components.开始日期选择器.value, end_date: components.结束日期选择器.value, reason: components.事由输入框.value, status: pending // 默认状态为待审批 }将这个查询重命名为插入请假记录。绑定按钮事件选中“提交按钮”组件在右侧属性面板找到 “Events” - “On click” - “ Add handler”。Action:Run QueryQuery:插入请假记录成功后的处理我们可以添加一个成功提示并清空表单。在 “On Success” 事件中添加两个 ActionShow Alert: Message 设为提交成功我们会尽快处理。Type 设为Success。Set Value(针对 Form): 将 Form 组件的值重置为空对象{}以清空所有输入。至此员工提交页面就完成了。员工填写信息点击提交数据就会存入内置数据库。4.4 构建审批看板页面切换到dashboard页面。这个页面会复杂一些涉及数据的读取、展示和更新。展示数据表格拖拽一个Table组件到画布。创建一个新查询选择 ToolJet Database 的 “Select rows” 操作表选择leave_applications。可以添加排序比如按created_at降序。重命名查询为获取请假列表。将 Table 组件的 “Table Data” 属性绑定到这个查询的结果{{queries.获取请假列表.data}}。为了让表格一进入页面就加载数据我们需要设置页面加载事件。点击画布空白处在右侧属性面板找到 “Events” - “On page load” - “ Add handler” Action 选择Run Query Query 选择获取请假列表。添加审批操作列在 Table 组件的属性面板找到 “Columns”。除了自动映射的字段我们手动添加一列设Column Type为Button。配置这一列Column Name设为approveButton Text设为批准。我们还需要根据行数据的状态来动态显示这个按钮——只有状态为pending时才显示。在Button Text的代码模式 (/) 下输入{{currentRow.status ‘pending’ ? ‘批准’ : ‘’}}。这样非待审批状态的行的按钮文本就是空的相当于隐藏。同理再添加一列reject按钮文本设为拒绝并设置相同的显示逻辑。实现批准与拒绝操作创建两个新的 ToolJet Database 查询操作类型都是 “Update row”。以“批准”查询为例重命名为更新状态为批准。在 “Where clause” 中我们需要指定更新哪一行。通常用主键id。点击/切换到代码模式输入{ id: {{triggeredRow.id}} }。triggeredRow是一个特殊变量代表触发当前事件的表格行数据。在 “Update object” 中输入{ status: ‘approved’, approved_by: ‘管理员’ }。实际应用中approved_by应该绑定当前登录用户。“拒绝”查询类似只是将状态更新为rejected。绑定按钮事件回到 Table 组件的列配置找到approve列的 “On Click” 事件。添加处理器ActionRun Query Query更新状态为批准。在 “On Success” 事件里添加一个Run Query动作再次执行获取请假列表以刷新表格数据。对reject列做同样配置绑定更新状态为拒绝查询。优化与筛选你可以在页面顶部添加一个Dropdown组件作为状态筛选器选项为全部, 待审批, 已批准, 已拒绝。然后修改获取请假列表查询在 “Where clause” 中动态添加筛选条件。例如在代码模式下{ ...(components.状态筛选器.value components.状态筛选器.value ! ‘全部’ ? { status: components.状态筛选器.value } : {}) }最后为筛选器组件的On select事件绑定Run Query-获取请假列表。现在一个具备基本功能的请假审批系统就搭建完成了。管理员在看板页面可以看到所有申请并点击按钮进行审批表格数据会实时更新。5. 高级技巧与避坑指南在实际使用中我积累了一些能极大提升开发效率和应用稳定性的经验。5.1 善用 JavaScript 查询和 TransformationsToolJet 允许你在查询中直接编写 JavaScript 或 Python 代码。这带来了无限的可能性。数据清洗与转换假设从 API 获取的数据结构不符合前端表格的要求你可以在查询的 “Transformations” 标签页下编写 JavaScript 函数对结果进行预处理。// 例如将 API 返回的嵌套对象拍平 return data.map(item ({ id: item.id, name: item.user.profile.name, department: item.user.department.name, // ... 其他字段 }));复杂业务逻辑你可以创建一个 “Run JavaScript Code” 类型的查询在其中实现复杂的逻辑比如计算、循环判断甚至调用多个其他查询的结果进行聚合。// 一个计算请假天数的例子 const start new Date(components.开始日期选择器.value); const end new Date(components.结束日期选择器.value); const diffTime Math.abs(end - start); const diffDays Math.ceil(diffTime / (1000 * 60 * 60 * 24)) 1; // 包含起止日 await actions.setVariable(‘total_leave_days’, diffDays); // 将结果存入变量5.2 状态管理与变量使用ToolJet 应用内部有自己的状态管理系统。除了组件自身的值你还可以创建全局或页面级的变量。何时使用变量当一个数据需要在多个查询或多个组件间共享时就应将其存入变量。例如当前登录的用户信息、一个全局的筛选条件。变量 vs 组件值组件值如components.输入框.value是响应式的改变会触发依赖它的查询或组件更新。变量则需要通过actions.setVariable来修改修改后也需要手动触发依赖更新。对于不频繁变化且需要跨页面共享的数据用变量更合适。一个常见陷阱在查询中引用变量或组件值时如果该值可能为null或undefined你的查询可能会失败。务必在 JavaScript 代码中做好空值判断。5.3 性能优化要点当应用变得复杂数据量增大时需要注意性能。查询去抖Debounce对于由输入框变化触发的查询如搜索为查询设置一个Debounce延迟例如 500ms。这可以防止用户每输入一个字符就发起一次请求。分页与懒加载ToolJet 的 Table 组件支持服务端分页。在连接数据库或 API 时确保你的查询支持pageIndex和pageSize参数并在 Table 组件中启用分页。对于图表如果数据量巨大考虑在后端先做聚合只返回汇总结果。减少不必要的查询检查页面加载事件和组件事件确保没有重复或循环触发查询的情况。利用变量的缓存特性避免重复获取不变的数据。审视数据源连接ToolJet 服务端作为代理其网络带宽和性能是关键。确保它部署在能高速访问所有数据源的网络环境中。对于查询缓慢的数据库要考虑在数据库层面建立索引或优化查询语句。5.4 部署与运维常见问题镜像拉取失败特别是国内环境拉取 Docker 镜像可能较慢或失败。可以考虑配置 Docker 镜像加速器或者先将镜像导出再导入到生产服务器。升级版本务必先备份数据卷升级前使用docker-compose down停止服务然后修改docker-compose.yml中的镜像版本号再执行docker-compose pull和docker-compose up -d。ToolJet 的数据库迁移通常是自动的但重大版本升级前最好在测试环境先演练。内存与 CPU 占用ToolJet 应用本身占用不大但如果你有大量并发用户或复杂查询需要监控服务器资源。可以考虑将 PostgreSQL 数据库独立部署到性能更好的机器上只需修改DATABASE_URL环境变量指向新的数据库地址即可。忘记管理员密码如果自托管且是单机部署可以通过进入 ToolJet 的数据库容器直接更新users表中的密码哈希来重置。密码是经过加密的但你可以通过创建一个新用户然后将其密码哈希复制到旧用户记录上来实现重置。ToolJet 的强大在于它用相对简单的概念组件、查询、事件构建了一个极其灵活的系统。它可能无法替代所有定制化开发但对于那些“重复造轮子”的内部工具场景它能将开发效率提升一个数量级。从简单的数据展示到带有审批流的中等复杂度应用它都能很好地胜任。关键在于理解其“状态驱动”和“事件响应”的思维模式一旦掌握你就能像搭积木一样快速构建出贴合业务需求的数字工具。