系列第 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 GB | STORED | 真正的升级数据:头部 + manifest + 各分区操作与数据块 |
payload_properties.txt | ~155 B | STORED | 4 个校验头(FILE_HASH/FILE_SIZE/METADATA_HASH/METADATA_SIZE) |
care_map.pb(或 care_map.txt) | 几 KB | STORED | dm-verity 覆盖的块范围,重启后 update_verifier 按它读回校验 |
apex_info.pb | 几 KB | STORED | APEX 信息(增量包用于判断 APEX 版本兼容) |
metadata | 几百 B | STORED | 纯文本 key=value,升级前置条件(pre-device、post-build…) |
metadata.pb | 几百 B | STORED | 同一个 metadata 的 protobuf 形式(新客户端读这个) |
META-INF/com/android/metadata | 同 metadata | DEFLATED | 老位置,很多设备侧校验器仍从这读(注意是两份) |
META-INF/com/android/otacert | ~1 KB | DEFLATED | 签名证书(PEM),update_engine 用它验 payload 签名 |
META-INF/MANIFEST.MF、*.SF、*.RSA | 若干 | DEFLATED | 整个 zip 的 jar 签名(保护 zip 条目未被改动) |
两个容易踩的点:
- metadata 在包里有两份:根目录的
metadata/metadata.pb,和META-INF/com/android/metadata。 排障时unzip -p xxx.zip META-INF/com/android/metadata | grep pre-device是老习惯写法, 但新版本真正被update_engine读取的是根目录那份(FinalizeMetadata写的)。 - 同名产物会互相覆盖:两个不同产品的平台烧写包都叫
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 签名
三个关键事实:
- 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 塞进来)。 - 所有头字段都是大端(
be64toh/be32toh,payload_metadata.cc:108、:126)。自己写解析脚本时最容易错在这里。 - 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_size | 395 | 固定 4096 | 日志里所有 extent 都以块为单位 |
minor_version | 410 | 0 = 全量包,非 0 = 增量包 | 判断包类型的第一依据 |
partitions[] | 418 | 要更新的分区列表及其操作 | "这包会动哪些分区"直接看这里 |
max_timestamp | 422 | 允许被覆盖的源的最大时间戳 | 防降级;也是"时间戳校验失败"的来源 |
dynamic_partition_metadata | 425 | 动态分区/snapshot 配置 | VABC 相关故障看这里 |
partial_update | 428 | 是否只更新部分分区(如只更 kernel) | 局部 OTA |
apex_info[] | 432 | APEX 解压所需空间 | "空间不足导致 APEX 安装失败" |
security_patch_level | 436 | 安全补丁级别 | 降级策略(spl-downgrade) |
每个分区是一个 PartitionUpdate(update_metadata.proto:242-291):
| 字段 | 行号 | 说明 |
|---|---|---|
partition_name | 245 | system / vendor / boot …(不带槽位后缀,写入时引擎自己拼 _a/_b) |
run_postinstall / postinstall_path / filesystem_type | 250-262 | 该分区要不要挂起来跑 postinstall |
old_partition_info | 270 | 只要存在,就说明这是增量包(下面 §5 详述) |
new_partition_info | 271 | 目标分区的大小与 hash(可用于核对镜像) |
operations[] | 276 | 真正的写操作列表 |
hash_tree_data_extent / fec_data_extent | 285+ | dm-verity 哈希树与 FEC 的位置 |
4.1 操作类型:决定"这包是不是自包含"
InstallOperation.Type(update_metadata.proto:150-176)是排障时最值钱的字段:
| 类型 | 值 | 依赖源分区? | 说明 |
|---|---|---|---|
REPLACE | 0 | 否 | 附带数据直接覆盖目标块 |
REPLACE_BZ / REPLACE_XZ | 1 / 8 | 否 | 压缩后覆盖(xz 需 minor ≥3) |
ZERO / DISCARD | 6 / 7 | 否 | 写零 / 丢弃(minor ≥4) |
SOURCE_COPY | 4 | 是 | 从源分区搬块(minor ≥2) |
SOURCE_BSDIFF | 5 | 是 | 源块 + 差分补丁(minor ≥2) |
BROTLI_BSDIFF | 10 | 是 | brotli 压缩的差分(minor ≥4) |
PUFFDIFF | 9 | 是 | 针对 deflate 数据流的差分(minor ≥5) |
ZUCCHINI | 11 | 是 | 可执行文件级差分(minor ≥8) |
LZ4DIFF_BSDIFF / LZ4DIFF_PUFFDIFF | 12 / 13 | 是 | EROFS + lz4 的差分(minor ≥9,A14 新建) |
MOVE / BSDIFF | 2 / 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_version | 0 | 非 0(A14 常见 6-9) |
old_partition_info | 无 | 有 |
metadata 里的 pre-build* | 无 | 有(限定源版本) |
| 体积 | 1.4 GB 级 | 十几 MB ~ 几百 MB |
| 能否跨版本装 | 能 | 不能,必须精确匹配源版本 |
| 生成命令 | ota_from_target_files target.zip out.zip | ota_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 |
POWERWASH | 1 表示升级后清用户数据 | 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-type | AB / 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。
要记住的两条经验:
pre-device只来自构建时的SYSTEM/build.prop的ro.product.device(由PRODUCT_DEVICE派生), 不读vendor/*/build.prop;设备实际属性是 init 按顺序加载后"最后者胜"的结果——两边天然可能不一致。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 / 仅 metadata | update_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 | 写入 manifest | SPL 降级策略 |
--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 mismatch | METADATA_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. 本篇小结
- A/B OTA zip = 控制面(metadata / payload_properties)+ 数据面(payload.bin)+ 信任面(otacert / 签名),
payload.bin必须是ZIP_STORED,因为要按偏移直取(流式升级)。 - payload 头 24 字节定长、大端:
CrAU+ version(2) + manifest_size + metadata_sig_size;METADATA_SIZE = 24 + manifest_size,不含 metadata 签名。 - manifest 是施工图纸:
partitions[]决定写哪些分区与怎么写; 只要 ops 里出现SOURCE_*,包就依赖设备当前版本;只有REPLACE*则是自包含全量包。 is_delta的官方判据是old_partition_info是否存在,不是"有没有 SOURCE_*"——两者可能不一致。- 四个校验头是入场券:Base64 的 hash,调用方必须原样传给
applyPayload; 另有SWITCH_SLOT_ON_REBOOT/POWERWASH这类行为开关头。 pre-device只来自构建时的SYSTEM/build.prop,设备侧是"四属性任一命中", 两边天然可能不一致——ro.build.product必须与PRODUCT_DEVICE同源。- 信任根是 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 权限缺口这类"接线"问题。