常见问题与排查顺序

先保留项目、设备、发生时间和非秘密 traceId，再从最靠近输入的环节逐步排查。不要用清空配置或关闭证书验证试探成功。

按现象定位

现象	先检查	下一步
菜单或按钮不可用	当前项目、账号、角色及服务端权限	请管理员核对授权，不绕过接口
设备认证失败	Key 与 ID 是否混淆、秘密状态、协议配置	轮换后更新客户端，并核对 TLS
MQTT 可连接但无数据	Topic、非 retained、模型、messageId、采集时间	查看消息日志与原始历史
历史有值但当前值未变	时间先后、历史来源、当前模型绑定	旧值可能只进入历史
曲线空白	数值属性、模型、时间范围、可读历史窗口	不把空图当零值或健康
命令已受理却未完成	在线或领取方式、设备处理、回复关联	查询原命令，避免重复副作用
自动化重复执行	多次合格属性事件、条件持续为真	核对触发语义及设备幂等
告警有记录而未收到通知	规则路由、收件目标、渠道、投递终态	送达和已读单独确认
目录可读但草稿打不开	当前身份、草稿版本与 Schema、宿主兼容	显式重读，不用空稿覆盖
API 或资源超额	租户共享池、UTC日窗口、有效额度	查询状态，不换Key扩大预算

响应丢失怎么办

写请求可能已经提交。优先用原 operationId、commandId 或幂等键读取结果，不自动重放新写入。查询元数据不能恢复密钥明文，确认丢失后明确轮换或撤销。

实时断开怎么办

增量通道断开或重连后读取权威当前值和历史。保留窗口外的数据不可读时不制造补点，票据过期应按当前资格重新申请。

请求支持时提供

提供脱敏错误、时间范围、协议、模型版本和复现步骤。不要提交设备秘密、API Key、登录令牌、私钥、完整通知目标或含秘密的原始请求。

连接问题见MQTT 接入，数据问题见遥测与历史，外部集成见API 与 Webhook。