ToolJet 多实例部署实战把每个自托管实例当作独立环境Instance as Environment管理与跨环境迁移【免费下载链接】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在自托管场景下很多团队希望把「环境隔离」做到基础设施层面开发、预发staging、生产分别运行一套完全独立的 ToolJet 实例互不共享用户、资源和应用数据。ToolJet 的官方文档将这种用法定义为Instance as Environment实例即环境本文基于仓库内 instance-as-environment.md 展开先讲清多实例模式的隔离模型与适用场景再以 GitSync 为核心完整讲解如何在多个实例之间推送、拉取、导入与同步应用最后用一个 dev → staging → production 的端到端示例串起整条流水线。读完你即可在自托管基础设施上搭建一套「一套代码、三套实例、通过 Git 仓库驱动流转」的发布体系。什么是「实例即环境」模式ToolJet 把「环境」这个概念分为两种落地方式单实例内的多环境在同一个 ToolJet 实例内部划分多个环境如 development、staging、production通过环境变量 / 数据源配置区分使用场景。相关说明见仓库的 self-hosted 多环境文档 与 cloud 多环境文档。多实例即多环境在你的自托管基础设施上分别部署多个相互隔离的 ToolJet 实例每个实例本身就代表一个环境development、staging、production用于支撑结构化的软件开发生命周期SDLC。本指南讨论的是第二种。多实例模式下每个实例独立运行、独立扩展并且对资源、用户和应用做到严格隔离资源隔离每个环境拥有独立的数据库、对象存储、消息队列等后端依赖互不产生脏数据用户隔离开发、测试、生产环境的登录用户与权限体系彼此分离生产环境可以只对发布负责人开放应用隔离同一应用在不同实例中各自独立演进只有当开发者主动通过 Git 同步时变更才会从一个实例流向下一个实例。多实例环境的前置准备部署多个 ToolJet 实例开启多实例模式本身不需要额外安装任何组件你需要做的只是把 ToolJet 实例部署多份。官方提供的自托管部署方式都可以作为实例载体Docker Compose、Kubernetes/Helm、云厂商部署模板等具体可参考 ToolJet 自托管部署与快速上手文档。部署要点提醒每个实例需要独立的数据库与基础设施避免多实例共享底层存储而破坏「实例隔离」的前提建议为三个实例约定统一的访问地址如dev.tooljet.corp.com、staging.tooljet.corp.com、tooljet.corp.com便于团队记忆与 CI/CD 接入实例之间没有内置的互通机制应用流转完全依赖 GitSync 走「共享 Git 仓库」这个中间层完成。用 GitSync 打通实例多实例间迁移应用的核心机制ToolJet 的GitSync特性负责多实例之间的应用迁移通过一个 Git 仓库作为「传输通道」一个实例把应用 push 上去另一个实例把应用 pull 下来。它支持的 Git 托管服务包括GitHub、GitLab、Gitea 和 Bitbucket。整体工作原理可用下图概括源码见 GitSync 概述上图展示的正是官方推荐的核心工作流开发实例中完成的应用被提交进共享 Git 仓库预发实例与生产实例再通过 GitSync 从同一仓库拉取从而实现跨实例的平滑流转。前提条件GitSync 在 ToolJet 中属于需要相应版本许可的功能且配置操作需要Admin管理员角色。详细前提与授权说明见 GitSync 概述文档。在实例上配置 GitSync以 GitHub 为例要让一个实例具备「推」和「拉」的能力需要在该实例的工作区中完成一次 GitSync 配置完整步骤见 GitSync 配置文档核心流程如下准备仓库在 GitHub或其他托管平台上新建一个仓库公开或私有均可也可以复用已有仓库但需保证仓库为空多实例共用一个仓库即可实现相互迁移。取得 SSH URL新建仓库后复制 GitHub 给出的 SSH 地址已有仓库则点击Code按钮获取。GitLab / Gitea 等平台的 SSH 地址生成方式见 SSH 配置文档。进入配置页打开Workspace settings工作区设置切换到Configure git标签页典型 URL 形如https://app.corp.com/nexus/workspace-settings/configure-git。填入仓库地址将 SSH URL 粘贴到Git repo URL字段。生成 SSH 密钥点击Generate SSH key并复制生成的公钥。ToolJet 提供两种算法ED25519安全且高效GitHub、GitLab 等主流平台推荐使用官方也建议默认选择RSA较老的算法仅在 Bitbucket 等平台要求时使用。部署密钥到仓库回到 GitHub 仓库的Settings → Deploy keys点击Add deploy key。粘贴并授权填写 Title粘贴上一步生成的 SSH 公钥。若该实例需要推送push务必勾选Allow write access若实例仅用于拉取pull例如只读的生产实例可不勾选。完成设置回到 ToolJet 的Configure git标签页点击Finalize setup密钥校验通过后会显示成功提示。需要说明的是不同 ToolJet 实例可以各自连接不同的仓库也可以连接同一个仓库——多实例迁移场景下为了让一个应用的变更能从开发流到生产三个实例通常指向同一个 Git 仓库。指定自定义 Git 分支可选从v3.5.3-ee-lts开始自托管版 ToolJet 支持为 GitSync 配置自定义分支。该配置属于实例级配置通过.env中的环境变量完成GITSYNC_TARGET_BRANCHbranch-name注意该分支是实例级全局生效的即使不同工作区可以连接不同仓库.env中指定的分支也必须存在于所有启用 GitSync 的仓库中。已有 GitSync 用户若想切换到自定义分支需先在仓库中基于 master 创建新分支再修改.env以保证所有操作平滑运行详见 GitSync 配置文档。推送变更把应用从当前实例提交到 Git 仓库GitSync 配置完成后实例中的多种操作都会触发提交。官方在 push.md 中归纳了以下触发点新建应用即提交App Creation在 Dashboard 点击Create New App时弹出框中会提供Commit changes复选项勾选后创建应用的同时即向 Git 仓库提交一个 commit提交信息为App creation作者为创建者。首次提交后仓库内会生成一个.meta文件夹内含meta.json记录最近一次 commit 的元信息一个与应用同名的应用文件夹存放v1.json包含 v1 版本的应用定义细节。注意如果仓库中已存在同名应用新创建应用会覆盖仓库中的旧应用。手动提交GitSync 按钮应用构建器App Builder顶部工具栏有GitSync按钮。点击后弹出提交对话框其中会显示当前连接的Git repo URL以及最近一次提交的信息message、author、日期时间方便你参考书写新的提交说明填写提交信息后点击Commit changes即可完成手动提交。自动提交重命名 / 版本更新应用重命名应用被重命名包括版本被重命名时会自动产生一次提交提交信息为App is renamed创建新版本新建应用版本时同样可选择Commit changes提交后应用文件夹中的 JSON 文件会被替换为新版本内容.meta/meta.json同步更新为新的版本 ID 与名称提交信息为Version creation。环境提升自动提交Promoting Environment可选从Development 提升到 Staging时会自动产生提交提交信息形如version_number Version of app_name promoted from source_environment to destination_environment而从 Staging 提升到 Production 则不会触发提交。该选项默认关闭可在Workspace settings → Configure git页开启或关闭。删除应用不会删除仓库文件在实例中删除应用只影响该实例自身Git 仓库中的对应文件会原样保留。这也是 GitSync 天然具备「应用备份 / 可恢复」能力的体现——相关内容可参考 GitSync 概述 中关于备份用途的说明。拉取变更把应用从 Git 仓库导入到实例推送只完成了「上游同步」目标实例还需要主动「拉取」。拉取能力正是多实例模式的另一半详见 pull.md。导入应用Import from Git Repository进入目标实例的ToolJet Dashboard点击Create New App按钮右侧的kebab 菜单三个点选择Import from Git Repository在弹出的下拉框中选择要导入的应用界面会显示应用名称与最近一次提交信息点击Import App完成导入。导入时请留意以下限制与还原 / 跨实例迁移强相关从 Git 仓库导入的应用处于只读view-only模式无法直接编辑如需修改必须**克隆clone**该应用后再编辑导入应用在目标工作区中须名称唯一若与现有应用同名需要先重命名或删除现有应用才能导入工作区常量不会随 Git 仓库同步拉取后如果应用因缺失常量而报错需要在目标实例中手动补充相应的工作区常量数据源配置中的密码与密钥不会随应用一起迁移导入会把数据源一并带入但出于安全考虑会剔除其中的 secrets需要在新实例中重新填写后才能正常连通与测试。拉取最新更新Pull Changes应用导入后若上游开发实例又提交了新版本目标实例可增量同步打开应用的GitSync按钮弹出框内提供Check for Updates选项点击Check for Updates从 Git 仓库拉取最新提交弹出框会展示提交信息commit message、作者与日期等细节确认后点击Pull changes最新变更即同步进当前实例。端到端示例dev → staging → production 的完整发布流水线把上面的机制串起来就得到了官方给出的多实例迁移标准动作。example.md 用一个虚拟公司 Vertex Solutions 的例子展示了完整过程该公司维护 development、staging、production 三套 ToolJet 实例并已分别按上文步骤将三套实例的 GitSync 配置指向同一个 GitHub 仓库。阶段一在 Development 实例开发并提交开发者准备构建「库存管理系统Inventory Management System」在 Dashboard 点击Create New App填写应用名并勾选Commit changes点击Create App——应用随即以一条提交进入 Git 仓库在 App Builder 中拖拽组件、配置查询完成功能开发完成后点击顶部GitSync按钮填写提交信息并提交——仓库中随即出现对应的 commit包含提交信息、作者与时间戳。阶段二导入 Staging 实例进行测试测试人员在 Staging 实例的 Dashboard 上通过Create New App 旁的三个点 → Import from Git Repository选择该应用并点击Import App完成导入。导入完成后应用与数据源一并导入但数据源中的密码与 secrets 不会带入测试人员需要在 Staging 实例中重新填写数据源连接凭据使应用能连上测试数据应用以只读模式打开测试人员验证功能与交互。阶段三迭代修复并同步到 Staging若测试发现缺陷需要修改开发者在 Development 实例中为应用创建新版本New Version并完成修改通过 GitSync 提交新版本——仓库内应用文件夹的 JSON 更新为新版本内容.meta/meta.json同步新的版本 ID 与名称Staging 实例的测试人员点击GitSync → Check for Updates确认提交详情message、author、date后点击Pull changes最新版本即同步至 Staging。阶段四发布到 Production应用在 Staging 验收通过后生产环境负责人以同样方式在 Production 实例中通过 GitSync 导入该应用、补全生产数据源凭据并完成发布应用随即对最终用户开放。小结与阅读路径「实例即环境」的核心价值在于用基础设施隔离换取 SDLC 的确定性而 GitSync 则用「一个 Git 仓库 push/pull」把隔离的实例串联成一条可审计、可回滚的发布流水线。它同时解决了两个实际问题一是把应用变更按阶段稳定地从一个环境搬到下一个环境二是在 Git 中留下每个应用完整、带版本的历史副本天然的备份机制。若需深入了解本文涉及的上下游细节可直接阅读仓库内的下列文档实例即环境指南instance-as-environment.md本文主体配套实操示例example.mdGitSync 功能总览与使用场景overview.mdGitSync 完整配置步骤SSH 密钥、分支、部署密钥gitsync-config.md 与 ssh-config.md推送与拉取的操作细节push.md、pull.md自托管实例部署try-tooljet.md【免费下载链接】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），仅供参考 
长河君 · 2026/9/9 13:12:01 · 阅读 1.2k ToolJet 多实例部署实战：把每个自托管实例当作独立环境（Instance as Environment）管理与跨环境迁移
ToolJet 多实例部署实战把每个自托管实例当作独立环境Instance as Environment管理与跨环境迁移【免费下载链接】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在自托管场景下很多团队希望把「环境隔离」做到基础设施层面开发、预发staging、生产分别运行一套完全独立的 ToolJet 实例互不共享用户、资源和应用数据。ToolJet 的官方文档将这种用法定义为Instance as Environment实例即环境本文基于仓库内 instance-as-environment.md 展开先讲清多实例模式的隔离模型与适用场景再以 GitSync 为核心完整讲解如何在多个实例之间推送、拉取、导入与同步应用最后用一个 dev → staging → production 的端到端示例串起整条流水线。读完你即可在自托管基础设施上搭建一套「一套代码、三套实例、通过 Git 仓库驱动流转」的发布体系。什么是「实例即环境」模式ToolJet 把「环境」这个概念分为两种落地方式单实例内的多环境在同一个 ToolJet 实例内部划分多个环境如 development、staging、production通过环境变量 / 数据源配置区分使用场景。相关说明见仓库的 self-hosted 多环境文档 与 cloud 多环境文档。多实例即多环境在你的自托管基础设施上分别部署多个相互隔离的 ToolJet 实例每个实例本身就代表一个环境development、staging、production用于支撑结构化的软件开发生命周期SDLC。本指南讨论的是第二种。多实例模式下每个实例独立运行、独立扩展并且对资源、用户和应用做到严格隔离资源隔离每个环境拥有独立的数据库、对象存储、消息队列等后端依赖互不产生脏数据用户隔离开发、测试、生产环境的登录用户与权限体系彼此分离生产环境可以只对发布负责人开放应用隔离同一应用在不同实例中各自独立演进只有当开发者主动通过 Git 同步时变更才会从一个实例流向下一个实例。多实例环境的前置准备部署多个 ToolJet 实例开启多实例模式本身不需要额外安装任何组件你需要做的只是把 ToolJet 实例部署多份。官方提供的自托管部署方式都可以作为实例载体Docker Compose、Kubernetes/Helm、云厂商部署模板等具体可参考 ToolJet 自托管部署与快速上手文档。部署要点提醒每个实例需要独立的数据库与基础设施避免多实例共享底层存储而破坏「实例隔离」的前提建议为三个实例约定统一的访问地址如dev.tooljet.corp.com、staging.tooljet.corp.com、tooljet.corp.com便于团队记忆与 CI/CD 接入实例之间没有内置的互通机制应用流转完全依赖 GitSync 走「共享 Git 仓库」这个中间层完成。用 GitSync 打通实例多实例间迁移应用的核心机制ToolJet 的GitSync特性负责多实例之间的应用迁移通过一个 Git 仓库作为「传输通道」一个实例把应用 push 上去另一个实例把应用 pull 下来。它支持的 Git 托管服务包括GitHub、GitLab、Gitea 和 Bitbucket。整体工作原理可用下图概括源码见 GitSync 概述上图展示的正是官方推荐的核心工作流开发实例中完成的应用被提交进共享 Git 仓库预发实例与生产实例再通过 GitSync 从同一仓库拉取从而实现跨实例的平滑流转。前提条件GitSync 在 ToolJet 中属于需要相应版本许可的功能且配置操作需要Admin管理员角色。详细前提与授权说明见 GitSync 概述文档。在实例上配置 GitSync以 GitHub 为例要让一个实例具备「推」和「拉」的能力需要在该实例的工作区中完成一次 GitSync 配置完整步骤见 GitSync 配置文档核心流程如下准备仓库在 GitHub或其他托管平台上新建一个仓库公开或私有均可也可以复用已有仓库但需保证仓库为空多实例共用一个仓库即可实现相互迁移。取得 SSH URL新建仓库后复制 GitHub 给出的 SSH 地址已有仓库则点击Code按钮获取。GitLab / Gitea 等平台的 SSH 地址生成方式见 SSH 配置文档。进入配置页打开Workspace settings工作区设置切换到Configure git标签页典型 URL 形如https://app.corp.com/nexus/workspace-settings/configure-git。填入仓库地址将 SSH URL 粘贴到Git repo URL字段。生成 SSH 密钥点击Generate SSH key并复制生成的公钥。ToolJet 提供两种算法ED25519安全且高效GitHub、GitLab 等主流平台推荐使用官方也建议默认选择RSA较老的算法仅在 Bitbucket 等平台要求时使用。部署密钥到仓库回到 GitHub 仓库的Settings → Deploy keys点击Add deploy key。粘贴并授权填写 Title粘贴上一步生成的 SSH 公钥。若该实例需要推送push务必勾选Allow write access若实例仅用于拉取pull例如只读的生产实例可不勾选。完成设置回到 ToolJet 的Configure git标签页点击Finalize setup密钥校验通过后会显示成功提示。需要说明的是不同 ToolJet 实例可以各自连接不同的仓库也可以连接同一个仓库——多实例迁移场景下为了让一个应用的变更能从开发流到生产三个实例通常指向同一个 Git 仓库。指定自定义 Git 分支可选从v3.5.3-ee-lts开始自托管版 ToolJet 支持为 GitSync 配置自定义分支。该配置属于实例级配置通过.env中的环境变量完成GITSYNC_TARGET_BRANCHbranch-name注意该分支是实例级全局生效的即使不同工作区可以连接不同仓库.env中指定的分支也必须存在于所有启用 GitSync 的仓库中。已有 GitSync 用户若想切换到自定义分支需先在仓库中基于 master 创建新分支再修改.env以保证所有操作平滑运行详见 GitSync 配置文档。推送变更把应用从当前实例提交到 Git 仓库GitSync 配置完成后实例中的多种操作都会触发提交。官方在 push.md 中归纳了以下触发点新建应用即提交App Creation在 Dashboard 点击Create New App时弹出框中会提供Commit changes复选项勾选后创建应用的同时即向 Git 仓库提交一个 commit提交信息为App creation作者为创建者。首次提交后仓库内会生成一个.meta文件夹内含meta.json记录最近一次 commit 的元信息一个与应用同名的应用文件夹存放v1.json包含 v1 版本的应用定义细节。注意如果仓库中已存在同名应用新创建应用会覆盖仓库中的旧应用。手动提交GitSync 按钮应用构建器App Builder顶部工具栏有GitSync按钮。点击后弹出提交对话框其中会显示当前连接的Git repo URL以及最近一次提交的信息message、author、日期时间方便你参考书写新的提交说明填写提交信息后点击Commit changes即可完成手动提交。自动提交重命名 / 版本更新应用重命名应用被重命名包括版本被重命名时会自动产生一次提交提交信息为App is renamed创建新版本新建应用版本时同样可选择Commit changes提交后应用文件夹中的 JSON 文件会被替换为新版本内容.meta/meta.json同步更新为新的版本 ID 与名称提交信息为Version creation。环境提升自动提交Promoting Environment可选从Development 提升到 Staging时会自动产生提交提交信息形如version_number Version of app_name promoted from source_environment to destination_environment而从 Staging 提升到 Production 则不会触发提交。该选项默认关闭可在Workspace settings → Configure git页开启或关闭。删除应用不会删除仓库文件在实例中删除应用只影响该实例自身Git 仓库中的对应文件会原样保留。这也是 GitSync 天然具备「应用备份 / 可恢复」能力的体现——相关内容可参考 GitSync 概述 中关于备份用途的说明。拉取变更把应用从 Git 仓库导入到实例推送只完成了「上游同步」目标实例还需要主动「拉取」。拉取能力正是多实例模式的另一半详见 pull.md。导入应用Import from Git Repository进入目标实例的ToolJet Dashboard点击Create New App按钮右侧的kebab 菜单三个点选择Import from Git Repository在弹出的下拉框中选择要导入的应用界面会显示应用名称与最近一次提交信息点击Import App完成导入。导入时请留意以下限制与还原 / 跨实例迁移强相关从 Git 仓库导入的应用处于只读view-only模式无法直接编辑如需修改必须**克隆clone**该应用后再编辑导入应用在目标工作区中须名称唯一若与现有应用同名需要先重命名或删除现有应用才能导入工作区常量不会随 Git 仓库同步拉取后如果应用因缺失常量而报错需要在目标实例中手动补充相应的工作区常量数据源配置中的密码与密钥不会随应用一起迁移导入会把数据源一并带入但出于安全考虑会剔除其中的 secrets需要在新实例中重新填写后才能正常连通与测试。拉取最新更新Pull Changes应用导入后若上游开发实例又提交了新版本目标实例可增量同步打开应用的GitSync按钮弹出框内提供Check for Updates选项点击Check for Updates从 Git 仓库拉取最新提交弹出框会展示提交信息commit message、作者与日期等细节确认后点击Pull changes最新变更即同步进当前实例。端到端示例dev → staging → production 的完整发布流水线把上面的机制串起来就得到了官方给出的多实例迁移标准动作。example.md 用一个虚拟公司 Vertex Solutions 的例子展示了完整过程该公司维护 development、staging、production 三套 ToolJet 实例并已分别按上文步骤将三套实例的 GitSync 配置指向同一个 GitHub 仓库。阶段一在 Development 实例开发并提交开发者准备构建「库存管理系统Inventory Management System」在 Dashboard 点击Create New App填写应用名并勾选Commit changes点击Create App——应用随即以一条提交进入 Git 仓库在 App Builder 中拖拽组件、配置查询完成功能开发完成后点击顶部GitSync按钮填写提交信息并提交——仓库中随即出现对应的 commit包含提交信息、作者与时间戳。阶段二导入 Staging 实例进行测试测试人员在 Staging 实例的 Dashboard 上通过Create New App 旁的三个点 → Import from Git Repository选择该应用并点击Import App完成导入。导入完成后应用与数据源一并导入但数据源中的密码与 secrets 不会带入测试人员需要在 Staging 实例中重新填写数据源连接凭据使应用能连上测试数据应用以只读模式打开测试人员验证功能与交互。阶段三迭代修复并同步到 Staging若测试发现缺陷需要修改开发者在 Development 实例中为应用创建新版本New Version并完成修改通过 GitSync 提交新版本——仓库内应用文件夹的 JSON 更新为新版本内容.meta/meta.json同步新的版本 ID 与名称Staging 实例的测试人员点击GitSync → Check for Updates确认提交详情message、author、date后点击Pull changes最新版本即同步至 Staging。阶段四发布到 Production应用在 Staging 验收通过后生产环境负责人以同样方式在 Production 实例中通过 GitSync 导入该应用、补全生产数据源凭据并完成发布应用随即对最终用户开放。小结与阅读路径「实例即环境」的核心价值在于用基础设施隔离换取 SDLC 的确定性而 GitSync 则用「一个 Git 仓库 push/pull」把隔离的实例串联成一条可审计、可回滚的发布流水线。它同时解决了两个实际问题一是把应用变更按阶段稳定地从一个环境搬到下一个环境二是在 Git 中留下每个应用完整、带版本的历史副本天然的备份机制。若需深入了解本文涉及的上下游细节可直接阅读仓库内的下列文档实例即环境指南instance-as-environment.md本文主体配套实操示例example.mdGitSync 功能总览与使用场景overview.mdGitSync 完整配置步骤SSH 密钥、分支、部署密钥gitsync-config.md 与 ssh-config.md推送与拉取的操作细节push.md、pull.md自托管实例部署try-tooljet.md【免费下载链接】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），仅供参考