---

📺 B站：博主个人介绍

📘 博主书籍-京东购买链接*：Yocto项目实战教程

📘 加博主微信，进技术交流群： jerrydev

---

Jetson 镜像级 OTA（Image-based OTA）产品化理解与实战：从 Payload 结构到 A/B 回滚

关键词：payload / recovery kernel / initramfs / flash.idx / system.img / A-B / rollback / nvbootctrl / 产品化 OTA client & server

适用读者：

• 已经能跑通或正在跑通 NVIDIA 官方 image-based OTA demo
• 想把“脚本跑通”升级为“能设计、能排障、能落地产品 OTA”

本文目标：

1. 讲清 镜像级 OTA 在产品体系中的位置；
2. 用你真实解包看到的目录，解释 payload 到底包含什么、为什么这样设计；
3. 解释 recovery kernel 的本质（≈ initramfs 最小系统）以及它与 flash.sh 的差异；
4. 系统讲清 A/B 分区对镜像 OTA 的必要性与落地要点；
5. 给出 回滚策略落点、以及从官方机制走向产品 OTA 的工程路线。

---

1. 先把结论摆出来：镜像级 OTA 本质是“把刷机能力搬到设备端”

Jetson 的 image-based OTA 不是 apt 更新，也不是“装几个 deb”。它的工程意义是：

在不连接 Host PC 的情况下，让设备自己启动到一个受控的最小系统（recovery kernel + initramfs），用分区镜像完成 BSP 级升级，并具备日志、重试与回滚设计的基础能力。

为什么这很重要？因为真正产品里，你迟早会遇到：

• 内核/驱动/DTB/boot 组件与 rootfs 必须匹配（“一锅端一致性”）；
• 用户现场没有 USB/没有刷机条件；
• 你需要灰度、监控、失败可恢复（不能靠“让用户重刷”）。

镜像级 OTA 就是解决这些问题的底座。

---

2. OTA 体系全景：官方提供的是“更新引擎 + payload 格式”，不是完整系统

很多工程师第一次读官方文档会觉得“缺东西”：

• 只给了脚本和流程，没有 server、没有客户端、没有安全方案。

这是正确的边界划分。你可以把它理解成：

• NVIDIA 提供：更新引擎（脚本链）+ payload 格式 + recovery 执行环境
• 产品必须补齐：OTA client（设备侧守护进程）+ OTA server（分发与策略）+ 安全机制（签名/鉴权/反回滚）+ 可观测性（日志与上报）

2.1 产品级 OTA 框架图（你应该把它记下来）

┌──────────────────────────────────────────────────────────────┐
│                         OTA Server/CDN                       │
│  - artifacts：ota_payload_package.tar.gz / ota_tools_*.tbz2    │
│  - manifest：版本/机型/兼容性/哈希/签名/灰度策略               │
│  - 灰度：分批/区域/设备组                                     │
└───────────────▲───────────────────────────────▲──────────────┘
                │                               │
                │ HTTPS/mTLS/Token              │ 状态/日志上报
                │                               │
┌───────────────┴───────────────────────────────┴──────────────┐
│                        Device OTA Client                       │
│  - poll/push：检查更新                                          │
│  - download：工具包 + payload                                   │
│  - verify：hash/signature/decrypt                               │
│  - stage：准备 /ota 与 WORKDIR                                  │
│  - trigger：nv_ota_start.sh                                     │
│  - report：成功/失败原因/日志采样                              │
└───────────────┬──────────────────────────────────────────────┘
                │ reboot（切换到 recovery kernel）
┌───────────────▼──────────────────────────────────────────────┐
│                      Recovery Kernel / Initramfs               │
│  - /init（PID1）→ nv_recovery.sh                               │
│  - nv_ota_run_tasks.sh → nv_ota_update.sh                       │
│  - 写分区/切换/验证/失败处理                                   │
│  - /ota_logs（失败日志）                                       │
└──────────────────────────────────────────────────────────────┘

你跑通官方 demo 其实只覆盖了“中间两层”的核心路径：

• Host 端生成 payload（l4t_generate_ota_package.sh）
• Target 端触发并进入 recovery 更新

产品化要做的，是把上层“下载/校验/策略/上报”加起来。

---

3. recovery kernel 模式到底是什么？它和按键 Recovery 是一回事吗？

**不是一回事。**你必须把两种 recovery 分清，否则会一直混乱。

3.1 两种 recovery 的定义

1. RCM/Force Recovery（按键进入）

• 作用：进入 BootROM 的恢复通道
• 用途：给 Host 侧 flash.sh 刷机用（USB 连接 PC）
• 本质：更接近“下载模式/救砖通道”，不是 Linux 系统

2. OTA 的 recovery kernel（自动进入）

• 作用：启动到“最小 Linux 系统”执行 OTA 更新
• 用途：设备自更新，不需要 Host PC
• 本质：一套专用的 kernel + initramfs（ramdisk）+ recovery DTB

3.2 recovery kernel ≈ initramfs 最小系统（你已经用事实验证了）

你解开 recovery.img 后看到的 init 文件，就是证据：

• recovery 环境启动后，PID 1 运行的是 initramfs 里的 /init

• 在某个分支下它会执行：

  • exec /bin/bash /bin/nv_recovery.sh

这句话非常重要：

OTA 的“刷写动作”不是 kernel 在做，而是在 initramfs 用户态脚本里完成的。

换句话说：recovery kernel 是“隔离执行环境”，真正写分区的是脚本链。

---

4. 镜像级 OTA 到底在更新什么？从你解包出来的 payload 看清楚

理解 payload 结构，是你从“能跑”走向“能排障/能产品化”的关键能力。

4.1 外层 payload：ota_payload_package.tar.gz（控制层 + 执行层 + 索引层）

你解开 ota_payload_package.tar.gz 后看到的典型文件（这类结构非常稳定）：

• ota_package.tar：内层镜像集合包（真正内容）
• ota_package.tar.sha1sum：内层包校验
• board_name / base_version / version.txt / user_release_version：版本与适配信息
• layout_change / update_control / ota_nv_boot_control.conf：策略与 boot 控制
• BOOTAA64.efi / TEGRA_BL.Cap / nv-l4t-bootloader-config.sh：UEFI/bootloader 相关更新材料
• nv_ota_*.sh + *.func + nv_ota_customer.conf：执行脚本与可定制配置

这说明：payload 不只是“镜像文件”，还包含“如何更新”的逻辑。

4.2 内层镜像集合：ota_package.tar（真正要写入分区的材料）

你 tar tf ota_package.tar 看到的内容非常典型，几乎就是 Jetson image-based OTA 的核心：

• internal_device/system.img + system.img.sha1sum

  • rootfs（APP 分区）镜像，一般最大

• internal_device/images-R36-ToT/<board-spec>/...

  • boot.img：boot 分区/启动相关镜像
  • kernel_tegra234-...dtb：正常系统 DTB
  • *.dtb.rec：recovery DTB
  • recovery.img：recovery kernel（kernel + initramfs）
  • flash.idx：写入索引（告诉脚本“写哪些分区、顺序、对应文件”）

• ota_backup_files_list.txt

  • 数据保留清单入口（可选）

你可以把它概括成四个“最关键部件”：

system.img（系统） + boot.img/DTB（启动） + recovery.img（执行环境） + flash.idx（写入说明书）

4.3 board spec（例如 3701–0005-）的价值：同一 payload 覆盖多硬件变体

你看到的目录结构里，不同 3701-xxxx 子目录其实是在做“硬件变体适配”。

这意味着：

• 同一份 OTA payload 可以覆盖多个模块料号/载板组合
• 设备端会根据当前 TNSPEC/兼容 spec 自动选对应子目录

这正是产品化的核心诉求之一：一套发版流程覆盖一个产品族，而不是每台机器一个包。

---

5. 镜像 OTA vs flash.sh vs 自己写 initrd：工程上应该怎么选？

5.1 快速对比表（建议收藏）

维度	镜像级 OTA（image-based）	flash.sh（RCM 刷机）	自己写 initrd 刷写
执行位置	设备端 recovery Linux	Host PC 通过 USB	设备端（你自研）
是否需要 PC	不需要	必须	不需要
典型场景	产品现场升级/批量升级	工厂/研发/救砖	强定制、完全自研
一致性	强（版本快照）	强（全量刷更干净）	取决于你实现
失败可恢复	有基础支持（日志、重试、可结合 A/B）	多靠重刷	取决于你实现
维护成本	中（基于官方机制扩展）	低（刷机即恢复）	高（你维护所有边界）
风险点	A/B、工具链完整性、策略落地	现场不可用、无法灰度	边界条件非常多

结论通常是：

• 产品升级：优先镜像级 OTA
• 工厂/救砖：flash.sh
• 自研 initrd：只有在你确实要“完全替换官方更新机制”时才做

---

6. A/B 分区为什么对镜像 OTA 很关键？

镜像 OTA 的目标之一是“升级失败不变砖”。

A/B 的意义就是：

• 有两套可启动系统（slot A/slot B）
• 更新时写“非当前运行 slot”
• 新系统第一次启动失败，自动切回旧 slot

你可以把 A/B 理解为“在线升级的保险丝”。

6.1 A/B 的四个实战要求（少一个都不完整）

1. 分区规划：哪些分区 A/B？（rootfs、boot、dtb、kernel 是否双份）
2. 写入策略：更新写 inactive slot
3. 切换策略：bootloader/UEFI 选择新 slot
4. 健康确认：新系统启动后必须写“boot success”标记，否则回滚

6.2 nvbootctrl 在镜像 OTA 里的角色（你遇到的错误就是典型案例）

在 Jetson 的脚本链里，判断 rootfs A/B 常常依赖：

• nvbootctrl -t rootfs is-rootfs-ab-enabled

你实操里出现：

• Failed to run "-t rootfs is-rootfs-ab-enabled"
• nvbootctrl NOT found

这说明一个非常现实的产品经验：

镜像 OTA 不仅需要 payload 与脚本，还需要系统工具链完整（nvbootctrl/相关包必须在基线系统里）。

因此，产品化时你要把“关键工具是否存在”放进 OTA client 的 Pre-check。

---

7. 回滚（Rollback）到底应该放在哪里实现？

回滚不是“一个按钮”，它是一套状态机与落点设计。

7.1 回滚发生的三个关键位置

1. 更新前（Pre-check）

• 版本路径检查（禁止降级/跳跃）
• 兼容性检查（board spec、chip、存储形态）
• 空间、电量、网络、维护窗口
• A/B 状态检查（nvbootctrl 能否工作）

2. 更新后首次启动（First boot health check）

• 新 slot 启动后，限定时间内完成关键服务启动与自检
• 成功：写入 boot-success 标记
• 失败：触发回滚

3. 失败处理（Rollback action）

• 自动切回旧 slot
• 报告失败原因并上传/保存日志

7.2 一个“最小可用”回滚策略模板（可以直接照着做）

IDLE
 -> CHECK_COMPAT
 -> DOWNLOAD
 -> VERIFY
 -> STAGE
 -> TRIGGER_UPDATE (nv_ota_start.sh)
 -> REBOOT_TO_RECOVERY
 -> APPLY_IN_RECOVERY
 -> REBOOT_TO_NEW_SLOT
 -> HEALTH_CHECK (60~180s)
      success -> MARK_BOOT_SUCCESS -> REPORT_OK
      fail    -> ROLLBACK_TO_OLD   -> REPORT_FAIL

注意：

• “写分区”在 recovery kernel
• “是否成功”由新系统证明
• “回滚”通过 slot 切换完成

---

8. 镜像 OTA 的学习价值：它逼你掌握真正产品 OTA 的关键能力

很多人把 OTA 看成“脚本集合”，但镜像 OTA 的真正价值是它会逼你系统性掌握：

1. 启动与分区结构：system.img、boot.img、DTB、ESP、UEFI capsule
2. 隔离执行环境：为什么必须在 recovery kernel 写分区
3. 机型与兼容性管理：board spec 自动选择
4. 可靠性机制：日志、重试、断电恢复
5. A/B 与回滚：把失败变成可恢复事件
6. 产品化边界：你必须实现 OTA client、server 与安全策略

这些能力一旦掌握，换平台（RK/Qualcomm）也能迁移。

---

9. 产品级 OTA：你必须补齐的模块清单（务实版）

9.1 OTA 客户端（device-side service）

• systemd 守护进程（自动运行）
• 状态机（断点续传、失败重试、失败上报）
• download：工具包 + payload
• verify：hash + signature（必要时 decrypt）
• stage：准备 /ota 与 WORKDIR
• trigger：调用 nv_ota_start.sh
• report：上报结果、日志采样、版本落库

9.2 OTA 服务端（server / artifacts / manifest）

建议至少具备：

• artifacts 存储：

  • ota_payload_package.tar.gz
  • ota_tools_<rel>_aarch64.tbz2

• manifest（JSON 是最常见）：

  • 适配机型：board spec / chip / storage
  • 版本 gate：允许升级路径（禁止降级）
  • 校验：sha256 + signature
  • 灰度：设备组/比例/地区

一个极简 manifest 示例（理解即可）：

{
  "product": "jetson-agx-orin",
  "from": "R36.4.3",
  "to": "R36.4.4",
  "board_specs": ["3701--0005-"],
  "payload": {
    "name": "ota_payload_package.tar.gz",
    "sha256": "<...>",
    "size": 2921975646
  },
  "tools": {
    "name": "ota_tools_R36.4.4_aarch64.tbz2",
    "sha256": "<...>"
  },
  "policy": {
    "rollout": "10%",
    "require_ac_power": true,
    "health_check_timeout_sec": 120
  }
}

9.3 安全机制（必须明确）

• 传输安全：HTTPS + 鉴权（mTLS/Token）
• 完整性校验：sha256（比 sha1 更常见）
• 可信性：签名验证（防篡改）
• 反回滚：版本 gate + rollback protection（只允许向前）

---

10. 故障案例：为什么 OTA 会卡在 A/B 检测（nvbootctrl 缺失）？

这是你实操里出现的真实问题，具有代表性：

• nv_ota_start.sh 前半段成功（解包、校验、选 spec）
• 卡在 is_rootfs_a_b_enabled
• 原因：nvbootctrl 不存在

这类问题的工程结论很明确：

1. 你的基线系统必须是“工具链完整的 Jetson Linux rootfs”
2. OTA client 在触发更新前必须做 Pre-check（关键工具、关键路径、关键分区）
3. 关键依赖（如 nvidia-l4t-tools）要纳入镜像基线验证与 CI

否则你会在升级时才暴雷。

---

11. 最佳实践：如何把官方 OTA 机制变成“可交付产品能力”

给你一条最稳的路线（按顺序做）：

1. 先跑通最小 demo（无加密、无 UEFI SB）

2. 固化证据链：

   • payload 的 hash/大小
   • 设备升级前后版本（nv_tegra_release）
   • /ota_logs 与 /ota_log 日志归档

3. 加入 OTA client 状态机（systemd）

4. 引入 manifest（版本 gate + sha256 + board spec）

5. 灰度与回滚策略落地（health check + slot rollback）

6. 最后再叠加安全启动/磁盘加密（UEFI SB / disk encryption）

核心原则：

先把“可靠性与可观测”做扎实，再加安全特性。

---

12. 关键问答（复习巩固）

Q1：为什么镜像级 OTA 要进入 recovery kernel？

• 因为更新要写分区，必须在隔离的最小环境执行，避免依赖正在被更新的 rootfs。

Q2：镜像 OTA 与 flash.sh 最大差异是什么？

• flash.sh 由 Host 强制写入；镜像 OTA 由设备端 recovery 自更新。

Q3：A/B 的价值是什么？

• 升级失败可回滚：更新写 inactive slot，失败自动回退。

Q4：回滚应该放在哪个阶段实现？

• Pre-check 做兼容与环境检查；首次启动做 health check；失败触发 slot 回退与上报。

Q5：仅靠官方脚本能做完整 OTA 吗？

• 不能。你必须实现 OTA client、server、安全策略与可观测机制。

---

13. 总结：把镜像 OTA 当成“系统工程”，你会真正掌握 OTA

镜像级 OTA 让你把“刷机”从线下带到线上，并迫使你掌握：

• payload 的结构与兼容性管理
• recovery kernel 的隔离执行
• A/B 与回滚策略
• 产品化的 client/server/security/observability

---

📺 B站：博主个人介绍

📘 博主书籍-京东购买链接*：Yocto项目实战教程

📘 加博主微信，进技术交流群： jerrydev

---