企业官网建设流程全解析

做物联网项目做久了，你会发现两个特别常见的需求：一是甲方要一个数据大屏，最好客人来了不用登录，打开浏览器就能看；二是甲方试用完平台后，总会盯着界面说，这个Logo换成我们公司的，平台名字也改一下，配色能不能跟企业VI靠一靠。这两个需求，在ThingsBoard里分别对应“公共发布”和“UI细节修改”两件事。今天这篇就集中把这两块讲透，全是实际项目里能直接用的操作，不绕弯子。

如果你是从头玩ThingsBoard的新手，前几篇已经解决了设备接入、数据可视化、规则链这些核心问题，那这篇就是收尾阶段最关键的一步：让你的平台既能对外展示，又带点“自家产品”的样子。不管你是给园区做能耗大屏，还是给设备厂商做演示环境，这套流程基本都适用。

1. 公共发布前先想清楚：这个功能到底解决什么问题

1.1 公共发布的典型使用场景

先说场景，不然容易搞混。ThingsBoard的公共发布，说白了就是把某个仪表板（Dashboard）变成一个没有登录门槛的公开链接，任何人拿到链接，打开就能看到页面内容。

我实际用下来的常见场景有几种：

• 园区访客大屏：前台放一台电视，循环播放设备状态、停车位占用、环境数据，不可能让访客去登录后台。
• 对外数据展示：给投资方、客户、评审专家演示项目成果，现场临时登录账号既麻烦又容易出问题，给个公开链接最省事。
• 大屏轮播系统：很多时候大屏是在浏览器里用iframe嵌进去的，做统一运营管理。公开链接天然适合这种嵌入，省去token刷新、会话过期这类麻烦。
• 多屏监控室看板：公司内部有几块屏幕，每块屏幕专注显示不同维度的数据，单独设个只读公开页面比给十几个账号更可控。

在这些场景里，公共发布的价值不在于“安全”，而在于“零门槛访问 + 只读展示”。想清楚这一点，后面配置时就不会对功能抱有错误期待。

1.2 公开仪表板与登录后仪表板到底差在哪

有朋友问，这不就是把URL分享出去嘛，跟把账号密码给别人有什么区别？

区别大了。公开仪表板的底层逻辑是以一个匿名身份去访问系统资源。它和登录后的仪表板相比，至少有这几个明显差异：

第一，不需要认证流程。访问公开链接时，ThingsBoard不会跳转登录页，而是直接渲染仪表板。这意味着你是以“游客”身份在浏览页面内容。

第二，所有交互都是只读的。公开页面上你没法打开设备详情、没法去改仪表板布局、没法确认告警、更没法下发任何RPC指令。页面上的组件大部分只能看看数据曲线和最新值。

第三，实体数据权限仍然受控。虽然链接是公开的，但不代表系统把整个平台的数据都给你看。公开仪表板里每个组件能读到哪些设备的数据，取决于这些设备是否被授权给了匿名访问这一层。

很多人第一次做公共发布，配置完链接发出去，发现页面是空白或者组件显示“No data”，90%的原因就在第三点。这个我后面专门讲怎么处理。

1.3 四个不适合公共发布的场景

公共发布不是万金油，这几个场景我用过或者见别人踩过坑，大概率不适合：

• 带控制按钮的仪表板。仪表板里放了RPC命令下发的按钮、规则链启停开关、告警确认按钮，公开之后就等于把这些能力暴露给了无认证用户。我见过有人把控制页面公开的，还好只是测试环境，生产环境这么干风险很大。
• 含敏感业务数据的页面。公开链接只要流出去，谁都能看。设备位置、客户信息、计费数据这类内容，千万不要放到公开仪表板里。
• 需要写回操作的场景。公共发布整体是只读思路，不适合用来做工单流转、维保登记这类交互流程。
• 频繁变化数据且需要高并发鉴权的场景。虽然公共链接没有登录压力，但大量并发访问仍然会打到后端查询接口上，性能瓶颈并没有消失。

想清楚“能不能用”“该不该用”这两个问题，再动手配置，后面会顺手很多。

2. 公共发布配置完整流程（附3个关键权限点）

2.1 前置检查：版本确认与仪表板梳理

不同ThingsBoard版本在公共发布这个功能的入口和文案上有差异。我这边用的是3.x系列的社区版，功能入口在仪表板右侧的分享/发布按钮上。如果你用的是2.x老版本，可能是在仪表板属性里设置。先确认下版本，不然照着教程找不到按钮就容易懵。

另外一个建议，在发布之前先在系统里把仪表板整理一下。只保留需要对外展示的页面，把调试用的临时仪表板、内部工作台、开发中的半成品都收起来或者直接删掉。这样后面生成公开链接时更清晰，也不会误把调试页面分享出去。

还有一个经验：尽量复制一个仪表板副本专门做公开版，而不是直接公开正在开发的仪表板。因为你在后台继续改布局时，公开页面会同步变化，很多时候改到一半看到线上页面“变形了”非常尴尬。专门的公开副本可以避免这个问题。

2.2 三步开启公共发布并生成链接

流程其实很短，我直接说操作步骤：

1. 进入目标仪表板，点击仪表板名称旁边的编辑或详情入口，在菜单里找到“设为公开”或者“Make Public”按钮。
2. 点击确认后，系统会给这个仪表板生成一个公开链接，通常格式长这样：

http://<你的服务器地址>/dashboard/<dashboardId>?publicId=<publicId>

3. 复制这个链接，在无痕浏览器里打开验证一下，确认能正常显示且没有跳转登录页。

生成链接后，仪表板顶部会多出一个公开状态的标识。如果你想把某个仪表板撤销公开，在同一入口选择“取消公开”就行。

这里要注意，公开链接里的dashboardId和publicId都是UUID格式的一长串字符。它们不是什么密钥，本质上是资源定位符。任何人拿到完整链接就能访问，所以不要往QQ群、微信群随便丢。

2.3 公开链接背后的publicId到底是什么

说实话，我第一次看到链接里带着publicId时也有点疑惑，它跟普通仪表板的ID有什么区别？

简单来说，dashboardId是这个仪表板本身的主键，所有仪表板都有。而publicId是仪表板进入公开状态后，系统额外生成的一个公开访问标识。只有在仪表板处于公开状态时，这个参数才有效；一旦取消公开，这个publicId对应的访问路径就立刻失效。

这就带来一个实际用途：你可以随时“作废”一个公开链接。只要取消公开，旧链接就废了。重新公开时会生成新的publicId，哪怕仪表板ID没变，旧链接也进不来了。这事对于管理对外分享非常有用，比如展会结束、合同到期，随时可以收回访问权限。

2.4 公共发布用到的实体权限配置方法

这才是公共发布里最容易被忽略，也是最关键的一步。

很多朋友按教程把仪表板设为公开后，打开链接发现页面元素都在，但所有组件都是空数据。这时候十有八九是实体权限没有配。

ThingsBoard在处理公开访问时，实际上是把这个公开链接当成一个特殊的匿名用户去读数据。仪表板里的数据组件要能读到设备数据，前提是该设备被授权给了这个匿名访问层。最常见的做法是找到系统里的“Public”客户（Customer），然后把仪表板用到的设备、资产分配给这个客户。

以大屏展示环境温湿度数据为例，我通常这么操作：

1. 在设备列表中，找到要展示的温湿度传感器。
2. 点击设备详情，在“客户”或“分配”选项卡里，把设备分配给Public客户。
3. 回到公开链接刷新页面，组件就能正常出数了。

如果你用的是资产分组、实体组的方式来管理设备，也要确认实体组本身是否给Public客户共享了访问权限。尤其是一些做了复杂资产拓扑的项目，设备挂在资产下，光分配了设备还不够，资产没有同步授权也会导致数据读不到。

这里补充一个容易混淆的点：我们需要区分“仪表板公开”和“实体数据公开”是两件事。仪表板公开解决的是“这个页面能被访问”，实体数据公开解决的是“页面上的组件能读到数据”。两个都配好，公开页面才算真正打通。

2.5 嵌入第三方大屏：iframe接入与参数控制

公共发布还有一个高频用法，就是往第三方大屏系统里嵌iframe。操作上非常简单：

<iframe src="http://<你的服务器地址>/dashboard/<dashboardId>?publicId=<publicId>" width="1920" height="1080" frameborder="0" allowfullscreen> </iframe>

有几点经验供参考：

• 如果大屏页面和你ThingsBoard不是同一个域名，注意跨域问题。一般的展示场景直接用iframe加载就行，不用做什么特殊处理。
• 可以在iframe上加allowfullscreen，让大屏播放器能够全屏切换。
• 如果担心被别的站点随意引用，可以在Nginx层增加Referer校验，只允许指定来源的请求。这个属于安全加固，生产环境值得做。

另外一个常见需求是在公开页面里隐藏鼠标、隐藏干扰元素，这个通常交给大屏本身的播放器解决，ThingsBoard里不用额外配置。

3. UI细节修改的两种路径：系统配置优先，源码定制兜底

3.1 版本区分：白标功能在开源版与商业版的位置

很多国内团队用的是社区开源版，而开源版和商业版（Professional Edition）在UI自定义上的能力差别很大。

商业版自带White Label白标功能，可以在管理界面直接配置品牌Logo、平台名称、配色主题、页脚版权信息等，不用改代码。如果你公司买了商业版授权，直接用后台上传Logo就行，这篇就不用往下看了。

但如果你跟我一样用的是开源社区版，那就得走源码定制路线。好消息是ThingsBoard的前端代码是Angular写的，结构比较清晰，改起来并不难。

这里我先说一个重要判断：UI细节修改前，先确认哪些是能在系统设置里改的，哪些必须动源码。能不改代码尽量不改代码，后面升级版本时省心很多。

3.2 系统设置里能直接改的细节：Logo、平台名、基础色

开源版本虽然在界面配置上没有商业版那么全，但部分内容仍然可以在系统设置中调整。主要入口是“系统设置”里的外观或主题相关配置。

比如说，平台标题和Logo在某些配置项里是支持的。如果你在本地源码启动或自编译安装，可以通过修改配置项来覆盖默认品牌信息。具体路径因版本不同会有差异，我常用的方法是登录后进入“设置”页面，找Appearance相关选项卡，看是否有Logo上传、平台名称配置入口。如果找到了，直接改就是了。

不过实践经验告诉我，开源版本的系统级UI自定义能力比较有限，真正要做出“像自己公司产品”的效果，动源码是绕不开的。

3.3 需要动源码的高频定制点

ThingsBoard前端的Logo、平台名、登录页文案这些资源，大多集中在ui-ngx的assets目录和对应的组件模板里。我改动比较多的几个点：

• 登录页Logo：替换assets目录下的logo文件，把默认的ThingsBoard图标换成自己公司的图标。
• 侧边栏Logo：顶部导航或左侧菜单里的图标，同样是通过替换对应svg/png资源实现。
• 平台显示名称：登录页、浏览器标签页、页面标题里显示的“ThingsBoard”文字，需要去对应的模板文件里修改。
• 登录页背景：登录页的背景图或主题色，通过CSS变量或背景图替换调整。
• 页脚版权信息：页面底部的版权声明，找到footer模板改掉即可。

我做UI修改时奉行一个原则：能改配置文件就改配置文件，其次改静态资源，最不济才去动模板代码。因为模板代码通常和组件结构绑定紧密，改不好会导致编译失败。

3.4 修改UI前必须备份的清单

动手改代码前，务必先备份。我自己的习惯是至少在三个层面留底：

1. 源码层面的Git提交或压缩包备份。改错一行还能退回。
2. 原始前端构建产物的备份。因为后面要部署替换，一旦新版本有兼容问题，可以快速回滚到旧版前端。
3. 数据库层面不需要特殊备份，但如果你在系统设置里改过主题、Logo，最好也记一下原始配置值，避免改过之后忘记了。

我见过有人直接在生产服务器上改了文件没有备份，后面想回退，发现找不到原文件，只能重新下载安装包，非常耽误事。

4. 前端重新构建与部署全记录

4.1 构建环境准备

ThingsBoard前端是Angular工程，前置环境需要Node.js和npm。版本要求上，3.x系列一般用Node 16或18都行，具体以源码里的package.json为准。

我第一次编译时踩过一个坑：直接用系统自带的Node版本太低，npm install报了一堆依赖错误。后来改用nvm管理Node版本，把Node切到项目要求的版本再装依赖，一路顺畅。

源码解压后进入ui-ngx目录，执行：

npm install

这一步会花一些时间，国内网络环境建议把npm源切到国内镜像，否则有些包会下载失败。

4.2 修改有效后的构建流程

资源改完之后执行构建：

npm run build

构建产物会输出到dist目录，里面就是可以部署的前端静态文件。

这里有个大坑：如果你只是改了assets目录里的Logo图片，其实不用重新编译整个前端。但如果你改了模板文件、CSS变量、路由配置这类代码，就必须重新走构建流程，否则改动不会生效。

我通常的流程是：先小范围验证，比如只改一个Logo文件，直接在已有构建产物的对应路径下替换文件，刷新页面看效果。确认Logo这种资源类修改没问题后，再统一处理需要重新编译的代码改动，最后一次性构建部署，减少反复编译的次数。

4.3 部署到Linux服务实例的完整路径

我的ThingsBoard实例是通过官方安装脚本部署在Linux服务器上的。前端静态资源的目录一般是/usr/share/thingsboard/ui。

部署步骤不复杂：

1. 把构建好的dist目录里的文件打包上传到服务器。
2. 替换前端静态资源目录，建议先备份原目录。
3. 执行重启命令，让服务加载新的静态资源：

sudo systemctl restart thingsboard

4. 用无痕浏览器打开平台首页，强制刷新验证改动。

替换时注意文件权限，保持和原来一致的属主和权限位，否则可能出现403。

如果你用的不是systemd管理，而是直接运行启动脚本，就重启对应进程。核心思路都一样：让前端资源文件被重新加载。

4.4 docker部署场景的替换方案

如果你用docker跑ThingsBoard，UI替换比Linux安装包方式稍微绕一点，不能直接ssh进宿主机改目录就完事，因为容器内是一个隔离环境。

常用方案有两种：

方案一，进入容器替换。先找到容器ID，然后把构建产物拷贝进去：

docker cp ./dist/. <容器ID>:/usr/share/thingsboard/ui/

然后重启容器：

docker restart <容器ID>

这套方案适合临时改改，但容器一旦删掉重建，改动就丢了。

方案二，挂载卷方式，也是我更推荐的方式。在docker run或docker-compose配置里，把宿主机的目录挂载到容器内的前端静态目录，之后只要往宿主机目录里丢新文件，重启容器或刷新页面就能生效，维护起来方便很多。

如果你用的是官方维护的docker-compose脚本，也可以自己改挂载配置，但记得提前备份原始compose文件，避免改错导致服务起不来。

4.5 部署后验证清单

每次部署完UI，我习惯快速核对一遍这几个点：

• 浏览器标签页标题是否变成新平台名。
• 登录页Logo、侧边栏Logo是否替换成功。
• 登录页背景色调是否符合预期。
• 页面整体布局有没有错乱，尤其是改了CSS变量之后。
• 使用手机访问一遍首页，确认响应式布局没被破坏。
• 找一个普通业务页面，确认组件能正常出数，接口没报错。

其中第四点和第六点最容易出问题，改主题色时一不小心就把某处文字颜色搞成和背景一样了，这种问题在电脑上看不明显，换到深色主题或手机上就会暴露。

统一说一下，浏览器缓存也是一个很常见的“改了没生效”原因。前端构建后的文件通常带hash值，正常不会有强缓存问题。但如果你改了index.html或者文件名没变，浏览器会用旧缓存。验证时直接用无痕窗口，省得被缓存误导。

5. 公共发布与UI修改的常见问题排查（含速查表）

5.1 公开链接打开后是空白页面

这是我收到最多的问题。公开链接打开后页面空白，排查顺序基本是：

第一步看URL格式。确认链接里带了dashboardId和publicId，而且没有因为拷贝截断缺失参数。

第二步看仪表板是否真的处于公开状态。回到后台，确认仪表板编辑页面里公开开关是开启的。

第三步看浏览器控制台报错。打开F12，看看有没有401、403或者加载静态资源的404。如果有403，大概率是Nginx或代理层配置拦截了什么。

第四步看实体权限。如果页面框架出来了但数据组件为空，重点检查设备/资产是否授权给了Public客户。

我排过最诡异的一个案例：仪表板、设备权限都配好了，公开链接在自己电脑上能打开，客户那边打开却空白。后来发现是客户公司内部网络屏蔽了部分域名，并不是ThingsBoard本身的问题。所以远程排查时，最好先让对方案浏览器访问一下其他公开网站，排除网络层因素。

5.2 公开仪表板数据不刷新

公开页面的数据不刷新，最常见原因是组件配置里的数据刷新周期太长，或者前端定时查询被浏览器节能策略限制。

ThingsBoard仪表板组件默认会定期刷新数据。如果页面切换标签页时间久了再切回来，数据看起来是“停住”的，这通常是浏览器对后台标签页的定时器做了节流。把页面固定在前台展示，或者降低刷新间隔可以缓解。

还有一种情况是时间窗口设置问题。有些组件默认展示最近一个时间段的时序数据，如果设备本身没有新数据上报，页面自然看起来不刷新。这时候先确认设备侧数据到底有没有持续上报，再怀疑前端配置。

我自己的习惯是：在大屏展示场景里，把组件的时间窗口设置为“最近1小时”或“最近24小时”，并且开启自动刷新，这样实际展示效果最好。

5.3 UI改完没有变化

UI代码改了、构建也成功了、部署也重启了，页面却还是老样子。这种现象大概率是浏览器缓存。

因为静态资源文件名如果没变，浏览器会直接使用本地缓存。解决办法很简单：用无痕窗口访问，或者在Nginx层给静态资源配置禁用缓存：

location /assets/ { add_header Cache-Control "no-cache, no-store, must-revalidate"; expires 0; }

另外确认一下你替换的前端资源目录，确实是被当前运行的ThingsBoard实例加载的那个目录。如果你部署了一套旧的，另一套还在跑，改来改去当然看不到效果。

5.4 登录页正常但侧边栏Logo未变

这类问题大多是改漏了资源文件。登录页和侧边栏使用的Logo通常是两个不同的文件，一个在登录页面用，一个在后台布局里用。你只替换了登录页的Logo，侧边栏自然不变。

解决方法是找到后台布局引用的Logo资源文件，一并替换。如果源码里是同一个文件名但目录不同，就把两个目录的文件都换掉，重新构建再部署。

5.5 常见问题速查表

这份速查表是我实际项目中归纳出来的，基本覆盖了公共发布和UI修改的绝大多数问题。碰到问题先按表排查，比自己瞎试快很多。

最后再分享一个小技巧：在ThingsBoard的UI定制上，不要追求一次把很多地方全部改完。我习惯于每次只改一个点，然后构建部署验证，确认没问题再改下一个。这样如果上线后出了样式问题，回溯起来非常清晰，也知道是哪一次改动引入的，处理起来不会手忙脚乱。做公共发布时也一样，先小范围验证一个仪表板，打通整套流程后，再推广到其他展示页面。这套节奏看起来很慢，实际上是最稳妥、返工最少的路径。