53 lines
5.4 KiB
Markdown
53 lines
5.4 KiB
Markdown
# 离线镜像 1.0.3 启动分区空间修复记录
|
||
|
||
## 结论与产物身份
|
||
|
||
- 旧 1.0.3 IMG 的 SHA-256 为 `de3c9bc88b25cd11b0450e50f219398d973dd78d997a5c6e3c91c0f4d23d9f64`，已确认不可用并从正式目录删除，不得再写卡或发布。
|
||
- 修复后仍使用软件版本和文件名 `1.0.3`，新 IMG SHA-256 为 `a5676576fb63a913ed9e40a02ce206e5ef71f47b1005a98a8758479b51413e0b`。
|
||
- `核桃派软件源代码/VERSION` 始终为 `1.0.3`；`发布记录.json` 中仍只有一条 1.0.3 记录，已原子更新到新摘要。
|
||
- 原 65,536 字节双槽配置区逐字节复用，新镜像未写入账户、密码、IP 或 Wi-Fi 等现场值。
|
||
- 本轮未写 TF 卡。真实首次启动、SSH、sudo、网页、候选内核和再次重启须由用户写卡后继续验收，本文不把这些项目写成通过。
|
||
|
||
## 首次启动失败根因
|
||
|
||
- 现场 FAT 日志为 `install: error writing '/boot/Image-matrix-axp313a1': No space left on device`，随后回滚并留下 `FAILED: stage=kernel; code=1; line=150`。
|
||
- 现场工具报告 FAT 容量 `149,778,432` 字节、剩余 `17,678,336` 字节；独立 FAT16 簇解析得到分区字节数 `149,946,368`、可分配空间 `17,694,720`。两种口径有 BPB/簇取整差异，但都小于新内核单文件 `22,468,616` 字节。
|
||
- 旧 `/boot/MSCBOOT.TGZ` 占 `76,117,351` 字节。即使不计双份 DTB、System.map、kernel config、启动脚本临时文件和原始脚本回滚副本，只写候选 Image 也至少短缺约 4.8 MB。
|
||
- 基础 Debian 和网络已先完成，因此设备可 ping；控制服务、网页和成功重启位于失败点之后，不能由 ping 可达推断为已安装。
|
||
|
||
## 设计修复
|
||
|
||
- 镜像元数据从 v2 升级为 v3。FAT 只保存 `MSCCFG.BIN`、`MSCMETA.JSN` 和 `MSCINIT`；应用离线包迁入 `/opt/matrix-image-bootstrap/app/MSCBOOT.TGZ`，内核载荷继续位于相邻的 `axp313a/`。
|
||
- rootfs 注入前检查“应用压缩载荷 + 内核压缩载荷 + 256 MiB”。首次启动失败保留两类压缩载荷供完整重试，全部成功后才删除整个 bootstrap 根。
|
||
- 构建端和内核安装器共用同一 FAT 预算算法，按 4,096 字节簇计入五个候选 boot 文件、原始回滚脚本、临时/最终受管脚本、摘要和健康标记，再额外保留固定 `32 MiB`。
|
||
- 新镜像实测 FAT 空闲 `93,814,784` 字节，实际文件预算 `26,279,936`，安全余量 `33,554,432`，总门槛 `59,834,368`，门槛之外仍有 `33,980,416` 字节。
|
||
- 新应用 bundle 为 `76,123,924` 字节、SHA-256 `74e90c7b93d3ffc55226d52bfb5cee214255704341ac40564cd9afc823b19616`；最终 FAT 明确不存在 `MSCBOOT.TGZ`。
|
||
|
||
## 导出入口报错与修复
|
||
|
||
- 先前正式脚本在创建发布锁和版本目录之前报远端系统 Python 缺少 FontTools；本机 bare Python 复现时先报缺少 Pillow。
|
||
- 根因不是镜像构建需要字体包，而是导出器导入 `app.ota.package` 时执行了 `app.ota.__init__`，后者提前加载 OTA manager、显示服务、Pillow 和 FontTools。
|
||
- 当时用已校验 wheelhouse 创建临时 Python 3.11 venv 可以绕过报错，但这不是正确的长期依赖边界。
|
||
- `app.ota` 现改为惰性导出。`python3 -S scripts/export_release.py --help` 在没有 site packages 的 Linux 系统 Python 上通过；正式镜像导出不再创建应用 venv 或访问网络。
|
||
- 旧 `refresh_sd_image_payload.py` 原地刷新方式已停用。同版本坏包只能通过 `image --repair-current` 从官方基线完整重建，验证后替换原目录和原记录。
|
||
|
||
## 构建和传输过程中的防坑记录
|
||
|
||
- Windows 端只创建不含凭据的最小项目快照，并对项目快照、官方基线压缩副本和旧 IMG 压缩副本分别做传输前后 SHA-256；三项全部一致后才解压。
|
||
- Windows Git tar 不能直接把带盘符的输出路径交给其 gzip 子进程；本轮改用 Windows 自带 bsdtar 生成项目快照。以后仍应把传输产物放在 Codex 临时目录，不放进项目。
|
||
- 官方镜像 `SHA256SUMS` 使用相对文件名，校验必须在清单所在目录执行或显式筛选 IMG 条目；不能在项目根直接执行整份清单。
|
||
- PuTTY SCP 对远端中文路径发生过编码失败。下载阶段使用同文件系统、ASCII 名称的临时硬链接目录；启用 `protected_hardlinks` 时由 sudo 只创建硬链接，不复制第二份 3.3 GB IMG。下载后仍以正式侧车摘要校验。
|
||
- 远端工具先按远端 PATH 检查；普通账户 PATH 不含 `/usr/sbin/losetup`，root 构建使用明确的系统 PATH。没有因本机具备工具而假设远端具备。
|
||
|
||
## 自动验证结果
|
||
|
||
- 本机聚焦镜像/内核测试：`27 passed`。
|
||
- 本机完整 Python：`356 passed, 8 skipped`；警告均为既有 FastAPI/Pillow 弃用警告。
|
||
- Node 前端：`72 passed`。
|
||
- 四个相关 shell 脚本通过 `bash -n`；远端 bare Python 参数入口通过。
|
||
- 官方基线 IMG 在解压后、构建后分别按项目清单复核为 `OK`。
|
||
- 正式构建输出 `rootfs bootstrap installed` 与 `rootfs bootstrap verified`；提交后又从 IMG 复制应用 bundle 为独立文件，再次运行只读 rootfs/FAT 验证并通过。
|
||
- 新 manifest、侧车摘要、实际整镜像摘要和唯一发布记录四者一致；发布锁、`.building` 和 `.invalid-backup` 均不得残留。
|
||
|
||
本记录是一次性故障和发布证据，不得作为后续构建输入；后续构建不得引用 `发布更新相关/导出包/1.0.3` 中的任何文件。
|