跳到主要内容

任务与OTA API

引用文件

本文引用的文件

目录​

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

简介​

本文件面向任务与OTA API的使用者与维护者，系统性梳理导出任务接口、文件管理接口、安全密钥接口、UOTA升级接口等核心能力。重点覆盖：

  • 导出任务的状态与类型定义
  • 文件上传下载与分片上传流程
  • 安全密钥的获取与缓存机制
  • TCP通信协议与UOTA升级流程
  • 任务调度示例、文件处理流程与安全配置指南

项目结构​

围绕任务与OTA相关的核心模块与文件如下：

  • 任务模块API与业务实现：yudao-module-task-api、yudao-module-task-biz
  • 安全框架与工具：yudao-framework（含安全工具类）
  • 基础设施文件管理：yudao-module-infra（文件与文件配置控制器）

Mermaid Diagram Code:

graph TB
subgraph "任务模块"
API["API 接口<br/>AppSdkSecurityKeyApi.java"]
IMPL["实现层<br/>AppSdkSecurityKeyApiImpl.java"]
CTRL_EXP["导出任务控制器<br/>BaseExportTaskController.java"]
CTRL_UOTA_APP["UOTA应用接口<br/>AppUotaDetailController.java"]
NETTY["Netty TCP 服务<br/>UotaTcpServer.java 等"]
ENUMS["枚举定义<br/>ExportTaskStatus/Type<br/>TcpMessageTypeEnum"]
end
subgraph "基础设施"
FILE_CTRL["文件控制器<br/>FileController.java"]
FILE_CFG_CTRL["文件配置控制器<br/>FileConfigController.java"]
end
API --> IMPL
IMPL --> NETTY
CTRL_EXP --> ENUMS
CTRL_UOTA_APP --> NETTY
FILE_CTRL --> FILE_CFG_CTRL

图表来源

章节来源

核心组件​

  • 导出任务接口与状态/类型
    • 导出任务状态：启动、手动终止、完成、失败、排队等待中
    • 导出任务类型：APP运行记录、黑名单MAC配置/结果、Launcher广告位配置/结果、APP活跃设备清单、APP安装列表（包名/设备）等
  • 文件管理接口
    • 文件上传、分片上传、文件列表、文件配置、下载
  • 安全密钥接口
    • 通过RPC接口按key与类型获取密钥，内部结合本地缓存与远端拉取
  • UOTA升级接口
    • HTTP接口：应用层检测更新
    • TCP接口：设备侧长连接，时间戳同步、请求响应、加密传输、密钥动态获取

章节来源

架构总览​

整体架构由“HTTP/Web接口层”、“TCP长连接服务层”、“导出任务与文件管理服务层”、“安全密钥服务层”组成。

Mermaid Diagram Code:

graph TB
Client["设备/应用客户端"] --> HTTP["HTTP 接口层<br/>AppUotaDetailController"]
Client --> TCP["TCP 接口层<br/>UotaTcpServer + Handler"]
HTTP --> Biz["业务服务层<br/>UOTA/导出/文件等"]
TCP --> Biz
Biz --> Sec["安全密钥服务<br/>AppSdkSecurityKeyApi + Utils"]
Biz --> Infra["基础设施服务<br/>文件上传/下载/配置"]
Biz --> DB["持久化存储<br/>MySQL/Redis"]
Infra --> FS["对象存储/文件系统"]
Sec --> Biz

图表来源

详细组件分析​

导出任务接口​

  • 接口职责
    • 提供导出任务的分页查询、保存、导出触发与结果下载
    • 支持多种导出类型（如APP运行记录、黑名单、Launcher广告等）
    • 导出任务状态包括：启动、手动终止、完成、失败、排队等待中
  • 关键枚举
    • 导出任务状态：ExportTaskStatus
    • 导出任务类型：ExportTaskType
  • 控制器
    • BaseExportTaskController 提供通用的分页、保存、导出等REST接口

Mermaid Diagram Code:

sequenceDiagram
participant Admin as "管理端"
participant Ctrl as "BaseExportTaskController"
participant Enum as "ExportTaskType/Status"
participant Biz as "导出服务"
participant Store as "存储/对象存储"
Admin->>Ctrl : "提交导出任务(类型/条件)"
Ctrl->>Enum : "校验类型/状态"
Ctrl->>Biz : "创建导出任务并异步执行"
Biz->>Store : "生成并上传导出文件"
Admin->>Ctrl : "查询导出任务状态"
Ctrl-->>Admin : "返回状态与下载链接"

图表来源

章节来源

文件管理接口​

  • 接口职责
    • 文件上传、分片上传、断点续传、秒传、上传进度追踪
    • 文件列表查询、文件分类管理、文件配置管理
    • 下载与删除
  • 关联模块
    • 与任务管理、UOTA信息管理、Launcher管理、域名分发等模块关联

Mermaid Diagram Code:

flowchart TD
Start(["开始上传"]) --> CheckChunk["检查分片/断点"]
CheckChunk --> Exists{"是否已存在?"}
Exists --> |是| ReturnUrl["返回文件URL"]
Exists --> |否| Upload["上传分片"]
Upload --> Merge["合并分片"]
Merge --> Index["索引/元数据入库"]
Index --> Done(["完成"])
ReturnUrl --> Done

图表来源

章节来源

安全密钥接口​

  • 接口职责
    • 通过RPC按key与类型获取密钥，内部结合本地缓存与远端拉取
  • 实现要点
    • 使用定时缓存与分布式锁，避免频繁远端调用
    • 返回时解密密钥值，确保不直接暴露敏感值

Mermaid Diagram Code:

sequenceDiagram
participant Caller as "调用方"
participant API as "AppSdkSecurityKeyApi"
participant Impl as "AppSdkSecurityKeyApiImpl"
participant Utils as "AppSdkSecurityKeyUtils"
participant Remote as "远端密钥服务"
Caller->>API : "getSecretKeyByKeyAndType(key,type)"
API->>Impl : "RPC转发"
Impl->>Utils : "查询缓存/拉取"
Utils->>Remote : "按key/type获取密钥"
Remote-->>Utils : "密钥DTO(含密文)"
Utils-->>Impl : "解密后返回"
Impl-->>Caller : "返回密钥DTO"

图表来源

章节来源

UOTA升级接口​

  • HTTP接口
    • 接口地址：/task/checkAppVersionIsUpdate
    • 权限：无需登录
    • 功能：接收客户端请求，调用Service层逻辑判断是否有新版本，并返回结果
  • TCP接口
    • 服务器组件：UotaTcpServer、UotaTcpServerInitializer、UotaTcpServerHandler
    • 消息类型：时间戳响应、UOTA信息请求、UOTA信息响应、错误响应
    • 加密与安全：AES-256-CBC（PKCS5Padding）、Base64编码、IV拼接于密文前；按请求头sdkVersion动态获取密钥；时间戳校验（默认5分钟窗口）

Mermaid Diagram Code:

sequenceDiagram
participant Dev as "设备"
participant Srv as "UotaTcpServer"
participant Hdl as "UotaTcpServerHandler"
participant Sec as "密钥服务"
participant DB as "数据库/服务"
Dev->>Srv : "建立TCP连接"
Srv->>Hdl : "channelActive"
Hdl-->>Dev : "TIMESTAMP_RESPONSE(当前时间戳)"
Dev->>Srv : "UOTA_INFO_REQUEST(加密payload+header)"
Srv->>Hdl : "channelRead0"
Hdl->>Sec : "按sdkVersion获取密钥"
Hdl->>Hdl : "AES-CBC解密data"
Hdl->>Hdl : "校验时间戳(差值<5min)"
Hdl->>DB : "查询最新固件信息(URL/MD5/Version)"
Hdl->>Hdl : "加密响应数据"
Hdl-->>Dev : "UOTA_INFO_RESPONSE(加密payload)"
opt 发生错误
Hdl-->>Dev : "ERROR_RESPONSE(错误描述)"
end

图表来源

章节来源

任务调度与域名分发​

  • 域名分发接口
    • App侧请求：DomainListReqVO（platform/mac/cpu）
    • 返回：DomainVO（包含域名列表与逗号分隔字符串）
    • 管理端：DomainController 提供域名的增删改查与设备数量统计
  • 与规则引擎集成
    • 通过规则引擎匹配设备业务ID，支持灰度发布、地区限制、渠道白名单等策略

Mermaid Diagram Code:

sequenceDiagram
participant App as "App/设备"
participant Ctrl as "DomainController"
participant Rule as "规则引擎"
participant Biz as "业务服务"
App->>Ctrl : "查询域名(平台/设备信息)"
Ctrl->>Biz : "解析设备信息"
Biz->>Rule : "matchBusinessIds(设备规则)"
Rule-->>Biz : "命中结果"
Biz-->>Ctrl : "组装DomainVO"
Ctrl-->>App : "返回域名列表"

图表来源

章节来源

依赖分析​

  • 组件耦合
    • AppSdkSecurityKeyApi 与 AppSdkSecurityKeyApiImpl 通过Feign RPC交互
    • AppSdkSecurityKeyUtils 作为缓存与远端拉取的协调者
    • UotaTcpServerHandler 依赖密钥服务与业务服务进行解密与查询
  • 外部依赖
    • Netty TCP框架、Redis缓存、对象存储（文件管理）
    • 规则引擎（设备规则匹配）

Mermaid Diagram Code:

graph LR
API["AppSdkSecurityKeyApi"] --> IMPL["AppSdkSecurityKeyApiImpl"]
IMPL --> UTIL["AppSdkSecurityKeyUtils"]
UTIL --> REMOTE["远端密钥服务"]
NETTY["UotaTcpServerHandler"] --> SEC["密钥服务"]
NETTY --> SVC["业务服务(UOTA/域名)"]

图表来源

章节来源

性能考虑​

  • 导出任务
    • 大数据量采用异步导出与排队机制，降低阻塞风险
    • 状态枚举便于前端轮询与可视化展示
  • 文件管理
    • 分片上传与断点续传提升成功率与稳定性
    • 缓存与索引优化下载与检索性能
  • 安全密钥
    • 本地定时缓存减少RPC调用频率
    • 解密在服务端完成，避免敏感值泄露
  • TCP升级
    • Netty高并发长连接，合理设置空闲检测与超时
    • 加密与时间戳校验兼顾安全性与性能

故障排查指南​

  • 导出任务
    • 若导出失败，检查任务状态是否为失败并查看日志
    • 确认导出类型与数据范围是否正确
  • 文件管理
    • 分片上传失败时，优先检查网络与存储权限
    • 合并阶段失败多因分片缺失或顺序错乱
  • 安全密钥
    • 密钥不存在或解密失败时，确认key与type是否匹配
    • 检查缓存是否过期或远端服务是否可用
  • TCP升级
    • 设备无法获取升级信息时，检查时间戳差异是否超过阈值
    • 确认加密算法、IV与Base64编码是否符合约定
    • 校验sdkVersion对应的密钥是否存在

章节来源

结论​

本文档系统化梳理了任务与OTA API的关键能力：导出任务的状态与类型、文件管理的上传下载与分片策略、安全密钥的获取与缓存机制、以及UOTA升级的HTTP与TCP接口规范。通过清晰的架构图与时序图，帮助读者快速理解各组件职责与交互关系，并提供实用的故障排查建议与性能优化方向。

附录​

  • 配置项参考
    • TCP服务器配置：enabled、port
  • 关键接口一览
    • 导出任务：BaseExportTaskController
    • 文件管理：FileController、FileConfigController
    • 安全密钥：AppSdkSecurityKeyApi、AppSdkSecurityKeyApiImpl、AppSdkSecurityKeyUtils
    • UOTA升级：AppUotaDetailController、UotaTcpServer、UotaTcpServerHandler

章节来源

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