442 lines
13 KiB
Markdown
442 lines
13 KiB
Markdown
# OTA 稳定性改造实施路线
|
||
|
||
## 1. 目标与原则
|
||
|
||
本路线的核心目标是：先利用现有 App OTA 发布一个风险尽可能小的桥接版本，建立可靠的升级控制、状态上报和灰度发布能力；随后验证系统级 OTA，修复 Kernel 和 Mini FOTA 中无法通过 App OTA 解决的问题；最后根据 Flash 空间和硬件条件决定是否实施 A/B 分区。
|
||
|
||
实施过程中遵循以下原则：
|
||
|
||
- 第一次桥接升级尽量小，不同时引入大量业务改动。
|
||
- 固件升级和音频资源更新相互独立，任何一方失败都不影响另一方。
|
||
- 每个阶段先小批量验证，通过验收门槛后再扩大范围。
|
||
- 所有升级必须可追踪、可暂停，并准备串口烧录救援方案。
|
||
- 在系统 OTA 和回滚能力验证完成前，不假设设备具备可靠的自动恢复能力。
|
||
|
||
## 2. 当前能力边界
|
||
|
||
当前生成的 `fota.bin` 只包含 `customer_app.bin`，属于 App-only OTA，可更新正常业务程序，但不能更新：
|
||
|
||
- Kernel；
|
||
- Mini FOTA 系统；
|
||
- Bootloader；
|
||
- 分区表；
|
||
- `customer_fs` 文件系统镜像；
|
||
- GNSS、DSP、RF 等底层固件。
|
||
|
||
当前设备没有明确的标准 A/B 应用分区。Mini FOTA 会下载并写入 `customer_app`，底层备份和回滚能力尚未得到完整验证。设备进入 FOTA 后，如果下载地址长期不可用，存在持续重启和无法进入正常业务程序的风险。
|
||
|
||
## 3. 推荐实施顺序
|
||
|
||
```text
|
||
阶段 0：建设发布基础设施和救援能力
|
||
↓
|
||
阶段 1：发布最小 App 桥接版本
|
||
↓
|
||
阶段 2：独立上线音频资源同步
|
||
↓
|
||
阶段 3：实验室验证系统级 OTA
|
||
↓
|
||
阶段 4：更新 Kernel 和 Mini FOTA
|
||
↓
|
||
阶段 5：建立启动健康确认和失败恢复
|
||
↓
|
||
阶段 6：评估并实施 A/B 或备份恢复方案
|
||
```
|
||
|
||
---
|
||
|
||
## 4. 阶段 0：发布基础设施和救援准备
|
||
|
||
### 目标
|
||
|
||
在不升级设备的前提下，降低第一次桥接 OTA 的发布风险。
|
||
|
||
### 工作内容
|
||
|
||
1. 固定 OTA 文件地址，发布后禁止覆盖、删除或改名。
|
||
2. 对固件下载服务器增加可用性、响应时间和错误率监控。
|
||
3. 为每个固件保存以下发布信息：
|
||
- 产品型号；
|
||
- 硬件版本范围；
|
||
- 软件版本；
|
||
- 构建时间；
|
||
- Git commit；
|
||
- 文件大小；
|
||
- SHA-256；
|
||
- 下载地址。
|
||
4. 服务端支持：
|
||
- 测试设备白名单；
|
||
- 分批灰度；
|
||
- 暂停下发；
|
||
- 防止重复下发；
|
||
- 成功率和失败率统计。
|
||
5. 准备专用测试设备和串口烧录救援流程。
|
||
6. 使用当前旧 FOTA 测试以下场景：
|
||
- 弱网和网络切换；
|
||
- DNS 失败；
|
||
- 下载前断网；
|
||
- 下载过程中断网；
|
||
- HTTP 404、500 和超时；
|
||
- 重复下发相同升级命令；
|
||
- 下载服务器临时不可用。
|
||
|
||
### 验收门槛
|
||
|
||
- 可以只向指定测试设备下发 OTA。
|
||
- 可以随时停止后续批次。
|
||
- 固件文件能够长期稳定访问。
|
||
- 能通过设备 ID、任务 ID 和版本号追踪升级结果。
|
||
- 已验证串口烧录恢复流程。
|
||
|
||
---
|
||
|
||
## 5. 阶段 1：最小 App 桥接版本
|
||
|
||
### 目标
|
||
|
||
整理正常 App 内的 OTA 控制逻辑，为后续系统 OTA、资源同步和结果追踪建立可靠入口。
|
||
|
||
### 5.1 统一 OTA 启动入口
|
||
|
||
- OTA 只允许由一个明确的业务入口启动。
|
||
- `parse_command()` 只解析和校验消息，不执行延时、删除文件、重启或调用 FOTA。
|
||
- 删除当前解析阶段和处理阶段可能重复启动 OTA 的设计。
|
||
- 检查并处理 `ql_fullfota_app_start()` 的返回值。
|
||
- OTA 准备期间拒绝或合并重复升级命令。
|
||
|
||
### 5.2 建立 OTA 状态机
|
||
|
||
建议至少包含以下状态：
|
||
|
||
```text
|
||
IDLE
|
||
RECEIVED
|
||
VALIDATED
|
||
ACCEPTED
|
||
PRECHECKING
|
||
STARTING
|
||
REBOOTING
|
||
FIRST_BOOT
|
||
SUCCEEDED
|
||
FAILED
|
||
```
|
||
|
||
状态变化和任务信息应持久化，避免重启后丢失上下文。
|
||
|
||
### 5.3 校验升级命令
|
||
|
||
升级前至少校验：
|
||
|
||
- OTA 任务 ID；
|
||
- 目标版本；
|
||
- 产品型号；
|
||
- 硬件版本；
|
||
- 固件类型；
|
||
- URL 协议；
|
||
- 域名白名单；
|
||
- 允许的端口和路径；
|
||
- 声明的文件大小；
|
||
- 声明的 SHA-256；
|
||
- 是否为重复升级；
|
||
- 是否属于未授权降级。
|
||
|
||
说明：正常 App 可以校验命令和服务器声明，但实际固件由重启后的旧 Mini FOTA 下载。在 Mini FOTA 支持 SHA-256 前，App 不能替代它对最终下载内容进行完整哈希校验。
|
||
|
||
### 5.4 OTA 前置检查
|
||
|
||
调用 FOTA 前检查：
|
||
|
||
- SIM 和网络注册状态；
|
||
- PDP 是否正常；
|
||
- DNS 是否能够解析；
|
||
- 下载地址是否可以建立连接；
|
||
- HTTP 是否返回 200；
|
||
- `Content-Length` 是否合理；
|
||
- 电池、电压或外部供电是否满足升级条件；
|
||
- 当前是否正在执行通话等关键业务。
|
||
|
||
推荐执行顺序：
|
||
|
||
```text
|
||
解析命令
|
||
→ 校验任务
|
||
→ 网络和 URL 预检查
|
||
→ 持久化任务信息
|
||
→ 向服务器上报已接受
|
||
→ 确认消息发送完成
|
||
→ 调用 FOTA 接口
|
||
→ 重启进入 Mini FOTA
|
||
```
|
||
|
||
预检查只能过滤明显的 URL、404 和服务器故障，不能保证重启后的 Mini FOTA 网络仍然正常。
|
||
|
||
### 5.5 升级结果补报
|
||
|
||
新版本第一次启动后读取持久化的 OTA 任务信息，上报：
|
||
|
||
- 任务 ID；
|
||
- 原版本；
|
||
- 目标版本；
|
||
- 当前实际版本；
|
||
- 开始和结束时间；
|
||
- 最终结果；
|
||
- 最后错误码；
|
||
- 是否发生异常重启。
|
||
|
||
暂时无法联网时，应保留结果并在下次连接后补报。
|
||
|
||
### 5.6 音频与 OTA 解耦
|
||
|
||
- 删除 OTA 前调用 `app_file_check_del()` 的行为。
|
||
- FBF 下载和 updater 安装期间不清空现有音频。
|
||
- 新 APP 启动、版本确认等于 OTA 目标且网络就绪后，才删除服务器管理的音频并立即补下载。
|
||
- `barge_in_cute.mp3` 纳入删除和补下载范围；发布前必须确认固定资源地址可用。
|
||
- 音频下载失败不得影响固件升级结果。
|
||
- 固件升级失败不得破坏原有可用音频。
|
||
|
||
### 第一版明确不做
|
||
|
||
- 不修改分区表；
|
||
- 不更新 Kernel 或 Mini FOTA；
|
||
- 不修改 Bootloader；
|
||
- 不替换整个 `customer_fs`；
|
||
- 不同时进行大规模业务重构；
|
||
- 不引入独立音频 manifest、SHA-256 或签名协议。
|
||
|
||
### 验收门槛
|
||
|
||
- 单条 OTA 命令只触发一次 FOTA。
|
||
- 无效 URL、错误型号和重复版本不会导致重启。
|
||
- 设备重启前能够上报已接受状态。
|
||
- 新版本启动后能够补报最终结果。
|
||
- OTA 下载失败时原有音频不被删除。
|
||
- 新版本确认成功后，服务器管理的音频被刷新且缺失文件能够在后续联网时继续补下载。
|
||
- 小批量设备升级成功率达到预定标准后才能扩大灰度。
|
||
|
||
---
|
||
|
||
## 6. 阶段 2：独立音频资源同步
|
||
|
||
### 目标
|
||
|
||
在不更新整个 `customer_fs.bin` 的情况下，安全地下发新增音频，并确保资源失败不会影响设备核心业务。
|
||
|
||
### 6.1 资源清单
|
||
|
||
每个资源至少记录：
|
||
|
||
- 资源版本；
|
||
- 文件名；
|
||
- 下载 URL；
|
||
- 文件大小；
|
||
- SHA-256；
|
||
- 是否必需；
|
||
- 最低 App 版本。
|
||
|
||
### 6.2 单文件下载流程
|
||
|
||
```text
|
||
检查 LittleFS 剩余空间
|
||
→ 下载到临时文件
|
||
→ 检查实际文件大小
|
||
→ 校验 SHA-256
|
||
→ 校验文件基本格式
|
||
→ 原子重命名为正式文件
|
||
→ 更新本地资源状态
|
||
```
|
||
|
||
### 6.3 可靠性要求
|
||
|
||
- 不能仅以“文件存在”判断下载成功。
|
||
- 下载中断后不能留下被当作有效资源的半文件。
|
||
- 新文件校验失败时保留原文件。
|
||
- 音频同步在后台低优先级执行，不阻塞 MQTT 上线。
|
||
- 每个文件独立记录重试次数，采用退避重试。
|
||
- 写入前计算 LittleFS 剩余空间并保留安全余量。
|
||
- 7 条超时提示音只从已校验有效的文件中随机选择。
|
||
- 新增资源全部不可用时，继续使用原 `tts_error.mp3` 作为兜底。
|
||
|
||
### 验收门槛
|
||
|
||
- 断网、空间不足或校验失败不会破坏现有音频。
|
||
- 半文件在重启后能够被识别并重新下载。
|
||
- 资源服务器不可用时设备仍能正常连接 MQTT。
|
||
- 新增 6 条音频全部写入后，LittleFS 仍保留规定的安全空间。
|
||
|
||
---
|
||
|
||
## 7. 阶段 3：实验室验证系统级 OTA
|
||
|
||
### 目标
|
||
|
||
确认 SDK 的系统 FOTA 是否能够安全更新 Kernel、Mini FOTA 和相关底层组件。
|
||
|
||
### 验证内容
|
||
|
||
1. 确认系统升级包的生成工具、输入文件和版本基线。
|
||
2. 确认升级包实际包含和修改的分区。
|
||
3. 确认是整包升级还是指定旧版本到新版本的差分升级。
|
||
4. 验证暂存空间、RAM 和 Flash 空间是否满足要求。
|
||
5. 验证以下异常场景：
|
||
- 下载前断网；
|
||
- 下载中断网；
|
||
- Flash 写入期间断电；
|
||
- URL 返回 404 或 500；
|
||
- 文件被截断；
|
||
- checksum 或签名错误；
|
||
- 固件型号不匹配；
|
||
- 版本基线不匹配；
|
||
- 新系统无法正常启动；
|
||
- 连续多次升级失败。
|
||
6. 确认失败后设备是否能恢复旧系统或进入明确的恢复模式。
|
||
|
||
此阶段可以与桥接版本研发并行，但系统 OTA 的正式上线必须在桥接版本稳定之后。
|
||
|
||
### 验收门槛
|
||
|
||
- 明确系统包的生成、签名、校验和发布流程。
|
||
- 明确升级会修改哪些分区。
|
||
- 关键断电和断网测试不会造成设备永久失联。
|
||
- 失败原因可以被持久化和上报。
|
||
- 已具备批量发布所需的恢复方案。
|
||
|
||
---
|
||
|
||
## 8. 阶段 4：更新 Kernel 和 Mini FOTA
|
||
|
||
### 目标
|
||
|
||
解决当前 App OTA 无法修复的底层下载、重试、恢复和安全问题。
|
||
|
||
### 工作内容
|
||
|
||
1. 持久化 FOTA 失败次数。
|
||
2. 设置单次启动和跨重启的最大重试次数。
|
||
3. 网络错误使用指数退避，不再主要依靠重启设备进行重试。
|
||
4. 区分并记录以下错误：
|
||
- 网络注册失败；
|
||
- PDP 激活失败；
|
||
- DNS 失败；
|
||
- TCP/TLS 连接失败；
|
||
- HTTP 非 200；
|
||
- 下载超时；
|
||
- 文件格式错误；
|
||
- Flash 擦除或写入失败；
|
||
- checksum 或签名失败。
|
||
5. 超过重试上限后清除 FOTA 状态，恢复进入旧 App。
|
||
6. 正常 App 启动后上报失败阶段和错误码。
|
||
7. 评估并启用可靠的断点续传。
|
||
8. 支持备用下载地址或可靠的服务端容灾。
|
||
9. 使用 HTTPS，并正确校验证书。
|
||
10. 对升级包进行数字签名验证。
|
||
11. 验证产品型号、硬件版本和升级基线。
|
||
|
||
“超过重试上限后恢复旧 App”应优先于 A/B 实施，用于直接解决当前可能无限重启的问题。
|
||
|
||
### 验收门槛
|
||
|
||
- 永久不可用的 URL 不会导致设备无限重启。
|
||
- 达到重试上限后能够恢复正常 App 或进入明确恢复模式。
|
||
- 异常原因能够被持久化并在联网后上报。
|
||
- 非法、损坏或型号不匹配的固件不会被安装。
|
||
|
||
---
|
||
|
||
## 9. 阶段 5：启动健康确认与失败恢复
|
||
|
||
### 目标
|
||
|
||
不再把“固件写入完成”直接等同于“升级成功”。
|
||
|
||
新版本启动后至少检查：
|
||
|
||
- 文件系统挂载成功；
|
||
- 关键配置读取成功；
|
||
- 关键线程正常运行；
|
||
- 看门狗状态正常；
|
||
- 网络能够注册；
|
||
- MQTT 能够连接；
|
||
- 设备版本和 OTA 任务可以正常上报；
|
||
- 没有连续崩溃或反复重启。
|
||
|
||
只有达到健康条件后才确认升级成功。
|
||
|
||
如果多次启动仍不能确认健康：
|
||
|
||
- 具备 A/B 时回滚到旧分区；
|
||
- 不具备 A/B 时恢复备份 App 或进入恢复模式。
|
||
|
||
---
|
||
|
||
## 10. 阶段 6：A/B 或备份恢复方案
|
||
|
||
### 优先方案：标准 A/B
|
||
|
||
```text
|
||
app_a
|
||
app_b
|
||
boot metadata
|
||
持久化升级状态
|
||
启动健康确认
|
||
自动回滚
|
||
```
|
||
|
||
A/B 实施前必须确认：
|
||
|
||
- Flash 是否能够容纳两个完整 App；
|
||
- Bootloader 是否支持分区选择和回滚；
|
||
- 分区表如何迁移；
|
||
- 现有设备是否能够在线完成分区变更；
|
||
- 工厂烧录包和售后工具是否同步支持新布局。
|
||
|
||
### 空间不足时的次优方案
|
||
|
||
```text
|
||
单 App 分区
|
||
+ 下载暂存区
|
||
+ 旧 App 备份区
|
||
+ 持久化失败计数
|
||
+ 启动健康确认
|
||
+ 明确恢复模式
|
||
```
|
||
|
||
如果现有设备必须修改分区表才能实现上述方案，不应默认可以通过当前 App OTA 安全完成。部分设备可能需要工厂重新烧录。
|
||
|
||
---
|
||
|
||
## 11. 灰度发布建议
|
||
|
||
每个阶段建议按以下顺序发布：
|
||
|
||
1. 开发板和可串口救援设备；
|
||
2. 内部测试设备；
|
||
3. 少量真实网络环境设备；
|
||
4. 1% 灰度；
|
||
5. 5% 灰度；
|
||
6. 20% 灰度；
|
||
7. 全量发布。
|
||
|
||
每一批次至少观察：
|
||
|
||
- 命令接收率；
|
||
- 开始升级率；
|
||
- 下载成功率；
|
||
- 平均重试次数；
|
||
- 最终版本到达率；
|
||
- 异常重启率；
|
||
- 设备重新上线时间；
|
||
- 音频和文件系统异常率。
|
||
|
||
出现以下任一情况应暂停后续批次：
|
||
|
||
- 设备持续重启；
|
||
- 升级后无法上线；
|
||
- 失败率超过预设阈值；
|
||
- 出现无法自动恢复的设备；
|
||
- 固件文件、下载服务或 MQTT 服务异常；
|
||
- 发现型号、版本或升级包对应错误。
|
||
|
||
## 12. 最终结论
|
||
|
||
当前最合适的路线不是立即实现 A/B，而是先发布 OTA-ready 工厂基线和最小 FULLOTA2，修复 OTA 入口、命令校验、预检查、状态持久化和结果补报。音频删除已从 OTA 前移到新 APP 版本确认成功且网络就绪之后，并由现有缺失文件下载器补回；后续再升级为带版本、SHA-256 和原子替换的独立资源清单。然后在实验设备上验证系统级 OTA，通过系统 OTA 修复 Mini FOTA 的恢复和安全校验问题；最后根据未来 Flash 空间决定是否采用标准 A/B。
|