MQTT 对接第三方平台:八个连接参数怎么填,收不到数据怎么查

2026-11-07 18:00 合众致达
5
通讯技术 · 平台对接

MQTT 对接第三方平台:八个连接参数怎么填,收不到数据怎么查

适用于把水电表或工控数据推给第三方平台的集成商、平台开发人员,以及需要和集团总部系统、政府能耗监测平台做数据对接的项目负责人

结论

MQTT 对接第三方,八个数必须填对:连接名称、服务器地址、端口、客户端标识、用户名、密码、加密开关、协议版本。最容易出错的是三个概念混在一起:连接名称是自己看的,客户端标识是服务器用来区分客户端的,用户名密码是身份认证。另外两个高频坑:服务器地址不要填成设备地址,127.0.0.1 永远指本机。收不到数据按四步排查:是否同一台服务器、订阅是否成功且有权限、主题是否完全一致、订阅之后发送端是否真的再发过。

摘要

这篇是一份实操清单。从「数据在自己电脑上,怎么推给别人」这个真实场景出发,先把链路上的两个连接区分清楚,再逐个解释八个连接参数的含义和常见填错方式,然后讲主题命名规范、发布和订阅时 QoS 与保留消息怎么设,最后给出收不到数据的四步排查顺序,以及水电表项目对接第三方时的三条约定建议。

01

先看清问题:数据在自己这儿,怎么推给别人

本节要点:采集到的数据只存在本机内存里,既没入库也没转发。要给别人用,得有一条推送通道。

很多项目的起点是这样的:现场设备的数据已经能读出来了,温度在变、运行状态在刷新,采集程序跑得好好的。

但这时候数据在哪儿。在采集程序所在那台电脑的内存里。没存数据库,没写文件,也没转发出去。程序一关,数据就没了。

接下来通常会出现一个需求:第三方厂家要数据。可能是做综合自动化平台的,可能是做上位机的,也可能是集团总部的能耗管理系统,或者政府的能耗监测平台。

怎么把数据推过去。

常见做法有几种,MQTT 是其中一个用得比较多的。它不需要对方给你开端口,不需要 IP 互通,双方各自连到同一个服务器就行。这一点在跨单位、跨网络的项目里优势很明显。

02

一条链路上有两个连接,别混成一个

本节要点:设备到采集程序是一个连接,采集程序到 MQTT 服务器是另一个连接。两个连接的地址完全不同。

这是对接阶段**个容易出错的地方。

完整链路是这样:

Modbus 设备 → 采集程序 → MQTT 服务器 → 订阅数据的第三方平台

注意中间有两个连接:

  • 连接一:采集程序连设备。这里填的是设备的地址,串口号或者 IP 加端口
  • 连接二:采集程序连 MQTT 服务器。这里填的是 MQTT 服务器的地址

两个地址完全是两回事。在配置 MQTT 的时候,服务器地址那一栏要填 MQTT 服务器,不是 PLC 或者电表的地址。这一点看着简单,实际项目里填错的不少,尤其是同一个人上午刚配完设备采集、下午接着配 MQTT 的时候。

再说三方角色的关系。MQTT 有三个角色:发消息的客户端、收消息的客户端、中间负责转发的服务器。服务器也叫 Broker。

放到这个场景里:采集程序是发布者,第三方平台是订阅者,MQTT 服务器是中间的 Broker。发布者和订阅者不直接通信,也不需要知道对方的 IP,两边都跟服务器通就行。

用个生活化的比方:像房产中介。卖家把房源信息给中介,买家跟中介说自己关注哪些小区,中介收到匹配的房源就推给买家。买卖双方不直接接触。

Broker 可以部署在局域网,也可以在云上。常见的选择有 Mosquitto(很轻量,适合小规模)、EMQX(功能全,适合大规模并发)、HiveMQ、NanoMQ 等。选哪个取决于接入设备数量和并发要求,几百个点位用 Mosquitto 就够,上万点位要考虑 EMQX 这类。

03

八个连接参数,逐个说清

本节要点:前四个决定连到哪儿、以什么身份连,后四个决定怎么连、连上之后干什么。

参数填什么常见填错
连接名称 Name自己起的名字,方便在列表里辨认误以为是服务器地址或登录账号
服务器地址 HostMQTT 服务器的 IP 或域名填成了 PLC 或电表的地址
端口 Port服务器监听的端口,普通 1883,TLS 8883自己随便填一个数字
客户端标识 Client ID服务器用来区分客户端的**标识和连接名称混为一谈,或多客户端重名
用户名 Username服务器分配的账号用了演示值或默认值
密码 Password服务器分配的密码同上
加密 SSL/TLS普通 TCP 关闭,跨公网对接按平台要求开启跨公网还关着,明文传输
协议版本 MQTT Version3.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 增加了会话过期、消息过期、原因码等特性,功能更强但要求两端都支持。对接第三方时以对方要求为准,不要自己定。

高级设置里通常有三项可以先保持默认:连接超时(单次连接等待多久算失败,一般 10 秒)、保活时间 Keep Alive(心跳周期,一般 60 秒)、自动重连(断线后是否自动尝试恢复)。跨公网且网络不稳定的场景,自动重连建议打开。
04

三个概念别混,这是最高频的错误

本节要点:连接名称、客户端标识、用户名密码,三件事管三件不同的事。

**组:连接名称和客户端标识。

连接名称是你自己看的,随便起,改成什么都行,它不参与任何通信。客户端标识是服务器用来认人的,必须**,改名会影响连接。

实际影响:有人为了整理列表把连接名称改成「测试2」,以为换了身份,结果发现服务器上的客户端标识还是旧的,权限也没变。反过来,有人改了客户端标识却以为只是改了个显示名,结果权限对不上了。

第二组:客户端标识和用户名密码。

客户端标识是「你是谁」,用户名密码是「你凭什么进来」。有些平台会做绑定,规定某个客户端标识只能用某个账号,这种情况下两个都要对。

第三组:127.0.0.1 和服务器真实地址。

127.0.0.1 永远指当前这台电脑,不管在谁的机器上都是这个意思。只有 MQTT 服务也装在当前这台电脑上,才用它连接。连另一台服务器,就要填那台服务器的实际地址。

这个坑在测试阶段特别常见:本机装了 Mosquitto 做测试,配的是 127.0.0.1,跑通了。换到现场连对方平台,忘了改地址,一直连不上,还以为是网络问题。

05

主题怎么定,别随手起个 abc

本节要点:主题是消息的分类名称,用斜杠分层。对接第三方时按对方规定的来,自己定就要有规范。

主题 Topic 是 MQTT 里最核心的概念之一。它就是消息的分类名称,用斜杠分层。

比如 demo/device01/data,可以理解成「演示项目、设备01、数据」。

水电表项目里,建议按这个层级设计:

项目编号/楼栋或区域/设备类型/设备编号/数据类型

举例:proj01/b03/meter/E2026001/freeze,表示一号项目三号楼电表 E2026001 的冻结数据。

为什么要分层。三个原因:

  • 订阅灵活:平台可以订阅整栋楼,也可以只订阅一只表,靠通配符就能做到
  • 权限好做:按主题前缀分配权限,一个项目的网关看不到另一个项目的数据
  • 后期好扩:新增楼栋、新增设备类型不用改结构

对接第三方时有一条硬规矩:主题按对方规定的来。对方平台已经定了主题格式,你这边就必须照做,大小写、斜杠、层级一个都不能差。自己觉得不合理也要先按对方的来,这是对接的基本规则。

如果主题是自己定的,那就要写进对接文档,双方签字确认。主题这种约定,口头说一遍后面一定会出问题。

一个隐蔽的坑:MQTT 的主题是区分大小写的。demo/Device01/data 和 demo/device01/data 是两个不同的主题,订阅了一个收不到另一个的消息。斜杠位置不同也是两个主题,demo/device01/data 和 demo/device01/data/ 末尾多一个斜杠就不一样。这类问题排查起来很费时间,因为肉眼看不出差别。
06

发布时 QoS 和保留消息怎么设

本节要点:**次跑通先设 QoS 0、关闭保留消息。正式对接再按数据类型调整。

**次调通链路,建议先用最简单的配置:QoS 0,保留消息关闭。

为什么。因为这两个参数会引入额外的行为,**次就开会让排查变复杂。比如开了保留消息,新订阅的客户端会立刻收到一条历史消息,容易误以为是实时数据;用了 QoS 1,网络重传会产生重复消息,也容易看花眼。先把最基本的收发跑通,再逐项加。

正式对接的时候再按数据类型调:

  • 实时遥测类(电压、电流、功率),用 QoS 0 就够,丢一条下一轮补上
  • 冻结电量、告警事件,用 QoS 1 保证送达,业务侧做幂等去重
  • 拉合闸指令、扣费指令,用 QoS 2 保证只执行一次

保留消息的用法要克制。它适合放设备档案、当前配置、开关状态这类静态快照,新客户端一连上就能拿到。不要拿它传电量流水,否则新上线的系统会收到一条历史数据,可能当成当前值用。

消息内容格式上,MQTT 协议本身不做约束,JSON、二进制结构体、Protobuf 都行。选 JSON 的理由是看得明白、平台好解析;选二进制或 Protobuf 的理由是省流量、省算力。低频配置类数据用 JSON,高频遥测用二进制,这个分工在行业里比较通用。

字段名必须双方统一。自己这边写 temperature,对方解析 temp,就是收不到。对接文档里要把每个字段的名称、类型、单位、精度写清楚。

07

为什么连上了还是没数据

本节要点:连接成功只说明接上了服务器,订阅成功也不代表有人正在发。两个状态都不等于收到数据。

这一节解决一个非常典型的困惑。

配好参数,点了连接,界面显示已连接。然后新建订阅,填了主题,确认。结果消息区一片空白。

很多人**反应是配置错了。其实大概率配置没错,只是时间顺序的问题。

关键点在这:如果发送端在订阅之前就把消息发了,而且没开保留消息,那这条消息不会补发给后来订阅的人。

MQTT 的默认行为是「只转发订阅之后发布的消息」。订阅之前的消息已经转发完了,新订阅者收不到。想要补发,只有一种办法:发送时把保留标志置上,Broker 会存这个主题的最后一条,新订阅者一连上就收到。

所以验证流程必须是这个顺序:

  1. 先建接收端连接,订阅主题,确认订阅成功
  2. 再切回发送端,重新发一条消息
  3. 回到接收端,看有没有收到

顺序反了,看到的就是空白,而且会误判成配置问题。

另外一个容易误解的地方:发送端显示「已发布」,只代表消息交给了 Broker,不代表订阅方收到了。要看实际收到什么,必须去接收端看「已接收」的记录。

08

收不到数据,四步排查

本节要点:同一台服务器、订阅权限、主题一致、订阅后有没有再发。按这个顺序查,不要跳步。

**步:两个客户端是不是连到了同一台服务器。

核对四项:IP 或域名、端口、用户名、密码。常见错误是一边连的是局域网内的测试服务器,另一边连的是云上的正式服务器;或者端口一个填 1883 一个填 8883,加密和非加密混了。

第二步:订阅有没有成功,账号有没有订阅权限。

很多 MQTT 服务器做了主题级权限控制。账号能连上,但只能发布不能订阅,或者只能订阅某个前缀下的主题。这种情况下连接和订阅操作都可能不报错,但就是收不到消息。要去看服务器的 ACL 配置或者日志。

第三步:发布和订阅的主题是否完全一致。

逐字符核对,重点看三处:大小写、斜杠位置、末尾有没有多余的斜杠。有通配符的话还要确认通配符用法对不对,+ 匹配单层,# 匹配多层且只能在末尾。

第四步:订阅之后,发送端到底有没有再发消息。

这一条最容易被跳过。前面讲过,订阅之前发的消息不会补发。确认方法是在订阅成功之后,让发送端重新发一条,再看接收端。

排查的时候有个高效做法:在服务器上直接看日志。EMQX 和 Mosquitto 都能记录连接、订阅、发布的详细日志。看日志能直接判断是「根本没连上」「连上了但没订阅成功」还是「订阅成功了但没人发」,比在客户端猜快得多。
09

水电表项目对接第三方,三条约定要先谈

本节要点:主题规范、字段定义、可靠性等级。这三件事在对接启动会上定死,后面省很多事。

**条:主题规范。

谁定主题、按什么层级、用不用通配符、大小写规则,全部写进对接文档。不要出现「先按这个跑,后面再改」的情况,因为主题一改,两边的代码都要动。

第二条:字段定义。

每个字段的名称、数据类型、单位、精度、时间格式都要写清楚。举几个具体例子:电量单位是 kWh 还是 Wh,时间戳是秒还是毫秒、是本地时间还是 UTC,温度是整数还是带小数。这些不写清,后面数据对不上就要返工。

第三条:可靠性等级和重发策略。

哪类数据用哪个 QoS,重复数据怎么去重,消息丢了怎么补,这些要在对接阶段定下来。特别是冻结电量这种要用于结算的数据,必须明确「允许重复但不允许丢」还是「必须恰好一次」。

还有一条实操建议:对接测试要留完整的抓包或日志记录。项目验收时如果出现数据对不上的争议,这份记录就是依据。口头确认过什么,事后都说不清。

10

八个常见问题

本节要点:**个问题问得最多,第五个是最容易误判的。

问:连接名称和客户端标识有什么区别

连接名称是你自己看的,随便起,不参与通信。客户端标识是服务器用来区分客户端的**标识,同一台服务器上不能重名,重名会导致后连的把先连的踢下线。这两个不要混。

问:端口填 1883 还是 8883

看服务器开的是哪种。1883 是普通 TCP,不加密;8883 是 TLS 加密。局域网测试可以用 1883,跨公网对接应该用 8883。具体以对方平台给的参数为准,不要自己猜。

问:服务器地址能不能填 127.0.0.1

只有 MQTT 服务装在当前这台电脑上才可以。127.0.0.1 永远指本机,不管在谁的机器上。连另一台服务器要填那台的实际地址。这个坑在从本机测试切到现场对接时特别容易踩。

问:连上了但收不到数据是什么原因

先查是不是订阅之前发的消息。MQTT 默认只转发订阅之后发布的消息,订阅之前的不会补发,除非发送时开了保留消息。所以验证顺序必须是先订阅、再发送。如果顺序对还是收不到,再查服务器地址是否一致、账号有没有订阅权限、主题是否完全一致。

问:主题里的大小写有影响吗

有,而且影响很大。MQTT 主题区分大小写,device01 和 Device01 是两个不同的主题,订阅了一个收不到另一个。斜杠位置和末尾多余的斜杠也会造成不匹配。这类问题肉眼很难看出来,排查时建议直接复制粘贴比对。

问:**次对接,QoS 该设几

先用 0 把链路跑通,不要一上来就用 1 或 2。QoS 1 会产生重复消息,QoS 2 有四次交互,**次调试时这些额外行为会让问题看起来更复杂。跑通之后再按数据类型调整。

问:保留消息要不要开

看数据类型。设备档案、当前配置、开关状态这类静态快照可以开,新客户端一连上就能拿到。电量流水、告警事件这类时序数据不要开,否则新系统上线会收到一条历史数据,可能误当成当前值。

问:MQTT 服务器用哪个好

看规模。几百个点位用 Mosquitto 就够,部署简单、资源占用低。上千点位或者需要集群、需要 Web 管理界面,考虑 EMQX 这类。选型时重点看并发连接数、消息吞吐、权限控制能力和运维成本,不要只看功能列表。

11

把对接这件事收成三句话

本节要点:两个连接分开看,三组概念别混,四个排查按顺序走。

**句:一条链路上有两个连接。设备到采集程序是一个,采集程序到 MQTT 服务器是另一个。地址完全不同,配置的时候要分清在填哪个。

第二句:连接名称、客户端标识、用户名密码是三件事。一个是给自己看的,一个是给服务器认人的,一个是身份凭证。混在一起就是权限对不上、连接被踢。

第三句:收不到数据按四步查,不要跳步。同一台服务器、订阅权限、主题一致、订阅后有没有再发。这四步覆盖了九成以上的对接问题,而且顺序不能乱,因为后一步的前提是前一步成立。

对做水电表项目的团队来说,MQTT 对接不是技术难点,是流程问题。参数、主题、字段这三样在对接启动时就定死写进文档,后面省下的是反复调试和扯皮的时间。

这篇文章解决什么问题

两个连接
设备到采集程序、采集程序到 MQTT 服务器,地址完全不同
八个参数
名称、地址、端口、客户端标识、用户名、密码、加密、协议版本
三组易混
连接名称与客户端标识、客户端标识与账号密码、127.0.0.1 与真实地址
主题规范
按项目、区域、设备类型、设备编号、数据类型分层,区分大小写
验证顺序
先订阅再发送,订阅之前的消息不会补发,除非开保留消息
四步排查
同一服务器、订阅权限、主题一致、订阅后是否再发
昵称:
内容:
验证码:
提交评论
评论一下
最新文章