跳到主要内容

设备生命周期管理

引用文件

本文引用的文件

目录​

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

简介​

本技术文档围绕设备生命周期管理展开，系统覆盖从设备入网激活、心跳维持、状态监控到注销清理的全链路能力。系统通过设备认证（入网激活）、心跳机制、运行时数据记录与渠道/任务交互，实现对设备的全生命周期治理。设备以 MAC 地址与 CPU ID 作为唯一标识，结合 Redis 缓存与数据库持久化，保障高并发场景下的稳定性与一致性。

项目结构​

设备生命周期管理由“设备模块”提供核心能力，包含 API、Biz 服务、控制器、数据对象与枚举等层次化组织，配合安全框架与字典配置，形成完整的设备管理闭环。

Mermaid Diagram Code:

graph TB
subgraph "设备模块"
API["DeviceApi 接口"]
API_IMPL["DeviceApiImpl 实现"]
CTRL_ADMIN["DeviceController 管理端"]
SVC["DeviceService 服务接口"]
SVC_IMPL["DeviceServiceImpl 服务实现"]
CERT_OLD["DeviceCertificationOldImpl 旧版认证"]
CERT_NEW["DeviceCertificationImpl 新版认证"]
HB_CTRL["AppDeviceHeartBeatController 心跳控制器"]
ENUM_HB["HeartBeatResCodeEnum 心跳响应枚举"]
DO["DeviceDO 设备数据对象"]
end
API --> API_IMPL
API_IMPL --> SVC_IMPL
CTRL_ADMIN --> SVC_IMPL
HB_CTRL --> SVC_IMPL
CERT_OLD --> SVC_IMPL
CERT_NEW --> SVC_IMPL
SVC --> DO

图表来源

章节来源

核心组件​

  • 设备认证与入网激活：支持旧版与新版接口，依据 MAC/CPU 校验设备是否存在，不存在则自动注册并设置激活状态。
  • 心跳与状态维护：心跳接口记录设备最后在线时间，结合渠道更新版本判断是否下发新任务；同时生成/刷新设备侧 Token。
  • 设备信息服务：提供设备查询、分页、导入导出、批量更新/删除、统计计数等能力。
  • 离线处理：通过心跳时间与阈值判定离线，结合 Redis 有序集合维护在线状态。
  • 管理端接口：提供设备创建、更新、删除、批量操作、导出等后台管理能力。

章节来源

架构总览​

系统采用“接口层-服务层-数据访问层”的分层架构，结合 Redis 缓存与数据库双写策略，确保高并发下的快速查询与稳定持久化。设备认证与心跳控制器作为入口，统一调度服务层完成设备状态与信息的维护。

Mermaid Diagram Code:

graph TB
APP["设备端应用"]
HB["心跳控制器<br/>AppDeviceHeartBeatController"]
AUTH["认证控制器<br/>DeviceCertificationImpl/OldImpl"]
SVC["设备服务层<br/>DeviceServiceImpl"]
DAO["设备DAO/Mapper"]
REDIS["Redis 缓存"]
DB["MySQL 数据库"]
ADMIN["管理端控制器<br/>DeviceController"]
APP --> HB
APP --> AUTH
HB --> SVC
AUTH --> SVC
SVC --> REDIS
SVC --> DAO
DAO --> DB
ADMIN --> SVC

图表来源

详细组件分析​

设备入网激活与认证​

  • 旧版接口：根据 MAC 查询设备，若不存在则解析 IP 定位区域并创建设备，状态置为“已激活”，返回激活码。
  • 新版接口：支持 MAC+CPU 双键校验，避免历史设备 CPU 为空导致的误判；同样在不存在时自动注册并激活。
  • 缓存穿透防护：查询不存在设备时写入空值缓存，降低数据库压力。

Mermaid Diagram Code:

sequenceDiagram
participant App as "设备端"
participant Ctrl as "认证控制器"
participant Svc as "设备服务"
participant DB as "数据库"
App->>Ctrl : 发起认证请求(MAC/CPU)
Ctrl->>Svc : 校验设备是否存在
alt 设备不存在
Svc->>DB : 自动创建设备并设置状态=已激活
DB-->>Svc : 返回设备信息
else 设备存在
Svc->>DB : 读取设备信息
DB-->>Svc : 返回设备信息
end
Svc-->>Ctrl : 返回设备与激活码
Ctrl-->>App : 认证结果

图表来源

章节来源

心跳与状态维护​

  • 心跳接口 V1/V2：记录设备最后在线时间，生成/刷新设备 Token；根据渠道更新版本判断是否下发新任务。
  • 心跳响应码：定义“新任务更新指令”“设备未激活”等业务码，便于设备侧处理。
  • 离线判定：通过心跳时间与阈值比较，将设备标记为离线，用于后续统计与告警。

Mermaid Diagram Code:

sequenceDiagram
participant App as "设备端"
participant HB as "心跳控制器"
participant Svc as "设备服务"
participant Redis as "Redis"
participant Chan as "渠道服务"
App->>HB : 心跳请求(MAC/CPU, updateVersion)
HB->>Svc : 校验设备并记录最后在线时间
Svc->>Redis : zadd 最后在线时间
HB->>Chan : 检查渠道更新版本
alt 版本有更新
HB-->>App : 返回新任务指令
else 无更新
HB-->>App : 返回无任务
end

图表来源

章节来源

设备信息服务与管理端​

  • 设备查询与分页：支持按条件查询、ES 分页与导出。
  • 批量导入/导出：支持 Excel 批量导入，覆盖/不覆盖两种模式；导出设备明细。
  • 批量更新/删除：支持按条件批量更新渠道、批量删除。
  • 统计计数：按渠道/型号维度统计设备数量。

Mermaid Diagram Code:

flowchart TD
Start(["管理端请求"]) --> Create["创建设备"]
Start --> Update["更新设备"]
Start --> Delete["删除设备"]
Start --> Import["导入设备(覆盖/不覆盖)"]
Start --> Export["导出设备明细"]
Start --> BatchUpdate["按条件批量更新渠道"]
Start --> BatchDelete["按条件批量删除"]
Start --> Count["按渠道/型号统计设备数量"]
Create --> End(["完成"])
Update --> End
Delete --> End
Import --> End
Export --> End
BatchUpdate --> End
BatchDelete --> End
Count --> End

图表来源

章节来源

设备状态定义与转换规则​

  • 状态字典：系统字典包含“未激活/在线/离线”等状态，用于前端展示与统计。
  • 状态转换：
    • 未激活 → 在线：设备完成入网激活并通过心跳校验。
    • 在线 → 离线：超过心跳阈值未收到心跳。
    • 离线 → 在线：恢复心跳后自动转为在线。
  • 状态维护：心跳控制器记录最后在线时间，服务层据此判定离线。

章节来源

设备信息维护机制​

  • 属性更新：支持设备型号、UI、SDK 版本、渠道等字段的更新。
  • 位置变更：通过区域 ID 与 IP 地址联动，结合认证流程更新设备归属。
  • 版本升级：心跳接口携带更新版本，服务层据此判断是否下发新任务。

章节来源

设备离线处理策略​

  • 离线检测：心跳控制器记录最后在线时间，服务层根据阈值判定离线。
  • 超时处理：超过阈值未心跳的设备视为离线，可用于统计与告警。
  • 数据清理：管理端支持按条件批量删除设备，清理无效设备数据。

章节来源

设备管理 API 接口文档​

  • 设备查询
    • 根据 MAC 获取设备：GET /device/get-by-mac
    • 从数据库强制查询：GET /device/get-by-mac-on-DB
    • 根据 MAC+CPU 获取：GET /device/get-by-mac-by-cpu
  • 设备更新
    • 更新设备数据：PUT /device/update
    • 推送更新：PUT /device/update-on-device-push
  • 统计与计数
    • 获取设备总数：GET /device/get-by-id
    • 按渠道/型号统计：GET /device/get-count-by-channelIds, GET /device/get-count-by-modelIds
    • 批量统计：GET /device/batch-get-count-by-channelIds, GET /device/batch-get-count-by-modelIds
  • 字段更新
    • 更新设备型号外键：GET /device/update-modelId-by-id
    • 更新设备 UI：GET /device/update-ui-by-id
  • 渠道与状态
    • 根据渠道与状态获取 MAC：GET /device/get-macs-by-channelIds-and-status
    • 根据渠道与状态获取设备数量：GET /device/get-device-count-by-channelIds-and-status

章节来源

依赖分析​

  • 控制器依赖服务层：心跳控制器与认证控制器均依赖设备服务实现具体业务。
  • 服务层依赖数据访问层：设备服务通过 Mapper/DAO 访问数据库，同时与 Redis 交互。
  • 字典与配置：系统字典提供设备状态枚举，心跳配置通过 Redis 缓存与字典联动。
  • 安全与 Token：客户端 Token 生成与校验，确保设备侧鉴权与上下文一致性。

Mermaid Diagram Code:

graph LR
HB["心跳控制器"] --> SVC["设备服务"]
AUTH["认证控制器"] --> SVC
SVC --> DAO["设备DAO/Mapper"]
SVC --> REDIS["Redis"]
SVC --> DICT["系统字典/配置"]
HB --> TOKEN["客户端Token工具"]

图表来源

章节来源

性能考虑​

  • 缓存优先：设备查询优先命中 Redis，不存在时写入空值缓存，降低数据库压力。
  • 批量处理：导入/更新/删除支持分批处理，避免大事务阻塞。
  • 分页优化：管理端在数据量较大时使用 ES 分页，减少 MySQL 深分页成本。
  • 心跳阈值：合理设置离线阈值，平衡实时性与资源消耗。

故障排查指南​

  • 网络连通性检测：若设备无法连接服务器或心跳异常，可通过指定域名与端口进行连通性检测，确认网络是否通畅。
  • 设备不存在：心跳返回“设备不存在”提示通常表示网络连通正常但设备未注册或未激活。
  • 常见错误码：心跳响应码包含“新任务更新指令”“设备未激活”等，需根据业务码进行相应处理。

章节来源

结论​

设备生命周期管理通过“认证—心跳—状态—管理”的闭环设计，实现了设备从入网到离线/注销的全链路治理。借助 Redis 缓存与数据库协同、批量处理与分页优化，系统在高并发场景下具备良好的稳定性与扩展性。建议在生产环境中结合心跳阈值与离线策略，持续优化设备在线率与系统可用性。

附录​

  • 设备状态字典：未激活、在线、离线
  • 心跳响应码：新任务更新指令、设备未激活
  • 管理端权限：设备创建、更新、删除、导入导出、批量操作等

章节来源

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