做物联网项目做久了你会发现两个特别常见的需求一是甲方要一个数据大屏最好客人来了不用登录打开浏览器就能看二是甲方试用完平台后总会盯着界面说这个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 三步开启公共发布并生成链接流程其实很短我直接说操作步骤进入目标仪表板点击仪表板名称旁边的编辑或详情入口在菜单里找到“设为公开”或者“Make Public”按钮。点击确认后系统会给这个仪表板生成一个公开链接通常格式长这样http://你的服务器地址/dashboard/dashboardId?publicIdpublicId复制这个链接在无痕浏览器里打开验证一下确认能正常显示且没有跳转登录页。生成链接后仪表板顶部会多出一个公开状态的标识。如果你想把某个仪表板撤销公开在同一入口选择“取消公开”就行。这里要注意公开链接里的dashboardId和publicId都是UUID格式的一长串字符。它们不是什么密钥本质上是资源定位符。任何人拿到完整链接就能访问所以不要往QQ群、微信群随便丢。2.3 公开链接背后的publicId到底是什么说实话我第一次看到链接里带着publicId时也有点疑惑它跟普通仪表板的ID有什么区别简单来说dashboardId是这个仪表板本身的主键所有仪表板都有。而publicId是仪表板进入公开状态后系统额外生成的一个公开访问标识。只有在仪表板处于公开状态时这个参数才有效一旦取消公开这个publicId对应的访问路径就立刻失效。这就带来一个实际用途你可以随时“作废”一个公开链接。只要取消公开旧链接就废了。重新公开时会生成新的publicId哪怕仪表板ID没变旧链接也进不来了。这事对于管理对外分享非常有用比如展会结束、合同到期随时可以收回访问权限。2.4 公共发布用到的实体权限配置方法这才是公共发布里最容易被忽略也是最关键的一步。很多朋友按教程把仪表板设为公开后打开链接发现页面元素都在但所有组件都是空数据。这时候十有八九是实体权限没有配。ThingsBoard在处理公开访问时实际上是把这个公开链接当成一个特殊的匿名用户去读数据。仪表板里的数据组件要能读到设备数据前提是该设备被授权给了这个匿名访问层。最常见的做法是找到系统里的“Public”客户Customer然后把仪表板用到的设备、资产分配给这个客户。以大屏展示环境温湿度数据为例我通常这么操作在设备列表中找到要展示的温湿度传感器。点击设备详情在“客户”或“分配”选项卡里把设备分配给Public客户。回到公开链接刷新页面组件就能正常出数了。如果你用的是资产分组、实体组的方式来管理设备也要确认实体组本身是否给Public客户共享了访问权限。尤其是一些做了复杂资产拓扑的项目设备挂在资产下光分配了设备还不够资产没有同步授权也会导致数据读不到。这里补充一个容易混淆的点我们需要区分“仪表板公开”和“实体数据公开”是两件事。仪表板公开解决的是“这个页面能被访问”实体数据公开解决的是“页面上的组件能读到数据”。两个都配好公开页面才算真正打通。2.5 嵌入第三方大屏iframe接入与参数控制公共发布还有一个高频用法就是往第三方大屏系统里嵌iframe。操作上非常简单iframe srchttp://你的服务器地址/dashboard/dashboardId?publicIdpublicId width1920 height1080 frameborder0 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前必须备份的清单动手改代码前务必先备份。我自己的习惯是至少在三个层面留底源码层面的Git提交或压缩包备份。改错一行还能退回。原始前端构建产物的备份。因为后面要部署替换一旦新版本有兼容问题可以快速回滚到旧版前端。数据库层面不需要特殊备份但如果你在系统设置里改过主题、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。部署步骤不复杂把构建好的dist目录里的文件打包上传到服务器。替换前端静态资源目录建议先备份原目录。执行重启命令让服务加载新的静态资源sudo systemctl restart thingsboard用无痕浏览器打开平台首页强制刷新验证改动。替换时注意文件权限保持和原来一致的属主和权限位否则可能出现403。如果你用的不是systemd管理而是直接运行启动脚本就重启对应进程。核心思路都一样让前端资源文件被重新加载。4.4 docker部署场景的替换方案如果你用docker跑ThingsBoardUI替换比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 常见问题速查表问题现象可能原因处理方向公开链接空白URL参数缺失、仪表板未公开核对链接、检查公开状态公开页面无数据设备未授权给Public客户分配实体给Public客户公开页面数据不刷新刷新周期过长、浏览器节流调整组件刷新时间页面显示旧的Logo浏览器缓存无痕窗口、设置禁止缓存侧边栏Logo没变改漏了后台布局的资源检查源码里另一处Logo引用登录页样式错乱CSS变量或主题色改动影响检查主题配置并回滚测试接口请求403Nginx拦截或跨域限制检查代理配置构建时npm依赖报错Node版本不匹配用nvm切换Node版本这份速查表是我实际项目中归纳出来的基本覆盖了公共发布和UI修改的绝大多数问题。碰到问题先按表排查比自己瞎试快很多。最后再分享一个小技巧在ThingsBoard的UI定制上不要追求一次把很多地方全部改完。我习惯于每次只改一个点然后构建部署验证确认没问题再改下一个。这样如果上线后出了样式问题回溯起来非常清晰也知道是哪一次改动引入的处理起来不会手忙脚乱。做公共发布时也一样先小范围验证一个仪表板打通整套流程后再推广到其他展示页面。这套节奏看起来很慢实际上是最稳妥、返工最少的路径。