跳到主要内容

设备SDK集成指南

引用文件

本文引用的文件

目录​

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

简介​

本指南面向需要在设备端集成设备SDK的开发者，提供从SDK下载、安装配置、初始化设置到核心功能接口使用的完整说明。内容涵盖设备认证、心跳发送、信息上报、状态查询等主要API的使用方法，以及配置项、错误处理与调试方法、性能优化建议与最佳实践。

项目结构​

设备SDK相关能力由后端模块提供，前端设备通过HTTP接口与后端交互完成认证、心跳、配置下发等功能。核心模块位于 yudao-module-device，包含服务层、控制器层、配置与常量等。

Mermaid Diagram Code:

graph TB
subgraph "设备端"
SDK["设备SDK"]
end
subgraph "后端服务"
C1["AppDeviceCertificationController<br/>设备认证接口"]
C2["AppDeviceHeartBeatController<br/>心跳接口"]
S1["DeviceService / DeviceServiceImpl<br/>设备服务"]
S2["DeviceCertificationImpl<br/>认证实现"]
CFG["DeviceConfig<br/>配置项"]
VER["DeviceApiVersionConstats<br/>API版本常量"]
end
SDK --> C1
SDK --> C2
C1 --> S2
C2 --> S1
S1 --> CFG
S1 --> VER

图表来源

章节来源

核心组件​

  • 设备认证服务：负责设备入网认证、激活码生成、设备信息补全与更新。
  • 心跳服务：负责设备在线状态维护、活跃度记录、任务检查与配置下发。
  • 配置中心：提供设备相关配置项，如是否记录认证请求、ES开关、分页上限等。
  • API版本常量：定义心跳接口支持CPU参数的版本阈值及SDK版本策略。

章节来源

架构概览​

下图展示设备SDK与后端服务的交互路径，包括认证、心跳、配置下发与活跃度记录。

Mermaid Diagram Code:

sequenceDiagram
participant D as "设备SDK"
participant HC as "AppDeviceHeartBeatController"
participant DC as "DeviceCertificationImpl"
participant DS as "DeviceServiceImpl"
participant CFG as "DeviceConfig"
Note over D : 设备启动/上线
D->>HC : GET /task/deviceHeartBeat/{mac}/{updateVersion}
HC->>DS : checkDeviceCertification(mac)
DS-->>HC : 设备认证结果
HC->>HC : 更新在线时间/活跃度
HC-->>D : 返回心跳响应(任务或配置)
Note over D : 设备首次接入
D->>DC : POST /device/certification/{deviceMac}
DC->>DS : create/updateDevice(...)
DS-->>DC : 设备信息
DC->>CFG : 判断是否记录认证请求
DC-->>D : 返回激活码/状态

图表来源

详细组件分析​

设备认证接口​

  • 接口路径：/device/certification/{deviceMac}
  • 功能：根据设备MAC与可选CPU进行认证；若设备不存在则创建并生成激活码；若已激活则更新设备信息并重新生成激活码。
  • 关键行为：
    • 校验MAC格式
    • 解析IP归属地区域ID
    • 默认渠道ID推断
    • 激活时间与设备信息更新
    • 激活码生成与返回
    • 可选记录认证请求到历史表

Mermaid Diagram Code:

sequenceDiagram
participant SDK as "设备SDK"
participant C as "AppDeviceCertificationController"
participant CI as "DeviceCertificationImpl"
participant DS as "DeviceServiceImpl"
participant CFG as "DeviceConfig"
SDK->>C : GET /device/certification/{deviceMac}
C->>CI : networkAccessCertification(AppDeviceCertificationReqVO, type)
alt 设备不存在
CI->>DS : createDevice(DeviceDO)
else 设备已存在
CI->>DS : updateDevice(DeviceDO)
end
CI->>CFG : addDeviceCertification(requestHost)
CI-->>C : 返回激活码/状态
C-->>SDK : 成功响应

图表来源

章节来源

心跳接口​

  • 接口路径（V1）：/task/deviceHeartBeat/{mac}/{updateVersion}
  • 接口路径（V2）：/task/deviceHeartBeat/v2/{mac} 或 /task/deviceHeartBeat/v2/{mac}/{cpu}
  • 功能：校验设备认证状态，更新在线时间与活跃度，下发任务或配置，必要时生成设备Token。
  • 关键行为：
    • 根据API版本与SDK版本决定是否携带CPU参数
    • 校验设备是否已激活
    • 更新Redis中的最后在线时间
    • 生成/刷新设备Token（当满足条件时）
    • 返回心跳配置列表

Mermaid Diagram Code:

sequenceDiagram
participant SDK as "设备SDK"
participant HC as "AppDeviceHeartBeatController"
participant DS as "DeviceServiceImpl"
participant DT as "DeviceActivityDetailService"
participant CT as "ClientTokenUtil"
SDK->>HC : GET /task/deviceHeartBeat/v2/{mac}[/{cpu}]
HC->>DS : checkDeviceCertification[CacheNull](mac, cpu?)
alt 认证通过
HC->>HC : 更新DEVICE_LAST_ON_LINE_TIME_KEY
HC->>DT : saveDeviceActivityIfNotExist(mac, cpu, ...)
HC->>CT : 生成/刷新设备Token(条件满足)
HC-->>SDK : 返回心跳配置列表 + 设备Token
else 未激活/不存在
HC-->>SDK : 返回错误码(如未激活)
end

图表来源

章节来源

设备服务接口（Service）​

  • 提供设备创建、更新、删除、分页查询、认证校验、计数统计、心跳配置获取、UI与型号更新等能力。
  • 关键方法：
    • createDevice / updateDevice / deleteDevice
    • checkDeviceCertification / checkDeviceCertificationCacheNull
    • getHearBeatConfig
    • updateModelIdById / updateUiById

Mermaid Diagram Code:

classDiagram
class DeviceService {
+createDevice(createReqVO)
+updateDevice(updateReqVO)
+deleteDevice(id)
+getDevicePage(pageReqVO)
+checkDeviceCertification(mac)
+checkDeviceCertificationCacheNull(mac, cpu)
+getHearBeatConfig()
+updateModelIdById(id, modelName)
+updateUiById(id, ui)
}
class DeviceServiceImpl {
+createDevice(...)
+updateDevice(...)
+checkDeviceCertification(...)
+checkDeviceCertificationCacheNull(...)
+getHearBeatConfig()
+updateModelIdById(...)
+updateUiById(...)
}
DeviceService <|.. DeviceServiceImpl

图表来源

章节来源

配置项与参数​

  • 设备认证配置
    • device.certification.add：是否记录设备入网认证请求（新版域名）
    • device.certification.addonip：是否记录旧版未带域名的认证请求
  • ES相关配置
    • device.es.enable：是否启用ES查询
    • device.es.pageMaxIndex：ES查询最大索引
    • device.es.sync.enable：是否同步设备信息到ES
  • APP安装列表写入
    • app.install.write.database：是否写入数据库
    • app.install.write.es：是否写入ES
    • app.install.es.enable：ES开关
    • app.install.pageMaxIndex：ES分页上限

章节来源

API版本与参数​

  • HTTP头：api-version（用于区分心跳接口是否支持CPU参数）
  • 版本常量：
    • BEAT_HEART_HAS_CPU_BEGIN_VERSION：心跳开始带CPU的版本阈值
    • SDK_VERSION_44 / SDK_VERSION_45：SDK版本策略

章节来源

依赖分析​

  • 控制器依赖服务层，服务层依赖数据访问层与配置中心。
  • 心跳接口依赖Redis存储在线状态与活跃度记录。
  • 认证接口依赖区域解析与默认渠道推断。

Mermaid Diagram Code:

graph LR
HC["AppDeviceHeartBeatController"] --> DS["DeviceServiceImpl"]
DCI["DeviceCertificationImpl"] --> DS
DS --> CFG["DeviceConfig"]
DS --> VER["DeviceApiVersionConstats"]
HC --> REDIS["Redis(在线时间/活跃度)"]

图表来源

性能考虑​

  • 批量导入与更新：服务层对设备导入与批量更新采用分批处理，避免一次性大事务造成阻塞。
  • 缓存策略：设备信息优先从缓存读取，未命中再查询数据库，并写入缓存；对不存在的设备进行空值缓存以防止缓存穿透。
  • Redis在线时间与活跃度：使用有序集合记录设备最后在线时间，便于快速查询与清理。
  • ES写入开关：通过配置项控制是否写入ES，降低写入压力。
  • BloomFilter：针对中国区设备IP更新使用布隆过滤器，减少无效写入。

章节来源

故障排除指南​

  • 常见错误码
    • 21：新任务更新指令
    • 24：设备未激活
  • 排查步骤
    • 确认设备已通过认证接口完成激活，获取激活码。
    • 检查心跳接口是否携带正确的API版本头与CPU参数（若SDK版本高于阈值）。
    • 核对Redis中设备在线时间是否更新，确认活跃度记录是否写入。
    • 查看认证请求是否被记录（依据配置项），定位是否因IP/域名差异导致未记录。
  • 日志分析
    • 关注认证与心跳接口的日志输出，定位异常抛出位置与参数。
    • 对批量导入与更新流程，关注分批处理的进度与异常堆栈。

章节来源

结论​

通过上述组件与流程，设备SDK可以稳定完成认证、心跳、配置下发与活跃度记录。建议在集成过程中严格遵循API版本约定、合理配置ES与缓存策略，并结合日志与错误码进行问题定位与优化。

附录​

A. 数据库与时序数据​

  • 设备运行时长与时序表结构（TDengine）
    • device_runtime.device_runtime：主表，按ts与data_key分区
    • device_runtime_count_day/device_runtime_count_month/year：按天/月/年聚合统计表

章节来源

B. API定义与使用要点​

  • 设备认证请求体字段
    • mac：设备MAC地址
    • cpu：CPU ID（可选）
    • deviceModel/systemVersion/sdkVersionName/channelId/build/deviceIp/ddr/ui等：设备软硬件信息
  • 心跳接口
    • V1：/task/deviceHeartBeat/{mac}/{updateVersion}
    • V2：/task/deviceHeartBeat/v2/{mac} 或 /task/deviceHeartBeat/v2/{mac}/{cpu}
    • 响应包含心跳配置列表与设备Token（满足条件时）

章节来源

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