设备接入排错清单
大约 6 分钟
设备接入排错清单
页面导读
适用场景适合设备不上线、数据不上报、指令不下发、协议解析异常、规则未触发等接入问题。
使用方式按“产品 → 设备 → 网络 → 认证 → 报文 → 平台日志 → 业务链路”的顺序排查。
验收点设备在线、运行状态刷新、设备日志有记录、平台下发指令能被设备收到。
关联对象适用于 MQTT、HTTP、CoAP、TCP、Modbus、网关子设备和视频设备接入。
- 先判断问题停在哪一层：网络不通、认证失败、设备不在线、数据不显示、指令收不到，还是规则告警未触发。
- 每次只改一个变量，并记录设备编号、产品 ID、请求时间、Topic/API、报文内容和后端日志。
- 先用 MQTTX、Postman 或 curl 复现最小链路，再回到真实设备排查固件、网络和协议实现。
一、排查顺序
不要一开始就修改代码。绝大多数接入问题来自产品未发布、认证字段不一致、设备编号写错、物模型标识符不匹配或端口未开放。
二、产品检查
| 检查项 | 正常状态 | 异常影响 |
|---|---|---|
| 产品状态 | 已发布 | 未发布时设备认证或创建失败 |
| 传输协议 | 与设备接入方式一致 | MQTT 设备选择 HTTP 会导致认证链路不匹配 |
| 通讯协议 | 与设备报文格式一致 | 报文无法正确解析到物模型 |
| 认证方式 | 与设备端实现一致 | 简单认证和加密认证不能混用 |
| 设备授权 | 设备端已携带授权码 | 启用授权但设备未携带会认证失败 |
| 物模型标识符 | 与设备端 id 完全一致 | 数据接收成功但不显示 |
三、设备检查
| 检查项 | 正常状态 | 排查建议 |
|---|---|---|
| 设备编号 | 平台和设备端完全一致 | 注意大小写、特殊字符、长度要求 |
| 禁用设备 | 关闭 | 禁用后设备无法连接 |
| 所属产品 | 与认证参数中的产品一致 | 产品 ID 和产品编号不要混淆 |
| 设备影子 | 根据业务选择 | 联调初期建议关闭，避免离线指令干扰 |
| 设备日志 | 有上线、上报、下发记录 | 没有日志时优先看认证和网络 |
四、网络与端口
| 协议 | 常见端口 | 验证方式 |
|---|---|---|
| MQTT | 1883 | MQTTX 连接，EMQX 控制台查看客户端 |
| MQTT WebSocket | 8083 | 浏览器或 WebSocket 工具连接 |
| HTTP | 后端服务端口或网关端口 | Postman/curl 调用接口 |
| CoAP | 部署配置中的 CoAP 端口 | CoAP 调试工具发送消息 |
| TCP | TCP 服务监听端口 | telnet/nc 或设备日志 |
| GB28181/SIP | 5061 等 | 设备注册日志、SIP 服务日志 |
| 流媒体 | 30000-30100 等 | 直播、回放、ZLM 日志 |
如果本地可以连接但外网设备无法连接，优先检查云服务器安全组、防火墙、NAT、端口映射和反向代理。
五、认证问题
MQTT
简单认证格式：
clientId = S&设备编号&产品ID&用户ID
username = 产品 MQTT 账号
password = 产品 MQTT 密码启用设备授权时：
password = 产品 MQTT 密码&设备授权码常见错误：
- 把产品编号当成产品 ID。
- 用户 ID 写错，导致设备归属不符合预期。
- 设备授权码启用后没有拼接授权码。
- 加密认证过期时间格式不对。
HTTP/CoAP/TCP
重点检查：
- 设备编号、产品 ID、认证账号、认证密码是否与产品一致。
- 请求路径、请求方法、Content-Type 是否正确。
- 设备端时间是否偏差过大。
- 网关或代理是否改写请求体。
六、报文问题
物模型上报
平台标准上报通常使用数组：
[
{
"id": "temperature",
"value": "26.5",
"remark": "设备上报"
}
]检查重点：
id是否与物模型标识符完全一致。value是否符合数据类型。- 数组、对象、对象数组是否按平台约定展开。
- 布尔和枚举是否使用约定键值。
- 报文编码是否为 UTF-8。
网关子设备
检查重点：
- 网关产品和子产品关系是否已配置。
- 子设备地址是否唯一。
- 子设备是否已导入或允许自动创建。
- 多子设备同时上报时，数据归属字段是否正确。
- 网关离线时，子设备同步离线逻辑是否符合预期。
Modbus
检查重点：
- 串口参数或 TCP 地址是否正确。
- 从机地址、寄存器地址、功能码是否正确。
- 数据类型、字节序、倍率、小数位是否正确。
- 云端轮询任务是否启用。
- 缓存变更后是否需要清理 Redis 中的 Modbus 相关缓存。
七、平台日志
| 日志位置 | 用途 |
|---|---|
| 设备详情 > 设备日志 | 查看上线、上报、下发和异常 |
| EMQX 控制台 | 查看客户端连接、订阅、认证结果 |
| 后端日志 | 查看接口、协议解析、数据库、缓存异常 |
| 规则引擎日志 | 查看规则是否触发、脚本是否报错 |
| ZLM/录像服务日志 | 查看视频流、回放、Hook、录像异常 |
排查时建议同时记录设备编号、产品 ID、请求时间和 requestId，便于在后端日志中定位。
八、常见问题定位
| 现象 | 优先检查 | 常见处理 |
|---|---|---|
| 设备一直离线 | 网络端口、产品发布、认证参数、设备禁用状态 | 先用调试工具连接，再替换真实设备参数 |
| 设备在线但无数据 | 上报主题/API、物模型标识符、数据类型、产品发布状态 | 使用最小 JSON 报文验证一个属性 |
| 指令下发失败 | 设备订阅主题、设备在线状态、物模型读写性、用户权限 | 在设备端打印收到的下发报文 |
| 自动注册失败 | 设备编号、产品 ID、用户 ID、授权码、租户归属 | 先手动创建设备，再对比认证参数 |
| 规则或告警未触发 | 运行状态是否刷新、规则变量绑定、条件类型、告警启用状态 | 先确认数据入库，再检查业务规则 |