ToolJet 自托管部署自定义域名配置指南基于 TOOLJET_HOST 的完整方案【免费下载链接】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 的开发者系统讲解如何通过设置TOOLJET_HOST环境变量为实例绑定自定义域名并在此基础上深入剖析该变量在服务端 CORS 校验、邮件链接生成、邀请 URL 构造等核心链路中的底层作用帮助读者不仅配得上更配得对。自定义域名配置概览在 ToolJet 的自托管部署中客户端服务默认通过localhost或服务器 IP 访问。若要使用自己注册的域名例如app.corp.ai对外提供服务核心做法是设置TOOLJET_HOST环境变量In a self-hosted deployment of ToolJet, you can configure a custom domain by setting theTOOLJET_HOSTenvironment variable.该变量定义了 ToolJet 客户端对外可访问的公共 URL是自托管实例身份的单一事实来源。除了影响用户访问入口外它还深度参与服务端的安全校验与各类链接生成详见源码实现剖析。前置条件开始配置前请确保满足以下三个前提一个正在运行的自托管 ToolJet 实例。可参考仓库中的部署方案通过 docker-compose.yaml 或 deploy/kubernetes/deployment.yaml 等方式完成部署。一个已注册的域名。例如corp.ai、app.corp.ai。一条已配置的 DNS 记录将你的域名解析指向 ToolJet 服务器。此外若 ToolJet 运行在反向代理如 Nginx之后还需确保代理将对应 Host 头正确转发到后端服务。配置步骤步骤 1设置 TOOLJET_HOST 环境变量TOOLJET_HOST变量用于定义 ToolJet 对外可访问的公共 URL。你需要将其更新为期望的域名取值形式如下表所示变量描述TOOLJET_HOSTToolJet 客户端的公共 URL例如https://app.corp.ai、https://corp.ai、https://corp.ai/app从表中可见该变量支持三种典型的取值形态带独立子域https://app.corp.ai——将客户端部署在专门的应用子域裸域https://corp.ai——直接使用主域名带路径前缀https://corp.ai/app——配合反向代理将 ToolJet 挂载在域名的子路径下此时还需配合子路径相关配置。在 docker-compose 部署中设置若使用 docker-compose.yaml 部署可直接在.env文件中配置。仓库根目录提供了完整的 .env.example 模板其中默认值为TOOLJET_HOSThttp://localhost:8082将其修改为你自己的域名即可例如TOOLJET_HOSThttps://app.corp.ai在 Kubernetes 部署中设置若使用 Kubernetes 部署TOOLJET_HOST通过 Secret 注入到部署清单中。见 deploy/kubernetes/deployment.yaml- name: TOOLJET_HOST valueFrom: secretKeyRef: name: server key: tj_host因此需要将serverSecret 中的tj_host键值更新为目标域名deploy/kubernetes/AKS/deployment.yaml 与 deploy/kubernetes/GKE/deployment.yaml 采用了相同的注入方式。Helm 方式则对应 deploy/helm/templates/tooljet/deployment.yaml。在 Docker 镜像中设置官方构建的 Dockerfile 也以ENV形式声明了默认值例如 docker/ce-preview.DockerfileENV TOOLJET_HOSThttp://localhost运行时可通过docker run -e TOOLJET_HOST...或 compose 的environment字段覆盖。补充说明ENABLE_CORS 与 SUB_PATH在修改TOOLJET_HOST时常会涉及两个关联变量ENABLE_CORS默认情况下服务端 CORS 严格限制为TOOLJET_HOST当把前端部署到与后端不同的主机时需将该值设为true见 .env.exampleSUB_PATH当TOOLJET_HOST采用https://corp.ai/app这种带路径前缀的形态时服务端在生成链接如邀请链接时会拼接SUB_PATH作为子路径见 utils.helper.ts。步骤 2重启服务在完成环境变量与 DNS 配置后重启 ToolJet 部署使改动生效。以 docker-compose 为例docker compose up -d或先停止再启动docker compose down docker compose up -dKubernetes 场景下更新 Secret 后滚动重启相关工作负载如kubectl rollout restart。重启后可通过浏览器访问新域名验证是否生效。:::info 自定义域名功能即将在 ToolJet Cloud云托管版中支持本文方案适用于自托管部署。 :::源码实现剖析TOOLJET_HOST 在服务端的作用设置TOOLJET_HOST不仅仅是改变访问入口它在服务端多个关键链路中被直接读取和使用。理解这些底层机制有助于避免配置后出现的能访问但功能异常问题。1. CORS 与 CSRF 校验的白名单基准服务端在设置安全响应头时会将TOOLJET_HOST解析为默认允许的来源Origin。见 bootstrap.helper.tsconst tooljetHost configService.getstring(TOOLJET_HOST)?.replace(/\/$/, ); const host new URL(tooljetHost); const domain host.hostname; const corsWildcard configService.getstring(ENABLE_CORS) true; // Always allow the default TOOLJET_HOST origin if (requestOrigin tooljetHost) { return callback(null, true); }当ENABLE_CORS为true时放行所有来源corsWildcard分支否则仅放行TOOLJET_HOST以及配置了自定义域名custom domains的来源其余来源会被拒绝callback(null, false)。同时setupCsrfOriginCheck 中间件在启用自定义域名时会校验变更类请求POST/DELETE 等的Origin头是否匹配TOOLJET_HOST或活跃的自定义域名否则返回403 Origin not allowed。注意实现细节代码会先对TOOLJET_HOST做replace(/\/$/, )去除末尾斜杠再与请求 Origin 做精确字符串比较因此配置时请保持值一致如统一使用https://app.corp.ai不要写成带尾斜杠的https://app.corp.ai/。2. 邮件链接与邀请链接的 URL 基准服务端生成各类对外链接时均以TOOLJET_HOST为基准拼接邀请链接生成utils.helper.ts 中的generateInviteURL与generateOrgInviteURL使用process.env.TOOLJET_HOST可通过host参数覆盖作为 base URL再拼接SUB_PATH子路径、邀请令牌与查询参数const effectiveHost host || process.env.TOOLJET_HOST; const subpath process.env.SUB_PATH; const baseURL ${effectiveHost}${subpath ? subpath : /};邮件服务email/service.ts 中通过stripTrailingSlash(process.env.TOOLJET_HOST)保存主机地址用于构造邮件正文中的链接email/util.service.ts 则从ConfigService读取同样的变量。这意味着如果TOOLJET_HOST未配置或配置错误用户收到的邀请邮件、重置密码邮件中的链接将指向错误地址。这也是官方文档将TOOLJET_HOST列为自托管必配变量的原因。3. 组织自定义域名回退Custom Domains仓库中已存在组织级自定义域名模块custom-domains/cache.service.ts。在 getHostForOrganization 中若某组织配置了活跃的 custom domain则优先返回https://domain否则回退到process.env.TOOLJET_HOSTif (organizationId cacheService) { const domain await cacheService.getActiveDomainForOrg(organizationId); if (domain) return https://${domain}; } return process.env.TOOLJET_HOST;也就是说TOOLJET_HOST是自托管实例的全局默认主机在引入组织级自定义域名后它仍作为兜底值存在cloud 版本的自定义域名支持正在建设中。4. 协议推断与 URL 解析utils.helper.ts 还基于TOOLJET_HOST做协议判断如startsWith(https)用于判定是否启用 HTTPS 相关行为并使用new URL()解析主机若TOOLJET_HOST不是合法的完整 URL如缺少协议头new URL()会抛出异常因此务必使用带协议前缀的完整 URLhttps://...而非app.corp.ai。验证配置生效配置并重启后可以通过以下方式验证访问验证浏览器打开https://app.corp.ai应正常进入 ToolJet 登录页。安全头验证在浏览器开发者工具或命令行中检查响应头curl -I确认 CORS 相关逻辑以新域名为准curl -I https://app.corp.ai邮件链接验证触发一封邀请邮件确认其中链接指向新域名而非旧的localhost。常见问题排查页面能打开但接口请求被 CORS 拦截检查TOOLJET_HOST是否与浏览器地址栏中的 Origin 完全一致含协议、去掉末尾斜杠必要时设置ENABLE_CORStrue。收到403 Origin not allowed多为变更类请求的Origin与TOOLJET_HOST或自定义域名不匹配可核对服务端日志中的拒绝记录bootstrap.helper.ts。邮件内链接指向 localhost确认服务端进程实际加载的环境变量已更新重启后生效且未在启动脚本中被覆盖。配置了https://corp.ai/app形态但路径不对确认反向代理正确转发子路径并检查SUB_PATH是否与服务端生成链接所需的路径一致见 .env.example 相关说明。参考资源.env.example——全部环境变量模板与注释含TOOLJET_HOST、ENABLE_CORS、SUB_PATH等bootstrap.helper.ts——CORS / CSRF / 安全头实现utils.helper.ts——邀请链接与主机解析工具email/service.ts——邮件链接构造docker-compose.yaml——自托管 docker-compose 部署入口deploy/kubernetes/deployment.yaml——Kubernetes 部署清单中的TOOLJET_HOST注入deploy/helm/templates/tooljet/deployment.yaml——Helm 部署中的环境变量声明【免费下载链接】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），仅供参考
ToolJet 自托管部署自定义域名配置指南：基于 TOOLJET_HOST 的完整方案
ToolJet 自托管部署自定义域名配置指南基于 TOOLJET_HOST 的完整方案【免费下载链接】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 的开发者系统讲解如何通过设置TOOLJET_HOST环境变量为实例绑定自定义域名并在此基础上深入剖析该变量在服务端 CORS 校验、邮件链接生成、邀请 URL 构造等核心链路中的底层作用帮助读者不仅配得上更配得对。自定义域名配置概览在 ToolJet 的自托管部署中客户端服务默认通过localhost或服务器 IP 访问。若要使用自己注册的域名例如app.corp.ai对外提供服务核心做法是设置TOOLJET_HOST环境变量In a self-hosted deployment of ToolJet, you can configure a custom domain by setting theTOOLJET_HOSTenvironment variable.该变量定义了 ToolJet 客户端对外可访问的公共 URL是自托管实例身份的单一事实来源。除了影响用户访问入口外它还深度参与服务端的安全校验与各类链接生成详见源码实现剖析。前置条件开始配置前请确保满足以下三个前提一个正在运行的自托管 ToolJet 实例。可参考仓库中的部署方案通过 docker-compose.yaml 或 deploy/kubernetes/deployment.yaml 等方式完成部署。一个已注册的域名。例如corp.ai、app.corp.ai。一条已配置的 DNS 记录将你的域名解析指向 ToolJet 服务器。此外若 ToolJet 运行在反向代理如 Nginx之后还需确保代理将对应 Host 头正确转发到后端服务。配置步骤步骤 1设置 TOOLJET_HOST 环境变量TOOLJET_HOST变量用于定义 ToolJet 对外可访问的公共 URL。你需要将其更新为期望的域名取值形式如下表所示变量描述TOOLJET_HOSTToolJet 客户端的公共 URL例如https://app.corp.ai、https://corp.ai、https://corp.ai/app从表中可见该变量支持三种典型的取值形态带独立子域https://app.corp.ai——将客户端部署在专门的应用子域裸域https://corp.ai——直接使用主域名带路径前缀https://corp.ai/app——配合反向代理将 ToolJet 挂载在域名的子路径下此时还需配合子路径相关配置。在 docker-compose 部署中设置若使用 docker-compose.yaml 部署可直接在.env文件中配置。仓库根目录提供了完整的 .env.example 模板其中默认值为TOOLJET_HOSThttp://localhost:8082将其修改为你自己的域名即可例如TOOLJET_HOSThttps://app.corp.ai在 Kubernetes 部署中设置若使用 Kubernetes 部署TOOLJET_HOST通过 Secret 注入到部署清单中。见 deploy/kubernetes/deployment.yaml- name: TOOLJET_HOST valueFrom: secretKeyRef: name: server key: tj_host因此需要将serverSecret 中的tj_host键值更新为目标域名deploy/kubernetes/AKS/deployment.yaml 与 deploy/kubernetes/GKE/deployment.yaml 采用了相同的注入方式。Helm 方式则对应 deploy/helm/templates/tooljet/deployment.yaml。在 Docker 镜像中设置官方构建的 Dockerfile 也以ENV形式声明了默认值例如 docker/ce-preview.DockerfileENV TOOLJET_HOSThttp://localhost运行时可通过docker run -e TOOLJET_HOST...或 compose 的environment字段覆盖。补充说明ENABLE_CORS 与 SUB_PATH在修改TOOLJET_HOST时常会涉及两个关联变量ENABLE_CORS默认情况下服务端 CORS 严格限制为TOOLJET_HOST当把前端部署到与后端不同的主机时需将该值设为true见 .env.exampleSUB_PATH当TOOLJET_HOST采用https://corp.ai/app这种带路径前缀的形态时服务端在生成链接如邀请链接时会拼接SUB_PATH作为子路径见 utils.helper.ts。步骤 2重启服务在完成环境变量与 DNS 配置后重启 ToolJet 部署使改动生效。以 docker-compose 为例docker compose up -d或先停止再启动docker compose down docker compose up -dKubernetes 场景下更新 Secret 后滚动重启相关工作负载如kubectl rollout restart。重启后可通过浏览器访问新域名验证是否生效。:::info 自定义域名功能即将在 ToolJet Cloud云托管版中支持本文方案适用于自托管部署。 :::源码实现剖析TOOLJET_HOST 在服务端的作用设置TOOLJET_HOST不仅仅是改变访问入口它在服务端多个关键链路中被直接读取和使用。理解这些底层机制有助于避免配置后出现的能访问但功能异常问题。1. CORS 与 CSRF 校验的白名单基准服务端在设置安全响应头时会将TOOLJET_HOST解析为默认允许的来源Origin。见 bootstrap.helper.tsconst tooljetHost configService.getstring(TOOLJET_HOST)?.replace(/\/$/, ); const host new URL(tooljetHost); const domain host.hostname; const corsWildcard configService.getstring(ENABLE_CORS) true; // Always allow the default TOOLJET_HOST origin if (requestOrigin tooljetHost) { return callback(null, true); }当ENABLE_CORS为true时放行所有来源corsWildcard分支否则仅放行TOOLJET_HOST以及配置了自定义域名custom domains的来源其余来源会被拒绝callback(null, false)。同时setupCsrfOriginCheck 中间件在启用自定义域名时会校验变更类请求POST/DELETE 等的Origin头是否匹配TOOLJET_HOST或活跃的自定义域名否则返回403 Origin not allowed。注意实现细节代码会先对TOOLJET_HOST做replace(/\/$/, )去除末尾斜杠再与请求 Origin 做精确字符串比较因此配置时请保持值一致如统一使用https://app.corp.ai不要写成带尾斜杠的https://app.corp.ai/。2. 邮件链接与邀请链接的 URL 基准服务端生成各类对外链接时均以TOOLJET_HOST为基准拼接邀请链接生成utils.helper.ts 中的generateInviteURL与generateOrgInviteURL使用process.env.TOOLJET_HOST可通过host参数覆盖作为 base URL再拼接SUB_PATH子路径、邀请令牌与查询参数const effectiveHost host || process.env.TOOLJET_HOST; const subpath process.env.SUB_PATH; const baseURL ${effectiveHost}${subpath ? subpath : /};邮件服务email/service.ts 中通过stripTrailingSlash(process.env.TOOLJET_HOST)保存主机地址用于构造邮件正文中的链接email/util.service.ts 则从ConfigService读取同样的变量。这意味着如果TOOLJET_HOST未配置或配置错误用户收到的邀请邮件、重置密码邮件中的链接将指向错误地址。这也是官方文档将TOOLJET_HOST列为自托管必配变量的原因。3. 组织自定义域名回退Custom Domains仓库中已存在组织级自定义域名模块custom-domains/cache.service.ts。在 getHostForOrganization 中若某组织配置了活跃的 custom domain则优先返回https://domain否则回退到process.env.TOOLJET_HOSTif (organizationId cacheService) { const domain await cacheService.getActiveDomainForOrg(organizationId); if (domain) return https://${domain}; } return process.env.TOOLJET_HOST;也就是说TOOLJET_HOST是自托管实例的全局默认主机在引入组织级自定义域名后它仍作为兜底值存在cloud 版本的自定义域名支持正在建设中。4. 协议推断与 URL 解析utils.helper.ts 还基于TOOLJET_HOST做协议判断如startsWith(https)用于判定是否启用 HTTPS 相关行为并使用new URL()解析主机若TOOLJET_HOST不是合法的完整 URL如缺少协议头new URL()会抛出异常因此务必使用带协议前缀的完整 URLhttps://...而非app.corp.ai。验证配置生效配置并重启后可以通过以下方式验证访问验证浏览器打开https://app.corp.ai应正常进入 ToolJet 登录页。安全头验证在浏览器开发者工具或命令行中检查响应头curl -I确认 CORS 相关逻辑以新域名为准curl -I https://app.corp.ai邮件链接验证触发一封邀请邮件确认其中链接指向新域名而非旧的localhost。常见问题排查页面能打开但接口请求被 CORS 拦截检查TOOLJET_HOST是否与浏览器地址栏中的 Origin 完全一致含协议、去掉末尾斜杠必要时设置ENABLE_CORStrue。收到403 Origin not allowed多为变更类请求的Origin与TOOLJET_HOST或自定义域名不匹配可核对服务端日志中的拒绝记录bootstrap.helper.ts。邮件内链接指向 localhost确认服务端进程实际加载的环境变量已更新重启后生效且未在启动脚本中被覆盖。配置了https://corp.ai/app形态但路径不对确认反向代理正确转发子路径并检查SUB_PATH是否与服务端生成链接所需的路径一致见 .env.example 相关说明。参考资源.env.example——全部环境变量模板与注释含TOOLJET_HOST、ENABLE_CORS、SUB_PATH等bootstrap.helper.ts——CORS / CSRF / 安全头实现utils.helper.ts——邀请链接与主机解析工具email/service.ts——邮件链接构造docker-compose.yaml——自托管 docker-compose 部署入口deploy/kubernetes/deployment.yaml——Kubernetes 部署清单中的TOOLJET_HOST注入deploy/helm/templates/tooljet/deployment.yaml——Helm 部署中的环境变量声明【免费下载链接】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），仅供参考
