跳到主要内容

心跳监控系统

引用文件

本文引用的文件

目录​

  1. 简介
  2. 项目结构
  3. 核心组件
  4. 架构总览
  5. 详细组件分析
  6. 依赖分析
  7. 性能考虑
  8. 故障排查指南
  9. 结论
  10. 附录

简介​

本文件面向心跳监控系统的技术实现与运维实践，围绕心跳包的数据结构与传输协议、心跳频率与超时阈值配置、异常检测机制、接收处理与设备状态更新、活跃度统计、异常恢复策略、数据存储与分析、API 接口规范与集成示例、最佳实践与性能优化进行全面阐述。读者可据此理解心跳系统的工作原理、掌握配置方法、定位异常问题并制定优化方案。

项目结构​

心跳监控系统主要由设备模块的控制层、服务层与数据层组成，结合文档与测试工具，形成从接口到配置、从数据到分析的闭环。

Mermaid Diagram Code:

graph TB
subgraph "设备模块"
C["AppDeviceHeartBeatController<br/>心跳接口控制器"]
S["DeviceService<br/>设备服务"]
A["DeviceActivityDetailService<br/>设备活跃明细服务"]
R["RedisClient<br/>在线时间缓存"]
end
subgraph "配置与文档"
D1["device-heart-beat-config.md<br/>心跳配置管理"]
D2["check-connectivity.md<br/>连通性检测"]
D3["README.md<br/>流程图与响应说明"]
end
subgraph "数据与分析"
T["TDengine/ES<br/>活跃明细与运行时数据"]
U["DeviceHeartUtils.java<br/>心跳数据清洗与分析"]
end
C --> S
C --> A
C --> R
S --> T
A --> T
D1 --> C
D2 --> C
D3 --> C
U --> T

图表来源

章节来源

核心组件​

  • 心跳接口控制器：提供 V1/V2 两套心跳接口，负责设备认证、在线时间更新、活跃明细记录、任务检查与配置下发。
  • 设备服务：负责设备认证、配置获取与版本兼容处理。
  • 活跃明细服务：负责设备活跃明细的持久化与初始化。
  • Redis 缓存：维护设备最后在线时间，作为离线判定依据。
  • 配置管理：通过字典管理心跳配置项，指导设备行为。
  • 文档与工具：提供连通性检测、流程图与心跳数据清洗分析工具。

章节来源

架构总览​

心跳监控系统采用“接口-服务-缓存-存储”的分层架构，接口层负责请求接入与响应封装；服务层负责业务逻辑与配置下发；缓存层负责在线状态与活跃明细的快速更新；存储层负责历史数据的长期留存与分析。

Mermaid Diagram Code:

graph TB
Client["设备客户端"] --> API["心跳接口<br/>GET /task/deviceHeartBeat/{mac}/{updateVersion}<br/>GET /task/deviceHeartBeat/v2/{mac}[/{cpu}]"]
API --> Auth["设备认证与版本判断"]
Auth --> Online["更新Redis在线时间"]
Auth --> Activity["记录设备活跃明细"]
Auth --> Config["生成心跳配置列表"]
Config --> Resp["返回心跳配置/任务"]
Resp --> Client
subgraph "数据与分析"
Redis["Redis 缓存<br/>DEVICE_LAST_ON_LINE_TIME_KEY"]
Store["TDengine/Elasticsearch<br/>活跃明细/运行时数据"]
Utils["心跳数据清洗工具<br/>DeviceHeartUtils"]
end
Online --> Redis
Activity --> Store
Utils --> Store

图表来源

详细组件分析​

心跳接口与处理流程​

  • V1 接口：deviceHeartBeat，支持携带 updateVersion 参数，用于检查是否有新任务；若存在则返回包含任务列表的响应，否则返回“无任务”错误。
  • V2 接口：deviceHeartBeatV2，支持携带 CPU 标识或仅 MAC；根据设备 API 版本与是否携带 CPU 决定认证方式；成功后返回心跳配置列表（包含任务检测、黑名单检测、APP 检测、事件上报、设备心跳等配置项），并按需生成设备 Token。
  • 版本兼容：当设备 API 版本满足条件且 Token 缺失或过期时，自动生成新 Token 并返回。

Mermaid Diagram Code:

sequenceDiagram
participant Dev as "设备客户端"
participant Ctrl as "AppDeviceHeartBeatController"
participant Svc as "DeviceService"
participant Act as "DeviceActivityDetailService"
participant Cache as "RedisClient"
Dev->>Ctrl : GET /task/deviceHeartBeat/v2/{mac}[/{cpu}]
Ctrl->>Svc : checkDeviceCertification[或带CPU认证]
Svc-->>Ctrl : 设备信息/认证结果
alt 认证成功
Ctrl->>Cache : zAdd 最后在线时间
Ctrl->>Act : saveDeviceActivityIfNotExist
Ctrl-->>Dev : 返回心跳配置列表 + 可选设备Token
else 认证失败
Ctrl-->>Dev : 返回错误 : 设备不存在
end

图表来源

章节来源

心跳配置响应结构（V2）​

心跳接口 V2 返回一系列配置指令，指导设备进行特定行为的周期性检测与上报。典型配置项包括：

  • 任务检测：[开关, 间隔分钟]
  • 黑名单检测：[开关, 间隔分钟]
  • APP 安装列表检测：[开关, 间隔分钟]
  • APP 更新检测：[开关, 间隔分钟]
  • APP 运行记录检测：[开关, 间隔分钟]
  • 事件上报：[开关, 间隔分钟]
  • 设备心跳：[开关, 间隔分钟]

章节来源

心跳频率与超时阈值配置​

  • 配置来源：心跳配置管理页面，支持查看与修改各项配置的“是否开启”和“间隔时长（分钟）”。未配置或未启用的项使用出厂默认配置。
  • 建议范围：文档建议心跳间隔为 15-60 秒，避免过短导致服务器压力过大。
  • 生效机制：修改配置后需设备重新调用心跳接口获取最新配置。

章节来源

异常检测机制与离线判定​

  • 在线时间缓存：每次心跳成功后，将设备的最后在线时间写入 Redis 的有序集合，键名对应“DEVICE_LAST_ON_LINE_TIME_KEY”。
  • 离线阈值：可通过比较当前时间与缓存中的最后在线时间，计算超过阈值即判定为离线。阈值可在业务侧按需配置。
  • 未激活设备：返回特定状态码，提示设备未激活。

章节来源

设备状态更新与活跃度统计​

  • 设备认证：根据设备 API 版本与是否携带 CPU 决定认证策略，确保不同版本设备的兼容性。
  • 活跃明细：首次活跃时初始化活跃明细记录，后续按需更新。
  • 统计维度：结合活跃明细与运行时数据，支持按设备、区域、渠道等维度进行活跃度统计与趋势分析。

章节来源

心跳异常处理策略​

  • 离线检测：基于 Redis 中的最后在线时间与阈值进行离线判定。
  • 重连机制：设备端定期重试心跳，直至恢复在线；服务端在认证失败时返回明确错误信息，便于前端或设备端进行重试与降级处理。
  • 告警通知：建议在离线阈值触发时，联动告警系统进行通知与处置。

章节来源

心跳数据存储与分析​

  • 存储位置：活跃明细与运行时数据存储于 TDengine/ES 等存储系统，便于长期留存与分析。
  • 数据清洗：提供心跳数据清洗工具，支持按时间戳特征区分带时间戳与不带时间戳的数据，辅助异常分析与归因。
  • 分析应用：结合活跃明细与运行时数据，进行设备活跃度、运行时长、任务执行等趋势分析。

章节来源

API 接口文档与集成示例​

  • 接口路径
    • V1：GET /task/deviceHeartBeat/{mac}/{updateVersion}
    • V2（含 CPU）：GET /task/deviceHeartBeat/v2/{mac}/{cpu}
    • V2（仅 MAC）：GET /task/deviceHeartBeat/v2/{mac}
  • 请求参数
    • mac：设备 MAC 地址
    • updateVersion（V1）：设备本地版本号，用于检查是否有新任务
    • cpu（V2）：设备 CPU 标识，用于区分同一 MAC 的多实例场景
  • 响应说明
    • V1：若存在新任务，返回包含任务列表的响应；否则返回“无任务”错误
    • V2：返回心跳配置列表（包含任务检测、黑名单检测、APP 检测、事件上报、设备心跳等），并按需返回设备 Token
  • 错误码
    • 21：新任务更新指令
    • 24：设备未激活
    • 700：设备不存在（连通性检测预期结果）

章节来源

依赖分析​

心跳接口控制器依赖设备服务与活跃明细服务，同时通过 Redis 缓存维护在线状态；配置来源于字典管理，响应结构由 VO 与枚举共同定义。

Mermaid Diagram Code:

classDiagram
class AppDeviceHeartBeatController {
+deviceHeartBeat(mac, updateVersion)
+deviceHeartBeatV2(mac, cpu?)
}
class DeviceService {
+checkDeviceCertification(mac)
+checkDeviceCertificationCacheNull(mac, cpu)
+getHearBeatConfig()
}
class DeviceActivityDetailService {
+saveDeviceActivityIfNotExist(mac, cpu?, regionId, deviceId)
}
class HeartBeatResCodeEnum {
+CMD_UPDATE_NEW_TASK
+DEVICE_NO_ACTOCATION
}
class DeviceHeartBeatRes {
+code
+mac
+desc
+tasks
}
AppDeviceHeartBeatController --> DeviceService : "认证/配置"
AppDeviceHeartBeatController --> DeviceActivityDetailService : "活跃明细"
AppDeviceHeartBeatController --> HeartBeatResCodeEnum : "状态码"
AppDeviceHeartBeatController --> DeviceHeartBeatRes : "V1响应"

图表来源

章节来源

性能考虑​

  • 心跳频率：建议在 15-60 秒范围内配置，避免过于频繁引发服务器压力。
  • 缓存命中：Redis 在线时间更新为 O(logN) 操作，具备良好吞吐能力；建议合理设置过期策略与键空间。
  • 版本兼容：V2 接口按设备 API 版本与 CPU 标识进行差异化认证，减少不必要的重复工作。
  • 配置下发：V2 返回的配置列表按分钟粒度控制，避免设备端频繁轮询。

章节来源

故障排查指南​

  • 连通性检测：通过访问心跳域名与端口，观察返回是否为“设备不存在”，以判断网络是否通畅。
  • 离线判定：检查 Redis 中的最后在线时间与当前时间差是否超过阈值。
  • 设备未激活：返回状态码 24，需在平台侧完成设备激活流程。
  • 重试与降级：设备端应具备指数退避重试策略；服务端在认证失败时返回明确错误，便于前端或设备端进行处理。

章节来源

结论​

心跳监控系统通过清晰的接口设计、灵活的配置下发与完善的异常处理机制，实现了对设备在线状态与活跃度的高效管理。结合 Redis 缓存与长期存储，系统能够支撑实时监控与历史分析需求。建议在实际部署中遵循配置建议、建立离线阈值与告警机制，并持续优化心跳频率与缓存策略以提升整体性能与稳定性。

附录​

  • 心跳配置项说明（节选）
    • app活跃上报间隔
    • 检测设备运行时长
    • 杀死进程时间间隔
    • 心跳检测
    • 事件上报
    • APP运行记录检测间隔时间
    • 检测APP更新
    • APP列表检测
    • 黑名单检测
    • 任务检测

章节来源

用户文档
AI 助手
Agent 列表
请选择一个 Agent 开始对话
AI 问答