OTA 升级操作说明
先上传固件包，再创建升级计划：平台可主动推送任务给在线设备，也可等设备主动拉取；升级结果在固件详情的批次与任务里核对。
1、名词解释
| 名词 | 白话解释 |
|---|---|
| OTA | Over-The-Air，远程把固件推到设备并升级，不用现场拆机刷包。 |
| 固件包 | 要升级的文件（整包或差分）及元数据：产品、版本、签名、下载地址等。 |
| 整包 | 完整固件。设备按目标版本升级；定向场景下允许对已是目标版本的设备重推（联调常用）。 |
| 差分 | 只含相对「源版本」的增量。设备当前版本必须等于源版本，否则跳过不下发。 |
| 产品名称 | 固件绑定的产品模型标识；升级范围按该产品下的设备筛选。 |
| 模块名称 | 设备内多模块时区分（如主控 / 通信模组）；可空，视设备协议而定。 |
| 目标版本 | 升级完成后设备应报到的版本号。 |
| 源版本 | 差分包专用：允许打补丁的当前版本（实现字段常叫待升级/源版本）。 |
| 签名 / 签名算法 | 上传后自动生成 MD5 或 SHA256，设备下载后校验，防篡改、防损坏。 |
| 升级计划 / 批次 | 针对某个固件开的一次「运单」：圈定谁升、怎么推、重试与超时；生成批次号如 B…。 |
| 升级任务 | 批次下每一台设备的一条任务（待推送 → 升级中 → 成功/失败等）。 |
| 静态升级 | 对当前圈定的设备开一次批次；可立即或定时开始/结束。 |
| 动态升级 | 策略持续生效：后续满足条件的设备（或仅新设备）会陆续进入升级。 |
| 全部设备 | 该产品下所有网关与直连设备（提示文案以页面为准）。 |
| 定向升级 | 手工勾选具体设备，适合灰度、单台联调。 |
| 云端主动推送 | 是：平台对在线设备下发 ota.push；否：设备需主动 ota.get 拉任务。 |
| 推送速率 | 每分钟最多推多少台，避免 MQTT/设备被打满（千台规模常建议约 60 台/分）。 |
| 队列分片 | 设备数较多时按「每片台数」切块入队下发（≥100 台常走 Redis 队列）。 |
| TraceID | 贯穿下发与设备上报的追踪号，排障时在日志里搜它。 |
2、OTA 逻辑（先看懂再操作）
把 OTA 想成寄快递：
- 备好包裹：上传固件，绑定产品、版本、签名
- 开运单：创建升级计划（静态/动态、全部/定向、推送策略）
- 通知设备：主动推送，或等设备来拉取
- 设备干活：按 URL 下载 → 校验签名 → 烧录 → 上报进度/版本
- 看签收：批次统计、设备列表状态、日志 TraceID
推荐最短路径（一次性批量）：
上传整包固件 → 固件详情 → 新建升级计划 → 静态 + 全部/定向 → 立即执行 + 主动推送 → 看批次成功数
3、入口在哪里
管理端菜单：OTA 升级管理（固件包列表为主入口；也可从固件「详情」进入批次与任务）。
| 页面 / 弹窗 | 干什么 |
|---|---|
| 固件列表 | 增删改查固件包、打开详情 |
| 新增/编辑固件 | 上传文件、选产品、版本与签名 |
| 固件详情 | 看升级汇总；管理升级批次 / 升级任务 |
| 创建升级计划 | 两步：选择设备 → 升级策略 |
| 批次详情 | 设备列表进度 + 批次基础信息/策略只读 |
| 日志详情 | 按设备 / TraceID 查 OTA 日志 |
产品侧：固件「产品名称」只挂网关、直连类产品模型；子设备是否纳入「全部设备」以创建计划时的提示与实现为准（当前全部设备提示为「网关和直连设备」）。
4、边界与注意点
| 边界 | 说明 |
|---|---|
| 产品绑定 | 固件必须选产品模型；计划只作用于该产品下设备 |
| 差分源版本 | 差分包必须填源版本；设备当前版本不符则跳过不下发 |
| 整包 + 全部/分组 | 无版本或已是目标版本通常跳过；定向整包可重推已达标设备 |
| 主动推送=否 | 平台不下发推送，只等设备拉取；设备需支持 ota.get |
| 定时窗口 | 静态定时：开始距现在至少约 5 分钟、最多 7 天；结束距开始至少 1 小时、最多 30 天（可不设结束） |
| 大批量 | ≥100 台常入队列分片；请设合理推送速率，避免打满 Broker |
| 覆盖已有任务 | 默认关；打开才会覆盖设备上未完成的旧升级任务 |
| 动态「仅对新设备」 | 是：主要跟后续新上报版本的设备；否：当前满足条件 + 后续都覆盖 |
| 与告警无关 | OTA 失败不会自动等同于告警规则；需另配监控/告警时请走规则引擎 |
5、操作步骤
5.1 固件包列表
打开 OTA 固件管理：刷新、新增、删除、搜索；表中可看包类型、产品、版本、签名、地址、大小等。
行操作：编辑、删除、详情。
5.2 新增固件
点「新增」，填写：
- 包类型：整包 / 差分
- 固件名称、产品名称（必选产品模型）
- 模块名称（可选）
- 目标版本；若选差分，填写源版本
- 签名算法：MD5 / SHA256
- 固件文件：选择文件上传；签名与大小自动生成
- 描述（可选）→ 保存
支持常见后缀如 .bin / .zip / .tar.gz 等（以页面上传控件为准）。
整包示例如下：
选 差分 时会多出必填的 源版本（设备当前版本须与此一致才会下发）：
5.3 固件详情与新建升级计划
打开某条固件的「详情」：
- 顶部：固件元数据（名称、版本、类型、签名等）
- 汇总卡：总升级设备数、成功、失败、进行中
- Tab：升级批次 / 升级任务
- 点 新建升级计划
步骤一：选择设备
- 升级方式：静态升级 / 动态升级
- 升级范围：全部设备 / 定向升级
- 全部：提示将升级该产品下所有网关和直连设备
- 定向：表格勾选设备后再下一步
步骤二：升级策略
- 执行时间（静态）：立即执行 / 定时执行（定时需填开始、可选结束）
- 云端主动推送升级：是 / 否
- 高级策略（按规模调整）：
- 推送速率（台/分钟）
- 队列分片（台/片）
- 失败重试间隔与重试次数
- 升级超时时间（分钟）
- 覆盖已有任务
- 动态升级时：是否「仅对新设备生效」
确认后点 确定创建。
立即执行示例如下：
选 定时执行 时需配置开始时间（距当前至少约 5 分钟、最多 7 天），结束时间可选（距开始至少 1 小时、最多 30 天；不填表示不强制结束）：
6、发布后如何核对
6.1 批次列表与批次详情 · 设备列表
固件详情 → 升级批次：看批次号、升级方式、范围、成功/失败计数、状态（如已完成）。
进入批次详情 → 升级设备列表：
- 顶部计数：总数、待推送、已推送、升级中、成功、失败、已取消
- 每台：当前版本、目标版本、状态、状态详情（如
OTA upgrade success, rebooting） - 日志：打开该设备 OTA 日志
6.2 批次基础信息
同一弹窗切到 批次基础信息：只读查看批次 ID、方式、范围、状态、开始时间，以及推送/重试/超时等策略快照。
6.3 日志详情
按时间、设备 ID、TraceID、摘要、结果等排查下发与上报是否对得上。无数据时先确认任务是否已真正下发、设备是否在线并上报。
7、怎么选配置（速查）
| 场景 | 建议 |
|---|---|
| 同产品全量升一版 | 整包 + 静态 + 全部设备 + 立即 + 主动推送 |
| 先灰度几台 | 整包/差分 + 静态 + 定向勾选 |
| 夜间窗口升级 | 静态 + 定时执行（设开始/结束） |
| 新接入设备自动跟上 | 动态升级（按需「仅对新设备」） |
| 设备侧自己拉任务 | 主动推送选 否（设备需支持拉取） |
| 带宽/Broker 压力大 | 降低推送速率、增大分片、分批定向 |
| 只打补丁且版本链清晰 | 差分并严格核对源版本 |
下一步
- 规则与告警联动监控：规则报警配置说明
- 设备接入与在线前提：MQTT 网关设备接入
- 平台能力总览：平台功能特性