跳到主要内容

设备认证API

引用文件

本文引用的文件

目录​

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

简介​

本文件面向设备侧SDK与集成方，系统性梳理设备认证API的设计与实现，覆盖以下能力：

  • 设备登录/激活认证接口
  • MAC地址认证接口
  • CPU序列号认证接口
  • 设备状态查询接口
  • 认证流程、安全机制、设备标识符格式、失败处理策略
  • 设备SDK集成要点、认证参数说明与故障排除

项目结构​

设备认证相关能力由“API接口定义 + 业务实现 + 控制器 + DTO/VO + 常量/枚举”构成，采用分层架构：

  • API层：通过Feign声明远程RPC接口，统一服务名与前缀
  • 控制器层：对外暴露REST接口，处理设备认证与心跳
  • 业务层：实现认证逻辑、设备创建/更新、入网凭证生成
  • 数据访问层：MyBatis Mapper与DO对象
  • DTO/VO：传输对象与请求体对象
  • 常量/枚举：服务名、API前缀、错误码、版本控制

Mermaid Diagram Code:

graph TB
subgraph "设备SDK"
APP["终端设备/应用"]
end
subgraph "网关/服务层"
CTRL["AppDeviceCertificationController<br/>认证控制器"]
SVC["DeviceCertificationImpl<br/>认证服务实现"]
DEV_SVC["DeviceService<br/>设备服务"]
REG_SVC["RegionService<br/>区域服务"]
CH_SVC["ChannelService<br/>渠道服务"]
MAPPER["DeviceCertificationMapper<br/>认证记录Mapper"]
end
subgraph "数据存储"
DB["MySQL 设备表/认证记录表"]
REDIS["Redis 缓存(如使用)"]
end
APP --> CTRL
CTRL --> SVC
SVC --> DEV_SVC
SVC --> REG_SVC
SVC --> CH_SVC
SVC --> MAPPER
DEV_SVC --> DB
MAPPER --> DB
REG_SVC --> DB
CH_SVC --> DB
REDIS -. 可选 .-> DEV_SVC

图表来源

章节来源

核心组件​

  • 设备认证控制器：提供新旧两条认证接口，分别处理带CPU+多字段的新版与仅传MAC的旧版
  • 认证服务实现：负责MAC/CPU匹配、设备不存在时创建、已激活设备的重激活、入网凭证生成与落库
  • 设备服务接口：提供按MAC+CPU查询设备、创建/更新设备等能力
  • 区域/渠道服务：解析IP归属地、默认渠道选择
  • DTO/VO：认证请求体、设备响应体、认证记录DO
  • 常量/枚举：服务名、API前缀、错误码、API版本控制

章节来源

架构总览​

设备认证API采用“控制器-服务-数据访问”的分层设计，结合RPC接口与本地服务协同工作。认证流程围绕“MAC+CPU”进行设备匹配，若设备不存在则自动创建并生成入网凭证；若已激活则按需更新设备信息并刷新凭证。

Mermaid Diagram Code:

sequenceDiagram
participant SDK as "设备SDK"
participant C as "AppDeviceCertificationController"
participant S as "DeviceCertificationImpl"
participant DS as "DeviceService"
participant RS as "RegionService"
participant CS as "ChannelService"
participant M as "DeviceCertificationMapper"
SDK->>C : POST /task/newNetworkAccessCertification
C->>S : networkAccessCertification(reqVO, 1)
S->>DS : getDeviceByMacByCpu(mac, cpu)
alt 设备不存在
S->>S : 校验MAC格式
S->>RS : 解析IP归属地
RS-->>S : regionId, ipAddress
S->>CS : 获取默认渠道ID
CS-->>S : channelId
S->>DS : createDevice(DeviceDO)
DS-->>S : 新设备ID
else 设备已存在
S->>S : 判断是否需要重激活/更新字段
end
S->>M : 异步入网记录缓存
S-->>C : 返回入网凭证certification_code
C-->>SDK : JSON响应

图表来源

详细组件分析​

设备认证接口族​

  • 新版设备激活认证
    • 方法：POST /task/newNetworkAccessCertification
    • 请求体：AppDeviceCertificationReqVO（包含MAC、CPU、设备信息、SDK版本等）
    • 响应：包含入网凭证certification_code
    • 适用场景：SDK版本较新，携带CPU与完整设备信息
  • 旧版设备激活认证
    • 方法：POST /task/networkAccessCertification/{deviceMac}
    • 请求体：仅MAC字符串
    • 响应：包含入网凭证certification_code
    • 适用场景：兼容老SDK或仅能提供MAC的场景

章节来源

MAC地址认证接口​

  • RPC接口：/device/get-by-mac
  • 功能：根据MAC查询设备信息
  • 参数：mac（必填）
  • 返回：CommonResult<DeviceRespDTO>

章节来源

CPU序列号认证接口​

  • RPC接口：/device/get-by-mac-by-cpu
  • 功能：根据MAC+CPU联合查询设备
  • 参数：mac（必填）、cpu（可选）
  • 返回：CommonResult<DeviceRespDTO>

章节来源

设备状态查询接口​

  • RPC接口：/device/get-by-id、/device/get-count-by-channelIds、/device/get-count-by-modelIds、/device/batch-get-count-by-modelIds、/device/batch-get-count-by-channelIds
  • 功能：按ID查询设备、按渠道/型号统计设备数量、批量统计
  • 返回：CommonResult<Long> 或 CommonResult<Map<Integer, Long>>

章节来源

设备状态查询（心跳/活跃）​

  • 控制器：AppDeviceHeartBeatController
  • 版本控制：通过HTTP头api-version区分心跳接口行为
  • 功能：设备心跳上报、任务下发检查、活跃度统计等

章节来源

认证流程与安全机制​

  • 设备唯一性：以MAC+CPU作为匹配依据，若设备不存在则创建
  • 入网凭证：每次激活/重激活均生成新的certification随机串，用于后续鉴权/对账
  • IP归属：解析请求IP归属地，填充regionId与ipAddress
  • 默认渠道：根据平台选择默认渠道ID
  • 重激活保护：若设备已激活且字段不全或版本变化，则更新字段并刷新凭证
  • 异步入网记录：认证请求异步缓存，定时批量入库，降低写放大

Mermaid Diagram Code:

flowchart TD
Start(["进入认证"]) --> CheckExist["按MAC+CPU查询设备"]
CheckExist --> Exists{"设备是否存在？"}
Exists --> |否| ValidateMAC["校验MAC格式"]
ValidateMAC --> ParseIP["解析IP归属地"]
ParseIP --> GetChannel["获取默认渠道ID"]
GetChannel --> BuildDO["构建设备DO(状态=已激活)"]
BuildDO --> Create["创建设备记录"]
Create --> GenCert["生成入网凭证"]
GenCert --> SaveLog["异步入网记录缓存"]
SaveLog --> Done(["返回入网凭证"])
Exists --> |是| NeedReactive{"是否需要重激活/更新字段？"}
NeedReactive --> |是| UpdateFields["更新设备字段/刷新凭证"]
UpdateFields --> SaveLog
NeedReactive --> |否| ReturnCert["直接返回已有入网凭证"]
ReturnCert --> Done

图表来源

章节来源

设备标识符格式与参数说明​

  • MAC地址：必填，格式校验通过后方可创建/激活
  • CPU序列号：建议提供，用于更精确的设备匹配
  • 设备信息：设备型号、品牌、系统版本、构建号、内存规格、UI包名、序列号等
  • SDK版本：用于识别设备SDK能力，触发字段更新策略
  • 平台：用于默认渠道选择

章节来源

错误处理与返回规范​

  • 常见错误码（节选）：设备不存在、MAC格式异常、导入失败、时间范围非法等
  • 控制器层：对空请求体、MAC为空、MAC格式异常进行显式校验并返回错误
  • 业务层：对异常进行捕获并记录日志，返回通用错误提示

章节来源

设备SDK集成示例（步骤指引）​

  • 步骤1：准备认证参数
    • 必填：mac
    • 建议：cpu、deviceModel、brand、systemVersion、build、ddr、ui、sdkVersionName、platform
  • 步骤2：调用新版认证接口
    • URL：POST /task/newNetworkAccessCertification
    • Content-Type：application/json
    • 成功后从响应中提取certification_code
  • 步骤3：后续请求携带入网凭证
    • 将certification_code用于后续接口鉴权（具体取决于业务接口要求）
  • 步骤4：心跳与任务检查
    • 使用心跳接口上报状态，并根据api-version头选择对应行为

章节来源

依赖关系分析​

  • 控制器依赖认证服务与租户上下文
  • 认证服务依赖设备服务、区域服务、渠道服务、Mapper与配置
  • 设备服务与Mapper依赖数据库
  • API常量统一服务名与前缀，便于跨模块协作

Mermaid Diagram Code:

classDiagram
class AppDeviceCertificationController {
+newNetworkAccessCertification(reqVO)
+networkAccessCertification(deviceMac)
}
class DeviceCertificationImpl {
+networkAccessCertification(reqVO, type)
+addDeviceCertification(...)
+opDeviceCertification(...)
+insertDeviceCertification()
}
class DeviceService {
+getDeviceByMacByCpu(mac, cpu)
+createDevice(deviceDO)
+updateDevice(deviceDO)
}
class RegionService {
+parseIpReturnRegionIdAndIp(ip)
}
class ChannelService {
+defaultChannelIdByPlatform(platform)
}
class DeviceCertificationMapper {
+batchInsertDevice(list)
}
AppDeviceCertificationController --> DeviceCertificationImpl : "调用"
DeviceCertificationImpl --> DeviceService : "查询/创建/更新"
DeviceCertificationImpl --> RegionService : "解析IP"
DeviceCertificationImpl --> ChannelService : "默认渠道"
DeviceCertificationImpl --> DeviceCertificationMapper : "批量入库"

图表来源

章节来源

性能考虑​

  • 异步入网记录：认证请求先缓存，定时批量入库，降低写放大
  • 缓存队列：环形队列限制最大容量，避免内存膨胀
  • 字段更新策略：仅在必要时更新字段，减少数据库写操作
  • IP解析与默认渠道：建议在服务端缓存常用映射，减少重复计算

故障排除指南​

  • MAC格式错误
    • 现象：返回MAC格式异常
    • 处理：确保mac符合标准格式后再调用
  • 设备不存在
    • 现象：首次激活成功但后续仍报设备不存在
    • 处理：确认MAC+CPU组合是否正确，检查设备是否被正确创建
  • IP解析失败
    • 现象：regionId/ipAddress为空
    • 处理：检查网络环境与IP解析服务可用性
  • 入网凭证缺失
    • 现象：certification_code为空
    • 处理：确认认证流程已完成，检查异步入网记录是否成功入库
  • 版本兼容问题
    • 现象：心跳接口行为异常
    • 处理：检查api-version头是否正确设置

章节来源

结论​

设备认证API以“MAC+CPU”为核心匹配条件，提供新旧双通道认证能力，并通过入网凭证实现后续鉴权。整体设计具备良好的扩展性与容错能力，建议在集成时严格遵循参数格式与版本控制要求，确保认证流程稳定可靠。

附录​

API清单与说明​

  • 新版设备激活认证
    • 方法：POST /task/newNetworkAccessCertification
    • 请求体：AppDeviceCertificationReqVO
    • 响应：包含certification_code
  • 旧版设备激活认证
    • 方法：POST /task/networkAccessCertification/{deviceMac}
    • 请求体：无（仅路径参数MAC）
    • 响应：包含certification_code
  • 设备查询RPC
    • GET /device/get-by-mac
    • GET /device/get-by-mac-by-cpu
    • GET /device/get-by-id
    • GET /device/get-count-by-channelIds
    • GET /device/get-count-by-modelIds
    • GET /device/batch-get-count-by-modelIds
    • GET /device/batch-get-count-by-channelIds

章节来源

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