跳到主要内容

固件管理

引用文件

本文引用的文件

目录​

  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 问答