常见问题排查
本页汇总使用过程中的高频问题与排查路径。按问题类别分区，先找现象，再按步骤排查。
设备连接类
设备连不上 MQTT
- 核对令牌：用户名是否与设备详情页的 Access Token 完全一致（首尾不能有空格）；
- 核对地址端口：公有云
cloudbridge.qiuhuasoft.top:1883，私有部署向管理员确认；网络侧防火墙是否放行； - 确认设备已建档：令牌对应的设备必须已在平台创建；
- 确认租户未被停用：平台侧停用租户后，其下所有设备一律拒绝接入；
- 以上都正常仍失败：联系平台管理员查服务端日志。
提示：平台的连接失败提示统一为"用户名或密码错误"，不区分具体原因，需按上述顺序排查。
设备频繁掉线重连
| 原因 | 判断方法 | 解决 |
|---|---|---|
| Client ID 冲突（两台设备共用） | 两台设备"最后连接"时间交替刷新 | 每台设备使用唯一 Client ID |
| 网络不稳定 | 掉线时间与网络波动吻合 | 检查现场网络；合理设置 Keep Alive |
| 令牌被重新生成 | 重新生成令牌后旧设备端未更新 | 同步更新设备端配置 |
设备在线但不报数据
连接正常说明认证与网络没问题，问题出在设备端程序：检查采集与发布逻辑是否卡死、报文是否为合法 JSON。设备详情的"最后活跃"时间长期不变是典型信号。
数据类
数据上报了，页面上没有
按顺序检查：
- 主题拼写：直连遥测是
v1/devices/me/telemetry（复数 devices、带me）；网关是v1/gateway/telemetry； - JSON 合法性：解析失败的报文被静默丢弃；用 MQTTX 工具发一条已知正确的报文对比；
- 报文格式：网关遥测的值必须是数组；直连设备用扁平键值时不要嵌套在别的键下；
- 配额：租户每日消息配额耗尽后，当天报文直接丢弃——联系平台管理员确认；
- 字段名/外部 ID 一致性：网关子设备的外部 ID 与建档完全一致（区分大小写与内部空格）。
历史曲线断点 / 缺段
| 现象 | 原因 |
|---|---|
| 某段时间整段空白 | 那段时间设备离线未上报 |
| 曲线从中间"裂成两条" | 字段名中途改过——新旧字段名是两条独立曲线 |
| 断续有洞 | 同一字段名数据类型混用（如数字/文本交替），按类型分开存储 |
预防方式：字段名与数据类型一旦定下不再更改。
查询很慢或超时
缩小时间范围；选择降采样窗口（如 1h + avg）再查。长时段查询原始点既慢又画不出可读曲线。
告警类
数据超限但没告警
- 规则是否启用；
- 规则绑定的设备是否就是这台设备；
- 条件字段名与实际上报字段是否完全一致（区分大小写）；
- "持续满足/连续满足"类条件需要满足时长/次数，刚超限就查可能还没到触发点；
- 规则保存后从下一条数据开始评估，历史数据不追溯。
告警太多 / 反复触发
- 提高阈值或启用"持续满足"防抖（1~5 分钟起步）；
- 清除条件与触发条件之间留出回差（如 60 触发、50 清除），避免临界点抖动；
- 按等级分层配置：只有真正严重的才设"严重"。
组织与权限类
客户登录后看不到设备
- 设备是否已分配给该客户（设备台账 → 分配客户）；
- 是否分配后又被取消（取消即时生效）；
- 该客户账号是否属于同一个租户（客户不跨租户）；
- 客户用户被停用则无法登录，需在客户详情页恢复。
登录后菜单比别人少
菜单按角色生成：系统管理员 > 租户管理员 > 客户用户。参考《角色分级规则》确认账号角色，这是设计行为不是故障。
平台治理类
设备报文被丢弃，怀疑配额问题
每日消息配额超限后，当天超出的报文被直接丢弃、次日恢复。联系平台管理员核对配额模板的"每日最大消息数"，或降低上报频率。估算公式：消息数 ≈ 设备数 ×（86400 ÷ 上报间隔秒数）。
租户被停用的影响范围
Web 端全部账号无法登录；设备 MQTT 接入全部被拒。数据与配置完整保留，重新启用即恢复。
找不到对应的问题？联系平台管理员并提供：设备名称、发生时间、设备端日志，能大幅加快定位。