MQTT接入

连接认证

配置 MQTT 安全连接、设备访问令牌认证、重连订阅,并排查连接问题。

设备访问令牌的取得方式见设备注册。已经取得令牌的设备使用下列配置建立正式连接;临时注册连接的认证方式单独在注册文档中说明。

安全连接环境要求

设备运行环境必须具备有效的系统根证书,并能够校验云平台服务证书和服务域名。系统根证书应随设备系统安装,并通过受信任的软件源及时更新。

设备接入前应确认:

  • 系统日期、时间和时区准确。
  • 系统根证书已经安装且处于有效状态。
  • 云平台服务域名能够正常解析。
  • 网络允许设备访问云平台安全连接端口。
  • 客户端已启用服务证书和服务域名校验。

对于使用 Debian、Ubuntu 等系统的设备,可通过以下命令安装或更新系统根证书:

sudo apt-get install ca-certificates
sudo update-ca-certificates

安装或更新完成后,应重新启动设备接入服务。其他操作系统请按照系统厂商提供的方法安装和更新根证书。

不得通过关闭证书校验、忽略域名不匹配或信任未知证书的方式处理连接问题。

连接认证

设备完成注册后,使用平台返回的访问令牌连接 MQTT 服务。

配置项要求
服务地址gateway.zkipc.cn
服务端口固定使用 8883
连接方式使用安全连接,不支持普通连接
客户端标识每台设备必须全局唯一,建议包含设备序列号或机器码
用户名设备访问令牌 {token}
密码设备访问令牌认证模式下留空
上行消息质量综合数据建议使用一级消息质量
下行消息质量属性、控制指令、设备联动和远程升级使用一级消息质量
断线重连恢复设备已启用能力对应的下行订阅;使用共享配置的设备应主动读取平台保存的最新共享属性

认证拒绝后的处理

MQTT 认证结果只表示允许或拒绝连接,不会把设备删除、禁用或凭据失效的具体原因直接传给设备。普通断线、连接超时、证书错误和服务暂时不可用按连接重试策略处理,不清空令牌、不申请注册。

采用自动注册的设备在明确收到认证拒绝后,应停止业务连接并保留旧令牌,使用临时注册连接发送接入恢复查询。平台验证产品注册密钥后返回原因码和处理指引,查询不创建设备、不签发或返回令牌。

处理指引 nextAction设备动作
RECONNECT原凭据有效,使用原令牌重连;仍被拒绝时核对 MQTT 服务和认证配置。
REGISTER只有合法恢复响应同时返回 code=REGISTRATION_ALLOWED 时,才使用新请求编号提交注册申请。
WAIT_ADMIN停止申请令牌,等待管理员处理设备或凭据,可低频重新查询处理结果。
RETRY保留原令牌,退避后使用新请求编号重新查询。

恢复查询超时、报文格式错误或出现未知指引时,保留原令牌并退避重试查询,不能自行转为注册。没有实现自动注册或没有产品注册密钥的设备,应由管理员核对状态并安全配置凭据。查询报文、响应字段和全部原因码见设备注册。

连接问题排查

现象检查内容
无法建立安全连接检查系统时间、系统根证书、域名解析、网络出口和服务端口
提示证书无效或不受信任更新系统根证书,并确认设备时间准确
提示服务域名不匹配确认连接地址使用本文提供的服务域名,不要直接使用解析后的地址
收到明确的认证拒绝保留原令牌;自动注册设备先进行接入恢复查询,按平台原因码和处理指引处理,不直接清空凭据或重复注册
连接后无法发布或订阅检查主题方向、主题格式、访问令牌和通配符使用方式
连接偶尔中断检查网络稳定性、保活设置,并确认断线后已重新连接和订阅;普通断线不触发注册

排查过程中不得在日志、截图或工单正文中提供完整的产品注册密钥和设备访问令牌。需要提交连接日志时,应先对敏感内容进行遮盖。

相关文档

© 2026 飞鸟智联