ThingsBoard 空气质量指数（AQI）解决方案的 Edge 计算扩展：部署边缘节点与数据上云实战指南

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

导读

本文围绕 ThingsBoard 开源仓库中"空气质量指数（AQI）监测解决方案"的边缘计算扩展文档（edge_instructions.md）展开，系统讲解如何为分布在多城市的空气质量传感器网络部署 ThingsBoard Edge 节点：在本地完成数据采集、AQI 计算与告警决策，断网时保证数据不丢失，恢复联网后自动将数据同步回云端。读完本文，你将掌握 Edge 实体的创建与实体组分配逻辑、Edge 安装连接流程，以及如何用curl向 Edge 上的设备模拟推送遥测数据，并结合仓库中的计算字段与告警规则源码理解 AQI 在边缘侧的处理原理。

一、什么是"空气质量管理"解决方案中的 Edge 计算扩展

在 ThingsBoard 的"Air Quality Monitoring"解决方案中，边缘计算（Edge computing）是文档明确标注的可选扩展能力。其核心设计理念是：把数据分析和设备管理能力带到数据产生的地方（edge），同时根据业务需要与中心云服务器无缝同步。

edge_instructions.md 开篇即说明了该扩展的适用场景：

如果城市分散在全国各地，可以在每个城市（远程位置）部署 ThingsBoard Edge，就地处理传感器和其他设备的数据、计算 AQI，实现实时分析与决策（例如在污染等级超标时生成告警）。

这正好对应本仓库中"Air Quality Index"解决方案的文件目录结构（solutions/air_quality_index），该目录下同时包含计算字段（calculated_fields/）、告警规则（alarm_rules/）与本文所述边缘说明文档，三者共同构成完整的 AQI 解决方案资产。

二、Edge 计算的核心价值：本地处理、数据不丢、按需上云

根据边缘说明文档，Edge 在 AQI 场景中承担三项关键职责：

1. 本地实时处理：Edge 直接处理所在城市传感器的上报数据，在本地方计算 AQI 值，并在污染等级超标时立刻生成告警，无需等待与中心服务器的往返通信；
2. 断网自愈：当与中心 ThingsBoard 服务器的网络连接中断时，Edge 继续处理数据，数据不会丢失，关键决策在本地完成；
3. 回连同步：网络恢复后，必要的数据会被推送到云端，实现边缘与云端的最终一致。

同时，文档强调了一个重要的运维模型：Edge 计算业务逻辑的配置是集中化的——所有规则、计算字段、告警的配置统一放在 ThingsBoard 服务器（云）上，由云端统一下发管理，运维人员不需要到每个远程站点单独配置。

从源码看 Edge 与云端如何"握手"

从仓库中的 edge.proto 可以看出边缘节点与云服务器的底层通信机制：

• EdgeRpcService定义了handleMsgs(stream RequestMsg) returns (stream ResponseMsg)，即 Edge 与云端之间通过双向流式 RPC持续交换消息；
• ConnectRequestMsg携带edgeRoutingKey与edgeSecret进行身份认证，连接成功后由云端下发EdgeConfiguration（包含cloudEndpoint、routingKey、secret、tenantId等字段）；
• UpdateMsgType枚举（ENTITY_CREATED_RPC_MESSAGE、ENTITY_UPDATED_RPC_MESSAGE、ENTITY_DELETED_RPC_MESSAGE、ALARM_ACK_RPC_MESSAGE、ALARM_CLEAR_RPC_MESSAGE）说明了云端向 Edge 下发实体同步与告警操作的协议类型。

这从代码层面印证了文档所述"Edge 与云端按业务需要无缝同步"的实现方式。

三、解决方案预置的 Edge 实体与实体组分配

在该解决方案范围内，系统已经创建了一个名为"Remote Location R1"的 Edge 实体，用于演示典型的"远程位置"部署。为了简化 Edge 的部署，以下实体组已经被预先分配（assigned）到该 Edge 实体：

实体组预先分配的意义在于：Edge 安装并连接成功后，这些实体会自动同步到边缘节点，无需在边缘侧手工重建任何资产、设备或仪表板。

从仓库的 calculated_fields 目录可以看到与这套实体体系对应的数据处理逻辑：

• aqi_sensor_aqi_calculation.json：绑定DEVICE_PROFILE的 SCRIPT 类型计算字段，实现"每个传感器"的 AQI 计算；
• aqi_city_aqi_sensor_aggregation.json：绑定ASSET_PROFILE的RELATED_ENTITIES_AGGREGATION类型计算字段，通过Contains关系把该城市下所有传感器的aqi、humidity聚合到城市资产上（详见后文）。

四、安装 Edge 并连接到云端

文档给出的 Edge 安装流程非常明确，分为两步：

1. 打开Edge 详情页面（Edge details page），点击"Install & Connect instructions"（安装与连接指引）按钮；
2. 按照指引完成 ThingsBoard Edge 的安装，并使其连接到云服务器。

连接成功后，你就可以使用**租户凭据（tenant credentials）**登录 Edge 的 Web UI。这意味着边缘节点共享云端租户的登录体系，同一个租户下的账号可以直接访问边缘控制台。

说明：原文档中的 Edge 详情页链接为模板占位符${Remote Location R1EDGE_DETAILS_URL}，实际部署时由系统根据当前环境动态替换为对应 Edge 实体的详情页地址。

登录后验证同步结果

Edge 连接云端的核心验证方式如下：

• 由于"AQI Sensor"DEVICE 组已被分配给 Edge 实体 "Remote Location R1"，该组内的所有设备都会被自动 provision 到边缘节点；
• 登录 Edge 后，进入Entities -> Devices页面即可看到这些设备；
• 其中典型的演示设备为"Air Quality Sensor 1"。

五、向 Edge 上的设备推送遥测数据（curl 实战）

文档提供了完整的、可直接执行的curl命令，用于模拟设备 "Air Quality Sensor 1" 向 Edge 上报遥测数据。这是验证整个 Edge 链路是否打通的最快捷方式。

默认端口（8080）写法

curl -v -X POST -d "{\"temperature\": 42, \"humidity\": 73, \"pm25\": 24.4, \"pm10\": 30, \"no2\": 13, \"co\": 2.8, \"so2\": 7, \"o3\": 0.164, \"batteryLevel\": 77 }" http://localhost:8080/api/v1/${Air Quality Sensor 1ACCESS_TOKEN}/telemetry --header "Content-Type:application/json"

修改过绑定端口（18080）的写法

如果在 Edge 安装过程中把 HTTP 8080 绑定端口改成了18080，则使用：

curl -v -X POST -d "{\"temperature\": 42, \"humidity\": 73, \"pm25\": 24.4, \"pm10\": 30, \"no2\": 13, \"co\": 2.8, \"so2\": 7, \"o3\": 0.164, \"batteryLevel\": 77 }" http://localhost:18080/api/v1/${Air Quality Sensor 1ACCESS_TOKEN}/telemetry --header "Content-Type:application/json"

命令要点解读

• URL 结构：/api/v1/${ACCESS_TOKEN}/telemetry是 ThingsBoard 标准的 HTTP 设备遥测上报接口，其中${Air Quality Sensor 1ACCESS_TOKEN}是设备 "Air Quality Sensor 1" 的访问令牌（Access Token），在设备详情页获取后替换占位符即可；
• 请求体字段：temperature（温度）、humidity（湿度）、pm25/pm10（颗粒物浓度）、no2/co/so2/o3（气体污染物浓度）以及batteryLevel（电池电量）——这正是 aqi_sensor_aqi_calculation.json 中 AQI 计算所需的全部输入遥测键（TS_LATEST）；
• 验证方式：命令执行成功并返回 200 状态码后，可以分别在 Edge 控制台（设备最新遥测）与云端控制台查看该设备的遥测更新。文档明确说明：向 Edge 上的设备推送数据后，云端同一设备的遥测也会同步更新，这正是"断网本地处理、联网自动上云"链路打通后的直接证据。

六、从源码看 AQI 在边缘侧的计算链路

边缘节点的计算能力之所以能在断网时保持自洽，是因为 AQI 解决方案的计算字段、告警规则均随实体组同步到了 Edge 上。仓库源码揭示了完整的计算链路：

1. 传感器级 AQI 计算（SCRIPT 计算字段）

aqi_sensor_aqi_calculation.json 定义了AQI Calculation计算字段：

• 输入参数为pm25、pm10、no2、co、so2、o3六种污染物的最新遥测值（TS_LATEST）；
• 脚本内置了各污染物浓度区间到 AQI 分段的映射表（如pm25AqiMapping、pm10AqiMapping、no2AqiMapping、coAqiMapping、so2AqiMapping、o3AqiMapping），对应 0-50、51-100、101-150、151-200、201-300、301-400、401-500 共七档 AQI 区间；
• calculateAqi(value, vMapping, aMapping)函数按线性插值公式(aqiHigh - aqiLow) / (bpHigh - bpLow) * (value - bpLow) + aqiLow计算单项污染物对应的 AQI 分数；
• 最终综合 AQI 取各污染物单项 AQI 的最大值（aqi = Math.max(aqi, ...)），并输出为时间序列（output.type = TIME_SERIES）。

2. 城市级聚合（RELATED_ENTITIES_AGGREGATION 计算字段）

aqi_city_aqi_sensor_aggregation.json 定义了AQI Sensor Aggregation计算字段：

• 通过Contains关系（direction: FROM）把城市资产与其下属传感器关联起来；
• 将关联传感器的aqi与humidity做AVG（平均值）、temperature做MAX（最大值）聚合，写入城市资产的时间序列；
• 每 10 秒（scheduledUpdateInterval: 10）定时更新一次，并启用scheduledUpdateEnabled。

3. 告警规则（ALARM 计算字段）

alarm_rules 目录下包含两条与边缘决策直接相关的告警规则：

• aqi_sensor_inactive.json：当传感器active（服务端属性）为false时创建 CRITICAL 级"设备失联"告警，恢复为true时自动清除，propagate: true表示告警可传播；
• aqi_sensor_low_battery_level.json：当batteryLevel遥测 ≤ 服务端属性batteryLevelThreshold（默认 30.0）时创建 CRITICAL 级"低电量"告警，充电恢复后清除。

这两条规则正是文档所述"在污染等级超标时生成告警"决策能力的落地形态——它们与计算字段一起随实体组同步到 Edge，保证断网时 Edge 依然能独立完成"计算 AQI → 判断超标 → 生成告警"的完整闭环。

七、端到端验证与常见排查要点

把前面各部分串起来，一套完整的 Edge 扩展验证流程如下：

1. 在云端创建/确认 Edge 实体 "Remote Location R1"，并确认四类实体组（2 个 Dashboard 组、1 个 Asset 组、1 个 Device 组）已分配；
2. 通过 Edge 详情页的Install & Connect instructions完成 Edge 安装与云端连接；
3. 使用租户凭据登录 Edge，进入Entities -> Devices确认 "Air Quality Sensor 1" 等设备已自动同步；
4. 执行第三节中的curl命令向 Edge 上报遥测（注意端口按安装配置选择 8080 或 18080，令牌替换为设备真实 Access Token）；
5. 分别在 Edge 与云端查看该设备遥测是否更新，验证同步链路；
6. 观察云端/边缘的告警与 AQI 计算输出，验证计算字段与告警规则在边缘侧生效。

常见注意点：

• 端口差异：Edge 安装时若修改过 HTTP 绑定端口，务必使用对应的 18080 写法，否则连接会被拒绝；
• 令牌占位符：${Air Quality Sensor 1ACCESS_TOKEN}必须替换为设备页面中的真实令牌，不能直接执行原样命令；
• 实体组同步是前提：只有被分配给 Edge 实体的设备组才会自动 provision 到边缘，未分配的实体不会出现在 Edge 的 Devices 页面。

八、小结

"Air Quality Monitoring"解决方案的 Edge 扩展（edge_instructions.md）为跨地域的空气质量监测网络提供了一套"边缘自治 + 云端统一管理 + 断网保数据、联网即同步"的落地方案：通过预置的 "Remote Location R1" Edge 实体与四类实体组简化部署，通过统一的curl遥测上报接口打通设备到边缘再到云端的全链路。结合仓库中 计算字段、告警规则 与 edge.proto 的源码实现，可以确认：AQI 计算、城市聚合与告警决策均可完全在边缘侧独立完成，这正是 ThingsBoard 在"数据产生地就地分析、按需回传云端"这一架构方向上的典型实践。

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