46 lines
4.3 KiB
Markdown
46 lines
4.3 KiB
Markdown
# 离线镜像 1.0.2 真实 TF 卡验收记录（旧产物，已失效）
|
||
|
||
## 失效说明
|
||
|
||
- 本记录对应 SHA-256 `3a28d9b5200ed22824a628a46ce8d36851cc8366bbf3b8cbd22a2b9a7c4b9128` 的旧 IMG。该镜像最终没有监听 SSH 22 端口，缺少正式导出包的必要功能，因此不得再作为正式包使用。
|
||
- 旧 IMG 已删除，并由同版本的新 IMG 原子替换；新产物摘要以根目录 `发布记录.json` 和 `发布更新相关/导出包/1.0.2/manifest.json` 为准。
|
||
- 以下内容只保留当时失败定位和已完成硬件检查的历史证据，不代表新产物已通过真实 TF 卡首启、SSH 或重启验收。新产物须在用户完成镜像编辑、写卡和上电后另行验证。
|
||
|
||
## 旧产物当时的结论
|
||
|
||
- 用户于 2026-08-19 现场确认控制界面没有问题，同意按当前结果完成本次任务验收。
|
||
- 当时测试的镜像软件版本为 `1.0.2`，旧 SHA-256 为 `3a28d9b5200ed22824a628a46ce8d36851cc8366bbf3b8cbd22a2b9a7c4b9128`；该摘要现已失效。
|
||
- 浏览器真实打开控制界面成功，首页和七项侧栏工作区入口正常渲染，控制台无 warning/error。
|
||
- `/api/status` 返回 `software_version=1.0.2`；真实 `walnutpi-h618-hub75` 驱动、PI bank 映射、H618 PWM4 OE、CPU3 绑定、实时优先级和内存锁定均生效，采样时截止丢失、OE fault、强制黑屏和 `last_error` 均为 0。
|
||
- 未连接 HUB75 屏幕和 ADC；ADC 被正确报告为断开，此项不算失败。
|
||
- 设备 Ping 与 HTTP 8080 持续可达。SSH 22 端口在最终复查时仍未监听，因此没有完成 SSH 登录；该项明确记为未通过/未验证，不伪写为通过。用户接受此例外并要求收口。
|
||
- 没有进行验收后的额外一次显式重启测试；首次启动过程中的自动重启无法从 5 秒网络采样中单独证明，持久重启项保留为未单独验证。
|
||
- 本文件不包含账户、密码、Wi-Fi、配置槽内容或设备身份值。
|
||
|
||
## 真实失败与修复过程
|
||
|
||
1. 首次启动在 `packages` 阶段失败。FAT 状态文件证明 FFmpeg 的 Debian AArch64 离线材料只有 13 个包，不是完整闭包。
|
||
2. 从基础镜像导出 790 个正常安装包作为 `BASE_IMAGE_PACKAGES.tsv`，使用 Debian Bookworm、Updates、Security AArch64 索引递归解析并补齐 FFmpeg/libheif 闭包。
|
||
3. 第二次启动越过包阶段后在 `deploy` 阶段失败。`MSCDEPLOY.TXT` 证明基础镜像缺少 `python3.11-venv/ensurepip`。
|
||
4. 将 `python3.11-venv` 加入正式根依赖并补齐 8 个包；最终 Debian 离线集合为 84 个 `.deb`。
|
||
5. venv、全部 wheel、H618 原生驱动编译、原生测试和专用主机检查随后全部通过，但部署停在 `systemctl enable --now`。
|
||
6. 根因是 `matrix-image-firstboot.service` 声明 `Before=matrix-screen-controller.service`，却在 oneshot 内同步等待控制服务启动，形成 systemd 排序死锁。
|
||
7. 镜像首启改为只启用控制服务并延迟到自动重启后启动；增加同版本中断恢复门禁，只有版本、venv、原生文件、unit 和专用主机检查全部通过时才接管已有 `/opt`。
|
||
8. 最终控制网页和真实驱动正常运行，用户现场确认界面没有问题。
|
||
|
||
## 自动验证
|
||
|
||
- Python：`297 passed, 8 skipped`。
|
||
- Node：`61 passed`。
|
||
- Debian：84 个 `.deb`，86 个摘要条目全部通过；三个根依赖的本地闭包解析共选择 84 个包。
|
||
- 发布相关 shell 脚本通过语法检查。
|
||
- 正式镜像 FAT 载荷每次均读回验证；修复前后第二分区 SHA-256 始终为 `9ea9f86fa39fbc481a6a99623c39cdbbdf1cf86fc642add49acdf02f8f26744a`，证明同版本修复没有改变已验收的 rootfs bootstrap 分区。
|
||
- 官方基础镜像保持只读，正式镜像只在复制件上修改。
|
||
|
||
## 防回归规则
|
||
|
||
- 镜像构建前必须以 `BASE_IMAGE_PACKAGES.tsv` 验证 `ffmpeg`、`libheif-examples`、`python3.11-venv` 的完整递归闭包；缺根包、传递包、基准清单或摘要时拒绝导出。
|
||
- Debian 安装失败保留无配置凭据的 `MSCPKG.TXT`/`MSCPKGS.TSV`；部署失败保留无配置凭据的 `MSCDEPLOY.TXT`；成功时删除这些诊断文件。
|
||
- 首启 oneshot 不得同步启动受其 `Before=` 排序约束的控制服务。
|
||
- 本归档是一次性验收记录，不得作为后续构建输入；后续构建不得引用 `发布更新相关/导出包/<版本>/`。
|