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 | 保留原令牌,退避后使用新请求编号重新查询。 |
恢复查询超时、报文格式错误或出现未知指引时,保留原令牌并退避重试查询,不能自行转为注册。没有实现自动注册或没有产品注册密钥的设备,应由管理员核对状态并安全配置凭据。查询报文、响应字段和全部原因码见设备注册。
连接问题排查
| 现象 | 检查内容 |
|---|---|
| 无法建立安全连接 | 检查系统时间、系统根证书、域名解析、网络出口和服务端口 |
| 提示证书无效或不受信任 | 更新系统根证书,并确认设备时间准确 |
| 提示服务域名不匹配 | 确认连接地址使用本文提供的服务域名,不要直接使用解析后的地址 |
| 收到明确的认证拒绝 | 保留原令牌;自动注册设备先进行接入恢复查询,按平台原因码和处理指引处理,不直接清空凭据或重复注册 |
| 连接后无法发布或订阅 | 检查主题方向、主题格式、访问令牌和通配符使用方式 |
| 连接偶尔中断 | 检查网络稳定性、保活设置,并确认断线后已重新连接和订阅;普通断线不触发注册 |
排查过程中不得在日志、截图或工单正文中提供完整的产品注册密钥和设备访问令牌。需要提交连接日志时,应先对敏感内容进行遮盖。