跳到主要内容

固件管理

目录

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

简介

本技术文档围绕固件管理系统,系统性梳理固件版本管理机制、固件包上传流程、升级过程生命周期、升级包分发机制、元数据管理以及API接口与客户端使用示例。文档以仓库中的任务模块、设备模块、基础设施模块与报告模块为核心,结合UOTA HTTP/TCP协议对接文档,形成从“版本配置—包上传—策略下发—设备升级—结果反馈”的闭环说明。

项目结构

固件管理相关能力分布在多个模块中:

  • 任务模块(task):负责UOTA版本信息管理、升级策略配置、域名分发、设备侧升级请求处理、推送回调与统计。
  • 设备模块(device):负责设备心跳、渠道与版本联动,驱动升级任务下发。
  • 基础设施模块(infra):负责文件上传、分片上传、存储与URL生成。
  • 报告模块(report):负责升级结果、卸载事件等历史数据的持久化与同步。

Mermaid Diagram Code:

graph TB
subgraph "任务模块(task)"
A["UotaDetailController<br/>UotaDetailService"]
B["DomainUotaAppController<br/>DomainUotaAppService"]
C["AppUotaDetailController<br/>设备侧升级请求"]
D["DeviceEventServiceImpl<br/>推送回调"]
end
subgraph "设备模块(device)"
E["AppDeviceHeartBeatController<br/>心跳/任务下发"]
end
subgraph "基础设施模块(infra)"
F["FilePartUploadServiceImpl<br/>分片上传"]
G["FileServiceImpl<br/>文件上传/存储"]
end
subgraph "报告模块(report)"
H["ApkPushHistoryServiceImpl<br/>历史/ES同步"]
I["ApkUninstallUpdateConsumer<br/>卸载事件消费"]
end
C --> A
A --> G
B --> G
D --> H
D --> I
E --> C

图表来源

章节来源

核心组件

  • UOTA版本管理与策略
    • UOTA明细管理:版本号、包名、版本名称、系统应用标识、安装路径、启用状态等。
    • 升级策略:规则引擎(灰度/地区/MAC/渠道等)、传统渠道白名单。
    • 域名分发:将升级包与域名/URL绑定,支持直链或重定向。
  • 固件包上传与存储
    • 文件上传:统一上传至文件存储器,生成URL与元信息。
    • 分片上传:初始化任务、批量获取分片上传URL、合并完成。
  • 升级生命周期
    • 设备侧请求:携带MAC、CPU、平台、当前版本号等。
    • 服务端处理:版本筛选、策略匹配(规则引擎+渠道)、返回最优升级包。
    • 推送与回调:Kafka推送APK升级回调事件,记录历史与ES同步。
  • 分发机制
    • CDN/直链:支持直链或重定向URL;支持断点续传(HTTP Range)。
    • 并发与重试:分片上传并发控制与失败重试;设备端断点续传与MD5校验。
  • 元数据与回滚
    • 版本信息:包名、版本号、版本名称、MD5、大小、URL。
    • 设备适配:渠道、区域、MAC白名单、规则引擎。
    • 回滚策略:通过版本号比较与强制升级标记控制。

章节来源

架构总览

固件管理整体架构围绕“版本配置—包上传—策略下发—设备升级—结果反馈”展开,设备侧通过HTTP/TCP协议请求升级信息,服务端结合规则引擎与渠道策略返回最优升级包,并通过文件存储与分发机制提供下载能力。

Mermaid Diagram Code:

sequenceDiagram
participant Dev as "设备端"
participant AppCtl as "AppUotaDetailController"
participant Svc as "UotaDetailService"
participant Rule as "规则引擎/渠道"
participant Store as "文件存储/直链"
participant Push as "推送/Kafka"
Dev->>AppCtl : "POST /task/checkAppVersionIsUpdate"
AppCtl->>Svc : "校验版本/策略"
Svc->>Rule : "规则匹配/渠道校验"
Rule-->>Svc : "命中结果"
Svc->>Store : "获取文件URL/MD5/大小"
Svc-->>AppCtl : "返回升级包信息"
AppCtl-->>Dev : "返回升级包详情"
Dev->>Store : "HTTP Range断点续传下载"
Dev->>Push : "上报安装/卸载事件"
Push-->>Svc : "回调/历史入库"

图表来源

详细组件分析

版本管理与策略配置

  • 版本号规则与兼容性
    • 版本号采用“内部版本号+版本名称”双字段,设备侧以内部版本号比较,确保升级顺序与兼容性。
    • 策略匹配包含规则引擎与传统渠道白名单,支持灰度发布、区域限制、MAC白名单等。
  • 升级策略配置
    • 规则引擎:灵活组合渠道、地区、MAC、设备型号等条件。
    • 传统渠道:按渠道维度限制。
    • 强制升级:返回字段标记强制升级,设备端据此决定静默安装。

Mermaid Diagram Code:

flowchart TD
Start(["设备请求升级"]) --> GetVer["获取当前版本号/平台"]
GetVer --> Query["查询更高版本包"]
Query --> Match["规则引擎匹配"]
Match --> Channel["渠道白名单校验"]
Channel --> Choice{"多个候选?"}
Choice --> |是| Pick["取最高版本"]
Choice --> |否| Return["返回升级包"]
Pick --> Return
Return --> End(["结束"])

图表来源

章节来源

固件包上传流程

  • 文件存储策略
    • 统一上传至文件存储器,生成URL与元信息(包名、版本号、版本名称、大小)。
    • 支持直链或重定向URL,便于CDN加速与分发。
  • MD5校验与压缩
    • 上传完成后由设备端通过HTTP Range下载并校验MD5,确保文件完整性。
    • 压缩处理由设备端按需执行,服务端不强制压缩。
  • 存储路径管理
    • 通过文件存储器生成稳定路径与URL,避免硬编码路径。

Mermaid Diagram Code:

sequenceDiagram
participant Admin as "管理员"
participant Ctrl as "UotaDetailController"
participant Svc as "UotaDetailService"
participant Store as "FileServiceImpl"
participant Part as "FilePartUploadServiceImpl"
Admin->>Ctrl : "创建/更新UOTA明细"
Ctrl->>Svc : "保存版本信息"
Svc->>Store : "上传文件/生成URL"
Store-->>Svc : "返回URL/元信息"
Svc-->>Ctrl : "完成保存"
Note over Part,Store : "分片上传:初始化任务/获取分片URL/合并完成"

图表来源

章节来源

升级过程生命周期

  • 升级任务创建
    • 管理员在UOTA明细中创建/更新版本信息,绑定文件与策略。
  • 设备匹配
    • 设备发起请求,携带MAC、CPU、平台、当前版本号,服务端进行版本筛选与策略匹配。
  • 推送执行
    • 通过Kafka推送APK升级回调事件,记录推送历史。
  • 状态跟踪与结果反馈
    • 历史记录与ES同步,支持卸载事件回调与更新。

Mermaid Diagram Code:

sequenceDiagram
participant Dev as "设备端"
participant Ctrl as "AppUotaDetailController"
participant Svc as "UotaDetailService"
participant Rule as "规则引擎/渠道"
participant Store as "文件存储"
participant MQ as "Kafka推送"
Dev->>Ctrl : "请求升级"
Ctrl->>Svc : "查询最新版本"
Svc->>Rule : "规则/渠道匹配"
Rule-->>Svc : "匹配结果"
Svc->>Store : "获取URL/MD5/大小"
Svc-->>Ctrl : "返回升级包"
Ctrl-->>Dev : "返回升级包详情"
Dev->>MQ : "上报安装/卸载事件"

图表来源

章节来源

升级包分发机制

  • CDN加速与直链
    • 支持直链或重定向URL,便于CDN加速与就近分发。
  • 断点续传与并发控制
    • HTTP Range支持断点续传;分片上传支持并发与失败重试。
  • 失败重试
    • 分片上传失败自动重试;设备端下载失败可断点续传。

章节来源

元数据管理与回滚策略

  • 版本信息
    • 包名、版本号、版本名称、MD5、大小、URL、是否系统应用、安装路径。
  • 设备适配
    • 渠道、区域、MAC白名单、规则引擎条件。
  • 回滚策略
    • 通过版本号比较与强制升级标记控制,避免降级风险。

章节来源

API接口与客户端使用示例

  • 设备侧升级请求
    • 接口:POST /task/checkAppVersionIsUpdate
    • 请求参数:mac、cpu、platform、当前版本号
    • 响应:升级包URL、MD5、大小、是否强制升级
  • 文件上传与分片上传
    • 文件上传:FileServiceImpl.upload
    • 分片上传:FilePartUploadServiceImpl.initiateMultipartUpload、getMultipartUploadUrls
  • RPC接口
    • TaskFileApi.checkFileUseOnTask:校验文件是否在任务模块使用

章节来源

依赖分析

  • 控制层依赖服务层,服务层依赖基础设施与规则引擎。
  • 设备心跳控制器与任务模块协同,驱动升级任务下发。
  • 推送回调通过Kafka与报告模块交互,实现历史与ES同步。

Mermaid Diagram Code:

graph LR
AppCtl["AppUotaDetailController"] --> Svc["UotaDetailService"]
Svc --> Rule["规则引擎/渠道"]
Svc --> Store["文件存储"]
DevHB["AppDeviceHeartBeatController"] --> AppCtl
Push["DeviceEventServiceImpl"] --> Hist["ApkPushHistoryServiceImpl"]
Hist --> ES["ES同步"]

图表来源

章节来源

性能考虑

  • 缓存优化:Redis缓存最新版本与索引,降低数据库压力。
  • 并发与重试:分片上传并发控制与失败重试,提升上传稳定性。
  • CDN与直链:直链或重定向URL配合CDN,提高下载速度与成功率。
  • 断点续传:HTTP Range减少网络波动影响,提升用户体验。

故障排查指南

  • 设备无法获取升级包
    • 检查UOTA明细状态与策略配置(规则引擎/渠道)。
    • 确认文件存储URL有效且可访问。
  • 下载失败或MD5不一致
    • 检查HTTP Range断点续传是否正确,确认MD5校验逻辑。
    • 核对文件大小与Range边界。
  • 推送回调未到达
    • 检查Kafka主题配置与消费者是否正常。
    • 核对历史记录与ES同步状态。

章节来源

结论

固件管理系统通过完善的版本管理、策略配置、文件上传与分发机制,以及设备侧升级与结果反馈闭环,实现了从版本配置到设备升级的全链路管理。结合规则引擎与CDN直链,系统具备良好的扩展性与稳定性,能够支撑大规模设备的固件升级与运维需求。

附录

  • 协议与对接
    • HTTP协议:时间戳校验、AES加密、断点续传、直链/重定向。
    • TCP协议:Netty长连接、消息结构、时间戳校验、加密传输。
  • 客户端示例
    • 提供C/C++ TCP客户端示例,便于快速接入与测试。

章节来源

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