企业官网建设流程全解析

• 物联网
• 后端
• 数据可视化
• 消息队列

导读

本文基于 ThingsBoard 仓库中 Smart Office（智能办公）解决方案的官方文档application/src/main/data/json/solutions/smart_office/edge_instructions.md，深入讲解如何为智能办公场景引入 ThingsBoard Edge 边缘计算：从「远程办公室为何需要边缘节点」的业务动因，到 Edge 实例的安装与云端连接、实体组自动分配原理，再到用curl命令向 Edge 上的设备模拟上传遥测数据的完整实操，最后结合服务端源码揭示占位符替换与 HTTP 遥测 API 的底层实现。读完本文，你将掌握在 Smart Office 解决方案中部署和验证边缘计算能力的一整套可复现方案。

边缘计算在 Smart Office 解决方案中的定位

文档明确指出，边缘计算是 Smart Office 解决方案的可选扩展（Optionally），并非安装时的强制部分。其核心理念是：把数据分析和处理能力下沉到数据产生的地方。

ThingsBoard Edge 允许在边缘侧进行数据分析和设备管理，同时根据业务需要与 ThingsBoard 云端无缝同步。在 Smart Office 的场景中，最典型的应用是全国分布多地的远程办公室：

• 在每个办公室内部署一台 ThingsBoard Edge；
• Edge 直接处理来自传感器、摄像头和其他设备的本地数据；
• 实现实时分析和本地决策，例如自动关灯、自动调节温度；
• 当办公室与中央 ThingsBoard 服务器之间没有网络连接时，Edge 仍然可以独立处理数据，保证数据不丢失、决策本地即时执行；
• 一旦网络连接恢复，Edge 会把所需数据回推（push）到云端。

这种架构的重要设计原则是：边缘计算业务逻辑的配置集中在单一位置——ThingsBoard 服务器。也就是说，运维人员只需要在云端统一配置规则、实体组和分配关系，Edge 端无需重复维护业务逻辑，配置变更通过同步机制下发到各边缘节点。

为 Smart Office 预置的边缘实体与实体组

在本文档所属解决方案的安装流程中，系统会自动创建一个名为Remote Office R1的边缘实体（Edge entity），它代表一个远程办公室的边缘计算节点。

为了简化边缘部署，安装过程中已经预先将以下实体组（Entity Groups）分配给了该边缘实体：

这种「实体组绑定边缘」的机制是 ThingsBoard 边缘同步的核心：被分配到边缘的实体组中的实体，会被自动配置（provision）到该边缘节点上。实体组的数据模型定义可参见仓库源码 EntityGroup.java，它是一个实现HasName、HasOwnerId等接口的标准实体，支持按所有者（租户或客户）归属管理。

安装 ThingsBoard Edge 并连接到云端

操作入口

要安装 ThingsBoard Edge 并连接到云端，请执行以下步骤：

1. 打开Remote Office R1的边缘详情页面（即安装 Smart Office 解决方案后生成的Edge details page）；
2. 点击页面上的Install & Connect instructions（安装与连接指引）按钮；
3. 系统会给出针对当前环境的 Edge 安装脚本与连接配置；
4. 完成安装后，Edge 会自动与云端建立连接（Connected状态）。

用租户凭据登录 Edge

文档特别强调：Edge 安装并连接到云端后，你可以直接使用你的租户凭据（tenant credentials）登录 Edge 界面。这是因为边缘节点复用了租户的身份体系，不需要单独创建边缘账号。

关于 Edge 安装与端口配置的细节，仓库中内置了完整的分环境安装指引，例如：

• Docker 安装：application/src/main/data/json/edge/instructions/install/docker/instructions.md
• CentOS 安装：application/src/main/data/json/edge/instructions/install/centos/instructions.md

其中与本文档直接相关的是HTTP 绑定端口的可配置性：Edge 默认通过8080端口对外提供 HTTP 服务，但如果 Edge 与 ThingsBoard 服务器运行在同一台机器上，为避免端口冲突，需要在安装时把 Edge 的 HTTP 端口修改为18080（Docker 场景下同时还需将 MQTT1883改为11883、CoAP5683-5688改为15683-15688）。这正是文档中后续两个curl命令分别使用8080与18080的原因。

设备如何自动配置到边缘：Office sensors 设备组

文档指出，"Office sensors" DEVICE 组已被分配给了边缘实体 "Remote Office R1"。这意味着：

该组中的所有设备都会在 Edge 与云端建立连接后，被自动配置（automatically provisioned）到边缘节点上。

具体验证方式：

1. 使用租户凭据登录 Edge 界面；
2. 导航到Entities -> Devices（实体 -> 设备）页面；
3. 即可看到Office sensors组中同步下来的所有设备。

对于 Smart Office 解决方案而言，这批设备包括"Energy meter"（电能表）等典型办公室能耗监测设备。这些设备在 Edge 端既可以被采集数据，也可以被下发控制指令，从而支撑"断网时本地决策"的业务目标。

模拟数据上传：向 Edge 上的 Energy meter 推送遥测

标准端口（8080）命令

在完成 Edge 部署与设备同步后，为了验证端到端的数据链路，可以以设备 "Energy meter" 的身份向 Edge 推送一条遥测数据。执行以下命令：

curl -v -X POST -d "{\"voltage\": 220, \"frequency\": 60, \"amperage\": 16, \"power\": 3000, \"energy\": 300}" http://localhost:8080/api/v1/${Energy meterACCESS_TOKEN}/telemetry --header "Content-Type:application/json"{:copy-code}

修改端口后的命令（18080）

如果在 Edge 安装过程中，你将 Edge 的 HTTP 绑定端口从默认的8080修改为18080，则请使用以下命令：

curl -v -X POST -d "{\"voltage\": 220, \"frequency\": 60, \"amperage\": 16, \"power\": 3000, \"energy\": 300}" http://localhost:18080/api/v1/${Energy meterACCESS_TOKEN}/telemetry --header "Content-Type:application/json"{:copy-code}

命令要素拆解

• URL 路径：/api/v1/{deviceToken}/telemetry是 ThingsBoard HTTP 传输服务的标准遥测上传端点。{deviceToken}即设备的Access Token（访问令牌），在解决方案安装完成后自动生成，文档中的${Energy meterACCESS_TOKEN}是服务端在渲染说明文档时动态填充的实际令牌占位符。
• 请求方法：POST，请求体为 JSON 格式的遥测键值对，本示例包含voltage（电压）、frequency（频率）、amperage（电流）、power（功率）、energy（累计电能）五个字段，与 energy_meter.json 所定义的"电能表"设备画像高度吻合。
• -v参数：输出详细的 HTTP 请求/响应过程，便于观察 HTTP 状态码（成功应为200 OK）与握手细节。

底层实现：HTTP 遥测 API

该端点在仓库中的真实实现位于 HTTP 传输模块的 DeviceApiController.java：

@RequestMapping(value = "/{deviceToken}/telemetry", method = RequestMethod.POST) public DeferredResult<ResponseEntity> postTelemetry( @PathVariable("deviceToken") String deviceToken, @RequestBody String json, HttpServletRequest request) { ... transportContext.getTransportService().process(DeviceTransportType.DEFAULT, ValidateDeviceTokenRequestMsg.newBuilder().setToken(deviceToken).build(), new DeviceAuthCallback(transportContext, responseWriter, sessionInfo -> { ... transportService.process(sessionInfo, JsonConverter.convertToTelemetryProto(JsonParser.parseString(json)), new HttpOkCallback(responseWriter)); })); }

其处理链路为：校验设备令牌 → 通过 TransportService 建立设备会话 → 将 JSON 遥测载荷转换为 protobuf 消息 → 进入消息队列交给 Rule Engine 处理。整个/api/v1/**路径在 TransportSecurityConfiguration.java 中被声明为设备 API 入口，任何持有有效设备令牌的请求都可以访问。

在 Edge 节点上，这一端点由 Edge 自带的 HTTP 传输服务提供，因此对 Edge 的请求与对云端服务器的请求在 API 形态上完全一致——这体现了 ThingsBoard 边缘同步"同一套设备 API"的设计。

数据从边缘回传到云端

文档给出的关键验证结论是：

一旦你向 Edge 上的设备 "Energy meter" 推送了数据，你同样能在云端看到该设备的遥测更新。

这条结论直接印证了边缘同步的双向特性：

• 边缘本地实时处理：数据先到达 Edge 的本地消息队列与规则引擎，可触发本地决策（如自动控制）与本地存储；
• 云端异步回推：Edge 按照与云端建立的同步通道，将必要的遥测数据持续回传到云端，业务侧可以在主控制台统一查看所有远程办公室的数据。

因此，即使远程办公室长时间处于断网状态，期间产生的遥测数据也会缓存在 Edge 本地；一旦网络恢复，数据自动补推到云端，实现"断网不丢数据、联网自动同步"的可靠性保障。

源码印证：说明文档中的占位符是如何被填充的

本文档（edge_instructions.md）在仓库中以模板形式存在，其中包含${Remote Office R1EDGE_DETAILS_URL}、${Energy meterACCESS_TOKEN}等运行时占位符。它们由服务端解决方案安装逻辑负责替换，核心实现位于 DefaultSolutionService.java 的prepareInstructions()方法中，关键逻辑包括：

1. 边缘说明注入：当模板包含${edge_instructions}占位符时，如果安装上下文中存在已创建的边缘实体，则读取edge_instructions.md文件内容并替换占位符；如果没有创建边缘实体，则将该占位符替换为空串，避免向用户展示不可用的边缘内容。
2. 边缘详情页链接：遍历已创建的边缘实体，将${Remote Office R1EDGE_DETAILS_URL}替换为指向/edgeManagement/edges/all/{edgeId}（若边缘归属客户，则前缀/customers/all/{customerId}）的实际界面链接。
3. 设备访问令牌：遍历安装过程中创建的设备，将${Energy meterACCESS_TOKEN}等占位符替换为对应设备凭据中的真实credentialsId（即 Access Token），保证文档中的curl命令开箱即用。

这意味着你在安装 Smart Office 解决方案后看到的边缘说明，是系统基于实际创建边缘的 ID、设备令牌等运行时数据动态生成的个性化文档，而非静态的通用文本。

总结

Smart Office 解决方案的边缘计算扩展为"多地远程办公室"的物联网场景提供了一条清晰的落地路径：在云端统一配置、通过实体组自动分发设备与资产到边缘、以租户凭据直接登录边缘节点、用与云端一致的 HTTP API 在本地模拟与验证设备遥测上传，并依靠边缘同步机制保证断网场景下的数据零丢失与决策本地化。如果你想在自己的租户中复现这一能力，只需安装 Smart Office 解决方案后，进入 "Remote Office R1" 边缘详情页点击Install & Connect instructions，再按本文档中的curl命令完成一次端到端验证即可。

• 物联网
• 后端
• 数据可视化
• 消息队列