123 lines
8.8 KiB
Markdown
123 lines
8.8 KiB
Markdown
# 固件真机联调一致性证据采集与校验说明
|
||
|
||
## 1. 目标
|
||
|
||
固件一致性证据用于回答“设备本地实际发生了什么”与“云端收到并据此处置了什么”是否一致。它把设备侧Bootloader、分区、启动尝试和健康结果，与云端可靠命令、固件阶段回执和批次终态绑定，避免只凭页面最后状态或设备口头说明判断升级结果。
|
||
|
||
本功能包含三部分：
|
||
|
||
1. V38`firmware_assignment_event`不可变事件表，留存每次下载、安装、写分区、重启、启动健康确认和回退回执；
|
||
2. 设备侧`firmware-device-evidence-v1`脱敏证据格式；
|
||
3. `cmd/firmware-conformance`离线校验命令，输出带输入SHA-256和逐项结论的`firmware-conformance-report-v1`报告。
|
||
|
||
校验结果为`PASS`只表示两份输入在协议、身份、顺序和结果上相互一致。模拟器证据固定标记为`PROTOCOL_SIMULATION`，真机证据标记为`HARDWARE_CAPTURE`；两者都保留`external_validation_required=true`，不能据此自动批准生产发布。
|
||
|
||
## 2. 云端阶段事件
|
||
|
||
设备通过`POST /device/v2/commands/{id}/ack`直接回执，或通过批量遥测中的`command_result`补交结果时，云端在更新命令和固件分配的同一事务内写入阶段事件。任一步失败会整体回滚，不会出现命令已变化但事件缺失的半完成状态。
|
||
|
||
事件使用`assignment_id + command_status + result_digest`唯一键去重。`result_digest`是服务端对规范JSON结果摘要计算的小写SHA-256；完全相同的重复ACK仍保持命令幂等，但不会生成重复时间线记录。不同进度、阶段、启动尝试或终态具有不同摘要，会形成新的事件。
|
||
|
||
| 字段 | 用途 |
|
||
|---|---|
|
||
| `command_id` | 对外设备命令编号，绑定设备证据 |
|
||
| `command_status`、`assignment_status` | 命令状态和云端固件分配主状态 |
|
||
| `phase`、`progress_percent`、`result_code` | 设备阶段、进度和稳定结果码 |
|
||
| `active_slot`、`target_slot`、`previous_slot`、`failed_slot` | A/B分区转换和失败分区 |
|
||
| `boot_attempt_id`、`boot_health_deadline` | 同一次启动尝试和健康窗口 |
|
||
| `rollback_applied`、`rollback_version` | 是否实际回退及回退版本 |
|
||
| `installed_version` | 成功确认的目标版本 |
|
||
| `verified_sha256`、`verified_signing_key_id` | 设备实际验证的制品和本地信任锚编号 |
|
||
| `result_digest`、`reported_at` | 去重摘要和云端接收时间 |
|
||
|
||
事件只保留固件状态和非敏感标识，不返回完整`result_summary`。原结果摘要继续留在当前分配和命令记录中，并受既有递归敏感字段拒绝规则保护。批次详情按设备、云端接收时间和事件编号升序返回时间线；V38之前创建的历史批次没有倒推事件，页面明确显示“暂无逐步时间线”，不会伪造历史。
|
||
|
||
## 3. 设备证据格式
|
||
|
||
设备侧文件必须使用`firmware-device-evidence-v1`，未知字段被校验器拒绝，避免采集程序和校验程序在未评审的情况下悄然漂移。
|
||
|
||
| 分类 | 必需字段 |
|
||
|---|---|
|
||
| 候选身份 | `candidate_version`、`build_digest`，摘要格式为`sha256:<64位小写十六进制>` |
|
||
| 证据来源 | `evidence_source=SIMULATOR/HARDWARE` |
|
||
| 设备身份 | 设备公开编号、型号、硬件版本、发布编号、命令编号 |
|
||
| 平台基线 | Bootloader版本、分区表SHA-256、是否启用安全启动 |
|
||
| 制品身份 | 固件SHA-256、设备本地采用的签名密钥编号 |
|
||
| 测试场景 | `AB_SUCCESS`、`AB_ROLLBACK`、`POWER_LOSS_AFTER_STAGE`或`POWER_LOSS_DURING_BOOT` |
|
||
| 分区与版本 | 初始、目标、最终分区及初始、目标、最终版本 |
|
||
| 启动尝试 | `boot_attempt_id`及设备本地事件时间线 |
|
||
| 采集时间 | UTC`collected_at`，不得早于任何本地事件 |
|
||
|
||
设备证据不得包含设备HMAC密钥、私钥、Token、完整序列号、家庭、长者、录音、字幕、网络口令或云账号。量产采集适配器应从受控Bootloader环境区、只读系统版本文件和升级日志生成证据，并在离开设备前完成字段白名单过滤。
|
||
|
||
## 4. 一致性校验项
|
||
|
||
校验器逐项输出`PASS/FAIL`，任何一项失败都会使总结果为`FAIL`：
|
||
|
||
1. 设备证据版本和来源合法；
|
||
2. 候选版本及构建摘要完整；
|
||
3. 设备、发布、命令公开编号和型号/硬件版本完整；
|
||
4. Bootloader及分区表摘要存在；
|
||
5. 制品摘要和签名密钥编号完整；
|
||
6. 云端批次唯一包含目标设备；
|
||
7. 云端批次与设备证据引用同一发布；
|
||
8. 云端时间线包含设备声明的已验证摘要和签名密钥；
|
||
9. 全部云端事件绑定同一命令；
|
||
10. 云端事件UUID、结果摘要哈希和接收顺序有效；
|
||
11. 设备本地事件顺序有效且不晚于采集时间；
|
||
12. 场景和必需阶段顺序正确；
|
||
13. 云端与设备引用同一启动尝试；
|
||
14. 同名设备/云端阶段最大时间差不超过10分钟；
|
||
15. 最终分区、版本、命令终态、分配终态及回退事实一致。
|
||
|
||
时间相关性使用同名阶段的最近时间，不要求设备与云端毫秒级相等；超过10分钟通常表示设备时钟、采集时区、离线补交或证据混用问题，必须先解释并重新采集，不能手工修改报告。
|
||
|
||
## 5. 命令用法
|
||
|
||
先以有权查看固件批次的账号下载`GET /api/v1/firmware-rollouts/{id}`完整JSON响应，再从设备导出证据文件。校验在离线环境执行：
|
||
|
||
```powershell
|
||
go run ./cmd/firmware-conformance `
|
||
-cloud C:\evidence\rollout-response.json `
|
||
-device C:\evidence\device-evidence.json `
|
||
-output C:\evidence\firmware-conformance-report.json
|
||
```
|
||
|
||
输出路径必须为绝对路径，文件权限限制为当前用户可读写。通过时进程退出码为0，业务不一致时仍写出完整失败报告并返回1，参数、文件或JSON格式错误返回2。报告包含两份输入文件的SHA-256，可在归档后判断输入是否被替换；报告不复制云端完整结果摘要或设备原始日志。
|
||
|
||
## 6. 模拟闭环
|
||
|
||
模拟器在A/B模式下可通过以下变量生成独立设备侧证据：
|
||
|
||
| 变量 | 作用 |
|
||
|---|---|
|
||
| `SIM_FIRMWARE_EVIDENCE_FILE` | 设备证据绝对路径 |
|
||
| `SIM_FIRMWARE_EVIDENCE_SCENARIO` | 本次场景 |
|
||
| `SIM_CANDIDATE_VERSION`、`SIM_BUILD_DIGEST` | 候选构建身份 |
|
||
| `SIM_BOOTLOADER_VERSION` | 模拟Bootloader版本 |
|
||
| `SIM_PARTITION_TABLE_SHA256` | 模拟分区表摘要 |
|
||
| `SIM_SECURE_BOOT_ENABLED` | 模拟安全启动状态，只允许true/false |
|
||
|
||
运行以下单条低强度烟测：
|
||
|
||
```powershell
|
||
powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\smoke-sim-firmware.ps1 -Mode ABRollback
|
||
```
|
||
|
||
脚本断言云端形成7条去重事件：两条下载、安装开始、非活动分区写入、等待重启、启动健康检查和已回退；随后使用模拟器独立生成的设备证据执行校验器。报告必须全部通过、范围必须是`PROTOCOL_SIMULATION`且必须继续声明外部验收未完成。烟测结束删除临时数据库记录、对象、固件、状态、两份输入和报告。
|
||
|
||
## 7. 真机交付要求
|
||
|
||
硬件团队应为每台候选设备的A→B、B→A、写入后断电、首次启动断电、健康超时和人工回滚分别交付设备证据与云端批次快照。研发或QA使用同一候选校验器生成报告，并把原输入及报告一并放入候选证据库。任何`FAIL`、不同命令编号、不同启动尝试、摘要不一致或时间差超限都必须进入联调问题台账；不得只保留截图或手工修改后的汇总表。
|
||
|
||
## 8. 阶段8发布证据包门禁
|
||
|
||
`cmd/release-evidence`使用`release-evidence-index-v2`中的`REAL_DEVICE_FIRMWARE`登记真机报告，并在`release-candidate-evidence-bundle-v3`清单内生成`firmware_validation`覆盖摘要。当前自动门禁要求至少3台不同候选设备中的每一台都完成以下四种可由一致性校验器结构化确认的场景：
|
||
|
||
- `AB_SUCCESS`：候选分区启动并完成健康确认；实际联调同时覆盖A→B和B→A方向；
|
||
- `AB_ROLLBACK`：启动健康失败或超时后自动回到旧分区；人工回滚另附操作与审计证据；
|
||
- `POWER_LOSS_AFTER_STAGE`：写入完成、切换启动前断电并恢复；
|
||
- `POWER_LOSS_DURING_BOOT`：首次候选分区启动期间断电并恢复。
|
||
|
||
每份报告必须是`PASS/HARDWARE_CAPTURE`，候选版本、构建摘要、公开设备/发布/批次/命令编号、两份输入摘要和全部20项检查必须完整。相同设备和场景只能登记一次。缺少任一设备或场景时，`REAL_DEVICE_FIRMWARE`必须保持`PENDING`，打包清单会列出每个场景的设备计数和缺口；把不完整项标记为`VERIFIED`会直接拒绝打包。该门禁不可用`WAIVED`绕过，也不接受`PROTOCOL_SIMULATION`报告。人工回滚、A/B双向覆盖及硬件团队签署继续作为同一证据项的外部复核材料，不因结构化四场景通过而自动获得生产批准。
|