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