首页 / 系统架构 / 设备与用户可观测平台
设备与用户可观测平台
统一采集设备、App、服务、网关与运维信号，完成脱敏、关联、告警、诊断与留存治理。
目标、边界与原图
可观测平台要回答的是：哪台设备、哪个用户会话、哪一版本、在哪一段链路、从何时开始出现了什么问题。它把 App、嵌入式设备、Java/Go 服务、MQTT/网关和运维任务产生的诊断信号关联起来，支撑设备排障、用户问题回放、版本质量分析、告警联动和远程诊断。
下图是目标架构蓝图，不等同于“所有组件已经上线”。接入、消息、存储与告警产品可按区域和现有基础设施选择实现，但字段口径、脱敏边界和关联键必须保持一致。
运行面与诊断面分离：定位上报、控制指令、告警和媒体会话仍走各自的生产链路；可观测数据是旁路采集或异步投递，任何日志/指标拥塞都不能阻塞设备控制、MQTT 心跳或实时媒体。
统一信号模型
| 信号 | 用于回答的问题 | 典型来源 | 主存储 |
|---|---|---|---|
| Log 日志 | “发生了什么、报错上下文是什么” | 设备环形日志、App SDK、Java/Go 结构化日志、Nginx/EMQX、运维脚本 | Loki / OpenSearch |
| Event 事件 | “业务状态是否变化、谁触发了它” | 绑定、登录、设备上线、告警、OTA、媒体会话、远程命令 | ClickHouse；关键业务事实仍在 MySQL/PostgreSQL |
| Metric 指标 | “系统现在是否健康、趋势是否变差” | 服务、Broker、网关、ZLMediaKit、设备资源与 App 性能 | Prometheus / VictoriaMetrics |
| Trace 链路 | “一次请求或会话卡在哪一跳” | OpenTelemetry SDK、Collector、网关、异步消费者 | Tempo / Jaeger |
所有信号至少可由 trace_id、伪名化 device_id、session_id（如登录/媒体/配网会话）、app_version、firmware_version 和 region 关联。不要把手机号、车牌、VIN、设备密钥、访问 Token、精确家庭地址或完整请求体作为可搜索标签。
公共事件信封
| 字段 | 规则 | 原因 |
|---|---|---|
event_time_ms | 事件在源端发生的 UTC epoch milliseconds | 用于弱网补传、轨迹和视频时间线排序 |
received_at_ms | 平台接收时间；不可覆盖源端时间 | 区分设备离线、网络延迟与服务处理延迟 |
event_name / schema_version | 稳定命名，演进时升版本，不改写旧含义 | 保证查询、告警和消费方兼容 |
trace_id / span_id | HTTP、gRPC、MQTT 关联消息和异步消费都透传 | 跨语言定位慢点与失败点 |
device_id / user_id | 仅保存内部 ID 或不可逆伪名；按权限展示 | 支持关联，又避免把 PII 复制进遥测库 |
severity / result_code | 使用枚举；错误码与业务码分开 | 避免只能全文检索、不能聚合告警 |
采集、处理与存储链路
| 阶段 | 必须做什么 | 关键失败处理 |
|---|---|---|
| 统一接入 | 鉴权、租户/区域路由、限流、Schema 校验、大小限制、去重、时间修正、脱敏与降级缓冲。 | 不合规或无法解析的数据进入隔离队列；拒绝原因本身要形成聚合指标。 |
| 消息缓冲 | Kafka / Pulsar / Redis Stream 承接突发流量；按设备或会话键保证局部有序。 | 积压达到阈值时采样低价值 Debug 日志，绝不丢弃安全审计和关键业务事件。 |
| 数据处理 | 解析、二次脱敏、富化版本/区域/产品模型、采样、分流、聚合、告警判断。 | 处理错误带原始引用、Schema 版本和失败原因进入死信队列，支持限速重放。 |
| 多模存储 | 日志、事件、指标、Trace、冷归档和业务事件库各归其位。 | 以存储 TTL 和可重建性决定保留；不能用日志库替代业务事实库。 |
时间修正规则：展示和业务判断优先使用
event_time_ms；接入层保留 received_at_ms，并标记时钟偏差与乱序。不得因为补传就把历史事件伪装成刚发生的事件。数据去向与职责
| 目标 | 保存内容 | 不应保存 |
|---|---|---|
| Loki / OpenSearch | 结构化诊断日志、脱敏后的错误上下文 | 明文凭证、完整请求体、未脱敏 PII |
| ClickHouse | 匿名化 App 行为、版本质量、漏斗与运营分析 | 主业务交易事实和密钥材料 |
| Prometheus / VictoriaMetrics | 可聚合数值、直方图、SLO/SLA 指标 | 高基数用户/设备 ID 标签、长文本日志 |
| Tempo / Jaeger | 采样 Trace、服务调用与耗时 | 敏感参数、未经脱敏的 SQL/HTTP Body |
| S3 / OSS / MinIO | 经授权的设备诊断包、冷归档 | 公开桶、永久有效下载链接 |
| MySQL / PostgreSQL | 告警工单、审计事实、可追责的业务事件索引 | 高频全量日志和指标明细 |
关联诊断与告警
一次设备/用户问题的最短排查路径
- 用工单号、时间窗和伪名化设备 ID 找到业务事件；确认产品、版本、区域和用户授权状态。
- 沿
trace_id查 App/API/Java/Go/消息消费者；比较源端事件时间与平台接收时间。 - 查看 MQTT 连接、设备心跳、网关拒绝原因和队列积压，判断是设备、网络、入口还是处理链路问题。
- 如涉及实时视频，按
media_session_id关联信令、ICE、TURN、首帧、丢包和会话结束原因；媒体内容本身不进入日志。 - 确定影响范围后创建告警/工单；修复后以相同查询确认恢复，并把根因与版本关联回写。
建议作为首批看板的指标
| 域 | 核心指标 | 关注方式 |
|---|---|---|
| 设备接入 | 在线率、认证失败率、心跳延迟、上报拒绝率、离线原因分布 | 按产品、固件、区域、运营商聚合；不按单设备建立指标标签。 |
| App 质量 | 崩溃/ANR、启动时长、网络重试、配网成功率、版本留存 | 仅使用伪名会话 ID；合规地区以用户同意为前提。 |
| 媒体会话 | ICE 成功率、首帧时延、TURN 中继比例、丢包率、RTT、会话异常退出率 | 媒体 ADD 的一期参考线为：ICE/建连成功率 ≥98%，首帧 P95 ≤1.5s，TURN 比例 ≤10%。上线前应按区域重设 SLO。 |
| 平台与成本 | 入口 QPS、队列积压、消费延迟、存储写入错误、采样率、对象存储费用 | 积压和拒绝率应与业务影响告警关联，避免只报机器 CPU。 |
安全、留存与成本治理
- 访问控制：按角色和数据域分权；支持“谁在何时查看了哪个设备的诊断信息”的审计。解密或查看高敏信息需要单独授权。
- 脱敏前置：在 Collector/Fluent Bit/处理器进入搜索索引前剔除 Token、DSN、密码、精确 IP 与 PII；不能只依赖查询侧遮罩。
- 设备日志按需拉取：云端通过 MQTT 控制命令触发，设备本地压缩后使用区域对象存储的预签名 URL 直传。URL 应短效（建议不超过 10 分钟），日志包独立桶且排障后按策略自动删除（建议 7 天）。
- 分层留存：热日志用于即时排障，温存储供短期复盘，冷归档只保留合规允许且有再利用价值的数据。原始保留期、聚合保留期、删除责任人和跨区边界必须逐项登记。
- 成本闸门：控制高基数标签、Trace 采样率、Debug 日志开关和对象存储生命周期；告警优先指向可行动的业务症状。
落地清单与验收
- 发布统一事件信封、字段字典、Schema 兼容规则与 PII 分类清单。
- 在 Java/Go 网关、核心消费者和 App/设备 SDK 接入统一 Trace 与结构化日志；先覆盖登录、设备上线、绑定、告警、OTA、媒体会话。
- 部署接入鉴权、限流、Schema 校验、脱敏与死信队列；压测突发上报和错误风暴。
- 建立日志、事件、指标、Trace 各自的数据源与保留策略，并用合成数据验证查询/索引。
- 上线设备、App、媒体、消息和成本五类看板，以及告警分级、值班路由和抑制规则。
- 用一次故障演练验证：可在限定权限下从告警追到版本、区域、链路节点和恢复证据；同时确认日志中没有泄露密钥或 PII。
验收证据：字段契约测试、脱敏回归、跨 Java/Go/消息链路的 Trace 样例、队列故障/重放演练、看板截图与告警闭环记录。仅“日志能搜到”不足以证明可观测闭环完成。