AOSP 14 OTA 升级指导(二):OTA 包的构成与生成

96 阅读17分钟

系列第 2 / 6 篇 · 承接第 1 篇《总览:A/B 无缝升级架构与核心组件》

0. 本篇要解决什么问题

第 1 篇讲清了"升级时 update_engine 把 payload 写进非活跃槽"。但真正上手时,第一个卡点通常是:

  • 打出来的 xxx-ota-eng.root.zip 里到底有什么?哪个文件才是"升级数据"?
  • payload.bin 里那 1.4GB 是什么结构,怎么在不刷机的情况下确认它写的是对的?
  • payload_properties.txt 那几百个字节的四个头是干什么的,为什么调用 applyPayload 必须原样传?
  • metadata 里的 pre-device / post-build 是谁生成的,为什么设备会报"升级包与设备机型不匹配"?
  • 签名到底签了几层?META-INF/com/android/otacert 和 jar 签名是一回事吗?

本篇按"解剖一个真包 → 看懂每个字段 → 追到生成代码 → 自己动手验证"的顺序走完。 读完你应该能仅凭一个 OTA zip 判断:它是全量还是增量、能装到哪台设备上、装完会写哪些分区、以及它有没有被篡改。


1. 解剖一个真实的 A/B 升级包

先看本项目一个 A/B 产品(Android 14,下文称 base)用 m otapackage 打出来的包:

unzip -l out/target/product/base/base-ota-eng.root.zip
条目典型大小压缩方式作用
payload.bin~1.43 GBSTORED真正的升级数据:头部 + manifest + 各分区操作与数据块
payload_properties.txt~155 BSTORED4 个校验头(FILE_HASH/FILE_SIZE/METADATA_HASH/METADATA_SIZE)
care_map.pb(或 care_map.txt)几 KBSTOREDdm-verity 覆盖的块范围,重启后 update_verifier 按它读回校验
apex_info.pb几 KBSTOREDAPEX 信息(增量包用于判断 APEX 版本兼容)
metadata几百 BSTORED纯文本 key=value,升级前置条件(pre-device、post-build…)
metadata.pb几百 BSTORED同一个 metadata 的 protobuf 形式(新客户端读这个)
META-INF/com/android/metadata同 metadataDEFLATED老位置,很多设备侧校验器仍从这读(注意是两份)
META-INF/com/android/otacert~1 KBDEFLATED签名证书(PEM),update_engine 用它验 payload 签名
META-INF/MANIFEST.MF、*.SF、*.RSA若干DEFLATED整个 zip 的 jar 签名(保护 zip 条目未被改动)

两个容易踩的点:

  1. metadata 在包里有两份:根目录的 metadata / metadata.pb,和 META-INF/com/android/metadata。 排障时 unzip -p xxx.zip META-INF/com/android/metadata | grep pre-device 是老习惯写法, 但新版本真正被 update_engine 读取的是根目录那份(FinalizeMetadata 写的)。
  2. 同名产物会互相覆盖:两个不同产品的平台烧写包都叫 upgrade_package.img, 放同一目录会静默覆盖(本项目真踩过一次,排查了半天才定位到"装的不是我以为的那个包")。

顺带区分:upgrade_package.img 是 全量烧写包(USB/SD 工具用), 不是 OTA 包。m otapackage 只产出 OTA zip,不会重新生成它。


2. 为什么 payload 相关条目必须 ZIP_STORED

因为它们要被按偏移直取。OTA 服务器把 ota-streaming-property-files 一起下发给客户端, 形如(ota_utils.py:73 的示例):

payload.bin:679:343,payload_properties.txt:378:45,metadata:69:379

含义是"条目名:zip 内偏移:长度"。客户端可以只发 HTTP Range 取 payload_properties.txt(155 字节), 不必下 1.4GB 整包就能判断"这包能不能装、要不要下"。压缩过的条目偏移不可预测,所以这几个条目必须 STORED—— ota_utils.py:940-947 的注释写得很直白:

    # Add the signed payload file and properties into the zip. In order to
    # support streaming, we pack them as ZIP_STORED. So these entries can be
    # read directly with the offset and length pairs.
    common.ZipWrite(output_zip, self.payload_file, arcname=payload_arcname,
                    compress_type=zipfile.ZIP_STORED)

3. payload.bin 的头部:24 字节定长 + 大端

payload.bin 不是"一个压缩镜像",而是有严格格式的容器。前 24 字节固定(payload_metadata.cc:34-39):

const uint64_t PayloadMetadata::kDeltaVersionOffset = sizeof(kDeltaMagic);
const uint64_t PayloadMetadata::kDeltaVersionSize = 8;
const uint64_t PayloadMetadata::kDeltaManifestSizeOffset =
    kDeltaVersionOffset + kDeltaVersionSize;
const uint64_t PayloadMetadata::kDeltaManifestSizeSize = 8;
const uint64_t PayloadMetadata::kDeltaMetadataSignatureSizeSize = 4;

拼起来就是:

偏移  0        4              12             20        24
      ┌────────┬──────────────┬──────────────┬─────────┬──────────────────────┐
      │ "CrAU" │ version (8B) │manifest_size │sig_size │  DeltaArchiveManifest │
      │ 4 字节 │  大端 u64    │  (8B,u64)    │(4B,u32) │   (protobuf, 变长)     │
      └────────┴──────────────┴──────────────┴─────────┴──────────────────────┘
                                                        ↓ 之后依次是
                         metadata 签名  →  各操作的 blob 数据  →  payload 签名

三个关键事实:

  1. magic 必须是 CrAU(payload_constants.cc:47:const char kDeltaMagic[4] = {'C','r','A','U'};)。 校验失败的错误码是 kDownloadInvalidMetadataMagicString(payload_metadata.cc:63-77)。 现场看到 "Bad payload format -- invalid delta magic" 就说明这个文件根本不是 payload (常见于把 A9 的 recovery 整包当成 payload 塞进来)。
  2. 所有头字段都是大端(be64toh / be32toh,payload_metadata.cc:108、:126)。自己写解析脚本时最容易错在这里。
  3. major version 只支持 2(payload_constants.cc:24:kBrilloMajorPayloadVersion = 2)。 于是每个分区自带名字(partition_name),不再依赖固定的 "kernel/rootfs" 约定—— 这是多分区动态设备(system/vendor/product/odm…)能统一走一条代码路径的前提。

4. manifest:这一包的"施工图纸"

紧跟在 24 字节头后面的 protobuf 就是 DeltaArchiveManifest(update_metadata.proto:388-437)。 它决定了 update_engine 要写哪些分区、每个分区怎么写、以及这包能不能装。

字段行号含义排障用途
block_size395固定 4096日志里所有 extent 都以块为单位
minor_version4100 = 全量包,非 0 = 增量包判断包类型的第一依据
partitions[]418要更新的分区列表及其操作"这包会动哪些分区"直接看这里
max_timestamp422允许被覆盖的源的最大时间戳防降级;也是"时间戳校验失败"的来源
dynamic_partition_metadata425动态分区/snapshot 配置VABC 相关故障看这里
partial_update428是否只更新部分分区(如只更 kernel)局部 OTA
apex_info[]432APEX 解压所需空间"空间不足导致 APEX 安装失败"
security_patch_level436安全补丁级别降级策略(spl-downgrade)

每个分区是一个 PartitionUpdate(update_metadata.proto:242-291):

字段行号说明
partition_name245system / vendor / boot …(不带槽位后缀,写入时引擎自己拼 _a/_b)
run_postinstall / postinstall_path / filesystem_type250-262该分区要不要挂起来跑 postinstall
old_partition_info270只要存在,就说明这是增量包(下面 §5 详述)
new_partition_info271目标分区的大小与 hash(可用于核对镜像)
operations[]276真正的写操作列表
hash_tree_data_extent / fec_data_extent285+dm-verity 哈希树与 FEC 的位置

4.1 操作类型:决定"这包是不是自包含"

InstallOperation.Type(update_metadata.proto:150-176)是排障时最值钱的字段:

类型值依赖源分区?说明
REPLACE0否附带数据直接覆盖目标块
REPLACE_BZ / REPLACE_XZ1 / 8否压缩后覆盖(xz 需 minor ≥3)
ZERO / DISCARD6 / 7否写零 / 丢弃(minor ≥4)
SOURCE_COPY4是从源分区搬块(minor ≥2)
SOURCE_BSDIFF5是源块 + 差分补丁(minor ≥2)
BROTLI_BSDIFF10是brotli 压缩的差分(minor ≥4)
PUFFDIFF9是针对 deflate 数据流的差分(minor ≥5)
ZUCCHINI11是可执行文件级差分(minor ≥8)
LZ4DIFF_BSDIFF / LZ4DIFF_PUFFDIFF12 / 13是EROFS + lz4 的差分(minor ≥9,A14 新建)
MOVE / BSDIFF2 / 3—已废弃

判据一句话:

ops 里只要出现任何 SOURCE_* / BSDIFF / PUFFDIFF / ZUCCHINI / LZ4DIFF_*, 这个包就依赖设备当前的源分区内容;全是 REPLACE*/ZERO,就是自包含全量包。

本项目 base 产品的实测结论(runbook):17 个分区、操作类型只有 REPLACE*,无任何 SOURCE_*/MOVE/BSDIFF ⇒ 虽然是"从源码树一路编出来的包",但它不依赖设备当前版本,可以给任意版本的 base 设备装。 这正是产线/维修场景最想要的属性,也是"为什么我的差分包装在老设备上失败"的反面教材。


5. 全量 vs 增量:is_delta 到底怎么判

很多人以为"包里有 SOURCE_* 就是增量包"。严格说,AOSP 的官方判据是有没有源分区信息:

// system/update_engine/payload_generator/payload_properties.cc:116-119
  is_delta_ = std::any_of(manifest.partitions().begin(),
                          manifest.partitions().end(),
                          [](const PartitionUpdate& part) {
                            return part.has_old_partition_info();

因为生成器可能在"增量包"里对某个分区判定"变化太大,不如整块 REPLACE",于是那个分区没有 SOURCE_*, 但包仍然是增量的(它带 old_partition_info、有 pre-build 前置条件、装错版本会失败)。

维度全量包(full)增量包(delta)
minor_version0非 0(A14 常见 6-9)
old_partition_info无有
metadata 里的 pre-build*无有(限定源版本)
体积1.4 GB 级十几 MB ~ 几百 MB
能否跨版本装能不能,必须精确匹配源版本
生成命令ota_from_target_files target.zip out.zipota_from_target_files -i old_target.zip target.zip out.zip

5.1 VABC(Virtual A/B Compression)为什么会让"全量包"也写 snapshot

A14 设备普遍是 virtual A/B:没有真正的第二份物理分区,升级时用 snapshot(COW) 把改动记下来, 重启后由 snapuserd 在 dm 层合并。所以即使是全量 payload,写入的也是 COW 设备而不是裸分区。

生成侧对应 GenerateAbOtaPackage 里的这几段(ota_from_target_files.py:898-925):

  • 源/目标任一不支持 VABC → OPTIONS.disable_vabc = True(否则新系统起不来时没有 snapuserd 服务);
  • 源与目标的 vabc_compression_param 不一致 → 取源的参数(保证旧系统能读懂);
  • vendor_api_level < 33 → 关掉 VABC XOR;
  • vendor_suppressed_vabc → 直接关。

排障提示:--disable_vabc=true 打出的包在 virtual A/B 设备上会退化成"直接写非活跃分区"(retrofit 场景才这么干), 一般不要动。


6. payload_properties.txt:四个头就是"入场券"

内容长这样(实测约 155 字节):

FILE_HASH=<Base64(sha256(整个 payload))>
FILE_SIZE=1437799148
METADATA_HASH=<Base64(sha256(payload 前 metadata_size 字节))>
METADATA_SIZE=xxxxx

生成代码只有几行(payload_properties.cc:73-78):

  properties.SetString(kPayloadPropertyFileSize, std::to_string(payload_size_));
  properties.SetString(kPayloadPropertyMetadataSize,
                       std::to_string(metadata_size_));
  properties.SetString(kPayloadPropertyFileHash, payload_hash_);
  properties.SetString(kPayloadPropertyMetadataHash, metadata_hash_);

几个必须搞准的细节:

问题答案依据
hash 是 hex 还是 base64?Base64(不是 hex!自己算时最容易错)payload_properties.cc:98、:104 的 Base64Encode
METADATA_SIZE 含签名吗?不含。= 24 + manifest_size(即头 + manifest)payload_metadata.cc:110:metadata_size_ = manifest_offset + manifest_size_;
METADATA_HASH 覆盖哪些字节?payload[0 : METADATA_SIZE],即"头 + manifest"payload_properties.cc:96-97 用 RawHashOfFile(payload_path_, metadata_size_, ...)
谁消费这四个头?调用方必须原样传给 applyPayload(url, offset, size, headers);引擎用它们决定"值不值得下""下完是否完整"common/constants.h:160-163

common/constants.h:160-163 定义了这四个名字:

static constexpr const auto& kPayloadPropertyFileSize = "FILE_SIZE";
static constexpr const auto& kPayloadPropertyFileHash = "FILE_HASH";
static constexpr const auto& kPayloadPropertyMetadataSize = "METADATA_SIZE";
static constexpr const auto& kPayloadPropertyMetadataHash = "METADATA_HASH";

6.1 除了这四个,还有"行为开关"型的头

同一个 headers 数组里还可以带控制头(由调用方或打包器写入):

头作用谁写
SWITCH_SLOT_ON_REBOOT默认 1;置 0 表示"写完不切槽",由调用方择机切(车机/待机场景)调用方;secondary payload 由 ota_utils.py:925 自动写成 0
POWERWASH1 表示升级后清用户数据ota_utils.py:929(--wipe_user_data 时)
RUN_POST_INSTALL是否跑 postinstall调用方
DISABLE_VABC非生产版本可关闭 VABC调试
AUTHORIZATION下载 payload 时带的 HTTP 头调用方(constants.h:165)

这也解释了为什么"不能自己拼 headers":少一个 METADATA_HASH,引擎要么拒绝,要么重复下载。


7. metadata:这台设备能不能装这一包

metadata 是纯文本 key=value,由 BuildLegacyOtaMetadata 生成(ota_utils.py:325-356), WriteMetadata 同时写文本与 pb 两份(ota_utils.py:169-192)。

真实样例(A/B,Android 14):

ota-type=AB
post-build=Brand/device_x/device_x:14/UP1A.231005.007/1.0.1:user/test-keys
post-build-incremental=1.0.1
post-sdk-level=34
post-security-patch-level=2024-05-05
post-timestamp=1726829000
pre-device=device_x
ota-required-cache=0
ota-streaming-property-files=payload_metadata.bin:xxx:yyy,payload.bin:...:...

本节及后文的产品名、设备名、厂商名一律替换为中性占位符(base = 被测产品、Test1 = 设备、 Test2 = 另一产品型号、device_x = 示例产品),不影响任何结论。

对照样例(A9 传统 Recovery,ota-type=BLOCK):

ota-type=BLOCK
post-build=Test1/Test1/Test1:9/PPR1.180610.011/1.0.1:userdebug/test-keys
post-sdk-level=28
pre-security-patch-level=2018-08-05
pre-device=Test2
键语义谁读
ota-typeAB / BLOCK / BRICK升级 Apk、Recovery、服务端
pre-device允许安装此包的设备(| 分隔多值)设备侧校验器 / Recovery
post-build目标版本指纹(tool/brand/device:rel/…)升级后版本确认
pre-build / pre-build-incremental仅增量包有:限定源版本引擎 + 校验器
post-timestamp目标构建时间戳防降级(与 max_timestamp 配合)
ota-required-cache需要预留的 cache 空间老设备安装前检查
ota-streaming-property-files / ota-streaming-metadata流式下载用的偏移表OTA 服务器

7.1 一个真实事故:pre-device 与设备的"四选一"匹配

某台 Android 9 设备(下文称 Test1)上曾报:

W/OtaChecker: device mismatch: expected Test2, device=Test1
E/UpgradeActivity: OTA package validation failed:
        升级包与设备机型不匹配 (该包适用于 pre-device=Test2)

根因链(现场分析记录里的完整版更细,此处只保留与"包"相关的部分):

Test2.mk:49   PRODUCT_DEVICE := Test2
        ↓
SYSTEM/build.prop  ro.product.device=Test2   ← 打包时只读 system/build.prop
        ↓
ota 包 metadata     pre-device=Test2

而设备上 ro.product.device 被 /vendor/test/build.prop 覆盖成了 Test1, 看起来必然失败——但实测是能装的,因为设备侧校验是"四选一":

String[] keys = {"ro.product.device", "ro.build.product",
                 "ro.product.board",  "ro.product.name"};

设备上 ro.build.product=Test2(未被覆盖)兜住了。当天"先失败后通过"的真正原因是 上午烧的是更旧的 img,四个属性里没有一个是 Test2。

要记住的两条经验:

  1. pre-device 只来自构建时的 SYSTEM/build.prop 的 ro.product.device(由 PRODUCT_DEVICE 派生), 不读 vendor/*/build.prop;设备实际属性是 init 按顺序加载后"最后者胜"的结果——两边天然可能不一致。
  2. ro.build.product 必须与 PRODUCT_DEVICE 保持同源,千万不要在 vendor/test/build.prop 里覆盖它, 否则四个属性会同时脱离包的 pre-device,校验会突然全线失败。

8. 签名:三层,但只有一层是"信任根"

层产物覆盖范围校验者作用
zip jar 签名META-INF/MANIFEST.MF / .SF / .RSA每个 zip 条目apksigner/jarsigner 语义的工具、部分校验器防 zip 条目被改(包完整性)
payload 签名payload.bin 末尾的 signature blob;metadata 签名紧跟 manifest整个 payload / 仅 metadataupdate_engine(PayloadVerifier::VerifySignature,payload_verifier.cc:96)真正的信任根:决定这包能不能被应用
证书META-INF/com/android/otacert—update_engine 用它验上面那层公钥分发

otacert 是 signapk 顺手写进 zip 的(SignApk.java:126、:328):

    private static final String OTACERT_NAME = "META-INF/com/android/otacert";

实践含义:

  • 换签名密钥重打包时,otacert 必须跟着换;只在设备上换 otacert 而 payload 签名不匹配 → 引擎直接拒绝;
  • payload_properties.txt 本身没有签名,它被 metadata/otacert 间接保护(hash 对不上就重新下载);
  • 想验证"这个 zip 没被人动过但要确认 payload 合法",权威做法是让引擎验: update_engine_client --payload=file:///data/ota/update.zip --offset=… --size=… --headers=…。

9. 生成链路:从 m otapackage 到可下发的 zip

m otapackage
  └─ build 系统产出 target-files zip(含 IMAGES/、META/、SYSTEM/ 等)
       └─ ota_from_target_files.py
            └─ GenerateAbOtaPackage()                       ota_from_target_files.py:866
                 ├─ 读 META/ab_partitions.txt(决定更新哪些分区)
                 ├─ GetPackageMetadata(target, source)       → metadata(pre/post 条件)
                 ├─ PayloadGenerator(...)                    ota_utils.py:776
                 │    └─ Generate()  → 调 delta_generator    参数见下表
                 │    └─ Sign()      → brillo_update_payload hash + sign
                 │    └─ WriteToZip()→ payload.bin / payload_properties.txt(ZIP_STORED)
                 ├─ care_map.pb / care_map.txt(avb_enable=true 时)
                 ├─ apex_info.pb
                 └─ FinalizeMetadata()                       ota_utils.py:66
                      ├─ 写 metadata + metadata.pb(先带占位 property-files)
                      ├─ 第一轮 signapk 签名(会重排/对齐 zip 条目)
                      ├─ 回填 ota-streaming-property-files(真实偏移)
                      └─ 第二轮签名 → 最终 zip(含 otacert)

为什么 metadata 要签两轮:ota-streaming-property-files 记录的是 zip 条目的字节偏移, 而 signapk 会重排/对齐条目、改变偏移。所以只能"先占位 → 签一次 → 按真实布局算偏移 → 回填 → 再签一次"。 ota_utils.py:100-130 的 ComputeAllPropertyFiles / FinalizeAllPropertyFiles 就是这两轮。

9.1 delta_generator 的关键参数(排障时按需加)

参数含义什么时候用
--old_partitions / --new_partitions旧/新镜像目录手工打增量包
--max_timestamp允许被覆盖源的最大时间戳时间戳校验失败时核对
--minor_version强制 minor 版本兼容老引擎做实验
--is_partial_update只更部分分区局部 OTA
--disable_vabc / --enable_vabc_xor关闭 VABC / 开 XOR起不来时排查 snapshot
--enable_zucchini / --enable_lz4diff开关高压缩差分算法体积 vs 兼容性
--security_patch_level写入 manifestSPL 降级策略
--properties_file(配合 --in_file)只导出四个校验头,不生成 payload事后复核一个已有 payload(见 §10)

全量包与增量包的差别在 python 层只有一处:GenerateAbOtaPackage(target_file, output_file, source_file=None)—— source_file 为 None 走全量,非 None 时还会额外校验源/目标的 ab_partitions、VABC 参数兼容性, 并写入 pre-build / pre-build-incremental 等前置条件。


10. 动手:不接设备也能验一个包(A 类实验)

A 类 = 在源码树/PC 上就能做,不需要设备。

10.1 三分钟体检

Z=out/target/product/base/base-ota-eng.root.zip

# ① 结构 + 压缩方式(payload 必须是 STORED,即 stored)
unzip -lv $Z | head -20

# ② 前置条件(能不能装我这台)
unzip -p $Z META-INF/com/android/metadata | grep -E "ota-type|pre-device|pre-build|post-build|post-sdk-level"

# ③ 四个校验头
unzip -p $Z payload_properties.txt

# ④ payload 头 24 字节:magic 必须是 CrAU
unzip -p $Z payload.bin | head -c 24 | xxd

10.2 用脚本把 manifest 打出来(附可直接运行的代码)

tools/payload_inspect.py(与本文同目录)做三件事:读 zip 结构、重算四个校验头与包内值比对、 解析 manifest 打印每个分区的操作类型统计。核心逻辑(头部与校验部分已在合成包上验证通过):

import base64, hashlib, struct, zipfile

with zipfile.ZipFile("base-ota-eng.root.zip") as z:
    payload = z.read("payload.bin")
    props = z.read("payload_properties.txt").decode()

assert payload[:4] == b"CrAU", "bad magic"
version, manifest_size, sig_size = struct.unpack(">QQI", payload[4:24])
metadata_size = 24 + manifest_size          # 不含 metadata 签名

file_hash = base64.b64encode(hashlib.sha256(payload).digest()).decode()
meta_hash = base64.b64encode(
    hashlib.sha256(payload[:metadata_size]).digest()).decode()

print("version=%d manifest=%d metadata=%d payload=%d"
      % (version, manifest_size, metadata_size, len(payload)))
print("FILE_HASH 一致      :", ("FILE_HASH=" + file_hash) in props)
print("METADATA_HASH 一致  :", ("METADATA_HASH=" + meta_hash) in props)

要打印分区与操作类型,需要 protobuf 绑定(AOSP 树里就有 proto):

protoc --python_out=. system/update_engine/update_metadata.proto   # 生成 update_metadata_pb2.py
PROTOCOL_BUFFERS_PYTHON_IMPLEMENTATION=python python3 payload_inspect.py $Z

输出形如(数值为示意,实际以你的包为准):

== payload header ==
  magic            : CrAU
  major version    : 2
  manifest_size    : 63421
  metadata_sig_size: 264
  metadata_size    : 63445  (= 24 + manifest_size)
  payload_size     : 1431394587
== 本地重算的校验头 ==
  FILE_HASH      = 6GmX...=     ← 与包内一致即说明 payload 未被改动
== manifest ==
  block_size=4096 minor_version=0 max_timestamp=1726829000 partial=False
  partition        new_size    ops is_delta  op_types
  boot              8388608     21    False   {'REPLACE': 21}
  system         2899102924   1793    False   {'REPLACE': 1793}
  ...
  结论: 全量自包含包(无 SOURCE_*)

10.3 用 AOSP 自带工具复核(不需要设备)

# 只导出四个头,对比包内 payload_properties.txt
$OUT/host/linux-x86/bin/delta_generator --in_file=payload.bin \
    --properties_file=/tmp/p.txt && cat /tmp/p.txt

# 手工解析 manifest(可选)
$OUT/host/linux-x86/bin/delta_generator --in_file=payload.bin --out_file=/dev/null \
    --old_partitions=… --new_partitions=…   # 或直接用 payload_dumper 之类工具

本项目 runbook 里的 payload_verify.py 就是这条路线的加长版:解出 17 个分区, 逐分区比对 size 与 sha256 与本机镜像是否一致,从而证明"包里的 system 就是刚编出来的 system"。


11. 包级故障对照表(先查包,再查设备)

现象/日志大概率原因查什么
Bad payload format -- invalid delta magic塞进去的不是 payload(如 A9 recovery 包 / 加密包)xxd 前 4 字节是否 CrAU
Payload hash mismatch / 一直重新下载FILE_HASH 不匹配(传输截断、代理改写、二次压缩)重算 FILE_HASH 与 props 比对
Metadata mismatchMETADATA_SIZE/HASH 与 payload 实际不符是否只替换了 payload.bin 而没更新 props
升级包与设备机型不匹配(pre-device=…)pre-device 与设备 4 属性全不命中getprop ro.product.device/ro.build.product/board/name
Package is for product X but expected Y(Recovery)同上(BLOCK 包)metadata pre-device
Not enough space / ota-required-cache预留空间不足(/data 或 /cache)ota-required-cache、df
Update timestamp … older than … / 降级失败max_timestamp / post-timestamp 与源版本关系不对manifest max_timestamp、ro.build.date.utc
装了包但版本没变装的是"另一个产品"的包(同名 upgrade_package.img 覆盖)包 md5 与预期是否一致
首启失败并回滚payload 内容与设备不匹配 / VABC 参数不兼容 / 空间不足第 5 篇:cutover、snapshot、rollback-happened

12. 本篇小结

  1. A/B OTA zip = 控制面(metadata / payload_properties)+ 数据面(payload.bin)+ 信任面(otacert / 签名), payload.bin 必须是 ZIP_STORED,因为要按偏移直取(流式升级)。
  2. payload 头 24 字节定长、大端:CrAU + version(2) + manifest_size + metadata_sig_size; METADATA_SIZE = 24 + manifest_size,不含 metadata 签名。
  3. manifest 是施工图纸:partitions[] 决定写哪些分区与怎么写; 只要 ops 里出现 SOURCE_*,包就依赖设备当前版本;只有 REPLACE* 则是自包含全量包。
  4. is_delta 的官方判据是 old_partition_info 是否存在,不是"有没有 SOURCE_*"——两者可能不一致。
  5. 四个校验头是入场券:Base64 的 hash,调用方必须原样传给 applyPayload; 另有 SWITCH_SLOT_ON_REBOOT / POWERWASH 这类行为开关头。
  6. pre-device 只来自构建时的 SYSTEM/build.prop,设备侧是"四属性任一命中", 两边天然可能不一致——ro.build.product 必须与 PRODUCT_DEVICE 同源。
  7. 信任根是 payload 签名 + otacert,jar 签名只保证 zip 条目未被改动; metadata 要签两轮,是因为流式偏移必须在最终 zip 布局确定后才能回填。

下一篇预告

第 3 篇《三条升级链路:Java API / 自研 HAL / TR069》会把"包怎么变成设备上的一次 apply"讲透: android.os.UpdateEngine.applyPayload 的完整 Binder 链路、file:// 与 http(s):// 两种取包方式的差异 (谁下载、要不要落整包、Range 分段)、自研升级 HAL(vendor 侧 AIDL 服务) 的 applyPayloadFd 路径, 以及自研运维守护进程的 TR069 状态机(下载 → MD5 → 应用 → 待重启 → 重启后判定); 附三条链路的选型对照表和 SELinux 权限缺口这类"接线"问题。