适用于把水电表或工控数据推给第三方平台的集成商、平台开发人员,以及需要和集团总部系统、政府能耗监测平台做数据对接的项目负责人
MQTT 对接第三方,八个数必须填对:连接名称、服务器地址、端口、客户端标识、用户名、密码、加密开关、协议版本。最容易出错的是三个概念混在一起:连接名称是自己看的,客户端标识是服务器用来区分客户端的,用户名密码是身份认证。另外两个高频坑:服务器地址不要填成设备地址,127.0.0.1 永远指本机。收不到数据按四步排查:是否同一台服务器、订阅是否成功且有权限、主题是否完全一致、订阅之后发送端是否真的再发过。
这篇是一份实操清单。从「数据在自己电脑上,怎么推给别人」这个真实场景出发,先把链路上的两个连接区分清楚,再逐个解释八个连接参数的含义和常见填错方式,然后讲主题命名规范、发布和订阅时 QoS 与保留消息怎么设,最后给出收不到数据的四步排查顺序,以及水电表项目对接第三方时的三条约定建议。
本节要点:采集到的数据只存在本机内存里,既没入库也没转发。要给别人用,得有一条推送通道。
很多项目的起点是这样的:现场设备的数据已经能读出来了,温度在变、运行状态在刷新,采集程序跑得好好的。
但这时候数据在哪儿。在采集程序所在那台电脑的内存里。没存数据库,没写文件,也没转发出去。程序一关,数据就没了。
接下来通常会出现一个需求:第三方厂家要数据。可能是做综合自动化平台的,可能是做上位机的,也可能是集团总部的能耗管理系统,或者政府的能耗监测平台。
怎么把数据推过去。
常见做法有几种,MQTT 是其中一个用得比较多的。它不需要对方给你开端口,不需要 IP 互通,双方各自连到同一个服务器就行。这一点在跨单位、跨网络的项目里优势很明显。
本节要点:设备到采集程序是一个连接,采集程序到 MQTT 服务器是另一个连接。两个连接的地址完全不同。
这是对接阶段**个容易出错的地方。
完整链路是这样:
Modbus 设备 → 采集程序 → MQTT 服务器 → 订阅数据的第三方平台
注意中间有两个连接:
两个地址完全是两回事。在配置 MQTT 的时候,服务器地址那一栏要填 MQTT 服务器,不是 PLC 或者电表的地址。这一点看着简单,实际项目里填错的不少,尤其是同一个人上午刚配完设备采集、下午接着配 MQTT 的时候。
再说三方角色的关系。MQTT 有三个角色:发消息的客户端、收消息的客户端、中间负责转发的服务器。服务器也叫 Broker。
放到这个场景里:采集程序是发布者,第三方平台是订阅者,MQTT 服务器是中间的 Broker。发布者和订阅者不直接通信,也不需要知道对方的 IP,两边都跟服务器通就行。
用个生活化的比方:像房产中介。卖家把房源信息给中介,买家跟中介说自己关注哪些小区,中介收到匹配的房源就推给买家。买卖双方不直接接触。
Broker 可以部署在局域网,也可以在云上。常见的选择有 Mosquitto(很轻量,适合小规模)、EMQX(功能全,适合大规模并发)、HiveMQ、NanoMQ 等。选哪个取决于接入设备数量和并发要求,几百个点位用 Mosquitto 就够,上万点位要考虑 EMQX 这类。
本节要点:前四个决定连到哪儿、以什么身份连,后四个决定怎么连、连上之后干什么。
| 参数 | 填什么 | 常见填错 |
|---|---|---|
| 连接名称 Name | 自己起的名字,方便在列表里辨认 | 误以为是服务器地址或登录账号 |
| 服务器地址 Host | MQTT 服务器的 IP 或域名 | 填成了 PLC 或电表的地址 |
| 端口 Port | 服务器监听的端口,普通 1883,TLS 8883 | 自己随便填一个数字 |
| 客户端标识 Client ID | 服务器用来区分客户端的**标识 | 和连接名称混为一谈,或多客户端重名 |
| 用户名 Username | 服务器分配的账号 | 用了演示值或默认值 |
| 密码 Password | 服务器分配的密码 | 同上 |
| 加密 SSL/TLS | 普通 TCP 关闭,跨公网对接按平台要求开启 | 跨公网还关着,明文传输 |
| 协议版本 MQTT Version | 3.1.1 或 5.0,按平台要求选 | 误以为是客户端软件的版本 |
逐条展开几个关键的。
服务器地址。左边一般要选协议,mqtt:// 是普通连接,mqtts:// 或 ssl:// 是加密连接。右边填服务器的 IP 或域名。如果是对方平台提供的服务,地址和端口由对方给,不要自己猜。
端口。端口不是自己随便挑的,服务器监听哪个端口,客户端就连哪个。普通 MQTT over TCP 默认 1883,TLS 加密默认 8883。也有平台用 8083 做 WebSocket、8084 做 WebSocket over TLS,具体看对方给什么。
客户端标识 Client ID。这个参数是服务器用来区分不同客户端的。同一台服务器上同时连接的客户端不能重名,重名会导致后连的把先连的踢下线,表现是两边都断断续续。做项目时建议按「项目-设备-角色」命名,比如 proj01-gw03-pub、proj01-platform-sub,一眼能看出是谁。
加密开关。普通 TCP 连接不加密,报文在网络上是明文。局域网内部测试可以不开,跨公网对接必须按平台要求开 TLS。这不是可选项,电表数据涉及用户用电信息,明文传输有泄露风险。
协议版本。这里选的是 MQTT 协议版本,不是客户端软件的版本。3.1.1 兼容性**,模组和网关固件支持成熟;5.0 增加了会话过期、消息过期、原因码等特性,功能更强但要求两端都支持。对接第三方时以对方要求为准,不要自己定。
本节要点:连接名称、客户端标识、用户名密码,三件事管三件不同的事。
**组:连接名称和客户端标识。
连接名称是你自己看的,随便起,改成什么都行,它不参与任何通信。客户端标识是服务器用来认人的,必须**,改名会影响连接。
实际影响:有人为了整理列表把连接名称改成「测试2」,以为换了身份,结果发现服务器上的客户端标识还是旧的,权限也没变。反过来,有人改了客户端标识却以为只是改了个显示名,结果权限对不上了。
第二组:客户端标识和用户名密码。
客户端标识是「你是谁」,用户名密码是「你凭什么进来」。有些平台会做绑定,规定某个客户端标识只能用某个账号,这种情况下两个都要对。
第三组:127.0.0.1 和服务器真实地址。
127.0.0.1 永远指当前这台电脑,不管在谁的机器上都是这个意思。只有 MQTT 服务也装在当前这台电脑上,才用它连接。连另一台服务器,就要填那台服务器的实际地址。
这个坑在测试阶段特别常见:本机装了 Mosquitto 做测试,配的是 127.0.0.1,跑通了。换到现场连对方平台,忘了改地址,一直连不上,还以为是网络问题。
本节要点:主题是消息的分类名称,用斜杠分层。对接第三方时按对方规定的来,自己定就要有规范。
主题 Topic 是 MQTT 里最核心的概念之一。它就是消息的分类名称,用斜杠分层。
比如 demo/device01/data,可以理解成「演示项目、设备01、数据」。
水电表项目里,建议按这个层级设计:
项目编号/楼栋或区域/设备类型/设备编号/数据类型
举例:proj01/b03/meter/E2026001/freeze,表示一号项目三号楼电表 E2026001 的冻结数据。
为什么要分层。三个原因:
对接第三方时有一条硬规矩:主题按对方规定的来。对方平台已经定了主题格式,你这边就必须照做,大小写、斜杠、层级一个都不能差。自己觉得不合理也要先按对方的来,这是对接的基本规则。
如果主题是自己定的,那就要写进对接文档,双方签字确认。主题这种约定,口头说一遍后面一定会出问题。
demo/Device01/data 和 demo/device01/data 是两个不同的主题,订阅了一个收不到另一个的消息。斜杠位置不同也是两个主题,demo/device01/data 和 demo/device01/data/ 末尾多一个斜杠就不一样。这类问题排查起来很费时间,因为肉眼看不出差别。本节要点:**次跑通先设 QoS 0、关闭保留消息。正式对接再按数据类型调整。
**次调通链路,建议先用最简单的配置:QoS 0,保留消息关闭。
为什么。因为这两个参数会引入额外的行为,**次就开会让排查变复杂。比如开了保留消息,新订阅的客户端会立刻收到一条历史消息,容易误以为是实时数据;用了 QoS 1,网络重传会产生重复消息,也容易看花眼。先把最基本的收发跑通,再逐项加。
正式对接的时候再按数据类型调:
保留消息的用法要克制。它适合放设备档案、当前配置、开关状态这类静态快照,新客户端一连上就能拿到。不要拿它传电量流水,否则新上线的系统会收到一条历史数据,可能当成当前值用。
消息内容格式上,MQTT 协议本身不做约束,JSON、二进制结构体、Protobuf 都行。选 JSON 的理由是看得明白、平台好解析;选二进制或 Protobuf 的理由是省流量、省算力。低频配置类数据用 JSON,高频遥测用二进制,这个分工在行业里比较通用。
字段名必须双方统一。自己这边写 temperature,对方解析 temp,就是收不到。对接文档里要把每个字段的名称、类型、单位、精度写清楚。
本节要点:连接成功只说明接上了服务器,订阅成功也不代表有人正在发。两个状态都不等于收到数据。
这一节解决一个非常典型的困惑。
配好参数,点了连接,界面显示已连接。然后新建订阅,填了主题,确认。结果消息区一片空白。
很多人**反应是配置错了。其实大概率配置没错,只是时间顺序的问题。
关键点在这:如果发送端在订阅之前就把消息发了,而且没开保留消息,那这条消息不会补发给后来订阅的人。
MQTT 的默认行为是「只转发订阅之后发布的消息」。订阅之前的消息已经转发完了,新订阅者收不到。想要补发,只有一种办法:发送时把保留标志置上,Broker 会存这个主题的最后一条,新订阅者一连上就收到。
所以验证流程必须是这个顺序:
顺序反了,看到的就是空白,而且会误判成配置问题。
另外一个容易误解的地方:发送端显示「已发布」,只代表消息交给了 Broker,不代表订阅方收到了。要看实际收到什么,必须去接收端看「已接收」的记录。
本节要点:同一台服务器、订阅权限、主题一致、订阅后有没有再发。按这个顺序查,不要跳步。
**步:两个客户端是不是连到了同一台服务器。
核对四项:IP 或域名、端口、用户名、密码。常见错误是一边连的是局域网内的测试服务器,另一边连的是云上的正式服务器;或者端口一个填 1883 一个填 8883,加密和非加密混了。
第二步:订阅有没有成功,账号有没有订阅权限。
很多 MQTT 服务器做了主题级权限控制。账号能连上,但只能发布不能订阅,或者只能订阅某个前缀下的主题。这种情况下连接和订阅操作都可能不报错,但就是收不到消息。要去看服务器的 ACL 配置或者日志。
第三步:发布和订阅的主题是否完全一致。
逐字符核对,重点看三处:大小写、斜杠位置、末尾有没有多余的斜杠。有通配符的话还要确认通配符用法对不对,+ 匹配单层,# 匹配多层且只能在末尾。
第四步:订阅之后,发送端到底有没有再发消息。
这一条最容易被跳过。前面讲过,订阅之前发的消息不会补发。确认方法是在订阅成功之后,让发送端重新发一条,再看接收端。
本节要点:主题规范、字段定义、可靠性等级。这三件事在对接启动会上定死,后面省很多事。
**条:主题规范。
谁定主题、按什么层级、用不用通配符、大小写规则,全部写进对接文档。不要出现「先按这个跑,后面再改」的情况,因为主题一改,两边的代码都要动。
第二条:字段定义。
每个字段的名称、数据类型、单位、精度、时间格式都要写清楚。举几个具体例子:电量单位是 kWh 还是 Wh,时间戳是秒还是毫秒、是本地时间还是 UTC,温度是整数还是带小数。这些不写清,后面数据对不上就要返工。
第三条:可靠性等级和重发策略。
哪类数据用哪个 QoS,重复数据怎么去重,消息丢了怎么补,这些要在对接阶段定下来。特别是冻结电量这种要用于结算的数据,必须明确「允许重复但不允许丢」还是「必须恰好一次」。
还有一条实操建议:对接测试要留完整的抓包或日志记录。项目验收时如果出现数据对不上的争议,这份记录就是依据。口头确认过什么,事后都说不清。
本节要点:**个问题问得最多,第五个是最容易误判的。
连接名称是你自己看的,随便起,不参与通信。客户端标识是服务器用来区分客户端的**标识,同一台服务器上不能重名,重名会导致后连的把先连的踢下线。这两个不要混。
看服务器开的是哪种。1883 是普通 TCP,不加密;8883 是 TLS 加密。局域网测试可以用 1883,跨公网对接应该用 8883。具体以对方平台给的参数为准,不要自己猜。
只有 MQTT 服务装在当前这台电脑上才可以。127.0.0.1 永远指本机,不管在谁的机器上。连另一台服务器要填那台的实际地址。这个坑在从本机测试切到现场对接时特别容易踩。
先查是不是订阅之前发的消息。MQTT 默认只转发订阅之后发布的消息,订阅之前的不会补发,除非发送时开了保留消息。所以验证顺序必须是先订阅、再发送。如果顺序对还是收不到,再查服务器地址是否一致、账号有没有订阅权限、主题是否完全一致。
有,而且影响很大。MQTT 主题区分大小写,device01 和 Device01 是两个不同的主题,订阅了一个收不到另一个。斜杠位置和末尾多余的斜杠也会造成不匹配。这类问题肉眼很难看出来,排查时建议直接复制粘贴比对。
先用 0 把链路跑通,不要一上来就用 1 或 2。QoS 1 会产生重复消息,QoS 2 有四次交互,**次调试时这些额外行为会让问题看起来更复杂。跑通之后再按数据类型调整。
看数据类型。设备档案、当前配置、开关状态这类静态快照可以开,新客户端一连上就能拿到。电量流水、告警事件这类时序数据不要开,否则新系统上线会收到一条历史数据,可能误当成当前值。
看规模。几百个点位用 Mosquitto 就够,部署简单、资源占用低。上千点位或者需要集群、需要 Web 管理界面,考虑 EMQX 这类。选型时重点看并发连接数、消息吞吐、权限控制能力和运维成本,不要只看功能列表。
本节要点:两个连接分开看,三组概念别混,四个排查按顺序走。
**句:一条链路上有两个连接。设备到采集程序是一个,采集程序到 MQTT 服务器是另一个。地址完全不同,配置的时候要分清在填哪个。
第二句:连接名称、客户端标识、用户名密码是三件事。一个是给自己看的,一个是给服务器认人的,一个是身份凭证。混在一起就是权限对不上、连接被踢。
第三句:收不到数据按四步查,不要跳步。同一台服务器、订阅权限、主题一致、订阅后有没有再发。这四步覆盖了九成以上的对接问题,而且顺序不能乱,因为后一步的前提是前一步成立。
对做水电表项目的团队来说,MQTT 对接不是技术难点,是流程问题。参数、主题、字段这三样在对接启动时就定死写进文档,后面省下的是反复调试和扯皮的时间。