ToolJet 白标（White Labeling）完整配置指南：实例级与工作区级的品牌定制实现

ToolJet 白标（White Labeling）完整配置指南：实例级与工作区级的品牌定制实现

【免费下载链接】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 的白标（White Labeling）功能允许你在不修改源码的前提下，将自托管部署或云端工作区的外观全面替换为你自己的品牌形象——包括登录页、仪表盘、应用编辑器与已发布应用中的 Logo、浏览器标签页的 Favicon 以及页面标题，让终端用户感知不到底层运行的是 ToolJet。本文以官方文档为骨架，结合当前仓库的前后端源码，深入讲解白标配置的入口、字段、生效范围与底层实现机制，读完即可在自己的实例或工作区上完成完整的品牌化改造。

白标功能是什么

白标（White Labeling）本质上是把 ToolJet 平台的"可感知品牌元素"抽取为可配置项，包括：

• Application Logo（应用 Logo）：展示在登录页、仪表盘、应用编辑器和已部署应用中的品牌 Logo，推荐尺寸为130px × 26px。
• Favicon（站点图标）：显示在浏览器标签页上的小图标，推荐尺寸为32px × 32px或16px × 16px。
• Page Title（页面标题）：显示在浏览器标签页上的页面标题，推荐长度50–60 个字符。

从仓库实体定义看，白标配置还额外支持一张可选的Banner 图片（banner_image字段，varchar(1024)，允许为空），以及用于启停的status状态字段（ACTIVE/INACTIVE），详见 white_labelling.entity.ts。

白标的应用层级：实例级 vs 工作区级

白标配置的生效层级取决于部署形态：

这一设计在数据模型上有直接体现：white_labelling表中的organization_id列设置了unique约束，其中organizationId为空的单行记录专门代表实例级白标（见实体文件中的注释与迁移AddUniqueConstraintForNullOrganizationId的说明）；而带organizationId的记录则代表具体工作区的白标，并与organizations表通过@OneToOne关联。相关历史迁移包括 AddWhiteLabellingsettings.ts、renameWhiteLabellingTableColumns.ts 与 MoveInstanceWhiteLabelsToWhiteLabelsEntity.ts。

前端请求逻辑同样区分了这两种层级：在 white-labelling.service.js 中，get方法会先读取请求头tj-workspace-id判断当前工作区；当运行版本为 cloud 且存在组织 ID 时，请求/white-labelling/:organizationId端点，否则（CE / EE / 无组织 ID 的 Cloud）请求通用的/white-labelling端点。

自托管实例级配置

对于自托管实例，白标是实例级设置，会影响该实例上所有工作区、所有应用：

1. 使用管理员账号登录 ToolJet 实例。
2. 进入Settings > White Labelling，对应 URL 为https://app.corp.com/instance-settings/white-labelling。
3. 在配置页中分别设置：
   • Application Logo：上传或填写 Logo 资源地址（推荐 130px × 26px）。
   • Favicon：填写站点图标地址（推荐 32px × 32px 或 16px × 16px）。
   • Page Title：填写浏览器标签页标题（推荐 50–60 字符）。
4. 保存后，品牌元素即在整个实例范围内生效。

云端工作区级配置

对于云端（Cloud）部署，白标按工作区生效，不同工作区可以拥有彼此独立的品牌配置：

1. 以工作区成员身份登录 ToolJet。
2. 进入Settings > White Labelling，对应 URL 为https://app.corp.com/<workspace-slug>/settings/white-labelling。
3. 配置项与自托管完全相同（Application Logo、Favicon、Page Title），仅作用于当前工作区。
4. 保存后，仅该工作区内的界面元素（登录页、仪表盘、编辑器、已发布应用）被品牌化。

底层实现：字段、接口与前端渲染链路

服务端数据模型与接口

服务端将白标建模为独立的white_labelling表，核心字段如下（white_labelling.entity.ts）：

对外接口由 WhiteLabellingController 提供，均以white-labelling为前缀并通过@InitModule(MODULES.WHITE_LABELLING)纳入权限模块：

• GET /white-labelling：获取实例级白标配置（getInstanceWhiteLabelling）。
• GET /white-labelling/:organizationId：获取指定工作区的白标配置（getWorkspaceWhiteLabelling）。
• PUT /white-labelling与PUT /white-labelling/:organizationId：对应的更新接口。

值得注意的实现细节：当前仓库的 CE 版本中，更新类接口（PUT）直接抛出NotFoundException，即白标配置作为付费能力被刻意禁用；同时getProcessedSettings在未配置时返回内置默认值并标记is_default: true。默认值与前端定义完全一致（constant/index.ts）：

{ white_label_logo: 'assets/images/tj-logo.svg', white_label_text: 'ToolJet', white_label_favicon: 'assets/images/logo.svg', }

更新请求的校验由 dto/index.ts 中的UpdateWhiteLabellingDto完成：white_label_logo、white_label_text、white_label_favicon、white_label_banner四个字段均为可选字符串，且统一经过sanitizeInput清洗，避免注入类输入。

前端渲染链路

前端通过 Zustand 全局 store 管理白标状态（whiteLabellingStore.js），初始化时使用默认品牌（text 为ToolJet，logo 与 favicon 为空），加载成功后写入whiteLabelText、whiteLabelLogo、whiteLabelFavicon、whiteLabelBanner及isDefaultWhiteLabel标记，同时同步给 AppBuilder 的whiteLabellingSlice，保证应用编辑器中也能即时反映品牌。

页面的实际渲染由 whiteLabelling.js 驱动：

• setFaviconAndTitle(location)：根据当前路由动态设置浏览器标签页的 favicon 与标题。若当前处于编辑器/查看器路径（/apps/、/applications/）则跳过标题改写；其余路由（Settings、Marketplace、Workflows、Data sources、Audit logs、Profile settings、Home 等）会拼接为页面名 | 品牌名的格式。
• fetchAndSetWindowTitle(pageDetails)：在应用查看器/编辑器场景下，将标题设置为应用名 | 品牌名（预览态加Preview -前缀），并会读取许可证状态，未授权时回退为应用名 | ToolJet。
• applyWhiteLabelling()：从 store 读取品牌值，动态替换<link rel="icon">的href并更新document.title。
• checkWhiteLabelsDefaultState()/resetToDefaultWhiteLabels()：判断当前配置是否仍为默认值，以及一键恢复默认品牌。

常见问题（FAQ）

问：许可证或订阅过期后，白标会怎样？

答：如果许可证或订阅过期，白标会自动回退为 ToolJet 的默认品牌形象，直到许可证续费生效。这一行为与前端读取许可证状态（licenseStatus）并回退| ToolJet标题的逻辑相吻合：品牌自定义与订阅状态强绑定。

配置建议与注意事项

• 图片尺寸：Logo 建议 130px × 26px（横向品牌条）；Favicon 建议 32px × 32px 或 16px × 16px，SVG 格式兼容性最好（前端默认创建image/svg+xml类型的 icon 链接）。
• 标题长度：50–60 字符能在浏览器标签页与搜索结果中完整展示而不被截断。
• 层级选择：自托管优先在实例级统一配置，避免逐工作区重复维护；云端则天然支持按工作区差异化品牌，适合多租户/MSP 场景。
• 权限：白标接口受能力守卫（ability/guard.ts）保护，只有具备对应能力（GET/UPDATE/GET_ORGANIZATION_WHITE_LABELS/UPDATE_WORKSPACE_SETTINGS_CLOUD）的用户才能读取或修改，参见 constant/index.ts。
• 回退行为：未配置任何自定义品牌时，系统自动使用默认 Logo（assets/images/tj-logo.svg）、默认 Favicon（assets/images/logo.svg）与默认品牌名ToolJet，因此无需额外初始化即可运行。

【免费下载链接】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