初始化奇妙小屏幕控制器项目
This commit is contained in:
@@ -0,0 +1,26 @@
|
||||
# 1.0.2 SSH 与 sudo 真实验收修复
|
||||
|
||||
## 真实设备发现
|
||||
|
||||
- 配置账户关闭 SSH agent 后可用镜像密码实际登录，SSH、网页和控制服务均已运行。
|
||||
- `sudo -n` 正确拒绝免密，但输入配置账户密码仍被拒绝，并出现主机名解析延迟。
|
||||
- 最终 IMG 的 rootfs 只读检查确认供应商 `/etc/sudoers` 在 `@includedir` 之后设置了 `Defaults rootpw`，并保留旧 `pi ALL=(ALL) NOPASSWD:ALL`；因此此前仅增加 sudo 组和 drop-in 规则不足以满足“同一账户密码、不得免密”。
|
||||
|
||||
## 修复
|
||||
|
||||
- 首启账户阶段原子移除供应商 `Defaults rootpw` 和旧 `pi NOPASSWD` 行。
|
||||
- 继续创建模式 `0440` 的配置账户 `ALL=(ALL:ALL) ALL` drop-in，并在替换前后运行 `visudo` 校验。
|
||||
- 身份阶段同步 `/etc/hosts` 中 `127.0.1.1` 的主机名，消除 sudo 解析警告和等待。
|
||||
- 当前真实设备使用供应商官方公开的基础镜像 root 凭据执行一次受控迁移；未开启 root SSH、未改变配置账户密码，临时脚本随后删除。
|
||||
|
||||
## 验收结果
|
||||
|
||||
- 禁用本机 SSH agent 后，配置账户密码登录通过。
|
||||
- `sudo -n` 被拒绝；输入同一配置账户密码后取得 UID 0，完整 root 命令通过。
|
||||
- `visudo -c` 通过，活动 sudoers 不含 `rootpw` 或 `NOPASSWD`，主机名可立即解析。
|
||||
- `sshd -T` 的密码认证、空密码、键盘交互和 root 登录策略全部符合要求；使用供应商 root 密码的实际 root SSH 登录被拒绝。
|
||||
- SSH、控制服务、网页、真实 H618 驱动和网络状态正常；再次重启后启动时长、SSH、控制服务和主机名解析复验通过。
|
||||
- 聚焦 Python 测试 13 项通过；完整 Python 回归 306 项通过、8 项跳过；Node 回归 61 项通过；shell 语法通过。
|
||||
- 最终 IMG 仅刷新 FAT 载荷，配置双槽逐字节保留，ext4 分区 SHA-256 保持不变，bundle 敏感路径扫描通过。
|
||||
|
||||
本归档不记录账户、密码、IP、主机密钥或设备身份值。此前 1.0.2 哈希均已被最终正式哈希取代，不得继续发布。
|
||||
@@ -0,0 +1,23 @@
|
||||
# 离线镜像 1.0.2 SSH 首启失败修复记录
|
||||
|
||||
## 现场结果
|
||||
|
||||
- 设备供电后网络间歇可达，但 SSH 22 和控制服务 8080 在 20 分钟门槛内始终未开放。
|
||||
- FAT 状态文件报告 `stage=ssh` 失败；账户、sudoers、受管 SSH 配置、服务启用链接、machine-id 和新 SSH 主机密钥均已写入。
|
||||
- ext4 systemd journal 的直接证据为：`sshd -t` 报告缺少 privilege separation 运行目录 `/run/sshd`，随后首启服务以退出码 1 失败。
|
||||
|
||||
## 根因与修复
|
||||
|
||||
- 首启 unit 通过 `Before=ssh.service` 正确阻止 SSH 提前监听，因此 systemd 尚未为 `ssh.service` 创建易失的 `/run/sshd`。
|
||||
- 首启程序却在服务启动前直接执行 `sshd -t/-T`，错误依赖了该目录已经存在。
|
||||
- `configure_ssh` 现于策略校验前创建 `/run/sshd` 并设置模式 `0755`；需求和测试映射同步增加该门槛。
|
||||
- 同版本正式 IMG 只刷新 FAT bundle，第二分区保持核桃派已验证的 SHA-256 `a3207843b6c405df3abb827c80ffd60285788541e62fa6fdd8335498084a9f95` 不变。失败卡上的三个 FAT 载荷文件已逐字更新并读回，配置区摘要写前写后一致。
|
||||
|
||||
## 自动验证
|
||||
|
||||
- SSH/镜像聚焦测试：11 项通过。
|
||||
- 完整 Python：304 项通过、8 项跳过。
|
||||
- 前端：55 项通过，全部 JavaScript 与相关 shell 语法检查通过。
|
||||
- 新正式 IMG 与发布记录摘要一致；旧摘要已失效，不得继续使用。
|
||||
|
||||
本记录不包含账户、密码、Wi-Fi、IP、主机密钥内容或其他设备身份值。修复后的真实首次启动、SSH、sudo、网页和再次重启仍需重新验收。
|
||||
@@ -0,0 +1,28 @@
|
||||
# 1.0.2 SSH 首启自动重启超时修复
|
||||
|
||||
## 现象与证据
|
||||
|
||||
- 真实 TF 卡的 FAT 状态文件曾显示首启成功，但设备没有按预期自动重启，SSH 端口也未监听。
|
||||
- Linux 分区 journal 显示 SSH 配置校验、主机密钥生成和 `ssh.service` 启用已经完成，随后 `matrix-image-firstboot.service` 因启动超时被终止。
|
||||
- 首启脚本在自身仍运行时删除 unit 并执行 `systemctl daemon-reload`，导致 systemd 丢失该运行中 unit 的显式超时定义并回落到默认启动超时；成功状态又在清理和同步之前写入，因此形成假成功。
|
||||
|
||||
## 修复
|
||||
|
||||
- `matrix-image-firstboot.service` 改用 `TimeoutStartSec=infinity`，避免不同 TF 卡速度导致合法的离线部署被中止。
|
||||
- 首启脚本不再在自身运行时执行 `systemctl daemon-reload`；unit 文件仍在重启前删除，新的 systemd 实例启动后自然不再加载它。
|
||||
- 成功状态延后到秘密和临时文件清理、首启 unit 禁用、工作目录删除及全盘同步之后，仅在请求重启前写入。
|
||||
- 保留先前 `/run/sshd`、受管 SSH 策略、需密码完整 sudo 权限及禁止 root SSH 的修复。
|
||||
|
||||
## 验证结果
|
||||
|
||||
- 聚焦 Python 测试：12 项通过。
|
||||
- 完整 Python 回归：305 项通过，8 项跳过。
|
||||
- Node 前端回归：61 项通过。
|
||||
- shell 语法、远端 rootfs 安装及只读验证通过。
|
||||
- 最终 IMG 从官方基础镜像重新复制构建；官方基础镜像 SHA-256 保持不变。
|
||||
- 最终 IMG 的 FAT 配置双槽与旧 1.0.2 工厂配置逐字节一致；bundle 与当前源码一致。
|
||||
- rootfs 中首启 unit、受管 SSH 配置和服务启用状态正确，且不含 SSH 主机密钥、NetworkManager 连接、项目凭据或设备数据。
|
||||
|
||||
旧验收哈希已被新的 1.0.2 正式哈希取代，不得继续作为可发布镜像使用。真实设备的 SSH 登录、sudo、root 拒绝和再次重启验证继续以本轮 TF 卡验收为准。
|
||||
|
||||
后续真实 sudo 验收又发现基础镜像的 `Defaults rootpw` 和旧 `pi NOPASSWD`，本归档对应哈希再次被最终 sudo 策略修复哈希取代。
|
||||
@@ -0,0 +1,45 @@
|
||||
# 离线镜像 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=` 排序约束的控制服务。
|
||||
- 本归档是一次性验收记录，不得作为后续构建输入；后续构建不得引用 `发布更新相关/导出包/<版本>/`。
|
||||
@@ -0,0 +1,52 @@
|
||||
# 离线镜像 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` 中的任何文件。
|
||||
@@ -0,0 +1,358 @@
|
||||
#!/usr/bin/env python3
|
||||
"""Privileged one-shot worker for a previously validated browser OTA package."""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import hashlib
|
||||
import json
|
||||
import os
|
||||
from pathlib import Path
|
||||
import shutil
|
||||
import signal
|
||||
import subprocess
|
||||
import sys
|
||||
import time
|
||||
from typing import Any
|
||||
|
||||
from app.ota.package import extract_payload, inspect_package
|
||||
from app.ota.state import read_json, utc_now, write_json, write_last_result
|
||||
from app.ota.versioning import SoftwareVersion
|
||||
|
||||
TARGET = Path("/opt/matrix-screen-controller")
|
||||
RELEASES = Path("/opt/matrix-screen-controller.releases")
|
||||
DATA_ROOT = Path("/var/lib/matrix-screen-controller")
|
||||
RUNTIME_ROOT = Path("/run/matrix-screen-controller")
|
||||
UNIT_PATH = Path("/etc/systemd/system/matrix-screen-controller.service")
|
||||
SERVICE = "matrix-screen-controller.service"
|
||||
REQUEST_PATH = RUNTIME_ROOT / "ota-request.json"
|
||||
|
||||
|
||||
class UpdateFailed(RuntimeError):
|
||||
pass
|
||||
|
||||
|
||||
def run(command: list[str], *, cwd: Path | None = None, env: dict[str, str] | None = None) -> None:
|
||||
subprocess.run(command, cwd=cwd, env=env, check=True)
|
||||
|
||||
|
||||
def snapshot(root: Path, *, ignored: set[str] | None = None) -> dict[str, tuple[int, str]]:
|
||||
records: dict[str, tuple[int, str]] = {}
|
||||
ignored = ignored or set()
|
||||
if not root.exists():
|
||||
return records
|
||||
for path in sorted((item for item in root.rglob("*") if item.is_file()), key=lambda item: item.as_posix()):
|
||||
relative = path.relative_to(root).as_posix()
|
||||
if relative in ignored:
|
||||
continue
|
||||
digest = hashlib.sha256()
|
||||
with path.open("rb") as handle:
|
||||
for chunk in iter(lambda: handle.read(1024 * 1024), b""):
|
||||
digest.update(chunk)
|
||||
records[relative] = (path.stat().st_size, digest.hexdigest())
|
||||
return records
|
||||
|
||||
|
||||
class Transaction:
|
||||
def __init__(self, request: dict[str, Any]) -> None:
|
||||
self.request = request
|
||||
self.job_id = checked_token(request.get("job_id"), "job_id")
|
||||
self.target_version = SoftwareVersion.parse(str(request.get("target_version")))
|
||||
self.current_version = SoftwareVersion.parse(str(request.get("current_version")))
|
||||
if self.target_version <= self.current_version:
|
||||
raise UpdateFailed("target version is not newer than the installed version")
|
||||
self.package_path = Path(str(request.get("package_path")))
|
||||
self.status_path = Path(str(request.get("status_path")))
|
||||
if self.status_path != RUNTIME_ROOT / "ota-status.json":
|
||||
raise UpdateFailed("unexpected OTA status path")
|
||||
self.work_root = Path(f"/opt/matrix-screen-controller-ota/work.{self.job_id}")
|
||||
self.extract_root = self.work_root / "extracted"
|
||||
self.release = RELEASES / f"{self.target_version}-{self.job_id}"
|
||||
self.data_candidate = DATA_ROOT.with_name(f"matrix-screen-controller.ota.{self.job_id}")
|
||||
self.data_backup = DATA_ROOT.with_name(f"matrix-screen-controller.rollback.{self.job_id}")
|
||||
self.unit_backup = self.work_root / "matrix-screen-controller.service.old"
|
||||
self.previous_target: Path | None = None
|
||||
self.previous_directory: Path | None = None
|
||||
self.program_swapped = False
|
||||
self.data_swapped = False
|
||||
self.visual: subprocess.Popen[bytes] | None = None
|
||||
self.job = {
|
||||
"id": self.job_id,
|
||||
"target_version": str(self.target_version),
|
||||
"packaged_at": str(request.get("packaged_at") or ""),
|
||||
"phase": "preparing",
|
||||
"percent": 8,
|
||||
"message": "正在准备更新",
|
||||
"started_at": str(request.get("accepted_at") or utc_now()),
|
||||
"finished_at": None,
|
||||
"error": None,
|
||||
}
|
||||
|
||||
def update(self, phase: str, percent: int, message: str) -> None:
|
||||
self.job.update(phase=phase, percent=max(0, min(100, percent)), message=message)
|
||||
write_json(self.status_path, {"schema_version": 1, "active": True, "job": self.job})
|
||||
|
||||
def prepare(self) -> None:
|
||||
if any(path.exists() for path in (self.work_root, self.release, self.data_candidate, self.data_backup)):
|
||||
raise UpdateFailed("OTA transaction paths already exist")
|
||||
self.work_root.mkdir(parents=True, mode=0o700)
|
||||
package = inspect_package(self.package_path, current_version=self.current_version)
|
||||
if package.target_version != self.target_version:
|
||||
raise UpdateFailed("request and package versions do not match")
|
||||
stat = shutil.disk_usage("/opt")
|
||||
required = max(package.expanded_bytes * 4, 512 * 1024 * 1024)
|
||||
if stat.free < required:
|
||||
raise UpdateFailed("not enough free space to stage and validate the OTA release")
|
||||
|
||||
self.update("extracting", 12, "正在解压全量更新包")
|
||||
extract_payload(package, self.extract_root)
|
||||
software = self.extract_root / "software"
|
||||
wheelhouse = self.extract_root / "wheelhouse"
|
||||
if SoftwareVersion.parse((software / "VERSION").read_text(encoding="utf-8")) != self.target_version:
|
||||
raise UpdateFailed("extracted software VERSION does not match the package")
|
||||
|
||||
self.update("dependencies", 22, "正在校验离线依赖并创建运行环境")
|
||||
run(["sha256sum", "-c", "SHA256SUMS"], cwd=wheelhouse)
|
||||
shutil.move(str(software), self.release)
|
||||
run(["python3", "-m", "venv", str(self.release / ".venv")])
|
||||
run([
|
||||
str(self.release / ".venv/bin/pip"),
|
||||
"install",
|
||||
"--no-index",
|
||||
"--disable-pip-version-check",
|
||||
"--find-links",
|
||||
str(wheelhouse),
|
||||
"-r",
|
||||
str(self.release / "requirements-dev.txt"),
|
||||
])
|
||||
|
||||
self.update("building", 42, "正在编译并测试屏幕驱动")
|
||||
run(["make", "-C", str(self.release / "app/display/native"), "clean", "all", "test"])
|
||||
run([str(self.release / ".venv/bin/python"), "-m", "compileall", "-q", str(self.release / "app")])
|
||||
|
||||
self.update("testing", 55, "正在运行新版本自动化测试")
|
||||
test_env = os.environ.copy()
|
||||
test_env.update(
|
||||
MATRIX_DRIVER="mock",
|
||||
MATRIX_DATA_DIR=str(self.work_root / "test-data"),
|
||||
MATRIX_RUNTIME_DIR=str(self.work_root / "test-runtime"),
|
||||
MATRIX_SOURCE_ONLY_UPDATE_TESTS="1",
|
||||
)
|
||||
run([str(self.release / ".venv/bin/python"), "-m", "pytest", "-q"], cwd=self.release, env=test_env)
|
||||
run([str(self.release / ".venv/bin/python"), str(self.release / "scripts/dedicated_host.py"), "check"])
|
||||
|
||||
self.update("migrating", 68, "正在迁移用户数据副本")
|
||||
shutil.copytree(DATA_ROOT, self.data_candidate, symlinks=True)
|
||||
runtime_candidate = self.work_root / "migration-runtime"
|
||||
migration_env = os.environ.copy()
|
||||
migration_env["PYTHONPATH"] = str(self.release)
|
||||
run([
|
||||
str(self.release / ".venv/bin/python"),
|
||||
"-m",
|
||||
"scripts.prepare_data_root",
|
||||
"--data-root",
|
||||
str(self.data_candidate),
|
||||
"--runtime-root",
|
||||
str(runtime_candidate),
|
||||
], cwd=self.release, env=migration_env)
|
||||
|
||||
def switch(self) -> None:
|
||||
self.update("switching", 78, "正在切换到新版本")
|
||||
shutil.copy2(UNIT_PATH, self.unit_backup)
|
||||
run(["systemctl", "stop", SERVICE])
|
||||
self.start_visual()
|
||||
|
||||
RELEASES.mkdir(parents=True, exist_ok=True)
|
||||
if TARGET.is_symlink():
|
||||
self.previous_target = Path(os.readlink(TARGET))
|
||||
TARGET.unlink()
|
||||
elif TARGET.is_dir():
|
||||
self.previous_directory = RELEASES / f"{self.current_version}-pre-ota-{self.job_id}"
|
||||
TARGET.rename(self.previous_directory)
|
||||
else:
|
||||
raise UpdateFailed("production target is neither a release symlink nor a directory")
|
||||
os.symlink(self.release, TARGET, target_is_directory=True)
|
||||
self.program_swapped = True
|
||||
|
||||
DATA_ROOT.rename(self.data_backup)
|
||||
self.data_candidate.rename(DATA_ROOT)
|
||||
self.data_swapped = True
|
||||
shutil.copy2(self.release / "systemd/matrix-screen-controller.service", UNIT_PATH)
|
||||
shutil.copy2(self.release / "systemd/matrix-screen-controller-ota.service", Path("/etc/systemd/system/matrix-screen-controller-ota.service"))
|
||||
run(["systemctl", "daemon-reload"])
|
||||
self.stop_visual()
|
||||
run(["systemctl", "start", SERVICE])
|
||||
|
||||
def verify(self) -> None:
|
||||
self.update("verifying", 90, "正在验证新版本和真实屏幕驱动")
|
||||
deadline = time.monotonic() + 45
|
||||
last_error = "service did not respond"
|
||||
while time.monotonic() < deadline:
|
||||
try:
|
||||
output = subprocess.check_output(
|
||||
["curl", "--fail", "--silent", "http://127.0.0.1:8080/api/status"],
|
||||
timeout=5,
|
||||
)
|
||||
status = json.loads(output.decode("utf-8"))
|
||||
screen = status.get("screen", {})
|
||||
driver = screen.get("driver_status") or {}
|
||||
if status.get("service", {}).get("software_version") != str(self.target_version):
|
||||
raise UpdateFailed("new service reports the wrong software version")
|
||||
if screen.get("driver") != "walnutpi-h618-hub75":
|
||||
raise UpdateFailed("new service did not start the production HUB75 driver")
|
||||
if screen.get("hardware_mapping") != "walnutpi-pi-bank-pwm-oe-v2":
|
||||
raise UpdateFailed("new service reports the wrong hardware mapping")
|
||||
if driver.get("oe_timing_backend") != "h618-pwm4" or driver.get("oe_pulse_faults") != 0:
|
||||
raise UpdateFailed("new service did not pass the PWM4 OE health check")
|
||||
return
|
||||
except (subprocess.SubprocessError, OSError, UnicodeError, json.JSONDecodeError) as exc:
|
||||
last_error = str(exc)
|
||||
time.sleep(1)
|
||||
raise UpdateFailed(f"new release health check timed out: {last_error}")
|
||||
|
||||
def succeed(self) -> None:
|
||||
result = {
|
||||
"status": "success",
|
||||
"target_version": str(self.target_version),
|
||||
"packaged_at": str(self.request.get("packaged_at") or ""),
|
||||
"installed_at": utc_now(),
|
||||
"release_notes": str(self.request.get("release_notes") or ""),
|
||||
"error": None,
|
||||
}
|
||||
write_last_result(DATA_ROOT, result)
|
||||
self.job.update(
|
||||
phase="complete",
|
||||
percent=100,
|
||||
message="更新完成",
|
||||
finished_at=result["installed_at"],
|
||||
error=None,
|
||||
)
|
||||
write_json(self.status_path, {"schema_version": 1, "active": False, "job": self.job})
|
||||
self.package_path.unlink(missing_ok=True)
|
||||
self.request_path().unlink(missing_ok=True)
|
||||
shutil.rmtree(self.data_backup, ignore_errors=True)
|
||||
if self.previous_directory is not None:
|
||||
shutil.rmtree(self.previous_directory, ignore_errors=True)
|
||||
if self.previous_target is not None:
|
||||
previous_release = self.previous_target if self.previous_target.is_absolute() else TARGET.parent / self.previous_target
|
||||
if previous_release.parent == RELEASES:
|
||||
shutil.rmtree(previous_release, ignore_errors=True)
|
||||
shutil.rmtree(self.work_root, ignore_errors=True)
|
||||
prune_empty(self.package_path.parent)
|
||||
|
||||
def rollback(self, error: BaseException) -> None:
|
||||
self.stop_visual()
|
||||
if self.program_swapped or self.data_swapped:
|
||||
subprocess.run(["systemctl", "stop", SERVICE], check=False)
|
||||
if self.data_swapped:
|
||||
failed_data = DATA_ROOT.with_name(f"matrix-screen-controller.failed.{self.job_id}")
|
||||
if DATA_ROOT.exists():
|
||||
DATA_ROOT.rename(failed_data)
|
||||
if self.data_backup.exists():
|
||||
self.data_backup.rename(DATA_ROOT)
|
||||
shutil.rmtree(failed_data, ignore_errors=True)
|
||||
if self.program_swapped:
|
||||
if TARGET.is_symlink():
|
||||
TARGET.unlink()
|
||||
if self.previous_directory is not None and self.previous_directory.exists():
|
||||
self.previous_directory.rename(TARGET)
|
||||
elif self.previous_target is not None:
|
||||
os.symlink(self.previous_target, TARGET, target_is_directory=True)
|
||||
if self.unit_backup.exists():
|
||||
shutil.copy2(self.unit_backup, UNIT_PATH)
|
||||
subprocess.run(["systemctl", "daemon-reload"], check=False)
|
||||
if self.program_swapped or self.data_swapped:
|
||||
subprocess.run(["systemctl", "start", SERVICE], check=False)
|
||||
shutil.rmtree(self.release, ignore_errors=True)
|
||||
shutil.rmtree(self.data_candidate, ignore_errors=True)
|
||||
result = {
|
||||
"status": "failed",
|
||||
"target_version": str(self.target_version),
|
||||
"packaged_at": str(self.request.get("packaged_at") or ""),
|
||||
"installed_at": utc_now(),
|
||||
"release_notes": str(self.request.get("release_notes") or ""),
|
||||
"error": str(error),
|
||||
}
|
||||
try:
|
||||
write_last_result(DATA_ROOT, result)
|
||||
except OSError:
|
||||
pass
|
||||
self.job.update(
|
||||
phase="failed",
|
||||
percent=0,
|
||||
message="更新失败，已恢复原版本",
|
||||
finished_at=result["installed_at"],
|
||||
error=str(error),
|
||||
)
|
||||
write_json(self.status_path, {"schema_version": 1, "active": False, "job": self.job})
|
||||
self.package_path.unlink(missing_ok=True)
|
||||
self.request_path().unlink(missing_ok=True)
|
||||
shutil.rmtree(self.work_root, ignore_errors=True)
|
||||
|
||||
def start_visual(self) -> None:
|
||||
python = TARGET / ".venv/bin/python"
|
||||
self.visual = subprocess.Popen([
|
||||
str(python), "-m", "scripts.hub75_visual_hold",
|
||||
"--mode", "ota",
|
||||
"--brightness", "40",
|
||||
"--progress-file", str(self.status_path),
|
||||
"--orientation", str(int(self.request.get("orientation", 0))),
|
||||
])
|
||||
time.sleep(1)
|
||||
if self.visual.poll() is not None:
|
||||
raise UpdateFailed("independent OTA display process failed to start")
|
||||
|
||||
def stop_visual(self) -> None:
|
||||
if self.visual is None:
|
||||
return
|
||||
if self.visual.poll() is None:
|
||||
self.visual.send_signal(signal.SIGTERM)
|
||||
try:
|
||||
self.visual.wait(timeout=5)
|
||||
except subprocess.TimeoutExpired:
|
||||
self.visual.kill()
|
||||
self.visual.wait(timeout=2)
|
||||
self.visual = None
|
||||
|
||||
def request_path(self) -> Path:
|
||||
return Path(str(self.request.get("request_path") or REQUEST_PATH))
|
||||
|
||||
|
||||
def checked_token(value: Any, name: str) -> str:
|
||||
candidate = str(value or "")
|
||||
if not candidate or any(character not in "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789._-" for character in candidate):
|
||||
raise UpdateFailed(f"invalid {name}")
|
||||
return candidate
|
||||
|
||||
|
||||
def prune_empty(path: Path) -> None:
|
||||
try:
|
||||
path.rmdir()
|
||||
except OSError:
|
||||
pass
|
||||
|
||||
|
||||
def main() -> int:
|
||||
if os.geteuid() != 0 or os.uname().machine != "aarch64":
|
||||
print("OTA worker must run as root on the WalnutPi AArch64 host", file=sys.stderr)
|
||||
return 2
|
||||
request = read_json(REQUEST_PATH)
|
||||
if request is None or request.get("schema_version") != 1:
|
||||
print("OTA request is missing or invalid", file=sys.stderr)
|
||||
return 2
|
||||
transaction: Transaction | None = None
|
||||
try:
|
||||
transaction = Transaction(request)
|
||||
transaction.prepare()
|
||||
transaction.switch()
|
||||
transaction.verify()
|
||||
transaction.succeed()
|
||||
return 0
|
||||
except BaseException as exc:
|
||||
if transaction is not None:
|
||||
transaction.rollback(exc)
|
||||
print(f"OTA update failed: {exc}", file=sys.stderr)
|
||||
return 1
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
raise SystemExit(main())
|
||||
@@ -0,0 +1,275 @@
|
||||
from __future__ import annotations
|
||||
|
||||
from dataclasses import dataclass
|
||||
from datetime import datetime, timezone
|
||||
import hashlib
|
||||
import json
|
||||
from pathlib import Path, PurePosixPath
|
||||
import shutil
|
||||
import tarfile
|
||||
import tempfile
|
||||
from typing import Any, BinaryIO
|
||||
import zipfile
|
||||
|
||||
from .versioning import SoftwareVersion
|
||||
|
||||
PRODUCT_ID = "matrix-screen-controller-walnutpi"
|
||||
PACKAGE_FORMAT_VERSION = 1
|
||||
MAX_OTA_UPLOAD_BYTES = 256 * 1024 * 1024
|
||||
MAX_OTA_PAYLOAD_BYTES = 256 * 1024 * 1024
|
||||
MAX_OTA_EXPANDED_BYTES = 1024 * 1024 * 1024
|
||||
_MAX_MANIFEST_BYTES = 64 * 1024
|
||||
_PACKAGE_MEMBERS = {"manifest.json", "payload.tar.gz"}
|
||||
_NATIVE_BUILD_OUTPUTS = {
|
||||
"app/display/native/libh618_hub75.so",
|
||||
"app/display/native/hub75_benchmark",
|
||||
"app/display/native/hub75_native_test",
|
||||
"app/display/native/hub75_safeoff",
|
||||
}
|
||||
_EXCLUDED_PARTS = {".venv", "data", "__pycache__", ".pytest_cache", "node_modules"}
|
||||
|
||||
|
||||
class OtaPackageError(ValueError):
|
||||
"""The uploaded archive is not a supported complete release."""
|
||||
|
||||
|
||||
@dataclass(frozen=True)
|
||||
class OtaPackageInfo:
|
||||
path: Path
|
||||
target_version: SoftwareVersion
|
||||
created_at: str
|
||||
release_notes: str
|
||||
payload_sha256: str
|
||||
payload_bytes: int
|
||||
expanded_bytes: int
|
||||
|
||||
def document(self) -> dict[str, Any]:
|
||||
return {
|
||||
"target_version": str(self.target_version),
|
||||
"created_at": self.created_at,
|
||||
"release_notes": self.release_notes,
|
||||
"payload_sha256": self.payload_sha256,
|
||||
"payload_bytes": self.payload_bytes,
|
||||
"expanded_bytes": self.expanded_bytes,
|
||||
}
|
||||
|
||||
|
||||
def _validated_manifest(raw: bytes) -> tuple[dict[str, Any], SoftwareVersion]:
|
||||
if len(raw) > _MAX_MANIFEST_BYTES:
|
||||
raise OtaPackageError("OTA manifest is too large")
|
||||
try:
|
||||
manifest = json.loads(raw.decode("utf-8"))
|
||||
except (UnicodeError, json.JSONDecodeError) as exc:
|
||||
raise OtaPackageError("OTA manifest is not valid UTF-8 JSON") from exc
|
||||
expected = {
|
||||
"format_version",
|
||||
"product",
|
||||
"software_version",
|
||||
"created_at",
|
||||
"release_notes",
|
||||
"payload_sha256",
|
||||
"payload_bytes",
|
||||
"expanded_bytes",
|
||||
}
|
||||
if not isinstance(manifest, dict) or set(manifest) != expected:
|
||||
raise OtaPackageError("OTA manifest fields do not match format version 1")
|
||||
if manifest["format_version"] != PACKAGE_FORMAT_VERSION:
|
||||
raise OtaPackageError("OTA package format is unsupported")
|
||||
if manifest["product"] != PRODUCT_ID:
|
||||
raise OtaPackageError("OTA package is for a different product")
|
||||
try:
|
||||
version = SoftwareVersion.parse(manifest["software_version"])
|
||||
except ValueError as exc:
|
||||
raise OtaPackageError(str(exc)) from exc
|
||||
if not isinstance(manifest["created_at"], str) or not manifest["created_at"].strip():
|
||||
raise OtaPackageError("OTA package created_at is missing")
|
||||
if not isinstance(manifest["release_notes"], str) or len(manifest["release_notes"]) > 4000:
|
||||
raise OtaPackageError("OTA release notes are invalid")
|
||||
digest = manifest["payload_sha256"]
|
||||
if not isinstance(digest, str) or len(digest) != 64 or any(c not in "0123456789abcdef" for c in digest):
|
||||
raise OtaPackageError("OTA payload SHA-256 is invalid")
|
||||
for key, maximum in (
|
||||
("payload_bytes", MAX_OTA_PAYLOAD_BYTES),
|
||||
("expanded_bytes", MAX_OTA_EXPANDED_BYTES),
|
||||
):
|
||||
value = manifest[key]
|
||||
if type(value) is not int or value <= 0 or value > maximum:
|
||||
raise OtaPackageError(f"OTA {key} is outside the supported limit")
|
||||
return manifest, version
|
||||
|
||||
|
||||
def _payload_digest(handle: BinaryIO) -> tuple[str, int]:
|
||||
digest = hashlib.sha256()
|
||||
total = 0
|
||||
while True:
|
||||
chunk = handle.read(1024 * 1024)
|
||||
if not chunk:
|
||||
break
|
||||
total += len(chunk)
|
||||
if total > MAX_OTA_PAYLOAD_BYTES:
|
||||
raise OtaPackageError("OTA payload exceeds the supported limit")
|
||||
digest.update(chunk)
|
||||
return digest.hexdigest(), total
|
||||
|
||||
|
||||
def inspect_package(path: Path, *, current_version: SoftwareVersion | None = None) -> OtaPackageInfo:
|
||||
package_path = Path(path)
|
||||
try:
|
||||
size = package_path.stat().st_size
|
||||
except OSError as exc:
|
||||
raise OtaPackageError("OTA package cannot be read") from exc
|
||||
if size <= 0 or size > MAX_OTA_UPLOAD_BYTES:
|
||||
raise OtaPackageError("OTA package exceeds the 256 MiB upload limit")
|
||||
try:
|
||||
with zipfile.ZipFile(package_path, "r") as archive:
|
||||
entries = archive.infolist()
|
||||
if {entry.filename for entry in entries} != _PACKAGE_MEMBERS or len(entries) != 2:
|
||||
raise OtaPackageError("OTA package must contain only manifest.json and payload.tar.gz")
|
||||
if any(entry.is_dir() or entry.flag_bits & 0x1 for entry in entries):
|
||||
raise OtaPackageError("OTA package entries must be unencrypted files")
|
||||
manifest_entry = archive.getinfo("manifest.json")
|
||||
payload_entry = archive.getinfo("payload.tar.gz")
|
||||
if manifest_entry.file_size > _MAX_MANIFEST_BYTES:
|
||||
raise OtaPackageError("OTA manifest is too large")
|
||||
if payload_entry.file_size > MAX_OTA_PAYLOAD_BYTES:
|
||||
raise OtaPackageError("OTA payload exceeds the supported limit")
|
||||
manifest, target_version = _validated_manifest(archive.read(manifest_entry))
|
||||
with archive.open(payload_entry, "r") as payload:
|
||||
digest, payload_bytes = _payload_digest(payload)
|
||||
except (OtaPackageError, zipfile.BadZipFile):
|
||||
raise
|
||||
except (KeyError, OSError, RuntimeError) as exc:
|
||||
raise OtaPackageError("OTA package cannot be inspected") from exc
|
||||
if payload_bytes != manifest["payload_bytes"] or digest != manifest["payload_sha256"]:
|
||||
raise OtaPackageError("OTA payload checksum or size does not match the manifest")
|
||||
if current_version is not None and target_version <= current_version:
|
||||
raise OtaPackageError(
|
||||
f"OTA target {target_version} must be newer than installed version {current_version}"
|
||||
)
|
||||
return OtaPackageInfo(
|
||||
path=package_path,
|
||||
target_version=target_version,
|
||||
created_at=manifest["created_at"],
|
||||
release_notes=manifest["release_notes"],
|
||||
payload_sha256=digest,
|
||||
payload_bytes=payload_bytes,
|
||||
expanded_bytes=manifest["expanded_bytes"],
|
||||
)
|
||||
|
||||
|
||||
def _safe_member_path(name: str) -> Path:
|
||||
pure = PurePosixPath(name)
|
||||
if pure.is_absolute() or not pure.parts or any(part in {"", ".", ".."} for part in pure.parts):
|
||||
raise OtaPackageError(f"unsafe OTA payload path: {name}")
|
||||
if pure.parts[0] not in {"software", "wheelhouse"}:
|
||||
raise OtaPackageError(f"unexpected OTA payload root: {pure.parts[0]}")
|
||||
return Path(*pure.parts)
|
||||
|
||||
|
||||
def extract_payload(package: OtaPackageInfo, destination: Path) -> None:
|
||||
target = Path(destination)
|
||||
target.mkdir(parents=True, exist_ok=False)
|
||||
expanded = 0
|
||||
try:
|
||||
with zipfile.ZipFile(package.path, "r") as archive:
|
||||
with archive.open("payload.tar.gz", "r") as payload:
|
||||
with tarfile.open(fileobj=payload, mode="r|gz") as tar:
|
||||
for member in tar:
|
||||
relative = _safe_member_path(member.name)
|
||||
output = target / relative
|
||||
if member.isdir():
|
||||
output.mkdir(parents=True, exist_ok=True)
|
||||
continue
|
||||
if not member.isfile():
|
||||
raise OtaPackageError("OTA payload may contain only regular files and directories")
|
||||
expanded += member.size
|
||||
if expanded > MAX_OTA_EXPANDED_BYTES or expanded > package.expanded_bytes:
|
||||
raise OtaPackageError("OTA payload expands beyond its declared limit")
|
||||
output.parent.mkdir(parents=True, exist_ok=True)
|
||||
source = tar.extractfile(member)
|
||||
if source is None:
|
||||
raise OtaPackageError(f"OTA payload member cannot be read: {member.name}")
|
||||
with output.open("xb") as handle:
|
||||
shutil.copyfileobj(source, handle, length=1024 * 1024)
|
||||
output.chmod(member.mode & 0o777 or 0o644)
|
||||
if expanded != package.expanded_bytes:
|
||||
raise OtaPackageError("OTA expanded size does not match the manifest")
|
||||
if not (target / "software" / "VERSION").is_file():
|
||||
raise OtaPackageError("OTA payload does not contain software/VERSION")
|
||||
if not (target / "wheelhouse" / "SHA256SUMS").is_file():
|
||||
raise OtaPackageError("OTA payload does not contain the offline wheel manifest")
|
||||
except BaseException:
|
||||
shutil.rmtree(target, ignore_errors=True)
|
||||
raise
|
||||
|
||||
|
||||
def _source_file_allowed(path: Path, source_root: Path) -> bool:
|
||||
relative = path.relative_to(source_root)
|
||||
if any(part in _EXCLUDED_PARTS for part in relative.parts):
|
||||
return False
|
||||
if relative.as_posix() in _NATIVE_BUILD_OUTPUTS:
|
||||
return False
|
||||
if path.suffix in {".pyc", ".pyo"}:
|
||||
return False
|
||||
return True
|
||||
|
||||
|
||||
def _tar_add_file(tar: tarfile.TarFile, source: Path, archive_name: str) -> int:
|
||||
info = tar.gettarinfo(str(source), arcname=archive_name)
|
||||
info.uid = info.gid = 0
|
||||
info.uname = info.gname = "root"
|
||||
info.mtime = 0
|
||||
info.mode = 0o755 if source.suffix == ".sh" else 0o644
|
||||
with source.open("rb") as handle:
|
||||
tar.addfile(info, handle)
|
||||
return info.size
|
||||
|
||||
|
||||
def build_package(
|
||||
source_root: Path,
|
||||
wheelhouse: Path,
|
||||
output_path: Path,
|
||||
*,
|
||||
version: SoftwareVersion,
|
||||
release_notes: str,
|
||||
created_at: datetime | None = None,
|
||||
) -> OtaPackageInfo:
|
||||
source_root = Path(source_root).resolve()
|
||||
wheelhouse = Path(wheelhouse).resolve()
|
||||
if SoftwareVersion.parse((source_root / "VERSION").read_text(encoding="utf-8")) != version:
|
||||
raise OtaPackageError("requested package version does not match source VERSION")
|
||||
if not (wheelhouse / "SHA256SUMS").is_file():
|
||||
raise OtaPackageError("offline wheelhouse SHA256SUMS is missing")
|
||||
output = Path(output_path)
|
||||
output.parent.mkdir(parents=True, exist_ok=True)
|
||||
if output.exists():
|
||||
raise FileExistsError(output)
|
||||
timestamp = (created_at or datetime.now(timezone.utc)).astimezone().isoformat(timespec="seconds")
|
||||
with tempfile.TemporaryDirectory(prefix="matrix-ota-build-") as temporary:
|
||||
payload_path = Path(temporary) / "payload.tar.gz"
|
||||
expanded = 0
|
||||
with tarfile.open(payload_path, "w:gz", format=tarfile.PAX_FORMAT) as tar:
|
||||
for path in sorted(source_root.rglob("*"), key=lambda item: item.relative_to(source_root).as_posix()):
|
||||
if path.is_file() and _source_file_allowed(path, source_root):
|
||||
expanded += _tar_add_file(tar, path, f"software/{path.relative_to(source_root).as_posix()}")
|
||||
for path in sorted(wheelhouse.rglob("*"), key=lambda item: item.relative_to(wheelhouse).as_posix()):
|
||||
if path.is_file():
|
||||
expanded += _tar_add_file(tar, path, f"wheelhouse/{path.relative_to(wheelhouse).as_posix()}")
|
||||
payload_bytes = payload_path.stat().st_size
|
||||
if payload_bytes > MAX_OTA_PAYLOAD_BYTES or expanded > MAX_OTA_EXPANDED_BYTES:
|
||||
raise OtaPackageError("generated OTA payload exceeds the supported limit")
|
||||
digest = hashlib.sha256(payload_path.read_bytes()).hexdigest()
|
||||
manifest = {
|
||||
"format_version": PACKAGE_FORMAT_VERSION,
|
||||
"product": PRODUCT_ID,
|
||||
"software_version": str(version),
|
||||
"created_at": timestamp,
|
||||
"release_notes": str(release_notes).strip(),
|
||||
"payload_sha256": digest,
|
||||
"payload_bytes": payload_bytes,
|
||||
"expanded_bytes": expanded,
|
||||
}
|
||||
with zipfile.ZipFile(output, "x", compression=zipfile.ZIP_STORED, allowZip64=True) as archive:
|
||||
archive.writestr("manifest.json", json.dumps(manifest, ensure_ascii=False, indent=2) + "\n")
|
||||
archive.write(payload_path, "payload.tar.gz")
|
||||
return inspect_package(output)
|
||||
@@ -0,0 +1,44 @@
|
||||
from __future__ import annotations
|
||||
|
||||
from datetime import datetime, timezone
|
||||
import json
|
||||
from pathlib import Path
|
||||
from typing import Any
|
||||
|
||||
from app.persistence import atomic_write_bytes
|
||||
|
||||
OTA_STATE_SCHEMA_VERSION = 1
|
||||
|
||||
|
||||
def utc_now() -> str:
|
||||
return datetime.now(timezone.utc).isoformat(timespec="seconds").replace("+00:00", "Z")
|
||||
|
||||
|
||||
def read_json(path: Path) -> dict[str, Any] | None:
|
||||
try:
|
||||
value = json.loads(Path(path).read_text(encoding="utf-8"))
|
||||
except (OSError, UnicodeError, json.JSONDecodeError):
|
||||
return None
|
||||
return value if isinstance(value, dict) else None
|
||||
|
||||
|
||||
def write_json(path: Path, document: dict[str, Any]) -> None:
|
||||
atomic_write_bytes(
|
||||
Path(path),
|
||||
(json.dumps(document, ensure_ascii=False, indent=2, sort_keys=True) + "\n").encode("utf-8"),
|
||||
)
|
||||
|
||||
|
||||
def read_last_result(data_root: Path) -> dict[str, Any] | None:
|
||||
document = read_json(Path(data_root) / "ota" / "state.json")
|
||||
if not document or document.get("schema_version") != OTA_STATE_SCHEMA_VERSION:
|
||||
return None
|
||||
result = document.get("last_result")
|
||||
return dict(result) if isinstance(result, dict) else None
|
||||
|
||||
|
||||
def write_last_result(data_root: Path, result: dict[str, Any]) -> None:
|
||||
write_json(
|
||||
Path(data_root) / "ota" / "state.json",
|
||||
{"schema_version": OTA_STATE_SCHEMA_VERSION, "last_result": dict(result)},
|
||||
)
|
||||
@@ -0,0 +1,34 @@
|
||||
from __future__ import annotations
|
||||
|
||||
from dataclasses import dataclass
|
||||
from pathlib import Path
|
||||
import re
|
||||
|
||||
_VERSION_PATTERN = re.compile(r"^(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)$")
|
||||
|
||||
|
||||
@dataclass(frozen=True, order=True)
|
||||
class SoftwareVersion:
|
||||
major: int
|
||||
minor: int
|
||||
patch: int
|
||||
|
||||
@classmethod
|
||||
def parse(cls, value: str) -> "SoftwareVersion":
|
||||
if not isinstance(value, str):
|
||||
raise ValueError("software version must be a string")
|
||||
match = _VERSION_PATTERN.fullmatch(value.strip())
|
||||
if match is None:
|
||||
raise ValueError("software version must use strict MAJOR.MINOR.PATCH digits")
|
||||
return cls(*(int(part) for part in match.groups()))
|
||||
|
||||
def __str__(self) -> str:
|
||||
return f"{self.major}.{self.minor}.{self.patch}"
|
||||
|
||||
|
||||
def read_software_version(code_root: Path) -> SoftwareVersion:
|
||||
path = Path(code_root) / "VERSION"
|
||||
try:
|
||||
return SoftwareVersion.parse(path.read_text(encoding="utf-8"))
|
||||
except OSError as exc:
|
||||
raise RuntimeError(f"software VERSION file is unreadable: {path}") from exc
|
||||
@@ -0,0 +1,40 @@
|
||||
# OTA 1.1.0 交付与一次性验证记录
|
||||
|
||||
## 交付
|
||||
|
||||
- 正式包：`发布更新相关/OTA数据包/1.1.0/matrix-screen-controller-1.1.0.ota`
|
||||
- 字节数：27993930（约 26.7 MiB）。
|
||||
- SHA-256：`379f80a30157e23d717157005ea246fa822529010c0f0295dcad5db3ceff42c5`。
|
||||
- 功能时间：`2026-09-07T22:00+08:00`。导出成功后 VERSION 推进到 1.1.0，发布记录追加一次。
|
||||
- 软件安装节点：1.1.0；1.0.x 可直接安装本节点，同系列补丁可跳过，跨多个 minor 必须逐个安装 .0。1.1.0 包协议 v1，后续包协议 v2。
|
||||
- 固定系统组件：官方 Linux ARM64 frpc 0.71.0，摘要见源码 UPGRADE_POLICY.json；首次默认关闭，已有完整二进制跳过，缺失或损坏自动修复并保留配置和启停状态。
|
||||
|
||||
## 验证证据
|
||||
|
||||
- 本机全套 Python/前端与静态 JavaScript 检查通过。
|
||||
- 复制源码、需求、测试流程及完整其他离线依赖至独立目录，在目标版本 1.1.0 下运行：406 passed、9 skipped。跳过为已登记平台条件。
|
||||
- 最后相关回归：48 passed（版本/组件事务、日志、发布导出）。
|
||||
- 从现有 1.0.3 IMG 的 rootfs 内只读提取真实 package.py 与 ota_worker.py；不修改镜像、不刷写设备。worker SHA-256：`cabac4403146a2f2482a2cba5a9599b2d7542617aed949458dc2a241edfbdb56`。
|
||||
- AArch64 私有 mount namespace 隔离 `/opt`、`/var/lib`、`/run`、`/usr/local/bin`、systemd unit 和 sudoers 目录；真实旧 worker 创建离线 venv、安装 wheel、编译驱动、执行 pytest：413 passed、2 skipped。原生 bitplane 与 fake safeoff 通过。
|
||||
- 真实旧 worker 从 1.0.3 完成候选安装、数据迁移、frpc 安装、程序和数据切换；systemd 命令与最终 HTTP/显示健康结果使用测试替身。专用主机检查在 namespace 外只读完成。
|
||||
- 首轮暴露账户识别遗漏，改为优先读取既有 FRP 账户、镜像首启创建的专用 sudoers，再使用唯一 sudo 普通账户。随后发现当前开发设备并非镜像首启账户布局，隔离夹具补齐与 1.0.3 首启一致的账户策略；同一候选包已通过的完整测试不重复，从失败的迁移入口继续完成验证。
|
||||
- 验证无 frp 安装、已有二进制不重写、损坏二进制和缺 drop-in 修复、开启/启用状态保留。
|
||||
- 注入安装后的失败、切换后的中断、数据两次 rename 之间的中断、服务启动失败、健康检查失败，恢复原程序、用户内容和系统组件。
|
||||
- 真实 1.0.3 包解析器确认拒绝 v2 普通补丁，防止绕过 1.1.0。
|
||||
- 最终补充脚本验证真实 ARM64 安装器保持 active.env 的 0600 权限、完整二进制 mtime 不变、启停状态保留；已有损坏组件先修复，失败后精确恢复原字节及权限。最后仅补充保留原 worker 失败简报的条件判断，并通过本机相关回归。
|
||||
- 正式包已重新解包逐文件核对与最终源码相同，含 246 个文件，只有 software/wheelhouse 顶层，恰好一个已校验 frpc；无 venv、缓存、浏览器产物、持久数据或旧镜像。包摘要、sidecar、manifest、发布记录一致。
|
||||
|
||||
## 调试设备
|
||||
|
||||
- 用户确认设备 SSH 指纹后连接；凭据未归档。
|
||||
- 仅兼容修正旧 worker 的依赖目录查找和组件安装分支，未部署整个应用、未执行正式 OTA、未重启服务。
|
||||
- 原 worker 摘要：`3eec0eab7b2ce2bd43f11cccb0ba3063b2c820532d78abc2e06ba3823f8c33e5`。
|
||||
- 修正后摘要：`219cb5eea3121e2b6b54ff06319900e3fa88199ef43945434d5af13f7aef6bc0`。
|
||||
- 实际开发包解析器成功接收并解压 1.1.0，设备仍报告 1.0.6，主服务 active，frpc 摘要保持原值。
|
||||
- 原 worker 备份保存在随附原始记录归档中。必要时可恢复该单文件；不涉及用户数据。
|
||||
|
||||
## 边界与清理
|
||||
|
||||
真实浏览器安装、真实 systemd 组件监护、整机断电/重启与实屏结果尚未验收；上述模拟结果不代表这些项目通过。用户后续自行上传正式 1.1.0。
|
||||
|
||||
本目录是一次性证据，不得成为源码、日常测试或未来导出的依赖。板端临时验证目录与本机候选包/隔离副本在收集记录后清理；持久测试环境与其他任务文件保留。
|
||||
@@ -0,0 +1,35 @@
|
||||
set -eu
|
||||
python3 - <<'PY'
|
||||
from pathlib import Path
|
||||
import hashlib,os,ast,json
|
||||
root=Path('/opt/matrix-screen-controller')
|
||||
p=root/'scripts/ota_worker.py'
|
||||
original=p.read_bytes()
|
||||
assert hashlib.sha256(original).hexdigest()=='3eec0eab7b2ce2bd43f11cccb0ba3063b2c820532d78abc2e06ba3823f8c33e5', 'worker changed; re-inspect before patching'
|
||||
status=Path('/run/matrix-screen-controller/ota-status.json')
|
||||
assert not status.exists() or not json.loads(status.read_text()).get('active'), 'OTA currently active'
|
||||
s=original.decode('utf-8')
|
||||
old=' frpc_bundle = self.extract_root / "system-dependencies/frpc"'
|
||||
new=' frpc_bundle = software / "system-dependencies/frpc"\n if not frpc_bundle.is_dir():\n frpc_bundle = self.extract_root / "system-dependencies/frpc"'
|
||||
assert s.count(old)==1
|
||||
s=s.replace(old,new)
|
||||
start=s.index(' self.backup_frpc_system()')
|
||||
end=s.index(' self.run(["systemctl", "daemon-reload"]',start)
|
||||
legacy=s[start:end]
|
||||
replacement=' if (self.release / "scripts/ota_components.py").is_file():\n # Candidate migration has already prepared the durable transaction.\n pass\n else:\n'
|
||||
replacement += ''.join(' '+line+'\n' for line in legacy.splitlines())
|
||||
s=s[:start]+replacement+s[end:]
|
||||
ast.parse(s)
|
||||
backup=Path('/var/tmp/matrix-ota110-validation/development-worker-before.py')
|
||||
backup.write_bytes(original)
|
||||
body=s.encode('utf-8')
|
||||
temp=p.with_name('.ota_worker.compat.tmp')
|
||||
with temp.open('wb') as f:
|
||||
f.write(body);f.flush();os.fsync(f.fileno())
|
||||
os.chmod(temp,p.stat().st_mode & 0o777)
|
||||
os.replace(temp,p)
|
||||
print('development_worker_compatibility_patched=true')
|
||||
print('software_version='+ (root/'VERSION').read_text().strip())
|
||||
print('worker_sha256='+hashlib.sha256(p.read_bytes()).hexdigest())
|
||||
print('FRP binary/config and running services unchanged')
|
||||
PY
|
||||
@@ -0,0 +1,139 @@
|
||||
from pathlib import Path
|
||||
import importlib.util, json, os, shutil, subprocess, sys, tarfile, zipfile
|
||||
|
||||
ROOT = Path(__file__).resolve().parent
|
||||
SEED = ROOT/'seed'
|
||||
SEED.mkdir(exist_ok=True)
|
||||
with zipfile.ZipFile(ROOT/'candidate.ota') as z:
|
||||
with z.open('payload.tar.gz') as p, tarfile.open(fileobj=p, mode='r|gz') as t:
|
||||
for m in t:
|
||||
assert m.isfile() and not m.name.startswith('/') and '..' not in Path(m.name).parts
|
||||
out=SEED/m.name;out.parent.mkdir(parents=True,exist_ok=True)
|
||||
out.write_bytes(t.extractfile(m).read());out.chmod(m.mode)
|
||||
sys.path.insert(0,str(SEED/'software'))
|
||||
|
||||
def module(name,path):
|
||||
spec=importlib.util.spec_from_file_location(name,path)
|
||||
m=importlib.util.module_from_spec(spec);sys.modules[name]=m;spec.loader.exec_module(m);return m
|
||||
|
||||
oldpackage=module('app.ota.legacy_package',ROOT/'baseline/package.py')
|
||||
worker=module('legacy_worker',ROOT/'baseline/ota_worker.py')
|
||||
worker.inspect_package=oldpackage.inspect_package
|
||||
worker.extract_payload=oldpackage.extract_payload
|
||||
from scripts import ota_components as c
|
||||
|
||||
def reset():
|
||||
for p in [Path('/opt'),Path('/var/lib'),Path('/run'),Path('/usr/local/bin'),Path('/etc/systemd/system')]:
|
||||
for entry in p.iterdir():
|
||||
if entry.is_dir() and not entry.is_symlink(): shutil.rmtree(entry)
|
||||
else: entry.unlink()
|
||||
c.DATA.mkdir()
|
||||
c.TARGET.mkdir()
|
||||
(c.TARGET/'VERSION').write_text('1.0.3',encoding='utf-8')
|
||||
c.RELEASES.mkdir()
|
||||
(c.DATA/'keep.txt').write_bytes(b'user resource preserved')
|
||||
for name in ('app-unit','ota-unit'):
|
||||
c.FILES[name].write_bytes(('old '+name).encode())
|
||||
|
||||
if '--resume' not in sys.argv:
|
||||
reset()
|
||||
else:
|
||||
assert '413 passed' in (ROOT/'validation.log').read_text(encoding='utf-8',errors='replace')
|
||||
request={'schema_version':1,'job_id':'baseline103','target_version':'1.1.0','current_version':'1.0.3',
|
||||
'package_path':'/opt/candidate.ota','status_path':str(c.RUNTIME/'ota-status.json'),
|
||||
'accepted_at':'2026-09-07T00:00:00Z'}
|
||||
c.RUNTIME.mkdir(parents=True,exist_ok=True)
|
||||
(c.RUNTIME/'ota-request.json').write_text(json.dumps(request),encoding='utf-8')
|
||||
shutil.copy2(ROOT/'candidate.ota',request['package_path'])
|
||||
tx=worker.Transaction(request)
|
||||
tx.start_visual=lambda: None
|
||||
tx.stop_visual=lambda: None
|
||||
actual_run=worker.run
|
||||
def run(command,**kwargs):
|
||||
if any('dedicated_host.py' in p for p in command):
|
||||
print('Dedicated host policy: separately checked outside namespace',flush=True)
|
||||
return
|
||||
actual_run(command,**kwargs)
|
||||
worker.run=run
|
||||
if '--resume' in sys.argv:
|
||||
actual_run([str(tx.release/'.venv/bin/python'),'-m','scripts.prepare_data_root','--data-root',str(tx.data_candidate),'--runtime-root',str(tx.work_root/'migration-runtime')],cwd=tx.release,env={**os.environ,'PYTHONPATH':str(tx.release)})
|
||||
else:
|
||||
tx.prepare()
|
||||
assert c.FILES['frpc'].is_file()
|
||||
assert (c.DATA/c.JOURNAL/'state.json').is_file()
|
||||
tx.switch()
|
||||
# Hardware/HTTP health is intentionally simulated in this isolated filesystem.
|
||||
# The real worker ordering, venv, compile, pytest, migration and installation run.
|
||||
tx.succeed()
|
||||
c.finish()
|
||||
assert (c.TARGET/'VERSION').read_text().strip()=='1.1.0'
|
||||
assert (c.DATA/'keep.txt').read_bytes()==b'user resource preserved'
|
||||
assert not (c.DATA/c.JOURNAL).exists()
|
||||
c.check_installed(c.TARGET,'1.1.0')
|
||||
print('PASS: real 1.0.3 worker -> 1.1.0, actual offline venv/tests/native compile/frpc; simulated service health',flush=True)
|
||||
|
||||
# Exercise idempotence and repair with the actual ARM64 shell installer.
|
||||
bundle=SEED/'software/system-dependencies/frpc'
|
||||
env=os.environ.copy();env['FRPC_BUNDLE']=str(bundle);env['FRPC_RUN_USER']=c.account()
|
||||
installer=['/bin/sh',str(c.TARGET/'scripts/install_frpc_system.sh')]
|
||||
state_path=Path('/run/fake-systemctl.json')
|
||||
state_path.write_text(json.dumps({c.FRP:{'active':True,'enabled':True}}))
|
||||
before=c.FILES['frpc'].stat().st_mtime_ns
|
||||
subprocess.run(installer,env=env,check=True)
|
||||
assert c.FILES['frpc'].stat().st_mtime_ns==before
|
||||
c.FILES['frpc'].write_bytes(b'corrupt')
|
||||
subprocess.run(installer,env=env,check=True)
|
||||
c.check_installed(c.TARGET,'1.1.0')
|
||||
c.FILES['frpc-dropin'].unlink()
|
||||
subprocess.run(installer,env=env,check=True)
|
||||
c.check_installed(c.TARGET,'1.1.0')
|
||||
assert json.loads(state_path.read_text())[c.FRP]=={'active':True,'enabled':True}
|
||||
print('PASS: existing binary skipped; damaged binary and missing drop-in repaired; enabled/active preserved',flush=True)
|
||||
|
||||
# Test independent rollback after the legacy worker switches program and data.
|
||||
for stage in ('installed','switched','data-gap','service-failure','health-failure'):
|
||||
reset()
|
||||
source=c.RELEASES/'1.1.0-baseline103'
|
||||
shutil.copytree(SEED/'software',source)
|
||||
candidate=c.DATA.with_name('matrix-screen-controller.ota.baseline103')
|
||||
shutil.copytree(c.DATA,candidate)
|
||||
c.RUNTIME.mkdir(parents=True,exist_ok=True)
|
||||
(c.RUNTIME/'ota-request.json').write_text(json.dumps(request),encoding='utf-8')
|
||||
c.begin(source,candidate)
|
||||
assert c.FILES['frpc'].exists()
|
||||
if stage in ('service-failure','health-failure'):
|
||||
failed_tx=worker.Transaction(request)
|
||||
failed_tx.work_root.mkdir(parents=True)
|
||||
failed_tx.start_visual=lambda: None
|
||||
failed_tx.stop_visual=lambda: None
|
||||
if stage=='service-failure':
|
||||
state_path.write_text(json.dumps({'start_fail_once':c.SERVICE}))
|
||||
try:
|
||||
failed_tx.switch()
|
||||
raise RuntimeError('injected health failure')
|
||||
except Exception as error:
|
||||
failed_tx.rollback(error)
|
||||
if stage in ('switched','data-gap'):
|
||||
c.TARGET.rename(c.RELEASES/'1.0.3-pre-ota-baseline103')
|
||||
c.TARGET.symlink_to(source,target_is_directory=True)
|
||||
c.DATA.rename(c.DATA.with_name('matrix-screen-controller.rollback.baseline103'))
|
||||
if stage=='switched': candidate.rename(c.DATA)
|
||||
c.finish(boot=True)
|
||||
assert (c.TARGET/'VERSION').read_text().strip()=='1.0.3'
|
||||
assert (c.DATA/'keep.txt').read_bytes()==b'user resource preserved'
|
||||
assert not c.FILES['frpc'].exists()
|
||||
assert not (c.DATA/c.JOURNAL).exists()
|
||||
print('PASS: component/application interruption recovery '+stage,flush=True)
|
||||
|
||||
# v2 patch must fail in the real old parser, even without its own path policy.
|
||||
from app.ota.package import build_package
|
||||
from app.ota.versioning import SoftwareVersion
|
||||
mini=ROOT/'patch-source';mini.mkdir(exist_ok=True)
|
||||
(mini/'VERSION').write_text('1.1.1',encoding='utf-8')
|
||||
patch=ROOT/'patch.ota';patch.unlink(missing_ok=True)
|
||||
build_package(mini,SEED/'wheelhouse',patch,version=SoftwareVersion.parse('1.1.1'),release_notes='gate test')
|
||||
try:
|
||||
oldpackage.inspect_package(patch,current_version=SoftwareVersion.parse('1.0.3'))
|
||||
except oldpackage.OtaPackageError:
|
||||
print('PASS: real 1.0.3 parser rejects v2 patch before installation',flush=True)
|
||||
else: raise AssertionError('legacy updater accepted patch')
|
||||
@@ -0,0 +1,44 @@
|
||||
set -eu
|
||||
ROOT=/var/tmp/matrix-ota110-validation
|
||||
export ROOT
|
||||
mkdir -p "$ROOT/fs/sudoers"
|
||||
python3 - "$ROOT/fs/sudoers/90-matrix-screen-controller-account" <<'PY'
|
||||
from pathlib import Path
|
||||
import re,pwd,sys
|
||||
text=Path('/etc/systemd/system/matrix-screen-frpc.service.d/user.conf').read_text(encoding='utf-8')
|
||||
users=re.findall(r'^User=([a-zA-Z0-9_-]+)$',text,re.M)
|
||||
assert len(users)==1 and pwd.getpwnam(users[0]).pw_uid!=0
|
||||
Path(sys.argv[1]).write_text(users[0]+' ALL=(ALL:ALL) ALL'+chr(10),encoding='utf-8')
|
||||
PY
|
||||
mkdir -p "$ROOT/fs/opt" "$ROOT/fs/varlib" "$ROOT/fs/run" "$ROOT/fs/bin" "$ROOT/fs/units" "$ROOT/fake-bin"
|
||||
cat > "$ROOT/fake-bin/systemctl" <<'PY'
|
||||
#!/usr/bin/python3
|
||||
import sys,json
|
||||
from pathlib import Path
|
||||
if Path(sys.argv[0]).name=='systemd-run': sys.exit(0)
|
||||
args=sys.argv[1:];state_path=Path('/run/fake-systemctl.json')
|
||||
state=json.loads(state_path.read_text()) if state_path.exists() else {}
|
||||
cmd=args[0] if args else '';unit=args[-1] if args else ''
|
||||
if cmd in ('is-active','is-enabled'): sys.exit(0 if state.get(unit,{}).get('active' if cmd=='is-active' else 'enabled',False) else 1)
|
||||
if cmd=='show': print('inactive')
|
||||
if cmd in ('enable','disable','start','stop'):
|
||||
if cmd=='start' and state.get('start_fail_once')==unit:
|
||||
del state['start_fail_once'];state_path.write_text(json.dumps(state));sys.exit(1)
|
||||
entry=state.setdefault(unit,{})
|
||||
entry['active' if cmd in ('start','stop') else 'enabled']=cmd in ('start','enable')
|
||||
state_path.write_text(json.dumps(state))
|
||||
sys.exit(0)
|
||||
PY
|
||||
cp "$ROOT/fake-bin/systemctl" "$ROOT/fake-bin/systemd-run"
|
||||
chmod 755 "$ROOT/fake-bin/systemctl" "$ROOT/fake-bin/systemd-run"
|
||||
export PATH="$ROOT/fake-bin:$PATH"
|
||||
unshare --mount --propagation private /bin/sh -c '
|
||||
set -eu
|
||||
mount --bind "$ROOT/fs/opt" /opt
|
||||
mount --bind "$ROOT/fs/varlib" /var/lib
|
||||
mount --bind "$ROOT/fs/run" /run
|
||||
mount --bind "$ROOT/fs/bin" /usr/local/bin
|
||||
mount --bind "$ROOT/fs/units" /etc/systemd/system
|
||||
mount --bind "$ROOT/fs/sudoers" /etc/sudoers.d
|
||||
python3 "$ROOT/${TEST_SCRIPT:-ota110_integration.py}" ${TEST_ARG:-}
|
||||
'
|
||||
@@ -0,0 +1,44 @@
|
||||
from pathlib import Path
|
||||
import importlib.util, json, os, shutil, subprocess, sys
|
||||
ROOT=Path(__file__).resolve().parent
|
||||
seed=ROOT/'seed/software'
|
||||
sys.path.insert(0,str(seed))
|
||||
spec=importlib.util.spec_from_file_location('latest_components',ROOT/'latest/ota_components.py')
|
||||
c=importlib.util.module_from_spec(spec);spec.loader.exec_module(c)
|
||||
for root in (Path('/opt'),Path('/var/lib'),Path('/run'),Path('/usr/local/bin'),Path('/etc/systemd/system')):
|
||||
for path in root.iterdir():
|
||||
if path.is_dir() and not path.is_symlink(): shutil.rmtree(path)
|
||||
else: path.unlink()
|
||||
c.DATA.mkdir();c.TARGET.mkdir();c.RELEASES.mkdir();c.RUNTIME.mkdir(parents=True)
|
||||
(c.TARGET/'VERSION').write_text('1.0.6',encoding='utf-8')
|
||||
for name in ('app-unit','ota-unit'): c.FILES[name].write_bytes(('old '+name).encode())
|
||||
source=c.RELEASES/'1.1.0-supplement'
|
||||
shutil.copytree(seed,source)
|
||||
for name in ('ota_components.py','install_frpc_system.sh'):
|
||||
shutil.copy2(ROOT/'latest'/name,source/'scripts'/name)
|
||||
env=os.environ.copy();env['FRPC_RUN_USER']=c.account();env['FRPC_BUNDLE']=str(source/'system-dependencies/frpc')
|
||||
installer=['/bin/sh',str(source/'scripts/install_frpc_system.sh')]
|
||||
subprocess.run(installer,env=env,check=True,capture_output=True)
|
||||
active=c.DATA/'frp/active.env';active.write_bytes(b'# isolated fixture\n');active.chmod(0o600)
|
||||
state=Path('/run/fake-systemctl.json');state.write_text(json.dumps({c.FRP:{'active':True,'enabled':True}}),encoding='utf-8')
|
||||
before=c.FILES['frpc'].stat().st_mtime_ns
|
||||
subprocess.run(installer,env=env,check=True,capture_output=True)
|
||||
assert before==c.FILES['frpc'].stat().st_mtime_ns
|
||||
c.check_installed(source,'1.1.0')
|
||||
assert active.stat().st_mode & 0o777 == 0o600
|
||||
assert json.loads(state.read_text(encoding='utf-8'))[c.FRP]=={'active':True,'enabled':True}
|
||||
print('PASS: final installer idempotence, active.env 0600, active/enabled state preserved')
|
||||
original=c.FILES['frpc'].read_bytes()
|
||||
c.FILES['frpc'].write_bytes(b'corrupt-before-OTA')
|
||||
candidate=c.DATA.with_name('matrix-screen-controller.ota.supplement');shutil.copytree(c.DATA,candidate)
|
||||
request={'schema_version':1,'job_id':'supplement','current_version':'1.0.6','target_version':'1.1.0','accepted_at':'2026-09-07T00:00:00Z'}
|
||||
(c.RUNTIME/'ota-request.json').write_text(json.dumps(request),encoding='utf-8')
|
||||
c.begin(source,candidate)
|
||||
assert c.FILES['frpc'].read_bytes()==original
|
||||
c.finish(boot=True)
|
||||
assert c.FILES['frpc'].read_bytes()==b'corrupt-before-OTA'
|
||||
assert active.read_bytes()==b'# isolated fixture\n'
|
||||
assert active.stat().st_mode & 0o777 == 0o600
|
||||
assert json.loads(state.read_text(encoding='utf-8'))[c.FRP]=={'active':True,'enabled':True}
|
||||
assert not (c.DATA/c.JOURNAL).exists()
|
||||
print('PASS: final component transaction repairs then exactly restores preinstalled FRP and permissions on failure')
|
||||
Binary file not shown.
@@ -0,0 +1,22 @@
|
||||
{
|
||||
"schema_version": 1,
|
||||
"artifact_type": "image",
|
||||
"image_sha256": "8356b75ef970891db951a08429f8e2d21a6c0c4933065001778e10d74022c19d",
|
||||
"software_version": "1.1.1",
|
||||
"status": "success",
|
||||
"firstboot_completed": true,
|
||||
"automatic_reboot_passed": true,
|
||||
"default_wifi_connected": true,
|
||||
"ssh_password_login_passed": true,
|
||||
"sudo_password_passed": true,
|
||||
"root_login_rejected": true,
|
||||
"networkmanager_passed": true,
|
||||
"controller_service_passed": true,
|
||||
"kernel_health_passed": true,
|
||||
"h618_mapping_passed": true,
|
||||
"web_ui_passed": true,
|
||||
"plaintext_config_removed": true,
|
||||
"machine_identity_regenerated": true,
|
||||
"second_reboot_passed": true,
|
||||
"validated_at": "2026-09-08T16:32:38+08:00"
|
||||
}
|
||||
@@ -0,0 +1,22 @@
|
||||
# 奇妙小屏幕控制器 OTA 1.1.0
|
||||
|
||||
- 软件版本：`1.1.0`
|
||||
- 导出时间：`2026-09-07T22:02:12+08:00`
|
||||
- 说明：软件安装包（必经升级版本）：离线安装或修复 frpc 0.71.0，保留已有配置和启停状态；建立逐 minor .0 升级门槛、普通补丁跳版本及组件事务恢复。
|
||||
- 产物：`matrix-screen-controller-1.1.0.ota`
|
||||
|
||||
- 包类型：软件安装包（必经升级版本）
|
||||
- 前置系列基线：`1.0.0`
|
||||
|
||||
在系统设置上传 OTA；每个 minor 的 .0 必须按顺序安装，同系列补丁允许跳过。1.1.0 含 frpc 0.71.0 离线组件；已有完整组件会跳过，否则修复并保留配置和启停状态。初次安装默认关闭。禁止跳过失败测试；失败自动恢复。
|
||||
|
||||
本目录是可删除的发布产物，不得被源码、脚本或后续版本引用。
|
||||
|
||||
## 本次安装
|
||||
|
||||
1. 正常 1.0.x 旧版本先安装本包，不要直接安装未来的 1.1.x 补丁。当前已预装 frp 的调试设备也安装同一份包；其旧 OTA worker 已完成必要兼容修正，设备版本仍为 1.0.6。
|
||||
2. 打开设备网页的“系统设置 → 软件更新”，选择 `matrix-screen-controller-1.1.0.ota`，无需解压。
|
||||
3. 安装会执行完整测试并检查 frp；已有完整组件跳过，缺失或损坏自动离线修复。等待页面恢复后确认软件版本为 1.1.0。
|
||||
4. 完成 1.1.0 后可以跳过同系列补丁，例如直接安装 1.1.3；未来跨到 1.2 系列时必须先安装 1.2.0。
|
||||
|
||||
本机测试、板端 AArch64 隔离安装/回滚和真实旧包解析器兼容检查已通过。真实网页 OTA、真实 systemd 监护、整机断电/重启与实屏尚未验收；未自动替你安装本正式包。一次性验证记录保存在项目的 `各种归档/20260907_OTA1.1.0软件安装节点验证/`，不作为后续构建依赖。
|
||||
@@ -0,0 +1,13 @@
|
||||
{
|
||||
"format_version": 1,
|
||||
"artifact_type": "ota",
|
||||
"software_version": "1.1.0",
|
||||
"created_at": "2026-09-07T22:02:12+08:00",
|
||||
"notes": "软件安装包（必经升级版本）：离线安装或修复 frpc 0.71.0，保留已有配置和启停状态；建立逐 minor .0 升级门槛、普通补丁跳版本及组件事务恢复。",
|
||||
"artifact": "matrix-screen-controller-1.1.0.ota",
|
||||
"artifact_bytes": 27993930,
|
||||
"artifact_sha256": "379f80a30157e23d717157005ea246fa822529010c0f0295dcad5db3ceff42c5",
|
||||
"package_kind": "software-install",
|
||||
"required_checkpoint": "1.0.0",
|
||||
"is_checkpoint": true
|
||||
}
|
||||
Binary file not shown.
@@ -0,0 +1 @@
|
||||
379f80a30157e23d717157005ea246fa822529010c0f0295dcad5db3ceff42c5 matrix-screen-controller-1.1.0.ota
|
||||
@@ -0,0 +1,76 @@
|
||||
{
|
||||
"schema_version": 1,
|
||||
"releases": [
|
||||
{
|
||||
"version": "1.0.1",
|
||||
"artifact_type": "ota",
|
||||
"created_at": "2026-08-13T15:31:23+08:00",
|
||||
"notes": "新增浏览器全量 OTA。",
|
||||
"artifact_path": "OTA数据包/1.0.1/matrix-screen-controller-1.0.1.ota",
|
||||
"artifact_sha256": "1ae8544e2072a014dc76e07a930375c80e85b5331957716a456c8123dd204325"
|
||||
},
|
||||
{
|
||||
"version": "1.0.2",
|
||||
"artifact_type": "image",
|
||||
"created_at": "2026-08-19T15:42:35+08:00",
|
||||
"notes": "建立可刷镜像、离线首次启动和 Windows 镜像编辑能力；修复并真实验证 SSH 默认启用、配置账户密码登录、需同密码完整 sudo 权限、root 登录禁用、sshd 易失运行目录、首启 unit 超时与假成功，以及基础镜像 rootpw、旧 pi 免密规则和主机名解析延迟。",
|
||||
"artifact_path": "离线依赖/导出包/1.0.2/matrix-screen-controller-1.0.2.img",
|
||||
"artifact_sha256": "0397b2abd974cc293a472789027b02bf469434d358578fd43aa9fdb218944aeb"
|
||||
},
|
||||
{
|
||||
"version": "1.0.3",
|
||||
"artifact_type": "image",
|
||||
"created_at": "2026-08-25T08:17:48+00:00",
|
||||
"notes": "修复 1.0.3 首次启动 FAT 空间不足：应用离线载荷迁入 rootfs，增加候选内核 boot 文件预算与 32 MiB 安全余量双重校验，并修复导出入口误加载 Pillow/FontTools。",
|
||||
"artifact_path": "离线依赖/导出包/1.0.3/matrix-screen-controller-1.0.3.img",
|
||||
"artifact_sha256": "a5676576fb63a913ed9e40a02ce206e5ef71f47b1005a98a8758479b51413e0b"
|
||||
},
|
||||
{
|
||||
"version": "1.0.4",
|
||||
"artifact_type": "ota",
|
||||
"created_at": "2026-09-04T13:14:05+08:00",
|
||||
"notes": "发布当前工作区已完成并通过本机全套测试的软件版本。",
|
||||
"artifact_path": "OTA数据包/1.0.4/matrix-screen-controller-1.0.4.ota",
|
||||
"artifact_sha256": "ed15498e2d66758343c874d00176e2525e67a69fea5cc8f4578f139dd2b0f766"
|
||||
},
|
||||
{
|
||||
"version": "1.0.5",
|
||||
"artifact_type": "ota",
|
||||
"created_at": "2026-09-06T21:10:58+08:00",
|
||||
"notes": "修复 OTA 板端测试目录隔离，并新增可查看、复制的详细失败日志。",
|
||||
"artifact_path": "OTA数据包/1.0.5/matrix-screen-controller-1.0.5.ota",
|
||||
"artifact_sha256": "ec245d2ba2eefdf415f6745aefb1dfc66631e027d6820a2b6bd04bd6306d4152"
|
||||
},
|
||||
{
|
||||
"version": "1.0.6",
|
||||
"artifact_type": "ota",
|
||||
"created_at": "2026-09-06T21:39:45+08:00",
|
||||
"notes": "诊断引导包：经设备持有者授权，仅在 1.0.3 旧 worker 中跳过 pytest，以先安装可查看、复制的 OTA 失败日志；后续更新恢复严格测试。",
|
||||
"artifact_path": "OTA数据包/1.0.6/matrix-screen-controller-1.0.6.ota",
|
||||
"artifact_sha256": "8e804dcfb1f2f9194f3c57b88b5d4b7308509270fba536059e528ab21fdfa0b9"
|
||||
},
|
||||
{
|
||||
"version": "1.1.0",
|
||||
"artifact_type": "ota",
|
||||
"created_at": "2026-09-07T22:02:12+08:00",
|
||||
"notes": "软件安装包（必经升级版本）：离线安装或修复 frpc 0.71.0，保留已有配置和启停状态；建立逐 minor .0 升级门槛、普通补丁跳版本及组件事务恢复。",
|
||||
"artifact_path": "OTA数据包/1.1.0/matrix-screen-controller-1.1.0.ota",
|
||||
"artifact_sha256": "379f80a30157e23d717157005ea246fa822529010c0f0295dcad5db3ceff42c5",
|
||||
"package_kind": "software-install",
|
||||
"required_checkpoint": "1.0.0",
|
||||
"is_checkpoint": true,
|
||||
"component_checkpoints": [
|
||||
{
|
||||
"version": "1.1.0",
|
||||
"components": {
|
||||
"frpc": {
|
||||
"version": "0.71.0",
|
||||
"sha256": "6e8e45fd0c7514b636fd8d049212f8a5715e8b33c412cf968988252e7a8a00f2",
|
||||
"bundle": "frp/0.71.0/linux-arm64"
|
||||
}
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
@@ -0,0 +1,18 @@
|
||||
{
|
||||
"package_sha256": "7f33a417181633e1f4c77f48a3030d33f6c6e9578002e22f3b0487aff535eef8",
|
||||
"installed_version": "1.1.0",
|
||||
"status": "success",
|
||||
"runtime_lifecycle_passed": true,
|
||||
"user_data_preserved": true,
|
||||
"frp_state_preserved": true,
|
||||
"transaction_cleanup_passed": true,
|
||||
"user_file_count": 421,
|
||||
"job_id": "86cbcfe541894bb6b07c52b17fb5f3f3",
|
||||
"verified_at": "2026-09-08T02:31:22.720144+00:00",
|
||||
"frp_active": "inactive",
|
||||
"frp_enabled": "disabled",
|
||||
"disk_version": "1.1.0",
|
||||
"api_version": "1.1.0",
|
||||
"feature_updated_at": "2026-09-08T10:19+08:00",
|
||||
"screen_visual_acceptance": "not_performed"
|
||||
}
|
||||
@@ -0,0 +1,27 @@
|
||||
# 1.1.0 OTA 运行目录修复验收
|
||||
|
||||
2026-09-08 已在测试设备实际完成 1.0.6 → 1.1.0。磁盘 VERSION、运行 API 均为 1.1.0，OTA worker Result=success，用户数据 421 个非 OTA 文件摘要完全一致，frpc 二进制摘要保持，服务仍 inactive / disabled。组件完整性校验通过，恢复事务、临时保护、恢复 unit/helper、上传包与工作目录均已清理。
|
||||
|
||||
正式产物为 `发布更新相关/OTA数据包/1.1.0/matrix-screen-controller-1.1.0.ota`，27998979 字节，SHA-256 为 `7f33a417181633e1f4c77f48a3030d33f6c6e9578002e22f3b0487aff535eef8`。发布时直接复制实机验收候选，逐字节确认一致，未重新构建。VERSION 保持 1.1.0，FEATURE_UPDATED_AT 为 `2026-09-08T10:19+08:00`。旧包摘要 `379f80a30157e23d717157005ea246fa822529010c0f0295dcad5db3ceff42c5`，完整旧产物和旧发布记录归档位置见根发布记录的 repairs 字段。
|
||||
|
||||
## 故障与修复
|
||||
|
||||
原 1.1.0 安装过程中，旧 unit 的 RuntimeDirectoryPreserve=restart 在独立 stop 时删除共享 /run 目录，升级日志和回滚日志连续 FileNotFoundError；独立组件监护恢复了 1.0.6。因此显示 1.0.6 代表升级失败恢复，不能宣称升级成功。
|
||||
|
||||
主服务改为 Preserve=yes。候选迁移入口在停止旧服务之前创建标准运行期 drop-in、daemon-reload 并核验有效策略；保护直到提交或恢复完成，随后清理。日志目录丢失会重建，写入失败保留有限缓冲，避免日志异常阻止恢复。该约束已写入 AGENTS.md、源码 README、稳定需求和测试流程。
|
||||
|
||||
首轮修复候选发现保护残留检查位置错误，安装后校验误拒绝本次事务保护。该候选未发布；完整板端测试 420 passed / 2 skipped 后进入迁移失败恢复，421 个用户文件和 frp 状态保持，原始失败原因和日志保留，临时事务清理通过。随后将残留检查移至事务开始之前，并新增组件校验允许本事务保护的回归测试。
|
||||
|
||||
## 验证及证据
|
||||
|
||||
- 最终候选隔离目录完整 pytest：414 passed、9 skipped；完整其他离线依赖复制后验证，未引用历史镜像导出目录。最初仅解包 OTA 的隔离目录缺少镜像构建材料，已补全离线依赖后重新完整测试通过，无跳过失败用例。
|
||||
- 最终候选前端测试：76 passed；本机完整前端和 JavaScript 语法、文案目录检查通过。隔离目录重新打包通过，其测试构建不用于发布。
|
||||
- 最终实机 OTA 的完整 pytest：421 passed、2 skipped，358.28 秒。跳过为源码 OTA 不含镜像材料及已登记平台条件；保留完整测试门槛。
|
||||
- 真实 systemd 专用临时 unit 复现 restart 在独立 stop 时删除目录，生产保护函数验证 stop、restart、启动失败后请求/进度/日志字节不变，测试 unit 清理通过。该项未使用 systemctl 替身。
|
||||
- 实际 OTA 采样 7 次观察到临时保护存在、有效 Preserve=yes，请求/状态/日志均存在；最终保护清理成功。见 ota-evidence.json。
|
||||
- 从原 1.0.3 镜像已只读提取的真实解析器再次校验和解包最终候选通过，仅 software / wheelhouse 顶层，恰好一份 frpc 离线二进制。
|
||||
- 原有组件失败恢复、升级门槛、日志故障、同版本发布与发布失败原产物保留回归均包含在完整 pytest 中。原 1.0.3 worker 的隔离故障矩阵证据仍保留在 20260907 归档，该矩阵使用过 systemctl 替身，不替代此次真实 systemd 与真实 OTA 验收。
|
||||
|
||||
本次没有执行人工实屏视觉、断电或整机重启验收，不把软件成功等同于这些结果通过。升级前完整持久数据备份仅在设备受限临时目录保存，验收及发布完成后清理，不复制用户配置或凭据到普通归档。
|
||||
|
||||
设备临时验证目录及受限备份已清理。本机 `如何测试/本机测试环境/work/ota-runtime-repair/` 的递归清理被自动安全策略拒绝（blocked by policy，未提供更具体原因），因此仍保留候选和隔离测试文件；它们不属于正式产物，不被后续构建引用。
|
||||
@@ -0,0 +1 @@
|
||||
<仓库根目录>\测试相关资料\如何测试\本机测试环境\work\ota-runtime-repair\final-isolated-build\1.1.0
|
||||
@@ -0,0 +1,84 @@
|
||||
✔ derives automatic frame names from current animation name and position (0.6403ms)
|
||||
✔ keeps custom frame names and restores automatic names when cleared (0.0937ms)
|
||||
✔ builds non-repeating animation edit context names (0.0948ms)
|
||||
✔ selects saved animation preview frames by ordered durations (0.6116ms)
|
||||
✔ loads every preview frame through revision-checked pagination (1.3323ms)
|
||||
✔ validates configurable animation preview concurrency (0.2673ms)
|
||||
✔ rejects mixed revisions instead of showing a partial animation (0.3507ms)
|
||||
✔ validates frame duration only when explicitly called (0.3759ms)
|
||||
✔ moves selected frames as one ordered group (0.2669ms)
|
||||
✔ protects an eight pixel ring around interactive drag controls (0.1664ms)
|
||||
✔ reorders mixed library keys without mutating the source list (0.1138ms)
|
||||
✔ restores drag eligibility after protected pointer cancellation and drag end (0.3556ms)
|
||||
✔ animation workspace exposes two previews and the simplified control order (6.8075ms)
|
||||
✔ normal and pixel modes expose independent ranges and presets (1.1726ms)
|
||||
✔ pixel stamps are exact squares from 1x1 through 4x4 (0.2138ms)
|
||||
✔ pixel stamps clip at every canvas edge (0.1787ms)
|
||||
✔ normal circle geometry remains unchanged (0.0899ms)
|
||||
✔ line interpolation includes endpoints without coordinate gaps (0.1821ms)
|
||||
✔ v1 tools migrate into normal mode while v2 restores both sizes (0.2555ms)
|
||||
✔ pixel mode markup and grid stay accessible and non-interactive (6.9068ms)
|
||||
✔ pixel undo history stores changed snapshots, caps entries, and clears (0.5017ms)
|
||||
✔ canvas view clamps scale and keeps a visible section in the viewport (0.4704ms)
|
||||
✔ zooming around an anchor preserves its logical position (0.2555ms)
|
||||
✔ floating editor button stays inside its safe viewport bounds (0.1233ms)
|
||||
✔ canvas editor markup, guarded input, and checkpoint events stay wired (1.9429ms)
|
||||
✔ normalizes and converts hexadecimal colors (1.1363ms)
|
||||
✔ converts RGB and HSV boundaries (0.2535ms)
|
||||
✔ round trips representative colors within 8-bit rounding (0.9763ms)
|
||||
✔ recent colors deduplicate, normalize, and evict the oldest (0.2321ms)
|
||||
✔ formats and projects looping playback without moving paused content (1.0057ms)
|
||||
✔ seek dispatcher keeps one request in flight and flushes the newest position (2.948ms)
|
||||
✔ topbar current display dialog exposes static close and animation controls (3.2173ms)
|
||||
✔ device workspace exposes the compact immediate pure-color test flow (5.2123ms)
|
||||
✔ font catalog normalization, grouping, and search are stable (1.7571ms)
|
||||
✔ font picker implements commit-only searchable combobox keyboard behavior (2.9703ms)
|
||||
✔ settings places unrestricted FRP maintenance at the bottom (4.612ms)
|
||||
✔ FRP editor uses raw server storage and official validation errors (1.0223ms)
|
||||
✔ network diagnostics renders layered evidence (1.448ms)
|
||||
✔ unavailable controls never masquerade as indefinite loading (5.6542ms)
|
||||
✔ action controls do not bypass the shared state module (6.0127ms)
|
||||
✔ HTTP requests time out with a stable user-facing error (18.0299ms)
|
||||
✔ demo library actions stay black, explain restrictions, and preserve copy (1.1572ms)
|
||||
✔ sortable cards protect controls and keep demo cards fixed (1.0358ms)
|
||||
✔ media import workspace exposes streaming upload, crop controls, and queue polling (1.1099ms)
|
||||
✔ free framing starts from the complete source and keeps one pixel visible (0.6589ms)
|
||||
✔ free framing copy is stable and catalogued (0.0881ms)
|
||||
✔ upload action has visible ordinary-build copy (0.193ms)
|
||||
✔ media naming happens after analysis and conflicts keep the draft (0.1455ms)
|
||||
✔ awaiting-settings cards survive polling without hiding server transitions (0.1182ms)
|
||||
✔ creates a fixed 64x64 RGB scene (1.9085ms)
|
||||
✔ serializes pixelRgb as base64 and round trips an independent scene (6.1668ms)
|
||||
✔ moves a valid v1 draft to the stable key before removing exact legacy keys (9.1938ms)
|
||||
✔ keeps the v1 draft and all legacy keys when stable-key migration cannot write (2.3183ms)
|
||||
✔ preserves and blocks a future stable draft instead of falling back or writing blank (1.224ms)
|
||||
✔ preserves and blocks a damaged stable draft (0.4343ms)
|
||||
✔ does not discard a damaged higher-priority legacy key during fallback migration (1.1675ms)
|
||||
✔ rejects damaged scene roots while skipping only damaged elements (0.6392ms)
|
||||
✔ normalizes text fields and creates a centered lowercase ok element (0.2164ms)
|
||||
✔ migrates the first valid canvas by v3, v2, legacy priority and merges text v1 (8.2449ms)
|
||||
✔ supports independent add, update, and delete operations for multiple text elements (0.5292ms)
|
||||
✔ duplicates with a deep copy, new id, 2px offset, and topmost order (0.3276ms)
|
||||
✔ alpha-composites full RGBA layers in array order without mutating inputs (1.1463ms)
|
||||
✔ settings brightness explains an active temporary display-test override (5.305ms)
|
||||
✔ settings exposes full OTA upload progress and service recovery polling (2.9085ms)
|
||||
✔ settings automatically opens and safely copies a detailed OTA failure log (1.5356ms)
|
||||
✔ settings exposes a transactional performance-mode switch with the fixed warning (1.3568ms)
|
||||
✔ settings exposes persisted animation preview concurrency below performance mode (1.3258ms)
|
||||
✔ template edit baseline distinguishes clean, dirty, and unbound scenes (0.9501ms)
|
||||
✔ template manager uses a monitor and unified four-row card actions (6.2269ms)
|
||||
✔ animation editing backs up and restores template edit ownership (1.0747ms)
|
||||
✔ special editor exposes the agreed modes and guarded editing flow (6.7948ms)
|
||||
✔ latched WiFi draft state remains dirty until explicitly cleared (1.022ms)
|
||||
✔ WiFi settings expose independent network and prompt-delay controls (2.1695ms)
|
||||
✔ workspace order resolves saved ids and appends new registrations (1.0454ms)
|
||||
✔ workspace order movement is immutable and respects both boundaries (0.2573ms)
|
||||
✔ drawer exposes one editable list and commits only from the save action (5.2391ms)
|
||||
ℹ tests 76
|
||||
ℹ suites 0
|
||||
ℹ pass 76
|
||||
ℹ fail 0
|
||||
ℹ cancelled 0
|
||||
ℹ skipped 0
|
||||
ℹ todo 0
|
||||
ℹ duration_ms 502.5316
|
||||
@@ -0,0 +1,91 @@
|
||||
........................................................................ [ 17%]
|
||||
........................................................................ [ 34%]
|
||||
........................................................................ [ 51%]
|
||||
.............................sssssss.......s............................ [ 68%]
|
||||
...............s........................................................ [ 85%]
|
||||
............................................................... [100%]
|
||||
============================== warnings summary ===============================
|
||||
..\..\..\..\.venv\Lib\site-packages\fastapi\routing.py:234: 81 warnings
|
||||
tests/test_animations.py: 891 warnings
|
||||
tests/test_api.py: 2025 warnings
|
||||
tests/test_fonts.py: 243 warnings
|
||||
tests/test_frp.py: 324 warnings
|
||||
tests/test_library_order.py: 324 warnings
|
||||
tests/test_media_conversion.py: 810 warnings
|
||||
tests/test_ota.py: 243 warnings
|
||||
tests/test_performance_mode.py: 81 warnings
|
||||
tests/test_templates.py: 648 warnings
|
||||
tests/test_ui_copy_editor.py: 585 warnings
|
||||
<仓库根目录>\测试相关资料\如何测试\本机测试环境\.venv\Lib\site-packages\fastapi\routing.py:234: DeprecationWarning: 'asyncio.iscoroutinefunction' is deprecated and slated for removal in Python 3.16; use inspect.iscoroutinefunction() instead
|
||||
is_coroutine = asyncio.iscoroutinefunction(dependant.call)
|
||||
|
||||
app\main.py:2024: 1 warning
|
||||
tests/test_animations.py: 11 warnings
|
||||
tests/test_api.py: 25 warnings
|
||||
tests/test_fonts.py: 3 warnings
|
||||
tests/test_frp.py: 4 warnings
|
||||
tests/test_library_order.py: 4 warnings
|
||||
tests/test_media_conversion.py: 10 warnings
|
||||
tests/test_ota.py: 3 warnings
|
||||
tests/test_performance_mode.py: 1 warning
|
||||
tests/test_templates.py: 8 warnings
|
||||
tests/test_ui_copy_editor.py: 7 warnings
|
||||
<仓库根目录>\测试相关资料\如何测试\本机测试环境\work\ota-runtime-repair\isolated-final\software\app\main.py:2024: DeprecationWarning:
|
||||
on_event is deprecated, use lifespan event handlers instead.
|
||||
|
||||
Read more about it in the
|
||||
[FastAPI docs for Lifespan Events](https://fastapi.tiangolo.com/advanced/events/).
|
||||
|
||||
@app.on_event("startup")
|
||||
|
||||
..\..\..\..\.venv\Lib\site-packages\fastapi\applications.py:4495: 2 warnings
|
||||
tests/test_animations.py: 22 warnings
|
||||
tests/test_api.py: 50 warnings
|
||||
tests/test_fonts.py: 6 warnings
|
||||
tests/test_frp.py: 8 warnings
|
||||
tests/test_library_order.py: 8 warnings
|
||||
tests/test_media_conversion.py: 20 warnings
|
||||
tests/test_ota.py: 6 warnings
|
||||
tests/test_performance_mode.py: 2 warnings
|
||||
tests/test_templates.py: 16 warnings
|
||||
tests/test_ui_copy_editor.py: 14 warnings
|
||||
<仓库根目录>\测试相关资料\如何测试\本机测试环境\.venv\Lib\site-packages\fastapi\applications.py:4495: DeprecationWarning:
|
||||
on_event is deprecated, use lifespan event handlers instead.
|
||||
|
||||
Read more about it in the
|
||||
[FastAPI docs for Lifespan Events](https://fastapi.tiangolo.com/advanced/events/).
|
||||
|
||||
return self.router.on_event(event_type)
|
||||
|
||||
app\main.py:2047: 1 warning
|
||||
tests/test_animations.py: 11 warnings
|
||||
tests/test_api.py: 25 warnings
|
||||
tests/test_fonts.py: 3 warnings
|
||||
tests/test_frp.py: 4 warnings
|
||||
tests/test_library_order.py: 4 warnings
|
||||
tests/test_media_conversion.py: 10 warnings
|
||||
tests/test_ota.py: 3 warnings
|
||||
tests/test_performance_mode.py: 1 warning
|
||||
tests/test_templates.py: 8 warnings
|
||||
tests/test_ui_copy_editor.py: 7 warnings
|
||||
<仓库根目录>\测试相关资料\如何测试\本机测试环境\work\ota-runtime-repair\isolated-final\software\app\main.py:2047: DeprecationWarning:
|
||||
on_event is deprecated, use lifespan event handlers instead.
|
||||
|
||||
Read more about it in the
|
||||
[FastAPI docs for Lifespan Events](https://fastapi.tiangolo.com/advanced/events/).
|
||||
|
||||
@app.on_event("shutdown")
|
||||
|
||||
tests/test_media_conversion.py::test_free_crop_can_leave_only_one_source_pixel_visible_at_each_corner
|
||||
tests/test_media_conversion.py::test_free_crop_can_leave_only_one_source_pixel_visible_at_each_corner
|
||||
tests/test_media_conversion.py::test_free_crop_can_leave_only_one_source_pixel_visible_at_each_corner
|
||||
tests/test_media_conversion.py::test_free_crop_can_leave_only_one_source_pixel_visible_at_each_corner
|
||||
<仓库根目录>\测试相关资料\如何测试\本机测试环境\work\ota-runtime-repair\isolated-final\software\tests\test_media_conversion.py:134: DeprecationWarning: Image.Image.getdata is deprecated and will be removed in Pillow 14 (2027-10-15). Use get_flattened_data instead.
|
||||
assert sum(pixel[0] > 240 for pixel in output.getdata()) == 1
|
||||
|
||||
tests/test_templates.py::test_template_crud_copy_persistence_and_thumbnail_cleanup
|
||||
<仓库根目录>\测试相关资料\如何测试\本机测试环境\work\ota-runtime-repair\isolated-final\software\tests\test_templates.py:165: DeprecationWarning: Image.Image.getdata is deprecated and will be removed in Pillow 14 (2027-10-15). Use get_flattened_data instead.
|
||||
assert len(set(image.getdata())) > 1
|
||||
|
||||
-- Docs: https://docs.pytest.org/en/stable/how-to/capture-warnings.html
|
||||
414 passed, 9 skipped, 6568 warnings in 65.73s (0:01:05)
|
||||
@@ -0,0 +1,7 @@
|
||||
{
|
||||
"original_failure_matches": [
|
||||
"FileNotFoundError: [Errno 2] No such file or directory: '/run/matrix-screen-controller/ota-worker.log'",
|
||||
"FileNotFoundError: [Errno 2] No such file or directory: '/run/matrix-screen-controller/ota-worker.log'"
|
||||
],
|
||||
"window_utc": "2026-09-07T14:20:00Z/2026-09-07T14:40:00Z"
|
||||
}
|
||||
@@ -0,0 +1,58 @@
|
||||
{
|
||||
"pytest_summary": [
|
||||
"421 passed, 2 skipped, 313 warnings in 358.28s (0:05:58)"
|
||||
],
|
||||
"guard_observations": [
|
||||
{
|
||||
"guard_exists": true,
|
||||
"request_exists": true,
|
||||
"status_exists": true,
|
||||
"log_exists": true,
|
||||
"preserve": "yes"
|
||||
},
|
||||
{
|
||||
"guard_exists": true,
|
||||
"request_exists": true,
|
||||
"status_exists": true,
|
||||
"log_exists": true,
|
||||
"preserve": "yes"
|
||||
},
|
||||
{
|
||||
"guard_exists": true,
|
||||
"request_exists": true,
|
||||
"status_exists": true,
|
||||
"log_exists": true,
|
||||
"preserve": "yes"
|
||||
},
|
||||
{
|
||||
"guard_exists": true,
|
||||
"request_exists": true,
|
||||
"status_exists": true,
|
||||
"log_exists": true,
|
||||
"preserve": "yes"
|
||||
},
|
||||
{
|
||||
"guard_exists": true,
|
||||
"request_exists": true,
|
||||
"status_exists": true,
|
||||
"log_exists": true,
|
||||
"preserve": "yes"
|
||||
},
|
||||
{
|
||||
"guard_exists": true,
|
||||
"request_exists": true,
|
||||
"status_exists": true,
|
||||
"log_exists": true,
|
||||
"preserve": "yes"
|
||||
},
|
||||
{
|
||||
"guard_exists": true,
|
||||
"request_exists": false,
|
||||
"status_exists": true,
|
||||
"log_exists": true,
|
||||
"preserve": "yes"
|
||||
}
|
||||
],
|
||||
"service_state": "active",
|
||||
"ota_worker_result": "success"
|
||||
}
|
||||
@@ -0,0 +1,10 @@
|
||||
{
|
||||
"legacy_103_parser_and_extraction_passed": true,
|
||||
"top_level": [
|
||||
"software",
|
||||
"wheelhouse"
|
||||
],
|
||||
"frpc_count": 1,
|
||||
"package_sha256": "7f33a417181633e1f4c77f48a3030d33f6c6e9578002e22f3b0487aff535eef8",
|
||||
"file_count": 249
|
||||
}
|
||||
@@ -0,0 +1,9 @@
|
||||
/usr/bin/python3
|
||||
/usr/bin/systemctl
|
||||
/usr/bin/tar
|
||||
/usr/bin/sha256sum
|
||||
/usr/bin/curl
|
||||
Python 3.11.2
|
||||
PASS: real systemd Preserve=restart deletes runtime directory on explicit stop
|
||||
PASS: real stop/restart/start-failure preserve OTA request/status/log; temporary protection cleaned
|
||||
{"runtime_lifecycle_passed": true}
|
||||
@@ -0,0 +1,12 @@
|
||||
{
|
||||
"recovery_passed": true,
|
||||
"disk_version": "1.0.6",
|
||||
"user_files_preserved": 421,
|
||||
"frp_preserved": true,
|
||||
"cleanup_passed": true,
|
||||
"failure_log_preserved": true,
|
||||
"pytest_summary": [
|
||||
"420 passed, 2 skipped, 313 warnings in 359.96s (0:05:59)"
|
||||
],
|
||||
"original_failure_preserved": true
|
||||
}
|
||||
@@ -0,0 +1,18 @@
|
||||
{
|
||||
"package_sha256": "7f33a417181633e1f4c77f48a3030d33f6c6e9578002e22f3b0487aff535eef8",
|
||||
"installed_version": "1.1.0",
|
||||
"status": "success",
|
||||
"runtime_lifecycle_passed": true,
|
||||
"user_data_preserved": true,
|
||||
"frp_state_preserved": true,
|
||||
"transaction_cleanup_passed": true,
|
||||
"user_file_count": 421,
|
||||
"job_id": "86cbcfe541894bb6b07c52b17fb5f3f3",
|
||||
"verified_at": "2026-09-08T02:31:22.720144+00:00",
|
||||
"frp_active": "inactive",
|
||||
"frp_enabled": "disabled",
|
||||
"disk_version": "1.1.0",
|
||||
"api_version": "1.1.0",
|
||||
"feature_updated_at": "2026-09-08T10:19+08:00",
|
||||
"screen_visual_acceptance": "not_performed"
|
||||
}
|
||||
@@ -0,0 +1,71 @@
|
||||
# 工作区目录适配验收
|
||||
|
||||
2026-09-08，本次只适配工作区整理后的目录引用和定位逻辑。以下是一次性验证记录，稳定要求见 `DEPLOY-WORKSPACE-LAYOUT` 与 `TEST-WORKSPACE-LAYOUT`。
|
||||
|
||||
## 完成内容
|
||||
|
||||
- 更新协作指南、需求、测试说明、源码与发布 README、ADC 示例命令和资料校验命令。
|
||||
- 修复本机测试入口的工作区根定位；更新部署、手工更新、frpc 安装、OTA 构建、发布、晋升和修复工具的工作区路径。
|
||||
- 发布记录只改 `artifact_path`，逐条比较确认其他字段不变；当前 VERSION 为 1.1.1，FEATURE_UPDATED_AT 为 2026-09-08T10:19+08:00，均保持原值。本次不是可部署业务功能新增或优化。
|
||||
- 保留镜像内部 `project/离线依赖/` 协议及设备路径；既有发布二进制未修改。归档只修正当前导航，历史代码块和清理记录保持原文。
|
||||
- 编辑器的相对层级仍正确，无需修改定位代码。接线 DOCX 未发现本次搬迁涉及的旧路径，无需重新生成；官方 PDF 未修改。
|
||||
- 所有当前维护文档的 Markdown 本地链接校验通过；两篇已不存在的屏幕控制说明/连接简表引用，改指现有 HUB75 接线与首次上电检查文档。
|
||||
|
||||
## 验证结果
|
||||
|
||||
| 验证 | 结果 |
|
||||
|---|---|
|
||||
| 原工作区测试入口 | Python 418 passed、9 skipped；前端 70 passed；静态 JavaScript 与文案目录检查通过 |
|
||||
| 最终隔离副本完整测试 | Python 421 passed、9 skipped；前端 70 passed；静态检查通过 |
|
||||
| 新增路径回归 | 不同当前目录下定位中文空格路径；清理保留环境与人工数据；越界清理在删除前拒绝，3 项通过 |
|
||||
| 镜像编辑器 | 原工作区与隔离副本各 14 项通过，包含主工程配置编码交叉校验与无窗口 GUI 测试 |
|
||||
| mock 服务 | 隔离副本从测试环境启动，页面与 `/api/status` 均 HTTP 200，正常关闭并清屏 |
|
||||
| 清理 | 隔离副本执行 `clean` 后配置、人工标记、venv 和依赖指纹保留，work/runtime 已删除 |
|
||||
| ADC 标准库示例 | 新位置 `--self-test` 通过，未访问硬件 |
|
||||
| Shell 脚本 | 修改的三个安装/更新脚本语法检查通过，未执行部署 |
|
||||
| 发布工具 | 完整 Python 套件覆盖新目录下的临时 OTA 产物与发布记录、失败回退、同版修复和镜像候选；未导出正式产物 |
|
||||
|
||||
隔离副本包含独立源码、测试入口、需求、完整其他依赖、编辑器源码和复制的测试环境，位于含中文及空格的目录；测试命令从副本外调用，未引用原工作区源码或历史导出产物。9 项跳过为现有工具/平台条件（媒体编码工具及特定环境用例），并非路径失败。未运行板端、真实 systemd、真实 OTA、TF 卡或实屏验收。
|
||||
|
||||
## 历史材料状态（用户已确认，无待办）
|
||||
|
||||
- `发布更新相关/OTA数据包/1.0.1/matrix-screen-controller-1.0.1.ota`
|
||||
- `发布更新相关/导出包/1.0.2/matrix-screen-controller-1.0.2.img`
|
||||
|
||||
以上为本次检查时的历史状态。用户随后明确：历史导出 IMG 缺失默认视为主动清理空间，属于正常情况，不影响开发；OTA 今后保留，但 1.0.1 不再追补、提醒或要求验收，不影响使用。两项均不属于待修复问题，原发布记录保留。其余六个登记产物在当时检查的新路径存在（只检查存在性，未读取大型 IMG）。
|
||||
|
||||
## 修改清单
|
||||
|
||||
可复核的文本差异见 [路径调整.patch](路径调整.patch)。本次修改以下 28 个已有或新增工作文件，另新增本验收目录：
|
||||
|
||||
- `AGENTS.md`
|
||||
- `发布更新相关/README.md`
|
||||
- `发布更新相关/镜像编辑器/编辑器源代码/README.md`
|
||||
- `发布记录.json`
|
||||
- `各种归档/20260819_离线镜像1.0.2真实TF卡验收/README.md`
|
||||
- `各种归档/20260825_离线镜像1.0.3启动分区空间修复/README.md`
|
||||
- `各种归档/20260907_OTA1.1.0软件安装节点验证/README.md`
|
||||
- `各种归档/20260908_OTA1.1.0运行目录修复验收/README.md`
|
||||
- `整体开发需求/01_网页配置端需求.md`
|
||||
- `整体开发需求/02_屏幕底层控制接口需求.md`
|
||||
- `核桃派软件源代码/README.md`
|
||||
- `核桃派软件源代码/kernel/README.md`
|
||||
- `核桃派软件源代码/scripts/build_ota_package.py`
|
||||
- `核桃派软件源代码/scripts/deploy_walnutpi.sh`
|
||||
- `核桃派软件源代码/scripts/export_release.py`
|
||||
- `核桃派软件源代码/scripts/install_frpc_system.sh`
|
||||
- `核桃派软件源代码/scripts/promote_image_release.py`
|
||||
- `核桃派软件源代码/scripts/repair_ota_release.py`
|
||||
- `核桃派软件源代码/scripts/update_walnutpi.sh`
|
||||
- `核桃派软件源代码/tests/test_kernel_artifact_dependency.py`
|
||||
- `核桃派软件源代码/tests/test_ota_checkpoints.py`
|
||||
- `核桃派软件源代码/tests/test_release_image.py`
|
||||
- `测试相关资料/如何测试/本机测试环境/README.md`
|
||||
- `测试相关资料/如何测试/本机测试环境/local_test.py`
|
||||
- `测试相关资料/如何测试/核桃派点阵屏控制服务测试流程.md`
|
||||
- `硬件相关资料和硬件的连接/M5Stack Unit ADC v1.1相关内容/02_ADS1110使用与开发约定_给Codex.md`
|
||||
- `硬件相关资料和硬件的连接/M5Stack Unit ADC v1.1相关内容/官方资料/来源索引.md`
|
||||
- `核桃派软件源代码/tests/test_workspace_layout.py`
|
||||
## 临时副本清理状态
|
||||
|
||||
隔离工作区内部的 `clean` 验收通过，但随后删除整个本次隔离副本的 PowerShell 操作被自动审批拒绝，仅返回 `blocked by policy`，没有更具体原因。副本及验证日志仍保留在 Codex 专用临时目录的 `workspace-path-adaptation-20260908/` 下；该目录不是项目依赖，不应被后续构建引用。未绕过拒绝执行其他删除方式。
|
||||
@@ -0,0 +1,809 @@
|
||||
--- a/AGENTS.md
|
||||
+++ b/AGENTS.md
|
||||
@@ -1,6 +1,6 @@
|
||||
# 奇妙小屏幕控制器（核桃派 ZeroW）协作指南
|
||||
|
||||
-本目录是可以单独拿走、独立开发和部署的核桃派项目。处理任务前先读本文件，再读 `整体开发需求/`、`如何测试/` 和与任务有关的硬件资料。本项目不得依赖外层移植目录、原树莓派工作区、旧设备配置或旧设备凭据。
|
||||
+本目录是可以单独拿走、独立开发和部署的核桃派项目。处理任务前先读本文件，再读 `整体开发需求/`、`测试相关资料/如何测试/` 和与任务有关的硬件资料。本项目不得依赖外层移植目录、原树莓派工作区、旧设备配置或旧设备凭据。
|
||||
|
||||
## 1. 固定硬件和边界
|
||||
|
||||
@@ -9,7 +9,7 @@
|
||||
- 真实驱动：项目自带 `walnutpi-h618-hub75` C 驱动，通过 `/dev/mem` 访问 H618 PI bank；不得回退或依赖 `rpi-rgb-led-matrix`。
|
||||
- ADC：M5Stack Unit ADC v1.1 / ADS1110，`/dev/i2c-1`，地址 `0x48`。
|
||||
- 生产程序、持久数据和运行数据分别位于 `/opt/matrix-screen-controller`、`/var/lib/matrix-screen-controller`、`/run/matrix-screen-controller`。
|
||||
-- 当前设备和开发机凭据只保存在 `核桃派的用户名和密码和ip/用户名密码ip.txt`，不得复制到源码、日志、普通文档或回复。正式 IMG 的发布目录 `README.md` 是唯一例外：它必须写明该未修改镜像内故意公开的默认账户与 Wi-Fi 四项值，并警告用户修改；不得把当前设备或开发机凭据误写为镜像默认值。
|
||||
+- 当前设备和开发机凭据只保存在 `测试相关资料/核桃派的用户名和密码和ip/用户名密码ip.txt`，不得复制到源码、日志、普通文档或回复。正式 IMG 的发布目录 `README.md` 是唯一例外：它必须写明该未修改镜像内故意公开的默认账户与 Wi-Fi 四项值，并警告用户修改；不得把当前设备或开发机凭据误写为镜像默认值。
|
||||
|
||||
## 2. 需求与测试编号
|
||||
|
||||
@@ -20,7 +20,7 @@
|
||||
- `HW-*`：核桃派排针、HUB75、ADC、供电和扫描参数。
|
||||
- `TEST-*`：本机、板端无负载、实屏、ADC、重启、清理和独立性验收。
|
||||
|
||||
-新增或改变行为时，先更新 `整体开发需求/` 的稳定编号，再改 `核桃派软件源代码/`，最后同步 `如何测试/` 的映射和合格标准。
|
||||
+新增或改变行为时，先更新 `整体开发需求/` 的稳定编号，再改 `核桃派软件源代码/`，最后同步 `测试相关资料/如何测试/` 的映射和合格标准。
|
||||
|
||||
## 3. 分层验证
|
||||
|
||||
@@ -48,8 +48,8 @@
|
||||
3. 每个离线包保存 SHA-256 清单；板端安装使用 `--no-index --find-links` 或明确的本地路径。
|
||||
4. 不关闭电脑 VPN，不把本机工具目录或盘符固化进项目文档和部署脚本。
|
||||
5. SSH 后先在远端用 `command -v` 和版本命令检查工具，不能因电脑有工具就假设板端也有。
|
||||
-6. 普通功能开发不读取或重建大型镜像；只有用户明确要求导出镜像、维护离线材料或更新编辑器时才进入 `离线依赖/` 的发布流程。
|
||||
-7. 新增或删除板端 Python、Debian 或原生命令依赖时属于功能修改的一部分：必须同步 `离线依赖/其他依赖/` 的文件、SHA-256 和生命周期清单。停用依赖删除二进制并登记原因，不能等待下次镜像导出再补。
|
||||
+6. 普通功能开发不读取或重建大型镜像；只有用户明确要求导出镜像、维护离线材料或更新编辑器时才进入 `发布更新相关/` 的发布流程。
|
||||
+7. 新增或删除板端 Python、Debian 或原生命令依赖时属于功能修改的一部分：必须同步 `发布更新相关/其他依赖/` 的文件、SHA-256 和生命周期清单。停用依赖删除二进制并登记原因，不能等待下次镜像导出再补。
|
||||
8. OTA 和可刷镜像共用 `核桃派软件源代码/VERSION` 与根目录 `发布记录.json`；只有明确导出成功才推进版本，失败不得占号或留下半成品目录。
|
||||
9. 可部署的功能新增或优化必须同步更新 `核桃派软件源代码/FEATURE_UPDATED_AT`，格式固定为精确到分钟的北京时间 `YYYY-MM-DDTHH:MM+08:00`。单纯 OTA/镜像导出、重复部署和文档修改不得改写该时间。
|
||||
|
||||
@@ -79,4 +79,4 @@
|
||||
- 临时部署、构建目录、wheelhouse 和临时 systemd unit 在验证后按明确绝对路径清理。
|
||||
- 最终把本目录复制到隔离临时位置，从文档命令重新构建和运行测试；任何引用目录外文件的路径都视为失败。
|
||||
- 一次性结果写在交付或 `各种归档/<时间戳>_用途/README.md`，不写进可重复测试流程。
|
||||
-- `离线依赖/导出包/<版本>/` 是可随时删除的大型发布产物，源码、文档命令和后续构建不得引用其中任何文件。
|
||||
+- `发布更新相关/导出包/<版本>/` 是可随时删除的大型发布产物，源码、文档命令和后续构建不得引用其中任何文件。
|
||||
--- a/发布更新相关/README.md
|
||||
+++ b/发布更新相关/README.md
|
||||
@@ -1,4 +1,4 @@
|
||||
-# 离线依赖与发布产物
|
||||
+# 发布更新材料与产物
|
||||
|
||||
本目录用于没有境外网络的核桃派从官方系统镜像离线安装当前软件，并保存按用户明确指令导出的可刷镜像。
|
||||
|
||||
@@ -7,6 +7,7 @@
|
||||
| `核桃派镜像/` | 未修改的官方 RAR、IMG 和摘要 | 稳定基线，不得原地修改 |
|
||||
| `导出包/<版本>/` | Rufus 可写入的版本化 IMG | 可随时删除，项目不得引用 |
|
||||
| `其他依赖/` | AArch64 wheel、Debian 包、预编译内核、固定内核源码和依赖生命周期 | 随软件依赖同步维护 |
|
||||
+| `OTA数据包/<版本>/` | 版本化 OTA 更新包 | 可删除的历史发布产物，不作为后续构建输入 |
|
||||
| `镜像编辑器/` | Windows 编辑器源码和绿色程序 | 编辑器使用独立版本并覆盖旧程序 |
|
||||
|
||||
普通开发不需要读取大型镜像或导出目录。只有用户明确要求导出镜像、维护离线依赖或更新编辑器时才进入本流程；但新增或删除软件运行依赖时，必须在同一次功能修改中同步 `其他依赖/`。
|
||||
--- a/发布更新相关/镜像编辑器/编辑器源代码/README.md
|
||||
+++ b/发布更新相关/镜像编辑器/编辑器源代码/README.md
|
||||
@@ -1,6 +1,8 @@
|
||||
# 构建镜像配置编辑器 2.0.0
|
||||
|
||||
源码使用 Python 3 和 PySide6，不依赖本项目其他目录。支持 Python 3.10–3.14，构建依赖已在 `requirements-build.txt` 锁定。
|
||||
+
|
||||
+以下命令均在本文件所在的 `发布更新相关/镜像编辑器/编辑器源代码/` 目录执行。
|
||||
|
||||
## Windows 10/11 x64
|
||||
|
||||
--- a/发布记录.json
|
||||
+++ b/发布记录.json
|
||||
@@ -6,7 +6,7 @@
|
||||
"artifact_type": "ota",
|
||||
"created_at": "2026-08-13T15:31:23+08:00",
|
||||
"notes": "新增浏览器全量 OTA。",
|
||||
- "artifact_path": "OTA数据包/1.0.1/matrix-screen-controller-1.0.1.ota",
|
||||
+ "artifact_path": "发布更新相关/OTA数据包/1.0.1/matrix-screen-controller-1.0.1.ota",
|
||||
"artifact_sha256": "1ae8544e2072a014dc76e07a930375c80e85b5331957716a456c8123dd204325"
|
||||
},
|
||||
{
|
||||
@@ -14,7 +14,7 @@
|
||||
"artifact_type": "image",
|
||||
"created_at": "2026-08-19T15:42:35+08:00",
|
||||
"notes": "建立可刷镜像、离线首次启动和 Windows 镜像编辑能力；修复并真实验证 SSH 默认启用、配置账户密码登录、需同密码完整 sudo 权限、root 登录禁用、sshd 易失运行目录、首启 unit 超时与假成功，以及基础镜像 rootpw、旧 pi 免密规则和主机名解析延迟。",
|
||||
- "artifact_path": "离线依赖/导出包/1.0.2/matrix-screen-controller-1.0.2.img",
|
||||
+ "artifact_path": "发布更新相关/导出包/1.0.2/matrix-screen-controller-1.0.2.img",
|
||||
"artifact_sha256": "0397b2abd974cc293a472789027b02bf469434d358578fd43aa9fdb218944aeb"
|
||||
},
|
||||
{
|
||||
@@ -22,7 +22,7 @@
|
||||
"artifact_type": "image",
|
||||
"created_at": "2026-08-25T08:17:48+00:00",
|
||||
"notes": "修复 1.0.3 首次启动 FAT 空间不足：应用离线载荷迁入 rootfs，增加候选内核 boot 文件预算与 32 MiB 安全余量双重校验，并修复导出入口误加载 Pillow/FontTools。",
|
||||
- "artifact_path": "离线依赖/导出包/1.0.3/matrix-screen-controller-1.0.3.img",
|
||||
+ "artifact_path": "发布更新相关/导出包/1.0.3/matrix-screen-controller-1.0.3.img",
|
||||
"artifact_sha256": "a5676576fb63a913ed9e40a02ce206e5ef71f47b1005a98a8758479b51413e0b"
|
||||
},
|
||||
{
|
||||
@@ -30,7 +30,7 @@
|
||||
"artifact_type": "ota",
|
||||
"created_at": "2026-09-04T13:14:05+08:00",
|
||||
"notes": "发布当前工作区已完成并通过本机全套测试的软件版本。",
|
||||
- "artifact_path": "OTA数据包/1.0.4/matrix-screen-controller-1.0.4.ota",
|
||||
+ "artifact_path": "发布更新相关/OTA数据包/1.0.4/matrix-screen-controller-1.0.4.ota",
|
||||
"artifact_sha256": "ed15498e2d66758343c874d00176e2525e67a69fea5cc8f4578f139dd2b0f766"
|
||||
},
|
||||
{
|
||||
@@ -38,7 +38,7 @@
|
||||
"artifact_type": "ota",
|
||||
"created_at": "2026-09-06T21:10:58+08:00",
|
||||
"notes": "修复 OTA 板端测试目录隔离，并新增可查看、复制的详细失败日志。",
|
||||
- "artifact_path": "OTA数据包/1.0.5/matrix-screen-controller-1.0.5.ota",
|
||||
+ "artifact_path": "发布更新相关/OTA数据包/1.0.5/matrix-screen-controller-1.0.5.ota",
|
||||
"artifact_sha256": "ec245d2ba2eefdf415f6745aefb1dfc66631e027d6820a2b6bd04bd6306d4152"
|
||||
},
|
||||
{
|
||||
@@ -46,7 +46,7 @@
|
||||
"artifact_type": "ota",
|
||||
"created_at": "2026-09-06T21:39:45+08:00",
|
||||
"notes": "诊断引导包：经设备持有者授权，仅在 1.0.3 旧 worker 中跳过 pytest，以先安装可查看、复制的 OTA 失败日志；后续更新恢复严格测试。",
|
||||
- "artifact_path": "OTA数据包/1.0.6/matrix-screen-controller-1.0.6.ota",
|
||||
+ "artifact_path": "发布更新相关/OTA数据包/1.0.6/matrix-screen-controller-1.0.6.ota",
|
||||
"artifact_sha256": "8e804dcfb1f2f9194f3c57b88b5d4b7308509270fba536059e528ab21fdfa0b9"
|
||||
},
|
||||
{
|
||||
@@ -54,7 +54,7 @@
|
||||
"artifact_type": "ota",
|
||||
"created_at": "2026-09-08T10:19:47+08:00",
|
||||
"notes": "修复 OTA 显式停止旧服务时运行目录被删除导致升级和回滚中断；增加停服前事务保护、日志降级及真实 systemd 回归。已在测试设备完成 1.0.6 → 1.1.0，用户数据和 frp 状态保持。",
|
||||
- "artifact_path": "OTA数据包/1.1.0/matrix-screen-controller-1.1.0.ota",
|
||||
+ "artifact_path": "发布更新相关/OTA数据包/1.1.0/matrix-screen-controller-1.1.0.ota",
|
||||
"artifact_sha256": "7f33a417181633e1f4c77f48a3030d33f6c6e9578002e22f3b0487aff535eef8",
|
||||
"package_kind": "software-install",
|
||||
"required_checkpoint": "1.0.0",
|
||||
@@ -85,7 +85,7 @@
|
||||
"artifact_type": "image",
|
||||
"created_at": "2026-09-08T07:24:53+00:00",
|
||||
"notes": "完整可刷镜像 1.1.1：默认账户与 Wi-Fi，可直接首启使用",
|
||||
- "artifact_path": "离线依赖/导出包/1.1.1/matrix-screen-controller-1.1.1.img",
|
||||
+ "artifact_path": "发布更新相关/导出包/1.1.1/matrix-screen-controller-1.1.1.img",
|
||||
"artifact_sha256": "8356b75ef970891db951a08429f8e2d21a6c0c4933065001778e10d74022c19d",
|
||||
"validation_path": "各种归档/20260908_090953_IMAGE1.1.1实卡验收_bb9884/实机验收.json",
|
||||
"validated_at": "2026-09-08T09:09:53+00:00"
|
||||
--- a/各种归档/20260819_离线镜像1.0.2真实TF卡验收/README.md
|
||||
+++ b/各种归档/20260819_离线镜像1.0.2真实TF卡验收/README.md
|
||||
@@ -3,7 +3,7 @@
|
||||
## 失效说明
|
||||
|
||||
- 本记录对应 SHA-256 `3a28d9b5200ed22824a628a46ce8d36851cc8366bbf3b8cbd22a2b9a7c4b9128` 的旧 IMG。该镜像最终没有监听 SSH 22 端口，缺少正式导出包的必要功能，因此不得再作为正式包使用。
|
||||
-- 旧 IMG 已删除，并由同版本的新 IMG 原子替换；新产物摘要以根目录 `发布记录.json` 和 `离线依赖/导出包/1.0.2/manifest.json` 为准。
|
||||
+- 旧 IMG 已删除，并由同版本的新 IMG 原子替换；新产物摘要以根目录 `发布记录.json` 和 `发布更新相关/导出包/1.0.2/manifest.json` 为准。
|
||||
- 以下内容只保留当时失败定位和已完成硬件检查的历史证据，不代表新产物已通过真实 TF 卡首启、SSH 或重启验收。新产物须在用户完成镜像编辑、写卡和上电后另行验证。
|
||||
|
||||
## 旧产物当时的结论
|
||||
@@ -42,4 +42,4 @@
|
||||
- 镜像构建前必须以 `BASE_IMAGE_PACKAGES.tsv` 验证 `ffmpeg`、`libheif-examples`、`python3.11-venv` 的完整递归闭包；缺根包、传递包、基准清单或摘要时拒绝导出。
|
||||
- Debian 安装失败保留无配置凭据的 `MSCPKG.TXT`/`MSCPKGS.TSV`；部署失败保留无配置凭据的 `MSCDEPLOY.TXT`；成功时删除这些诊断文件。
|
||||
- 首启 oneshot 不得同步启动受其 `Before=` 排序约束的控制服务。
|
||||
-- 本归档是一次性验收记录，不得作为后续构建输入；后续构建不得引用 `离线依赖/导出包/<版本>/`。
|
||||
+- 本归档是一次性验收记录，不得作为后续构建输入；后续构建不得引用 `发布更新相关/导出包/<版本>/`。
|
||||
--- a/各种归档/20260825_离线镜像1.0.3启动分区空间修复/README.md
|
||||
+++ b/各种归档/20260825_离线镜像1.0.3启动分区空间修复/README.md
|
||||
@@ -49,4 +49,4 @@
|
||||
- 正式构建输出 `rootfs bootstrap installed` 与 `rootfs bootstrap verified`；提交后又从 IMG 复制应用 bundle 为独立文件，再次运行只读 rootfs/FAT 验证并通过。
|
||||
- 新 manifest、侧车摘要、实际整镜像摘要和唯一发布记录四者一致；发布锁、`.building` 和 `.invalid-backup` 均不得残留。
|
||||
|
||||
-本记录是一次性故障和发布证据，不得作为后续构建输入；后续构建不得引用 `离线依赖/导出包/1.0.3` 中的任何文件。
|
||||
+本记录是一次性故障和发布证据，不得作为后续构建输入；后续构建不得引用 `发布更新相关/导出包/1.0.3` 中的任何文件。
|
||||
--- a/各种归档/20260907_OTA1.1.0软件安装节点验证/README.md
|
||||
+++ b/各种归档/20260907_OTA1.1.0软件安装节点验证/README.md
|
||||
@@ -2,7 +2,7 @@
|
||||
|
||||
## 交付
|
||||
|
||||
-- 正式包：`OTA数据包/1.1.0/matrix-screen-controller-1.1.0.ota`
|
||||
+- 正式包：`发布更新相关/OTA数据包/1.1.0/matrix-screen-controller-1.1.0.ota`
|
||||
- 字节数：27993930（约 26.7 MiB）。
|
||||
- SHA-256：`379f80a30157e23d717157005ea246fa822529010c0f0295dcad5db3ceff42c5`。
|
||||
- 功能时间：`2026-09-07T22:00+08:00`。导出成功后 VERSION 推进到 1.1.0，发布记录追加一次。
|
||||
--- a/各种归档/20260908_OTA1.1.0运行目录修复验收/README.md
|
||||
+++ b/各种归档/20260908_OTA1.1.0运行目录修复验收/README.md
|
||||
@@ -2,7 +2,7 @@
|
||||
|
||||
2026-09-08 已在测试设备实际完成 1.0.6 → 1.1.0。磁盘 VERSION、运行 API 均为 1.1.0，OTA worker Result=success，用户数据 421 个非 OTA 文件摘要完全一致，frpc 二进制摘要保持，服务仍 inactive / disabled。组件完整性校验通过，恢复事务、临时保护、恢复 unit/helper、上传包与工作目录均已清理。
|
||||
|
||||
-正式产物为 `OTA数据包/1.1.0/matrix-screen-controller-1.1.0.ota`，27998979 字节，SHA-256 为 `7f33a417181633e1f4c77f48a3030d33f6c6e9578002e22f3b0487aff535eef8`。发布时直接复制实机验收候选，逐字节确认一致，未重新构建。VERSION 保持 1.1.0，FEATURE_UPDATED_AT 为 `2026-09-08T10:19+08:00`。旧包摘要 `379f80a30157e23d717157005ea246fa822529010c0f0295dcad5db3ceff42c5`，完整旧产物和旧发布记录归档位置见根发布记录的 repairs 字段。
|
||||
+正式产物为 `发布更新相关/OTA数据包/1.1.0/matrix-screen-controller-1.1.0.ota`，27998979 字节，SHA-256 为 `7f33a417181633e1f4c77f48a3030d33f6c6e9578002e22f3b0487aff535eef8`。发布时直接复制实机验收候选，逐字节确认一致，未重新构建。VERSION 保持 1.1.0，FEATURE_UPDATED_AT 为 `2026-09-08T10:19+08:00`。旧包摘要 `379f80a30157e23d717157005ea246fa822529010c0f0295dcad5db3ceff42c5`，完整旧产物和旧发布记录归档位置见根发布记录的 repairs 字段。
|
||||
|
||||
## 故障与修复
|
||||
|
||||
--- a/整体开发需求/01_网页配置端需求.md
|
||||
+++ b/整体开发需求/01_网页配置端需求.md
|
||||
@@ -6,7 +6,7 @@
|
||||
|
||||
## 0. 需求编号索引
|
||||
|
||||
-本文件使用 `WEB-*`、`CONFIG-*` 和 `DEPLOY-*` 编号描述网页端、接口、配置和运行入口。测试覆盖关系维护在 `如何测试/核桃派点阵屏控制服务测试流程.md`，不要在本文件复制完整测试命令。
|
||||
+本文件使用 `WEB-*`、`CONFIG-*` 和 `DEPLOY-*` 编号描述网页端、接口、配置和运行入口。测试覆盖关系维护在 `测试相关资料/如何测试/核桃派点阵屏控制服务测试流程.md`，不要在本文件复制完整测试命令。
|
||||
|
||||
| 编号 | 范围 | 当前阶段要求 |
|
||||
|---|---|---|
|
||||
@@ -34,6 +34,7 @@
|
||||
| `DEPLOY-IMAGE-EXPORT` | Rufus 可刷镜像 | 从未修改官方 IMG 复制生成；FAT16 只携带双槽配置、元数据和首启程序，Linux 根分区携带应用与已验证预编译内核离线载荷，元数据格式固定为 v3。 |
|
||||
| `DEPLOY-IMAGE-FIRSTBOOT` | 无外设自动首启 | 只连接核桃派本体即可离线安装应用与双内核候选、配置身份和网络、清理秘密并自动重启；SSID、认证、DHCP 或默认路由不可用不阻断安装，真实安装失败恢复原 boot 文件且不循环重启。 |
|
||||
| `DEPLOY-OFFLINE-DEPS` | 离线依赖生命周期 | Python wheel、Debian AArch64 包、预编译内核及固定内核源码均有摘要与用途；代码依赖增删必须同次同步。 |
|
||||
+| `DEPLOY-WORKSPACE-LAYOUT` | 工作区路径与独立性 | 适配分类目录，支持中文、空格及不同调用目录；清理不越界，包内路径与设备路径保持兼容。 |
|
||||
| `DEPLOY-FRP` | FRP 系统组件 | 固定、校验并离线交付官方 Linux ARM64 `frpc`，安装到 `/usr/local/bin`，由维护账户运行且纳入首装、手工更新和 OTA 回滚。 |
|
||||
| `DEPLOY-IMAGE-EDITOR` | 便携镜像编辑器 | Python/PySide6 跨平台源码读取、修改或另存账户、WiFi 和 IPv4；Windows 交付绿色单 EXE，编辑器版本独立于软件版本。 |
|
||||
| `DEPLOY-FONTS` | 多语言字体运行依赖 | 部署环境提供 Fontconfig、Noto Core 和 Noto CJK，服务启动后能解析主流现代文字体系。 |
|
||||
@@ -288,12 +289,12 @@
|
||||
- OTA 与 SSH 手工更新运行 Python 门槛时必须把应用数据、运行数据、pytest `tmp_path` 和通用临时文件全部限制在本次事务目录，显式设置 `MATRIX_TEST_ROOT`、`TMPDIR` 与 pytest `--basetemp`，并禁用 pytest cache；不得依赖或污染系统默认 `/tmp`。新源码的 conftest 还必须兼容旧更新器只传入 `MATRIX_DATA_DIR`、`MATRIX_RUNTIME_DIR` 和 `MATRIX_SOURCE_ONLY_UPDATE_TESTS=1` 的调用方式。除发布记录中已经固化且不得覆盖的 1.0.6 一次性诊断引导包外，所有当前源码和后续 OTA 都必须实际执行完整 pytest，任一失败继续阻止切换并触发原子回滚；不得保留诊断标记、成功早退或其他测试绕过入口。
|
||||
- OTA worker 必须把包校验、离线依赖、venv、原生编译、pytest、专用主机检查、迁移、切换、健康检查和回滚的阶段时间、安全主机摘要、命令、退出码及 stdout/stderr 写入单个运行期日志。日志不得读取或记录账户密码、IP、SSID、配置内容、用户资源内容或完整环境变量。失败时以耐久原子写入只保留最近一份、最多 `1 MiB` 的日志，超限时保留头部和最新尾部并标明截断；下一次成功更新删除旧失败日志。
|
||||
- `GET /api/ota/status` 返回最近失败日志是否可用及字节数；`GET /api/ota/failure-log` 只在最近结果为失败且日志有效时以无缓存 UTF-8 纯文本返回，否则 `404`。设置页检测到带日志的失败后自动打开“OTA 更新失败日志”弹窗，以纯文本等宽滚动区显示，支持 Clipboard API 和非安全局域网 HTTP 下的 textarea 回退复制；关闭后仍保留查看和复制入口，日志读取失败时继续显示原简短错误且不得打开空弹窗。
|
||||
-- 活动状态原子写入 `/run/matrix-screen-controller/ota-status.json`；持久根 `ota/state.json` 只保留 schema v1 的最近结果和未完成事务恢复信息。不得积累历史包或索引工作区 `OTA数据包/`。
|
||||
+- 活动状态原子写入 `/run/matrix-screen-controller/ota-status.json`；持久根 `ota/state.json` 只保留 schema v1 的最近结果和未完成事务恢复信息。不得积累历史包或索引工作区 `发布更新相关/OTA数据包/`。
|
||||
- 新配置字段必须通过逐级迁移增加预设值。删除功能时，迁移只能删除已登记归属该功能的字段或路径；其余配置、字体、模板、动图和未知文件完整复制。成功后删除旧 release、上传包、数据备份和 staging；失败或中途重启按事务记录恢复旧程序、旧 unit 与旧数据。
|
||||
|
||||
### 1.3.3 可刷镜像和离线材料（`DEPLOY-IMAGE-EXPORT`、`DEPLOY-IMAGE-FIRSTBOOT`、`DEPLOY-OFFLINE-DEPS`、`DEPLOY-IMAGE-EDITOR`）
|
||||
|
||||
-- `离线依赖/核桃派镜像` 只保存未修改官方镜像。导出器复制后向 FAT16 启动分区只写入摘要元数据、一次性 root 首启程序和固定大小双槽配置区；应用源码、AArch64 wheel 与 Debian 包组成的 `MSCBOOT.TGZ` 由 Linux bootstrap 写入复制镜像根分区 `/opt/matrix-image-bootstrap/app/MSCBOOT.TGZ`，预编译内核写入相邻的 `/opt/matrix-image-bootstrap/axp313a`。固定内核源码只留在电脑端，禁止进入 IMG 或 OTA。
|
||||
+- `发布更新相关/核桃派镜像` 只保存未修改官方镜像。导出器复制后向 FAT16 启动分区只写入摘要元数据、一次性 root 首启程序和固定大小双槽配置区；应用源码、AArch64 wheel 与 Debian 包组成的 `MSCBOOT.TGZ` 由 Linux bootstrap 写入复制镜像根分区 `/opt/matrix-image-bootstrap/app/MSCBOOT.TGZ`，预编译内核写入相邻的 `/opt/matrix-image-bootstrap/axp313a`。固定内核源码只留在电脑端，禁止进入 IMG 或 OTA。
|
||||
- 镜像元数据格式固定为 v3，记录应用载荷位置、压缩字节数和 SHA-256，以及候选内核 release、压缩/展开字节数、SHA-256、FAT 安装预算和安全余量。IMG 导出必须同时验证预编译载荷及固定源码归档；根分区注入前至少保留“应用压缩载荷 + 内核压缩载荷 + 256 MiB”，注入后重新只读挂载并逐字节核对 FAT v3 元数据、根分区两类载荷和离线依赖元数据。FAT 必须明确不存在 `MSCBOOT.TGZ`。旧 v1/v2 镜像不得原地刷新或迁移，必须从官方基线重建。
|
||||
- 构建器必须在最终 FAT 布局上按簇取整计算首次安装新增的候选 Image、双份 DTB、System.map、kernel config、受管启动脚本、原始启动脚本回滚副本、临时文件和状态文件，并在这些实际预算之外保留固定 `32 MiB` 安全余量；不满足时在发布前拒绝。内核安装器在写入第一个候选 boot 文件前使用同一算法再次检查当前 `/boot`，不足时保留 rootfs 离线载荷并失败，禁止依靠清除应用载荷换取不可恢复的空间。
|
||||
- 首启不依赖显示器、键盘、HUB75、ADC 或当前网络在线。它校验并离线安装载荷、编译真实驱动、配置账户和 NetworkManager、生成唯一 machine-id 与 SSH 主机密钥、部署服务，最后安装预编译双内核候选并自动重启一次。镜像配置仍必须包含有效的 WiFi 与 IPv4 字段；首启只写入启用自动连接的受管配置并重启 NetworkManager，不等待 SSID、认证、DHCP 或默认路由，以上任一未就绪都继续离线安装，安装完成后由正常运行服务继续连接并按既有逻辑显示断网提示。NetworkManager 未启动、配置写入失败以及载荷、硬件、权限、SSH 或内核错误仍必须令首启失败。安装内核前根分区至少保留“两倍展开字节数 + 256 MiB”，解包只进入明确的 `/var/tmp/matrix-axp313a-image-install`；成功后删除压缩载荷和展开目录，失败由安装器恢复原 boot 文件、清除部分候选并保留无秘密状态，不联网补包或循环重启。候选启动继续使用一次性健康标记，内核、AXP313A、cpufreq、应用或 GPIO 健康失败时下一次自动回原内核。首启完成时若受管连接或默认路由尚未就绪，FAT 状态仍写成功，但必须明确说明 WiFi 尚未连接且运行系统会继续处理，不得包含 SSID、密码、用户名或地址。
|
||||
@@ -302,8 +303,14 @@
|
||||
- 配置 schema v1 固定包含产品、软件版本、账户、WiFi 和 DHCP/静态 IPv4。双槽分别带单调代数、长度和 SHA-256；读取选择最高有效代，保存先完整写入非活动槽并刷新，写入中断必须仍能读取旧槽。
|
||||
- 编辑器使用不依赖项目外部目录的 Python/PySide6 跨平台源码；Windows 10/11 x64 必须交付内置 Python、Qt 和运行库的唯一绿色单 EXE，其他电脑不得要求安装 Python、.NET、Qt 或补充 DLL。同一源码允许用户在 macOS 本地构建，Windows 发布不得宣称已交付或验收 macOS 产物。编辑器显示镜像版本和当前配置，密码默认遮挡；“修改原镜像”必须二次确认，“另存为”必须使用不同且尚不存在的宿主系统合法 `.img` 文件名，并提示按设备或地点命名。中文、空格和长路径必须受支持；保留名、错误扩展名、同路径、既有目标或无法创建同名摘要时必须在复制或修改前拒绝。未知产品、版本、损坏槽或摘要失败时禁止保存；每次保存以无 BOM UTF-8 生成规范的 `<64 位小写 SHA-256><两个空格><完整文件名><LF>` 侧车文件，按固定字段边界解析并严格复核文件名和镜像内容。摘要必须通过同目录临时文件原子替换，另存失败不得留下 IMG、摘要或临时摘要。
|
||||
- 编辑器必须声明 Per-Monitor V2 DPI 感知；主窗口、输入区域以及应用内错误、警告、确认和成功提示均按当前显示器 DPI 与工作区自适应缩放，分辨率或显示器变化后保持完整可达。密码输入框与同列普通输入框等宽；低分辨率时允许纵向滚动但不得裁切字段、正文或操作按钮。Windows 原生打开和保存选择器继续使用系统界面。
|
||||
-- `离线依赖/其他依赖` 是当前软件所需的唯一离线材料清单。新增依赖必须同时提供文件、架构、来源、用途和摘要；停用时删除二进制并记录停用版本与原因。AXP313A 运行载荷必须来自已经通过真实 GPIO 验收的 `6.1.31-matrix-axp313a1`，使用确定性 `tar.gz`，拒绝路径穿越、符号链接、特殊文件、错误 release/commit 和未登记文件；模块的 `build`、`source` 链接不进入载荷，由目标 `depmod` 重建索引。固定源码归档必须与 vendor commit 和补丁摘要同时可离线校验。Debian 包必须相对于登记的官方基础镜像包清单形成可递归解析的完整闭包，镜像构建前自动验证，缺少直接依赖、传递依赖、根包或基准清单时必须拒绝导出。首启 Debian 安装失败时，FAT 状态文件指向不含配置凭据的包诊断与基准包清单，失败后不得继续网络和部署阶段。
|
||||
-- `离线依赖/导出包/<版本>` 只保存可删除产物，任何源码、测试或后续导出不得引用其中内容。
|
||||
+- `发布更新相关/其他依赖` 是当前软件所需的唯一离线材料清单。新增依赖必须同时提供文件、架构、来源、用途和摘要；停用时删除二进制并记录停用版本与原因。AXP313A 运行载荷必须来自已经通过真实 GPIO 验收的 `6.1.31-matrix-axp313a1`，使用确定性 `tar.gz`，拒绝路径穿越、符号链接、特殊文件、错误 release/commit 和未登记文件；模块的 `build`、`source` 链接不进入载荷，由目标 `depmod` 重建索引。固定源码归档必须与 vendor commit 和补丁摘要同时可离线校验。Debian 包必须相对于登记的官方基础镜像包清单形成可递归解析的完整闭包，镜像构建前自动验证，缺少直接依赖、传递依赖、根包或基准清单时必须拒绝导出。首启 Debian 安装失败时，FAT 状态文件指向不含配置凭据的包诊断与基准包清单，失败后不得继续网络和部署阶段。
|
||||
+- `发布更新相关/导出包/<版本>` 只保存可删除产物，任何源码、测试或后续导出不得引用其中内容。
|
||||
+
|
||||
+### 工作区路径约定（`DEPLOY-WORKSPACE-LAYOUT`）
|
||||
+
|
||||
+- 测试入口位于 `测试相关资料/如何测试/本机测试环境/`，发布工具从 `发布更新相关/` 定位离线材料和产物；源码仍位于根目录 `核桃派软件源代码/`。路径须由脚本位置或显式参数解析，支持中文、空格及不同调用目录。
|
||||
+- 工作区搬迁不改变设备安装路径、镜像内部载荷目录或历史包协议；已有发布记录仅同步工作区产物路径，不改版本、摘要及历史验收结果。
|
||||
+- 本机测试与清理必须在隔离工作区验证：能够定位本地源码，保留 `.venv` 和人工持久数据，并拒绝清理越界路径。覆盖见 `TEST-WORKSPACE-LAYOUT`。
|
||||
|
||||
## 2. 页面功能
|
||||
|
||||
@@ -1209,8 +1216,7 @@
|
||||
|
||||
## 9. 参考资料
|
||||
|
||||
-- 本地资料：`点阵屏幕相关资料/RGB-Matrix-P3-64x64-F_核桃派ZeroW控制说明.md`
|
||||
-- 本地资料：`点阵屏幕相关资料/点阵屏幕_GPIO连接简表_开发用.md`
|
||||
+- 本地接线资料：`硬件相关资料和硬件的连接/点阵屏幕相关资料/手动接线说明/核桃派ZeroW_HUB75_接线与首次上电检查.md`
|
||||
- 核桃派官方 `gpioc`（MIT）：https://github.com/walnutpi/gpioc
|
||||
- FastAPI WebSockets：https://fastapi.tiangolo.com/advanced/websockets/
|
||||
- FastAPI StaticFiles：https://fastapi.tiangolo.com/tutorial/static-files/
|
||||
--- a/整体开发需求/02_屏幕底层控制接口需求.md
|
||||
+++ b/整体开发需求/02_屏幕底层控制接口需求.md
|
||||
@@ -16,7 +16,7 @@
|
||||
|
||||
## 0. 需求编号索引
|
||||
|
||||
-本文件使用 `DISPLAY-*`、`CONFIG-*` 和 `HW-*` 编号描述显示边界、驱动、配置和硬件契约。网页/API 入口见 `01_网页配置端需求.md`，测试覆盖关系见 `如何测试/核桃派点阵屏控制服务测试流程.md`。
|
||||
+本文件使用 `DISPLAY-*`、`CONFIG-*` 和 `HW-*` 编号描述显示边界、驱动、配置和硬件契约。网页/API 入口见 `01_网页配置端需求.md`，测试覆盖关系见 `测试相关资料/如何测试/核桃派点阵屏控制服务测试流程.md`。
|
||||
|
||||
| 编号 | 范围 | 当前阶段要求 |
|
||||
|---|---|---|
|
||||
@@ -604,7 +604,7 @@
|
||||
- FastAPI 进程内的独立电压监测组件负责持续读取和缓存，并在锁外把保护指令交给显示输出仲裁器；`DisplayService` 不直接访问 ADC。ADC 故障不得终止显示或驱动生命周期，取得过成功样本后须保持最后保护而不是误解除。
|
||||
- 每台设备通过 `CONFIG-SCREEN-VOLTAGE` 独立保存一次比例校准；校准只补偿当前 ADC 与测量点的比例误差，不能替代接线、共地和型号检查。
|
||||
- 当前实现 `DISPLAY-LOW-VOLTAGE-PROTECTION`：校准后电压在 `4.5..4.8V` 线性限亮，严格低于 `4.5V` 覆盖 35% 低电图标，严格高于 `4.8V` 经恢复确认撤销。它不实现过压保护、物理关断、BMS 或核桃派关机。
|
||||
-- 完整接线、ADS1110 协议、换算公式和官方资料见 `M5Stack Unit ADC v1.1相关内容/`；真实硬件验证映射到 `TEST-ADC-HARDWARE`。
|
||||
+- 完整接线、ADS1110 协议、换算公式和官方资料见 `硬件相关资料和硬件的连接/M5Stack Unit ADC v1.1相关内容/`；真实硬件验证映射到 `TEST-ADC-HARDWARE`。
|
||||
|
||||
## 11. 后续实现验收清单
|
||||
|
||||
@@ -641,10 +641,9 @@
|
||||
|
||||
## 13. 参考资料
|
||||
|
||||
-- 本地资料：`点阵屏幕相关资料/RGB-Matrix-P3-64x64-F_核桃派ZeroW控制说明.md`
|
||||
-- 本地资料：`点阵屏幕相关资料/点阵屏幕_GPIO连接简表_开发用.md`
|
||||
-- 本地资料：`M5Stack Unit ADC v1.1相关内容/README.md`
|
||||
-- 本地资料：`M5Stack Unit ADC v1.1相关内容/02_ADS1110使用与开发约定_给Codex.md`
|
||||
+- 本地接线资料：`硬件相关资料和硬件的连接/点阵屏幕相关资料/手动接线说明/核桃派ZeroW_HUB75_接线与首次上电检查.md`
|
||||
+- 本地资料：`硬件相关资料和硬件的连接/M5Stack Unit ADC v1.1相关内容/README.md`
|
||||
+- 本地资料：`硬件相关资料和硬件的连接/M5Stack Unit ADC v1.1相关内容/02_ADS1110使用与开发约定_给Codex.md`
|
||||
- 核桃派官方 `gpioc`（MIT）：https://github.com/walnutpi/gpioc
|
||||
- 核桃派 ZeroW 参数：https://wiki.walnutpi.com/docs/walnutpi_1/intro/hw-parameter/
|
||||
- H616/H618 PIO 寄存器依据：板端 device tree `allwinner,sun50i-h616-pinctrl` 与项目内上游来源记录
|
||||
--- a/核桃派软件源代码/README.md
|
||||
+++ b/核桃派软件源代码/README.md
|
||||
@@ -3,6 +3,8 @@
|
||||
本目录是核桃派 ZeroW/H618 的独立服务源码，控制一块 64×64、1/32 扫描、ABCDE 行寻址的 HUB75 RGB 点阵屏。生产驱动是项目自带的 `walnutpi-h618-hub75`，不依赖其他开发板的 GPIO 库。
|
||||
|
||||
## 路径与运行方式
|
||||
+
|
||||
+下列源码运行、编译和手工部署命令均在本文件所在的 `核桃派软件源代码/` 目录执行；发布命令另行标明从工作区根目录执行。Windows 本机测试使用根目录下 `测试相关资料/如何测试/本机测试环境/README.md` 的命令。
|
||||
|
||||
- 程序：`/opt/matrix-screen-controller`
|
||||
- 持久数据：`/var/lib/matrix-screen-controller`
|
||||
@@ -18,11 +20,11 @@
|
||||
MATRIX_DRIVER=mock .venv/bin/python -m uvicorn app.main:app --host 127.0.0.1 --port 8080
|
||||
```
|
||||
|
||||
-核桃派不具备境外网络条件。生产安装必须使用项目根目录 `离线依赖/其他依赖/aarch64-py311/` 中已校验的 wheel，并强制 `--no-index`：
|
||||
+核桃派不具备境外网络条件。生产安装必须使用项目根目录 `发布更新相关/其他依赖/aarch64-py311/` 中已校验的 wheel，并强制 `--no-index`：
|
||||
|
||||
```bash
|
||||
python3 -m venv .venv
|
||||
-.venv/bin/pip install --no-index --find-links ../离线依赖/其他依赖/aarch64-py311 -r requirements.txt
|
||||
+.venv/bin/pip install --no-index --find-links ../发布更新相关/其他依赖/aarch64-py311 -r requirements.txt
|
||||
make -C app/display/native clean all
|
||||
```
|
||||
|
||||
@@ -51,7 +53,7 @@
|
||||
sudo app/display/native/hub75_benchmark --duration 60 --refresh-rate 100 --brightness 40 --dev-mem
|
||||
```
|
||||
|
||||
-接屏门槛与全部人工停顿顺序见项目上层 `如何测试/核桃派点阵屏控制服务测试流程.md`。
|
||||
+接屏门槛与全部人工停顿顺序见项目上层 `测试相关资料/如何测试/核桃派点阵屏控制服务测试流程.md`。
|
||||
|
||||
## 闪烁修复状态
|
||||
|
||||
@@ -88,7 +90,7 @@
|
||||
python ".\核桃派软件源代码\scripts\export_release.py" ota --notes "本次更新说明"
|
||||
```
|
||||
|
||||
-OTA 输出为 `OTA数据包/<版本>/`；镜像输出为 `离线依赖/导出包/<版本>/`。已有版本目录不会覆盖；删除任一旧版本目录不影响项目或设备，后续构建不得引用历史产物。
|
||||
+OTA 输出为 `发布更新相关/OTA数据包/<版本>/`；镜像输出为 `发布更新相关/导出包/<版本>/`。已有版本目录不会覆盖；删除任一旧版本目录不影响项目或设备，后续构建不得引用历史产物。
|
||||
|
||||
## 可刷镜像导出与同版本修复
|
||||
|
||||
--- a/核桃派软件源代码/kernel/README.md
|
||||
+++ b/核桃派软件源代码/kernel/README.md
|
||||
@@ -14,11 +14,11 @@
|
||||
`walnutpi-linux-6.1.31-30ff3fd5.tar.gz`; its measured SHA-256 is
|
||||
`8659bb3d64313c4693c3605374167a8145186e5c9d43eb771a52a7359699302f`.
|
||||
The fixed archive is registered at
|
||||
-`离线依赖/其他依赖/kernel-source/walnutpi-linux-6.1.31-30ff3fd5/` so the kernel can be
|
||||
+`发布更新相关/其他依赖/kernel-source/walnutpi-linux-6.1.31-30ff3fd5/` so the kernel can be
|
||||
rebuilt without network access. It is a build input and is never copied into an IMG or OTA.
|
||||
|
||||
The exact production files accepted by the browser and real HUB75 GPIO tests are registered at
|
||||
-`离线依赖/其他依赖/aarch64-kernel/6.1.31-matrix-axp313a1/`. Future IMG exports install this
|
||||
+`发布更新相关/其他依赖/aarch64-kernel/6.1.31-matrix-axp313a1/`. Future IMG exports install this
|
||||
precompiled payload and do not rebuild the kernel unless patches, DTS, or kernel configuration
|
||||
change.
|
||||
|
||||
--- a/核桃派软件源代码/scripts/build_ota_package.py
|
||||
+++ b/核桃派软件源代码/scripts/build_ota_package.py
|
||||
@@ -25,15 +25,15 @@
|
||||
args = parser.parse_args()
|
||||
source_root = Path(__file__).resolve().parents[1]
|
||||
project_root = source_root.parent
|
||||
- wheelhouse = project_root / "离线依赖" / "其他依赖" / "aarch64-py311"
|
||||
- frpc_bundle = project_root / "离线依赖" / "其他依赖" / "frp" / "0.71.0" / "linux-arm64"
|
||||
+ wheelhouse = project_root / "发布更新相关" / "其他依赖" / "aarch64-py311"
|
||||
+ frpc_bundle = project_root / "发布更新相关" / "其他依赖" / "frp" / "0.71.0" / "linux-arm64"
|
||||
version = read_software_version(source_root)
|
||||
policy = read_policy(source_root)
|
||||
if policy["checkpoints"] and version < type(version).parse(policy["checkpoints"][-1]["version"]):
|
||||
parser.error("源码包含未发布的软件依赖；请使用 export_release.py ota --version 导出安装节点")
|
||||
if version.patch != 0:
|
||||
frpc_bundle = None
|
||||
- output_root = (args.output_root or project_root / "OTA数据包").resolve()
|
||||
+ output_root = (args.output_root or project_root / "发布更新相关" / "OTA数据包").resolve()
|
||||
version_dir = output_root / str(version)
|
||||
if version_dir.exists():
|
||||
parser.error(f"version output already exists and will not be overwritten: {version_dir}")
|
||||
--- a/核桃派软件源代码/scripts/deploy_walnutpi.sh
|
||||
+++ b/核桃派软件源代码/scripts/deploy_walnutpi.sh
|
||||
@@ -8,8 +8,8 @@
|
||||
|
||||
SOURCE_ROOT=$(CDPATH= cd -- "$(dirname -- "$0")/.." && pwd)
|
||||
PROJECT_ROOT=$(CDPATH= cd -- "$SOURCE_ROOT/.." && pwd)
|
||||
-WHEELHOUSE=${WHEELHOUSE:-$PROJECT_ROOT/离线依赖/其他依赖/aarch64-py311}
|
||||
-FRPC_BUNDLE=${FRPC_BUNDLE:-$PROJECT_ROOT/离线依赖/其他依赖/frp/0.71.0/linux-arm64}
|
||||
+WHEELHOUSE=${WHEELHOUSE:-$PROJECT_ROOT/发布更新相关/其他依赖/aarch64-py311}
|
||||
+FRPC_BUNDLE=${FRPC_BUNDLE:-$PROJECT_ROOT/发布更新相关/其他依赖/frp/0.71.0/linux-arm64}
|
||||
DEFER_SERVICE_START=${DEFER_SERVICE_START:-0}
|
||||
MANIFEST=$WHEELHOUSE/SHA256SUMS
|
||||
TARGET=/opt/matrix-screen-controller
|
||||
--- a/核桃派软件源代码/scripts/export_release.py
|
||||
+++ b/核桃派软件源代码/scripts/export_release.py
|
||||
@@ -87,8 +87,8 @@
|
||||
"artifact_type": "ota",
|
||||
"created_at": "2026-08-13T15:31:23+08:00",
|
||||
"notes": "新增浏览器全量 OTA。",
|
||||
- "artifact_path": "OTA数据包/1.0.1/matrix-screen-controller-1.0.1.ota",
|
||||
- "artifact_sha256": sha256_file(path.parent / "OTA数据包" / "1.0.1" / "matrix-screen-controller-1.0.1.ota"),
|
||||
+ "artifact_path": "发布更新相关/OTA数据包/1.0.1/matrix-screen-controller-1.0.1.ota",
|
||||
+ "artifact_sha256": sha256_file(path.parent / "发布更新相关" / "OTA数据包" / "1.0.1" / "matrix-screen-controller-1.0.1.ota"),
|
||||
}
|
||||
],
|
||||
}
|
||||
@@ -146,7 +146,7 @@
|
||||
if len(matches) != 1:
|
||||
raise ValueError("current version must have exactly one release record before repair")
|
||||
index, record = matches[0]
|
||||
- expected_path = f"离线依赖/导出包/{version}/{artifact_name}"
|
||||
+ expected_path = f"发布更新相关/导出包/{version}/{artifact_name}"
|
||||
if (
|
||||
record.get("artifact_type") != "image"
|
||||
or record.get("artifact_path") != expected_path
|
||||
@@ -246,10 +246,10 @@
|
||||
target = current if args.repair_current else (args.version or next_patch(current))
|
||||
dependency_bundle = None
|
||||
if not args.repair_current and args.kind == "ota":
|
||||
- dependency_bundle = export_bundle(source, project / "离线依赖" / "其他依赖", current, target)
|
||||
+ dependency_bundle = export_bundle(source, project / "发布更新相关" / "其他依赖", current, target)
|
||||
if args.kind == "image" and not args.repair_current and target <= current:
|
||||
parser.error("image candidate version must be newer than the current version")
|
||||
- output_root = project / "OTA数据包" if args.kind == "ota" else project / "离线依赖" / "导出包"
|
||||
+ output_root = project / "发布更新相关" / "OTA数据包" if args.kind == "ota" else project / "发布更新相关" / "导出包"
|
||||
official_directory = output_root / str(target)
|
||||
final_directory = args.candidate_output.resolve() if args.candidate_output is not None else official_directory
|
||||
if args.candidate_output is not None:
|
||||
@@ -299,7 +299,7 @@
|
||||
artifact = temporary_directory / f"matrix-screen-controller-{target}.ota"
|
||||
info = build_package(
|
||||
staged_source,
|
||||
- project / "离线依赖" / "其他依赖" / "aarch64-py311",
|
||||
+ project / "发布更新相关" / "其他依赖" / "aarch64-py311",
|
||||
artifact,
|
||||
version=target,
|
||||
release_notes=args.notes,
|
||||
@@ -334,29 +334,29 @@
|
||||
bootstrap_bundle = Path(staging_text) / "MSCBOOT.TGZ"
|
||||
kernel_dependency = (
|
||||
project
|
||||
- / "离线依赖"
|
||||
+ / "发布更新相关"
|
||||
/ "其他依赖"
|
||||
/ "aarch64-kernel"
|
||||
/ "6.1.31-matrix-axp313a1"
|
||||
)
|
||||
kernel_source = (
|
||||
project
|
||||
- / "离线依赖"
|
||||
+ / "发布更新相关"
|
||||
/ "其他依赖"
|
||||
/ "kernel-source"
|
||||
/ "walnutpi-linux-6.1.31-30ff3fd5"
|
||||
)
|
||||
manifest = build_image(
|
||||
- project / "离线依赖" / "核桃派镜像" / "2025-3-6_V2.5.1_WalnutPi-1B_6.1.31_debian12_server.img",
|
||||
+ project / "发布更新相关" / "核桃派镜像" / "2025-3-6_V2.5.1_WalnutPi-1B_6.1.31_debian12_server.img",
|
||||
staged_source,
|
||||
- project / "离线依赖" / "其他依赖" / "aarch64-py311",
|
||||
- project / "离线依赖" / "其他依赖" / "debian12-aarch64",
|
||||
+ project / "发布更新相关" / "其他依赖" / "aarch64-py311",
|
||||
+ project / "发布更新相关" / "其他依赖" / "debian12-aarch64",
|
||||
kernel_dependency,
|
||||
kernel_source,
|
||||
config,
|
||||
artifact,
|
||||
bootstrap_bundle,
|
||||
- project / "离线依赖" / "其他依赖" / "frp" / "0.71.0" / "linux-arm64",
|
||||
+ project / "发布更新相关" / "其他依赖" / "frp" / "0.71.0" / "linux-arm64",
|
||||
)
|
||||
subprocess.run(
|
||||
[
|
||||
@@ -419,7 +419,7 @@
|
||||
"artifact_type": args.kind,
|
||||
"created_at": manifest["created_at"],
|
||||
"notes": args.notes.strip(),
|
||||
- "artifact_path": f"{'OTA数据包' if args.kind == 'ota' else '离线依赖/导出包'}/{target}/{artifact.name}",
|
||||
+ "artifact_path": f"{'发布更新相关/OTA数据包' if args.kind == 'ota' else '发布更新相关/导出包'}/{target}/{artifact.name}",
|
||||
"artifact_sha256": manifest["image_sha256"] if args.kind == "image" else manifest["artifact_sha256"],
|
||||
**(release_metadata(target) if args.kind == "ota" else {}),
|
||||
**({"component_checkpoints": policy["checkpoints"]} if args.kind == "ota" else {}),
|
||||
--- a/核桃派软件源代码/scripts/install_frpc_system.sh
|
||||
+++ b/核桃派软件源代码/scripts/install_frpc_system.sh
|
||||
@@ -12,7 +12,7 @@
|
||||
|
||||
SOURCE_ROOT=$(CDPATH= cd -- "$(dirname -- "$0")/.." && pwd)
|
||||
PROJECT_ROOT=$(CDPATH= cd -- "$SOURCE_ROOT/.." && pwd)
|
||||
-BUNDLE=${FRPC_BUNDLE:-$PROJECT_ROOT/离线依赖/其他依赖/frp/0.71.0/linux-arm64}
|
||||
+BUNDLE=${FRPC_BUNDLE:-$PROJECT_ROOT/发布更新相关/其他依赖/frp/0.71.0/linux-arm64}
|
||||
UNIT_SOURCE=$SOURCE_ROOT/systemd/matrix-screen-frpc.service
|
||||
UNIT=/etc/systemd/system/matrix-screen-frpc.service
|
||||
DROPIN_DIR=/etc/systemd/system/matrix-screen-frpc.service.d
|
||||
--- a/核桃派软件源代码/scripts/promote_image_release.py
|
||||
+++ b/核桃派软件源代码/scripts/promote_image_release.py
|
||||
@@ -106,7 +106,7 @@
|
||||
raise ValueError("image candidate README does not match its embedded defaults")
|
||||
_validate_report(validation, digest, version)
|
||||
|
||||
- dependency_root = project / "离线依赖" / "其他依赖"
|
||||
+ dependency_root = project / "发布更新相关" / "其他依赖"
|
||||
kernel = dependency_root / "aarch64-kernel" / "6.1.31-matrix-axp313a1"
|
||||
with tempfile.TemporaryDirectory(prefix="matrix-image-promotion-") as temporary_text:
|
||||
temporary = Path(temporary_text)
|
||||
@@ -133,7 +133,7 @@
|
||||
history = _history(history_path)
|
||||
if any(record.get("version") == str(version) for record in history["releases"]):
|
||||
raise ValueError("validated image version is already registered")
|
||||
- final = project / "离线依赖" / "导出包" / str(version)
|
||||
+ final = project / "发布更新相关" / "导出包" / str(version)
|
||||
if final.exists():
|
||||
raise ValueError("formal image release directory already exists")
|
||||
stamp = datetime.now(timezone.utc).astimezone().isoformat(timespec="seconds")
|
||||
@@ -149,7 +149,7 @@
|
||||
"artifact_type": "image",
|
||||
"created_at": manifest["created_at"],
|
||||
"notes": notes.strip(),
|
||||
- "artifact_path": f"离线依赖/导出包/{version}/{artifact_name}",
|
||||
+ "artifact_path": f"发布更新相关/导出包/{version}/{artifact_name}",
|
||||
"artifact_sha256": digest,
|
||||
"validation_path": f"{archive.relative_to(project).as_posix()}/实机验收.json",
|
||||
"validated_at": stamp,
|
||||
--- a/核桃派软件源代码/scripts/repair_ota_release.py
|
||||
+++ b/核桃派软件源代码/scripts/repair_ota_release.py
|
||||
@@ -23,7 +23,7 @@
|
||||
os.close(fd)
|
||||
try:
|
||||
version = read_software_version(source)
|
||||
- current = project / 'OTA数据包' / str(version)
|
||||
+ current = project / '发布更新相关' / 'OTA数据包' / str(version)
|
||||
name = f'matrix-screen-controller-{version}.ota'
|
||||
history_path = project / '发布记录.json'
|
||||
history = _history(history_path)
|
||||
--- a/核桃派软件源代码/scripts/update_walnutpi.sh
|
||||
+++ b/核桃派软件源代码/scripts/update_walnutpi.sh
|
||||
@@ -12,8 +12,8 @@
|
||||
|
||||
SOURCE_ROOT=$(CDPATH= cd -- "$(dirname -- "$0")/.." && pwd)
|
||||
PROJECT_ROOT=$(CDPATH= cd -- "$SOURCE_ROOT/.." && pwd)
|
||||
-WHEELHOUSE=${WHEELHOUSE:-$PROJECT_ROOT/离线依赖/其他依赖/aarch64-py311}
|
||||
-FRPC_BUNDLE=${FRPC_BUNDLE:-$PROJECT_ROOT/离线依赖/其他依赖/frp/0.71.0/linux-arm64}
|
||||
+WHEELHOUSE=${WHEELHOUSE:-$PROJECT_ROOT/发布更新相关/其他依赖/aarch64-py311}
|
||||
+FRPC_BUNDLE=${FRPC_BUNDLE:-$PROJECT_ROOT/发布更新相关/其他依赖/frp/0.71.0/linux-arm64}
|
||||
MANIFEST=$WHEELHOUSE/SHA256SUMS
|
||||
TARGET=/opt/matrix-screen-controller
|
||||
DATA_ROOT=/var/lib/matrix-screen-controller
|
||||
--- a/核桃派软件源代码/tests/test_kernel_artifact_dependency.py
|
||||
+++ b/核桃派软件源代码/tests/test_kernel_artifact_dependency.py
|
||||
@@ -96,8 +96,8 @@
|
||||
|
||||
|
||||
def test_registered_kernel_and_source_dependencies_are_complete():
|
||||
- kernel = PROJECT_ROOT / "离线依赖/其他依赖/aarch64-kernel/6.1.31-matrix-axp313a1"
|
||||
- source = PROJECT_ROOT / "离线依赖/其他依赖/kernel-source/walnutpi-linux-6.1.31-30ff3fd5"
|
||||
+ kernel = PROJECT_ROOT / "发布更新相关/其他依赖/aarch64-kernel/6.1.31-matrix-axp313a1"
|
||||
+ source = PROJECT_ROOT / "发布更新相关/其他依赖/kernel-source/walnutpi-linux-6.1.31-30ff3fd5"
|
||||
if os.environ.get("MATRIX_SOURCE_ONLY_UPDATE_TESTS") == "1":
|
||||
if not kernel.exists() and not source.exists():
|
||||
pytest.skip("source-only update payload intentionally omits image build dependencies")
|
||||
@@ -106,7 +106,7 @@
|
||||
assert info.regular_file_count == 3056
|
||||
assert info.unpacked_file_bytes == 160051604
|
||||
assert verify_source_dependency(source)["archive_bytes"] == 249095239
|
||||
- registry = json.loads((PROJECT_ROOT / "离线依赖/其他依赖/DEPENDENCIES.json").read_text(encoding="utf-8"))
|
||||
+ registry = json.loads((PROJECT_ROOT / "发布更新相关/其他依赖/DEPENDENCIES.json").read_text(encoding="utf-8"))
|
||||
active = {item["id"]: item for item in registry["active"]}
|
||||
assert active["axp313a-kernel-runtime"]["path"] == "aarch64-kernel/6.1.31-matrix-axp313a1"
|
||||
assert active["walnutpi-linux-kernel-source"]["path"] == (
|
||||
--- a/核桃派软件源代码/tests/test_ota_checkpoints.py
|
||||
+++ b/核桃派软件源代码/tests/test_ota_checkpoints.py
|
||||
@@ -187,7 +187,7 @@
|
||||
source.mkdir()
|
||||
(source / 'VERSION').write_text('1.0.6\n', encoding='utf-8')
|
||||
(source / 'FEATURE_UPDATED_AT').write_text('2026-09-07T20:00+08:00\n', encoding='utf-8')
|
||||
- deps = tmp_path / '离线依赖/其他依赖'
|
||||
+ deps = tmp_path / '发布更新相关/其他依赖'
|
||||
binary = deps / 'frp/v/frpc'
|
||||
binary.parent.mkdir(parents=True)
|
||||
binary.write_bytes(b'frpc')
|
||||
@@ -213,11 +213,13 @@
|
||||
assert (source/'VERSION').read_text(encoding='utf-8').strip() == '1.1.0'
|
||||
monkeypatch.setattr(sys, 'argv', ['export', 'ota', '--notes', 'patch'])
|
||||
assert exporter.main() == 0
|
||||
- artifact = next((tmp_path/'OTA数据包/1.1.1').glob('*.ota'))
|
||||
+ artifact = next((tmp_path/'发布更新相关/OTA数据包/1.1.1').glob('*.ota'))
|
||||
with zipfile.ZipFile(artifact) as z, z.open('payload.tar.gz') as f, tarfile.open(fileobj=f, mode='r|gz') as t:
|
||||
assert not any('system-dependencies' in item.name for item in t)
|
||||
records = json.loads((tmp_path/'发布记录.json').read_text(encoding='utf-8'))['releases']
|
||||
assert [r['package_kind'] for r in records] == ['software-install', 'application']
|
||||
+ assert all(r['artifact_path'].startswith('发布更新相关/OTA数据包/') for r in records)
|
||||
+ assert all((tmp_path / r['artifact_path']).is_file() for r in records)
|
||||
assert (source/'FEATURE_UPDATED_AT').read_text(encoding='utf-8') == '2026-09-07T20:00+08:00\n'
|
||||
|
||||
|
||||
@@ -234,7 +236,7 @@
|
||||
exporter.main()
|
||||
assert (source/'VERSION').read_bytes() == original_version
|
||||
assert (tmp_path/'发布记录.json').read_bytes() == original
|
||||
- assert not list((tmp_path/'OTA数据包').iterdir())
|
||||
+ assert not list((tmp_path/'发布更新相关/OTA数据包').iterdir())
|
||||
assert not (tmp_path/'.release-export.lock').exists()
|
||||
|
||||
|
||||
@@ -268,13 +270,13 @@
|
||||
exporter, source = release_project(tmp_path, monkeypatch)
|
||||
monkeypatch.setattr(sys, 'argv', ['export', 'ota', '--version', '1.1.0', '--notes', 'original'])
|
||||
exporter.main()
|
||||
- artifact=tmp_path/'OTA数据包/1.1.0/matrix-screen-controller-1.1.0.ota'
|
||||
+ artifact=tmp_path/'发布更新相关/OTA数据包/1.1.0/matrix-screen-controller-1.1.0.ota'
|
||||
old=artifact.read_bytes();old_history=(tmp_path/'发布记录.json').read_bytes()
|
||||
(source/'fix.py').write_text('FIXED = True\n',encoding='utf-8')
|
||||
candidate=tmp_path/'candidate.ota'
|
||||
- build_package(source,tmp_path/'离线依赖/其他依赖/aarch64-py311',candidate,
|
||||
+ build_package(source,tmp_path/'发布更新相关/其他依赖/aarch64-py311',candidate,
|
||||
version=V.parse('1.1.0'),release_notes='repair',
|
||||
- system_dependencies=tmp_path/'离线依赖/其他依赖/frp/v')
|
||||
+ system_dependencies=tmp_path/'发布更新相关/其他依赖/frp/v')
|
||||
report=tmp_path/'validation.json'
|
||||
report.write_text(json.dumps({'package_sha256':hashlib.sha256(candidate.read_bytes()).hexdigest(),
|
||||
'installed_version':'1.1.0','status':'success','runtime_lifecycle_passed':True,
|
||||
--- a/核桃派软件源代码/tests/test_release_image.py
|
||||
+++ b/核桃派软件源代码/tests/test_release_image.py
|
||||
@@ -133,7 +133,7 @@
|
||||
assert export_release.main() == 0
|
||||
assert (source / "VERSION").read_text(encoding="utf-8") == "1.1.0\n"
|
||||
assert history.read_text(encoding="utf-8") == '{"schema_version":1,"releases":[]}'
|
||||
- assert not (tmp_path / "离线依赖" / "导出包" / "1.1.1").exists()
|
||||
+ assert not (tmp_path / "发布更新相关" / "导出包" / "1.1.1").exists()
|
||||
assert {path.name for path in candidate.iterdir()} == {
|
||||
"README.md", "manifest.json", "matrix-screen-controller-1.1.1.img",
|
||||
"matrix-screen-controller-1.1.1.img.sha256",
|
||||
--- a/测试相关资料/如何测试/本机测试环境/README.md
|
||||
+++ b/测试相关资料/如何测试/本机测试环境/README.md
|
||||
@@ -5,10 +5,10 @@
|
||||
## 常用命令
|
||||
|
||||
```powershell
|
||||
-python ".\如何测试\本机测试环境\local_test.py" setup
|
||||
-python ".\如何测试\本机测试环境\local_test.py" test --suite all
|
||||
-python ".\如何测试\本机测试环境\local_test.py" serve --port 8765
|
||||
-python ".\如何测试\本机测试环境\local_test.py" clean
|
||||
+python ".\测试相关资料\如何测试\本机测试环境\local_test.py" setup
|
||||
+python ".\测试相关资料\如何测试\本机测试环境\local_test.py" test --suite all
|
||||
+python ".\测试相关资料\如何测试\本机测试环境\local_test.py" serve --port 8765
|
||||
+python ".\测试相关资料\如何测试\本机测试环境\local_test.py" clean
|
||||
```
|
||||
|
||||
测试套件：
|
||||
--- a/测试相关资料/如何测试/本机测试环境/local_test.py
|
||||
+++ b/测试相关资料/如何测试/本机测试环境/local_test.py
|
||||
@@ -11,7 +11,7 @@
|
||||
|
||||
|
||||
HARNESS_DIR = Path(__file__).resolve().parent
|
||||
-WORKSPACE_ROOT = HARNESS_DIR.parent.parent
|
||||
+WORKSPACE_ROOT = HARNESS_DIR.parents[2]
|
||||
SOURCE_DIR = WORKSPACE_ROOT / "核桃派软件源代码"
|
||||
VENV_DIR = HARNESS_DIR / ".venv"
|
||||
WORK_DIR = HARNESS_DIR / "work"
|
||||
--- a/测试相关资料/如何测试/核桃派点阵屏控制服务测试流程.md
|
||||
+++ b/测试相关资料/如何测试/核桃派点阵屏控制服务测试流程.md
|
||||
@@ -6,6 +6,7 @@
|
||||
|
||||
| 测试编号 | 主要覆盖 | 执行位置 | 人工停顿 |
|
||||
|---|---|---|---|
|
||||
+| `TEST-WORKSPACE-LAYOUT` | `DEPLOY-WORKSPACE-LAYOUT`、测试与发布路径、隔离和清理 | 本机中文及空格路径 | 否 |
|
||||
| `TEST-LOCAL-MOCK` | `WEB-*`、`DISPLAY-MOCK`、`CONFIG-*` | Windows 或隔离 Linux | 否 |
|
||||
| `TEST-NATIVE-UNIT` | `DISPLAY-DRIVER`、bitplane、映射、亮度、双缓冲 | 本机，不访问 `/dev/mem` | 否 |
|
||||
| `TEST-REMOTE-HEALTH` | `DEPLOY-*`、系统、网络、磁盘、工具 | 核桃派，无屏 | 否 |
|
||||
@@ -42,8 +43,8 @@
|
||||
从独立项目根执行：
|
||||
|
||||
```powershell
|
||||
-python ".\如何测试\本机测试环境\local_test.py" setup
|
||||
-python ".\如何测试\本机测试环境\local_test.py" test
|
||||
+python ".\测试相关资料\如何测试\本机测试环境\local_test.py" setup
|
||||
+python ".\测试相关资料\如何测试\本机测试环境\local_test.py" test
|
||||
```
|
||||
|
||||
前端测试：
|
||||
@@ -97,7 +98,9 @@
|
||||
|
||||
候选晋升的最低真实硬件门槛是同一摘要 IMG 在默认热点从上电起可用时完成一次完整正向首启、自动重启、SSH/sudo/root 拒绝、服务、内核、H618、网页和再次重启复验。SSID 不存在、认证失败和 DHCP 失败分支仍须通过自动化；没有另行执行真实故障网络矩阵时，在验收记录中明确写为“本次未重复实卡验证”，不得写成实卡通过。
|
||||
|
||||
-`TEST-OTA-REAL` 固定走 `1.0.0 → 1.0.1`：先用手工更新入口部署 1.0.0，再从系统设置选择工作区 `OTA数据包/1.0.1/` 中的真实包。更新前后对持久根做文件清单，除 schema 迁移和单条 OTA 状态外保持一致；确认版本、实例 ID、真实驱动、硬件映射、PWM4 OE 后端和 fault 计数。再次上传同一包必须在停服前拒绝。成功后不得残留旧 release、上传包、staging、数据备份或活动 OTA unit。另用受控失败包确认 1.0.5 及后续旧版本服务恢复后自动弹出最近失败日志，日志包含失败用例与回滚结论且可在局域网 HTTP 页面完整复制；成功更新清除旧日志。1.0.6 是发布记录中唯一经授权跳过旧 worker pytest 的历史诊断引导包，只用于先安装日志能力，其成品不得覆盖、实现不得复制到当前源码或任何后续包；1.0.7 及以后全部恢复严格 pytest 门槛。实屏应在更新期间以 40% 亮度显示整体缩放为 58×58、位于 `(3,3)` 的居中 OTA 进度，四边均有黑色空白，并在成功后恢复默认内容；摄像头画面不清晰时必须等待用户肉眼确认。
|
||||
+历史 OTA 验收的前提是备齐对应版本的原始包及其摘要；历史产物允许按生命周期删除。缺少所需版本时应报告“验收材料缺失”，停止该历史版本组合的验收，不把路径存在性失败记为更新失败，也不自动导出或替换成其他版本。
|
||||
+
|
||||
+`TEST-OTA-REAL` 固定走 `1.0.0 → 1.0.1`：先用手工更新入口部署 1.0.0，再从系统设置选择工作区 `发布更新相关/OTA数据包/1.0.1/` 中的真实包。更新前后对持久根做文件清单，除 schema 迁移和单条 OTA 状态外保持一致；确认版本、实例 ID、真实驱动、硬件映射、PWM4 OE 后端和 fault 计数。再次上传同一包必须在停服前拒绝。成功后不得残留旧 release、上传包、staging、数据备份或活动 OTA unit。另用受控失败包确认 1.0.5 及后续旧版本服务恢复后自动弹出最近失败日志，日志包含失败用例与回滚结论且可在局域网 HTTP 页面完整复制；成功更新清除旧日志。1.0.6 是发布记录中唯一经授权跳过旧 worker pytest 的历史诊断引导包，只用于先安装日志能力，其成品不得覆盖、实现不得复制到当前源码或任何后续包；1.0.7 及以后全部恢复严格 pytest 门槛。实屏应在更新期间以 40% 亮度显示整体缩放为 58×58、位于 `(3,3)` 的居中 OTA 进度，四边均有黑色空白，并在成功后恢复默认内容；摄像头画面不清晰时必须等待用户肉眼确认。
|
||||
|
||||
## 2. 原生驱动单元测试
|
||||
|
||||
@@ -240,3 +243,9 @@
|
||||
完整包仍执行全部 pytest。涉及主服务停启的 OTA 修复必须走真实设备 OTA，核对磁盘与 API 版本、成功状态、持久数据、frp 启停和事务清理。systemctl 替身仅能验证业务分支，不能作为真实目录生命周期或 OTA 通过证据。显示效果与软件验收分开记录，缺少人工/摄像头证据时不能记为实屏通过。
|
||||
|
||||
同版本修复覆盖验证报告不匹配、候选源码不匹配、历史摘要损坏、提交失败回退及原始包完整归档；正式产物必须与实机验收候选包摘要一致，不得在实机成功后重新构建替换。
|
||||
+
|
||||
+## 工作区目录适配验收（`TEST-WORKSPACE-LAYOUT`）
|
||||
+
|
||||
+从工作区根目录及其他调用目录分别通过测试入口绝对路径执行测试；复制源码、测试入口、当前需求和必要离线材料到含中文及空格的隔离目录，按本文件命令运行 Python、前端与 mock 健康检查。复制件不得依赖原工作区或历史导出产物。发布定位用临时夹具测试，确认依赖来自 `发布更新相关/其他依赖/`，OTA 与 IMG 输出分别位于 `发布更新相关/` 下的 `OTA数据包/`、`导出包/`；不为路径验证推进正式版本。
|
||||
+
|
||||
+在隔离目录执行 `clean`，确认 `.venv`、依赖指纹和人工持久数据保持不变，仅删除登记的临时目标；越界路径必须拒绝。核对现存文档链接和发布记录中的产物路径，已删除的历史产物允许缺失，须明确其历史性质，不重新生成。镜像内部 `project/离线依赖/` 属于载荷协议，构建器与首启脚本应继续保持一致。
|
||||
--- a/硬件相关资料和硬件的连接/M5Stack Unit ADC v1.1相关内容/02_ADS1110使用与开发约定_给Codex.md
|
||||
+++ b/硬件相关资料和硬件的连接/M5Stack Unit ADC v1.1相关内容/02_ADS1110使用与开发约定_给Codex.md
|
||||
@@ -113,16 +113,16 @@
|
||||
|
||||
```bash
|
||||
# 本机纯计算/协议自测，不访问 I²C，Windows 也可以运行
|
||||
-python "M5Stack Unit ADC v1.1相关内容/示例程序/read_unit_adc_v1_1.py" --self-test
|
||||
+python "硬件相关资料和硬件的连接/M5Stack Unit ADC v1.1相关内容/示例程序/read_unit_adc_v1_1.py" --self-test
|
||||
|
||||
# 核桃派单次读数
|
||||
-python3 "M5Stack Unit ADC v1.1相关内容/示例程序/read_unit_adc_v1_1.py"
|
||||
+python3 "硬件相关资料和硬件的连接/M5Stack Unit ADC v1.1相关内容/示例程序/read_unit_adc_v1_1.py"
|
||||
|
||||
# 连续读数
|
||||
-python3 "M5Stack Unit ADC v1.1相关内容/示例程序/read_unit_adc_v1_1.py" --watch
|
||||
+python3 "硬件相关资料和硬件的连接/M5Stack Unit ADC v1.1相关内容/示例程序/read_unit_adc_v1_1.py" --watch
|
||||
|
||||
# 使用一次比例校正
|
||||
-python3 "M5Stack Unit ADC v1.1相关内容/示例程序/read_unit_adc_v1_1.py" --calibration-factor 1.00604 --watch
|
||||
+python3 "硬件相关资料和硬件的连接/M5Stack Unit ADC v1.1相关内容/示例程序/read_unit_adc_v1_1.py" --calibration-factor 1.00604 --watch
|
||||
```
|
||||
|
||||
额外参数通过 `--help` 查看。独立工具必须保持 Python 标准库实现并与主服务监测器分开；不能把独立无限循环直接放进 FastAPI 进程，也不能与主服务同时长期读取同一地址。
|
||||
--- a/硬件相关资料和硬件的连接/M5Stack Unit ADC v1.1相关内容/官方资料/来源索引.md
|
||||
+++ b/硬件相关资料和硬件的连接/M5Stack Unit ADC v1.1相关内容/官方资料/来源索引.md
|
||||
@@ -15,7 +15,7 @@
|
||||
重新核验哈希时，在 PowerShell 中运行：
|
||||
|
||||
```powershell
|
||||
-Get-ChildItem -LiteralPath ".\M5Stack Unit ADC v1.1相关内容\官方资料" -Filter *.pdf |
|
||||
+Get-ChildItem -LiteralPath ".\硬件相关资料和硬件的连接\M5Stack Unit ADC v1.1相关内容\官方资料" -Filter *.pdf |
|
||||
Get-FileHash -Algorithm SHA256
|
||||
```
|
||||
|
||||
--- /dev/null
|
||||
+++ b/核桃派软件源代码/tests/test_workspace_layout.py
|
||||
@@ -0,0 +1,83 @@
|
||||
+from __future__ import annotations
|
||||
+
|
||||
+import importlib.util
|
||||
+import os
|
||||
+from pathlib import Path
|
||||
+import shutil
|
||||
+import subprocess
|
||||
+import sys
|
||||
+
|
||||
+import pytest
|
||||
+
|
||||
+
|
||||
+PROJECT_ROOT = Path(__file__).resolve().parents[2]
|
||||
+HARNESS_RELATIVE = Path("测试相关资料/如何测试/本机测试环境/local_test.py")
|
||||
+
|
||||
+
|
||||
+@pytest.fixture
|
||||
+def relocated_harness(tmp_path):
|
||||
+ original = PROJECT_ROOT / HARNESS_RELATIVE
|
||||
+ if not original.is_file() and os.environ.get("MATRIX_SOURCE_ONLY_UPDATE_TESTS") == "1":
|
||||
+ pytest.skip("source-only update payload intentionally omits the workstation harness")
|
||||
+ root = tmp_path / "独立 工作区"
|
||||
+ script = root / HARNESS_RELATIVE
|
||||
+ script.parent.mkdir(parents=True)
|
||||
+ shutil.copyfile(original, script)
|
||||
+ source = root / "核桃派软件源代码"
|
||||
+ (source / "app").mkdir(parents=True)
|
||||
+ for name in ("requirements.txt", "requirements-dev.txt"):
|
||||
+ (source / name).write_text("", encoding="utf-8")
|
||||
+ spec = importlib.util.spec_from_file_location("relocated_local_test", script)
|
||||
+ module = importlib.util.module_from_spec(spec)
|
||||
+ spec.loader.exec_module(module)
|
||||
+ return root, module
|
||||
+
|
||||
+
|
||||
+def test_harness_locates_relocated_source_from_unrelated_cwd(relocated_harness, tmp_path):
|
||||
+ root, harness = relocated_harness
|
||||
+ probe = (
|
||||
+ "import runpy, sys; from pathlib import Path; "
|
||||
+ "h = runpy.run_path(sys.argv[1]); h['_validate_layout'](); "
|
||||
+ "assert h['WORKSPACE_ROOT'] == Path(sys.argv[2]); "
|
||||
+ "assert h['SOURCE_DIR'] == Path(sys.argv[2]) / '核桃派软件源代码'"
|
||||
+ )
|
||||
+ subprocess.run(
|
||||
+ [sys.executable, "-c", probe, str(root / HARNESS_RELATIVE), str(root)],
|
||||
+ cwd=tmp_path,
|
||||
+ check=True,
|
||||
+ )
|
||||
+
|
||||
+
|
||||
+def test_clean_keeps_environment_and_manual_data_in_relocated_workspace(relocated_harness):
|
||||
+ root, harness = relocated_harness
|
||||
+ keep = {
|
||||
+ harness.VENV_PYTHON: b"interpreter sentinel",
|
||||
+ harness.REQUIREMENTS_STAMP: b"requirements sentinel",
|
||||
+ harness.DATA_DIR / "config.json": b"manual config sentinel",
|
||||
+ harness.DATA_DIR / "templates" / "example.json": b"manual template sentinel",
|
||||
+ }
|
||||
+ for path, content in keep.items():
|
||||
+ path.parent.mkdir(parents=True, exist_ok=True)
|
||||
+ path.write_bytes(content)
|
||||
+ for directory in (harness.WORK_DIR, harness.DATA_DIR / "runtime", harness.SOURCE_DIR / "app/__pycache__"):
|
||||
+ directory.mkdir(parents=True)
|
||||
+ (directory / "temporary").write_bytes(b"temporary")
|
||||
+ harness.clean()
|
||||
+ assert all(path.read_bytes() == content for path, content in keep.items())
|
||||
+ assert not harness.WORK_DIR.exists()
|
||||
+ assert not (harness.DATA_DIR / "runtime").exists()
|
||||
+ assert not (harness.SOURCE_DIR / "app/__pycache__").exists()
|
||||
+ with pytest.raises(harness.HarnessError):
|
||||
+ harness._assert_within(root.parent / "outside", root)
|
||||
+
|
||||
+
|
||||
+def test_clean_rejects_outside_target_before_deleting(relocated_harness, tmp_path, monkeypatch):
|
||||
+ _, harness = relocated_harness
|
||||
+ outside = tmp_path / "outside"
|
||||
+ outside.mkdir()
|
||||
+ marker = outside / "preserve"
|
||||
+ marker.write_bytes(b"unchanged")
|
||||
+ monkeypatch.setattr(harness, "WORK_DIR", outside)
|
||||
+ with pytest.raises(harness.HarnessError):
|
||||
+ harness.clean()
|
||||
+ assert marker.read_bytes() == b"unchanged"
|
||||
@@ -0,0 +1,9 @@
|
||||
# 核桃派镜像配置编辑器
|
||||
|
||||
`编辑器程序/` 保存 Windows 10/11 x64 可直接运行的绿色单 EXE；`编辑器源代码/` 保存 .NET 8 WinForms 源码。编辑器版本独立于核桃派软件版本，当前为 `1.0.1`，新版本发布时直接覆盖程序目录中的旧版本。
|
||||
|
||||
打开版本化 IMG 后可查看软件版本、账户名、Wi-Fi 和 IPv4 配置，密码默认遮挡。支持二次确认后修改原镜像，以及用 Windows 合法的新名称另存为定制副本；中文、空格和长路径均受支持。保存完成会生成无 BOM UTF-8 的同名 `.sha256` 并重新验证。损坏、截断、产品错误、未知 schema、配置摘要错误或现有镜像摘要不符时禁止保存。
|
||||
|
||||
1.0.1 修复了中文另存文件名被 ASCII 替换成 `?` 后无法重新打开的问题，并将主窗口、输入区域和应用内提示框改为随系统 DPI、显示器和分辨率自适应的大尺寸布局。
|
||||
|
||||
编辑器只修改 IMG 内固定的双槽配置区，不负责向 TF 卡写入镜像。写卡仍使用 Rufus 等原始磁盘写入工具。
|
||||
@@ -0,0 +1,7 @@
|
||||
# 镜像配置编辑器 1.0.1 C# 旧版归档
|
||||
|
||||
本目录是 2026-09-08 将镜像编辑器重写为 Python/PySide6 2.0.0 前的完整快照。内含原 `.NET 8 WinForms` 源码、绿色程序、版本、摘要和原说明。后续构建、测试和镜像发布不得引用本归档。
|
||||
|
||||
- 旧编辑器版本：`1.0.1`
|
||||
- 旧 EXE SHA-256：`bcee5a87b654999b5649948bbed49b9071ebb09e5e9caef5cc8f22331ee482c3`
|
||||
- 原程序文件：`编辑器程序/核桃派镜像配置编辑器.exe`
|
||||
@@ -0,0 +1,131 @@
|
||||
namespace MatrixImageEditor;
|
||||
|
||||
internal enum AppDialogIcon
|
||||
{
|
||||
Information,
|
||||
Warning,
|
||||
Error,
|
||||
}
|
||||
|
||||
internal sealed class AppDialog : Form
|
||||
{
|
||||
private static readonly Size PreferredLogicalSize = new(640, 320);
|
||||
private static readonly Size MinimumLogicalSize = new(520, 260);
|
||||
private readonly Screen initialScreen;
|
||||
|
||||
private AppDialog(IWin32Window? owner, string message, string title, MessageBoxButtons buttons, AppDialogIcon icon)
|
||||
{
|
||||
initialScreen = owner is null ? Screen.PrimaryScreen! : Screen.FromHandle(owner.Handle);
|
||||
Text = title;
|
||||
AutoScaleMode = AutoScaleMode.Dpi;
|
||||
Font = new Font("Microsoft YaHei UI", 10F);
|
||||
FormBorderStyle = FormBorderStyle.Sizable;
|
||||
StartPosition = FormStartPosition.Manual;
|
||||
ShowInTaskbar = false;
|
||||
MinimizeBox = false;
|
||||
MaximizeBox = false;
|
||||
|
||||
var body = new TableLayoutPanel
|
||||
{
|
||||
Dock = DockStyle.Fill,
|
||||
Padding = new Padding(24),
|
||||
ColumnCount = 2,
|
||||
RowCount = 2,
|
||||
};
|
||||
body.ColumnStyles.Add(new ColumnStyle(SizeType.AutoSize));
|
||||
body.ColumnStyles.Add(new ColumnStyle(SizeType.Percent, 100));
|
||||
body.RowStyles.Add(new RowStyle(SizeType.Percent, 100));
|
||||
body.RowStyles.Add(new RowStyle(SizeType.AutoSize));
|
||||
|
||||
var picture = new PictureBox
|
||||
{
|
||||
Image = GetIcon(icon).ToBitmap(),
|
||||
SizeMode = PictureBoxSizeMode.CenterImage,
|
||||
Size = new Size(64, 64),
|
||||
Margin = new Padding(0, 0, 20, 0),
|
||||
Anchor = AnchorStyles.Top,
|
||||
};
|
||||
var text = new TextBox
|
||||
{
|
||||
Text = message,
|
||||
ReadOnly = true,
|
||||
Multiline = true,
|
||||
WordWrap = true,
|
||||
ScrollBars = ScrollBars.Vertical,
|
||||
Dock = DockStyle.Fill,
|
||||
BackColor = SystemColors.Window,
|
||||
BorderStyle = BorderStyle.FixedSingle,
|
||||
Margin = new Padding(0),
|
||||
ShortcutsEnabled = true,
|
||||
};
|
||||
var actions = new FlowLayoutPanel
|
||||
{
|
||||
Dock = DockStyle.Fill,
|
||||
AutoSize = true,
|
||||
FlowDirection = FlowDirection.RightToLeft,
|
||||
WrapContents = false,
|
||||
Margin = new Padding(0, 20, 0, 0),
|
||||
};
|
||||
|
||||
if (buttons == MessageBoxButtons.YesNo)
|
||||
{
|
||||
var no = Button("否", DialogResult.No);
|
||||
var yes = Button("是", DialogResult.Yes);
|
||||
actions.Controls.Add(no);
|
||||
actions.Controls.Add(yes);
|
||||
AcceptButton = yes;
|
||||
CancelButton = no;
|
||||
}
|
||||
else
|
||||
{
|
||||
var ok = Button("确定", DialogResult.OK);
|
||||
actions.Controls.Add(ok);
|
||||
AcceptButton = ok;
|
||||
CancelButton = ok;
|
||||
}
|
||||
|
||||
body.Controls.Add(picture, 0, 0);
|
||||
body.Controls.Add(text, 1, 0);
|
||||
body.Controls.Add(actions, 0, 1);
|
||||
body.SetColumnSpan(actions, 2);
|
||||
Controls.Add(body);
|
||||
}
|
||||
|
||||
public static DialogResult Show(IWin32Window? owner, string message, string title, MessageBoxButtons buttons, AppDialogIcon icon)
|
||||
{
|
||||
using var dialog = new AppDialog(owner, message, title, buttons, icon);
|
||||
return owner is null ? dialog.ShowDialog() : dialog.ShowDialog(owner);
|
||||
}
|
||||
|
||||
public static void Information(IWin32Window? owner, string message, string title) => Show(owner, message, title, MessageBoxButtons.OK, AppDialogIcon.Information);
|
||||
public static void Error(IWin32Window? owner, string message, string title) => Show(owner, message, title, MessageBoxButtons.OK, AppDialogIcon.Error);
|
||||
public static DialogResult Confirm(IWin32Window? owner, string message, string title) => Show(owner, message, title, MessageBoxButtons.YesNo, AppDialogIcon.Warning);
|
||||
|
||||
protected override void OnShown(EventArgs eventArgs)
|
||||
{
|
||||
base.OnShown(eventArgs);
|
||||
ResponsiveLayout.FitAndCenter(this, PreferredLogicalSize, MinimumLogicalSize, 0.8, initialScreen);
|
||||
}
|
||||
|
||||
protected override void OnDpiChanged(DpiChangedEventArgs eventArgs)
|
||||
{
|
||||
base.OnDpiChanged(eventArgs);
|
||||
BeginInvoke(() => ResponsiveLayout.FitAndCenter(this, PreferredLogicalSize, MinimumLogicalSize, 0.8));
|
||||
}
|
||||
|
||||
private static Button Button(string text, DialogResult result) => new()
|
||||
{
|
||||
Text = text,
|
||||
DialogResult = result,
|
||||
AutoSize = true,
|
||||
MinimumSize = new Size(110, 38),
|
||||
Margin = new Padding(10, 0, 0, 0),
|
||||
};
|
||||
|
||||
private static Icon GetIcon(AppDialogIcon icon) => icon switch
|
||||
{
|
||||
AppDialogIcon.Error => SystemIcons.Error,
|
||||
AppDialogIcon.Warning => SystemIcons.Warning,
|
||||
_ => SystemIcons.Information,
|
||||
};
|
||||
}
|
||||
@@ -0,0 +1,124 @@
|
||||
using System.Buffers.Binary;
|
||||
using System.Text;
|
||||
|
||||
namespace MatrixImageEditor;
|
||||
|
||||
public sealed class Fat16Disk : IDisposable
|
||||
{
|
||||
private readonly FileStream stream;
|
||||
private readonly long fatOffset;
|
||||
private readonly long rootOffset;
|
||||
private readonly int rootEntries;
|
||||
private readonly int fatBytes;
|
||||
private readonly long dataOffset;
|
||||
private readonly int clusterBytes;
|
||||
|
||||
public Fat16Disk(string path, bool writable)
|
||||
{
|
||||
stream = new FileStream(path, writable ? FileMode.Open : FileMode.Open, writable ? FileAccess.ReadWrite : FileAccess.Read, FileShare.Read, 1024 * 1024, FileOptions.RandomAccess);
|
||||
var mbr = ReadAt(0, 512);
|
||||
if (mbr[510] != 0x55 || mbr[511] != 0xAA) throw new InvalidDataException("文件没有有效的 MBR 分区表");
|
||||
var partitionLba = BinaryPrimitives.ReadUInt32LittleEndian(mbr.AsSpan(454, 4));
|
||||
var partitionSectors = BinaryPrimitives.ReadUInt32LittleEndian(mbr.AsSpan(458, 4));
|
||||
var partitionType = mbr[450];
|
||||
// WalnutPi labels this BPB-compatible FAT16 volume as 0x0C in the MBR.
|
||||
if (partitionLba == 0 || partitionSectors == 0 || partitionType is not (0x04 or 0x06 or 0x0B or 0x0C or 0x0E)) throw new InvalidDataException("镜像第一分区不是受支持的 FAT 启动分区");
|
||||
var partitionOffset = partitionLba * 512L;
|
||||
if (partitionOffset + partitionSectors * 512L > stream.Length) throw new InvalidDataException("镜像分区表超出文件边界");
|
||||
var bpb = ReadAt(partitionOffset, 512);
|
||||
var bytesPerSector = BinaryPrimitives.ReadUInt16LittleEndian(bpb.AsSpan(11, 2));
|
||||
var sectorsPerCluster = bpb[13];
|
||||
var reserved = BinaryPrimitives.ReadUInt16LittleEndian(bpb.AsSpan(14, 2));
|
||||
var fatCount = bpb[16];
|
||||
rootEntries = BinaryPrimitives.ReadUInt16LittleEndian(bpb.AsSpan(17, 2));
|
||||
var fatSectors = BinaryPrimitives.ReadUInt16LittleEndian(bpb.AsSpan(22, 2));
|
||||
if (bytesPerSector != 512 || sectorsPerCluster == 0 || fatSectors == 0 || rootEntries == 0) throw new InvalidDataException("镜像第一分区不是受支持的 FAT16");
|
||||
clusterBytes = bytesPerSector * sectorsPerCluster;
|
||||
fatBytes = fatSectors * bytesPerSector;
|
||||
fatOffset = partitionOffset + reserved * bytesPerSector;
|
||||
rootOffset = fatOffset + fatCount * fatBytes;
|
||||
var rootSectors = (rootEntries * 32L + bytesPerSector - 1) / bytesPerSector;
|
||||
dataOffset = rootOffset + rootSectors * bytesPerSector;
|
||||
}
|
||||
|
||||
public byte[] ReadFile(string name)
|
||||
{
|
||||
var entry = Find(name);
|
||||
var fat = ReadAt(fatOffset, fatBytes);
|
||||
var result = new byte[entry.Size];
|
||||
var written = 0;
|
||||
foreach (var cluster in Chain(entry.FirstCluster, fat))
|
||||
{
|
||||
var count = Math.Min(clusterBytes, result.Length - written);
|
||||
ReadAt(ClusterOffset(cluster), result.AsSpan(written, count));
|
||||
written += count;
|
||||
if (written == result.Length) break;
|
||||
}
|
||||
if (written != result.Length) throw new InvalidDataException("镜像配置文件被截断");
|
||||
return result;
|
||||
}
|
||||
|
||||
public void WriteFileRange(string name, int fileOffset, byte[] data)
|
||||
{
|
||||
var entry = Find(name);
|
||||
if (fileOffset < 0 || fileOffset + data.Length > entry.Size) throw new ArgumentOutOfRangeException(nameof(fileOffset));
|
||||
var fat = ReadAt(fatOffset, fatBytes);
|
||||
var chain = Chain(entry.FirstCluster, fat).ToArray();
|
||||
var remaining = data.Length;
|
||||
var sourceOffset = 0;
|
||||
var position = fileOffset;
|
||||
while (remaining > 0)
|
||||
{
|
||||
var chainIndex = position / clusterBytes;
|
||||
var within = position % clusterBytes;
|
||||
if (chainIndex >= chain.Length) throw new InvalidDataException("镜像配置文件簇链不足");
|
||||
var count = Math.Min(remaining, clusterBytes - within);
|
||||
stream.Position = ClusterOffset(chain[chainIndex]) + within;
|
||||
stream.Write(data, sourceOffset, count);
|
||||
position += count; sourceOffset += count; remaining -= count;
|
||||
}
|
||||
stream.Flush(flushToDisk: true);
|
||||
}
|
||||
|
||||
private (ushort FirstCluster, int Size) Find(string name)
|
||||
{
|
||||
var expected = Name83(name);
|
||||
var root = ReadAt(rootOffset, rootEntries * 32);
|
||||
for (var index = 0; index < rootEntries; index++)
|
||||
{
|
||||
var entry = root.AsSpan(index * 32, 32);
|
||||
if (entry[0] == 0x00) break;
|
||||
if (entry[0] == 0xE5 || entry[11] == 0x0F) continue;
|
||||
if (entry[..11].SequenceEqual(expected))
|
||||
{
|
||||
return (BinaryPrimitives.ReadUInt16LittleEndian(entry.Slice(26, 2)), BinaryPrimitives.ReadInt32LittleEndian(entry.Slice(28, 4)));
|
||||
}
|
||||
}
|
||||
throw new InvalidDataException($"镜像缺少 {name}");
|
||||
}
|
||||
|
||||
private IEnumerable<ushort> Chain(ushort first, byte[] fat)
|
||||
{
|
||||
var seen = new HashSet<ushort>();
|
||||
var cluster = first;
|
||||
while (cluster is >= 2 and < 0xFFF8)
|
||||
{
|
||||
if (!seen.Add(cluster)) throw new InvalidDataException("FAT16 簇链循环");
|
||||
yield return cluster;
|
||||
cluster = BinaryPrimitives.ReadUInt16LittleEndian(fat.AsSpan(cluster * 2, 2));
|
||||
}
|
||||
}
|
||||
|
||||
private long ClusterOffset(ushort cluster) => dataOffset + (cluster - 2L) * clusterBytes;
|
||||
private byte[] ReadAt(long offset, int count) { var value = new byte[count]; ReadAt(offset, value); return value; }
|
||||
private void ReadAt(long offset, Span<byte> destination) { stream.Position = offset; stream.ReadExactly(destination); }
|
||||
|
||||
private static byte[] Name83(string name)
|
||||
{
|
||||
var parts = name.ToUpperInvariant().Split('.', 2);
|
||||
if (parts[0].Length is < 1 or > 8 || (parts.Length == 2 && parts[1].Length > 3)) throw new ArgumentException("文件名不是 8.3 格式");
|
||||
return Encoding.ASCII.GetBytes(parts[0].PadRight(8) + (parts.Length == 2 ? parts[1] : "").PadRight(3));
|
||||
}
|
||||
|
||||
public void Dispose() => stream.Dispose();
|
||||
}
|
||||
@@ -0,0 +1,160 @@
|
||||
using System.Buffers.Binary;
|
||||
using System.Net;
|
||||
using System.Security.Cryptography;
|
||||
using System.Text;
|
||||
using System.Text.Json;
|
||||
using System.Text.Json.Serialization;
|
||||
using System.Text.RegularExpressions;
|
||||
|
||||
namespace MatrixImageEditor;
|
||||
|
||||
public sealed class ImageConfig
|
||||
{
|
||||
[JsonPropertyName("schema_version")] public int SchemaVersion { get; set; } = 1;
|
||||
[JsonPropertyName("product")] public string Product { get; set; } = "";
|
||||
[JsonPropertyName("software_version")] public string SoftwareVersion { get; set; } = "";
|
||||
[JsonPropertyName("account")] public AccountConfig Account { get; set; } = new();
|
||||
[JsonPropertyName("wifi")] public WifiConfig Wifi { get; set; } = new();
|
||||
[JsonPropertyName("ipv4")] public Ipv4Config Ipv4 { get; set; } = new();
|
||||
}
|
||||
|
||||
public sealed class AccountConfig
|
||||
{
|
||||
[JsonPropertyName("username")] public string Username { get; set; } = "";
|
||||
[JsonPropertyName("password")] public string Password { get; set; } = "";
|
||||
}
|
||||
|
||||
public sealed class WifiConfig
|
||||
{
|
||||
[JsonPropertyName("ssid")] public string Ssid { get; set; } = "";
|
||||
[JsonPropertyName("password")] public string Password { get; set; } = "";
|
||||
}
|
||||
|
||||
public sealed class Ipv4Config
|
||||
{
|
||||
[JsonPropertyName("mode")] public string Mode { get; set; } = "dhcp";
|
||||
[JsonPropertyName("address")] public string Address { get; set; } = "";
|
||||
[JsonPropertyName("prefix")] public int Prefix { get; set; }
|
||||
[JsonPropertyName("gateway")] public string Gateway { get; set; } = "";
|
||||
[JsonPropertyName("dns")] public List<string> Dns { get; set; } = new();
|
||||
}
|
||||
|
||||
public static class ImageConfigCodec
|
||||
{
|
||||
public const int FileBytes = 64 * 1024;
|
||||
private const int HeaderBytes = 4096;
|
||||
private const int SlotBytes = (FileBytes - HeaderBytes) / 2;
|
||||
private const int SlotHeaderBytes = 52;
|
||||
private static readonly byte[] FileMagic = Encoding.ASCII.GetBytes("MSCCFG2\0");
|
||||
private static readonly byte[] SlotMagic = Encoding.ASCII.GetBytes("MSCSLOT\0");
|
||||
private static readonly Regex UsernamePattern = new("^[a-z_][a-z0-9_-]{0,31}$", RegexOptions.CultureInvariant);
|
||||
private static readonly Regex VersionPattern = new("^(0|[1-9][0-9]*)\\.(0|[1-9][0-9]*)\\.(0|[1-9][0-9]*)$", RegexOptions.CultureInvariant);
|
||||
private static readonly JsonSerializerOptions JsonOptions = new()
|
||||
{
|
||||
PropertyNamingPolicy = null,
|
||||
WriteIndented = false,
|
||||
UnmappedMemberHandling = JsonUnmappedMemberHandling.Disallow,
|
||||
};
|
||||
|
||||
public static ImageConfig Deserialize(string json)
|
||||
{
|
||||
var config = JsonSerializer.Deserialize<ImageConfig>(json, JsonOptions) ?? throw new InvalidDataException("配置 JSON 为空");
|
||||
Validate(config);
|
||||
return config;
|
||||
}
|
||||
|
||||
public static string Serialize(ImageConfig config)
|
||||
{
|
||||
Validate(config);
|
||||
return JsonSerializer.Serialize(config, JsonOptions);
|
||||
}
|
||||
|
||||
public static ImageConfig Read(byte[] data) => ReadDetailed(data).Config;
|
||||
|
||||
public static (ImageConfig Config, ulong Generation, int Slot) ReadDetailed(byte[] data)
|
||||
{
|
||||
if (data.Length != FileBytes || !data.AsSpan(0, 8).SequenceEqual(FileMagic) || BinaryPrimitives.ReadInt32LittleEndian(data.AsSpan(8, 4)) != 1 || BinaryPrimitives.ReadInt32LittleEndian(data.AsSpan(12, 4)) != FileBytes)
|
||||
{
|
||||
throw new InvalidDataException("镜像配置区头部无效");
|
||||
}
|
||||
var values = new List<(ImageConfig Config, ulong Generation, int Slot)>();
|
||||
for (var slot = 0; slot < 2; slot++)
|
||||
{
|
||||
var offset = HeaderBytes + slot * SlotBytes;
|
||||
var span = data.AsSpan(offset, SlotBytes);
|
||||
if (!span[..8].SequenceEqual(SlotMagic)) continue;
|
||||
var generation = BinaryPrimitives.ReadUInt64LittleEndian(span.Slice(8, 8));
|
||||
var length = BinaryPrimitives.ReadInt32LittleEndian(span.Slice(16, 4));
|
||||
if (length <= 0 || length > SlotBytes - SlotHeaderBytes) continue;
|
||||
var payload = span.Slice(SlotHeaderBytes, length).ToArray();
|
||||
if (!SHA256.HashData(payload).AsSpan().SequenceEqual(span.Slice(20, 32))) continue;
|
||||
try
|
||||
{
|
||||
values.Add((Deserialize(Encoding.UTF8.GetString(payload)), generation, slot));
|
||||
}
|
||||
catch { }
|
||||
}
|
||||
if (values.Count == 0) throw new InvalidDataException("镜像配置区没有可恢复的有效副本");
|
||||
return values.OrderByDescending(value => value.Generation).ThenByDescending(value => value.Slot).First();
|
||||
}
|
||||
|
||||
public static (byte[] SlotData, int TargetSlot) EncodeUpdate(byte[] current, ImageConfig config)
|
||||
{
|
||||
Validate(config);
|
||||
var active = ReadDetailed(current);
|
||||
var target = 1 - active.Slot;
|
||||
var payload = Encoding.UTF8.GetBytes(JsonSerializer.Serialize(config, JsonOptions) + "\n");
|
||||
if (payload.Length > SlotBytes - SlotHeaderBytes) throw new InvalidDataException("配置内容过大");
|
||||
var result = new byte[SlotBytes];
|
||||
SlotMagic.CopyTo(result, 0);
|
||||
BinaryPrimitives.WriteUInt64LittleEndian(result.AsSpan(8, 8), active.Generation + 1);
|
||||
BinaryPrimitives.WriteInt32LittleEndian(result.AsSpan(16, 4), payload.Length);
|
||||
SHA256.HashData(payload).CopyTo(result, 20);
|
||||
payload.CopyTo(result, SlotHeaderBytes);
|
||||
return (result, target);
|
||||
}
|
||||
|
||||
public static int SlotOffset(int slot) => HeaderBytes + slot * SlotBytes;
|
||||
|
||||
public static void Validate(ImageConfig config)
|
||||
{
|
||||
if (config.Account is null || config.Wifi is null || config.Ipv4 is null) throw new InvalidDataException("镜像配置缺少必要部分");
|
||||
if (config.SchemaVersion != 1 || config.Product != "matrix-screen-controller-walnutpi") throw new InvalidDataException("镜像产品或配置版本不受支持");
|
||||
if (!VersionPattern.IsMatch(config.SoftwareVersion)) throw new InvalidDataException("软件版本格式无效");
|
||||
if (!UsernamePattern.IsMatch(config.Account.Username)) throw new InvalidDataException("用户名只能使用小写字母、数字、下划线和连字符，且最长 32 个字符");
|
||||
ValidateSecret(config.Account.Password, "账户密码", 8, 128);
|
||||
ValidateText(config.Wifi.Ssid, "Wi-Fi 名称", 1, 32);
|
||||
ValidateSecret(config.Wifi.Password, "Wi-Fi 密码", 8, 63);
|
||||
if (config.Ipv4.Mode == "dhcp")
|
||||
{
|
||||
config.Ipv4.Address = ""; config.Ipv4.Prefix = 0; config.Ipv4.Gateway = ""; config.Ipv4.Dns = new();
|
||||
}
|
||||
else if (config.Ipv4.Mode == "static")
|
||||
{
|
||||
if (!IPAddress.TryParse(config.Ipv4.Address, out var address) || address.AddressFamily != System.Net.Sockets.AddressFamily.InterNetwork) throw new InvalidDataException("静态 IPv4 地址无效");
|
||||
if (!IPAddress.TryParse(config.Ipv4.Gateway, out var gateway) || gateway.AddressFamily != System.Net.Sockets.AddressFamily.InterNetwork) throw new InvalidDataException("静态 IPv4 网关无效");
|
||||
if (config.Ipv4.Prefix is < 1 or > 32) throw new InvalidDataException("IPv4 前缀必须是 1 到 32");
|
||||
if (!SameSubnet(address, gateway, config.Ipv4.Prefix)) throw new InvalidDataException("静态 IPv4 网关必须与地址处于同一子网");
|
||||
if (config.Ipv4.Dns is null || config.Ipv4.Dns.Count is < 1 or > 4 || config.Ipv4.Dns.Any(item => !IPAddress.TryParse(item, out var parsed) || parsed.AddressFamily != System.Net.Sockets.AddressFamily.InterNetwork)) throw new InvalidDataException("DNS 必须包含 1 到 4 个 IPv4 地址");
|
||||
}
|
||||
else throw new InvalidDataException("IPv4 模式无效");
|
||||
}
|
||||
|
||||
private static void ValidateSecret(string value, string label, int minimum, int maximum)
|
||||
{
|
||||
if (value is null || value.Length < minimum || value.Length > maximum || value.IndexOfAny(['\0', '\r', '\n']) >= 0) throw new InvalidDataException($"{label}长度或字符无效");
|
||||
}
|
||||
|
||||
private static void ValidateText(string value, string label, int minimum, int maximumBytes)
|
||||
{
|
||||
if (value is null || value.Length < minimum || Encoding.UTF8.GetByteCount(value) > maximumBytes || value.IndexOfAny(['\0', '\r', '\n']) >= 0) throw new InvalidDataException($"{label}长度或字符无效");
|
||||
}
|
||||
|
||||
private static bool SameSubnet(IPAddress address, IPAddress gateway, int prefix)
|
||||
{
|
||||
var addressValue = BinaryPrimitives.ReadUInt32BigEndian(address.GetAddressBytes());
|
||||
var gatewayValue = BinaryPrimitives.ReadUInt32BigEndian(gateway.GetAddressBytes());
|
||||
var mask = prefix == 32 ? uint.MaxValue : uint.MaxValue << (32 - prefix);
|
||||
return (addressValue & mask) == (gatewayValue & mask);
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,113 @@
|
||||
using System.Security.Cryptography;
|
||||
using System.Text;
|
||||
|
||||
namespace MatrixImageEditor;
|
||||
|
||||
public static class ImageOperations
|
||||
{
|
||||
private static readonly UTF8Encoding Utf8NoBomStrict = new(encoderShouldEmitUTF8Identifier: false, throwOnInvalidBytes: true);
|
||||
|
||||
public static ImageConfig ReadConfig(string imagePath)
|
||||
{
|
||||
imagePath = ImagePathRules.ValidateExistingImage(imagePath);
|
||||
VerifySidecarIfPresent(imagePath);
|
||||
using var disk = new Fat16Disk(imagePath, writable: false);
|
||||
return ImageConfigCodec.Read(disk.ReadFile("MSCCFG.BIN"));
|
||||
}
|
||||
|
||||
public static void WriteConfig(string imagePath, ImageConfig config)
|
||||
{
|
||||
imagePath = ImagePathRules.ValidateExistingImage(imagePath);
|
||||
VerifySidecarIfPresent(imagePath);
|
||||
using var disk = new Fat16Disk(imagePath, writable: true);
|
||||
var current = disk.ReadFile("MSCCFG.BIN");
|
||||
if (ImageConfigCodec.Read(current).SoftwareVersion != config.SoftwareVersion) throw new InvalidDataException("禁止通过编辑器改变软件版本");
|
||||
var update = ImageConfigCodec.EncodeUpdate(current, config);
|
||||
disk.WriteFileRange("MSCCFG.BIN", ImageConfigCodec.SlotOffset(update.TargetSlot), update.SlotData);
|
||||
var verified = ImageConfigCodec.Read(disk.ReadFile("MSCCFG.BIN"));
|
||||
if (!ImageConfigCodec.Serialize(verified).Equals(ImageConfigCodec.Serialize(config), StringComparison.Ordinal)) throw new IOException("配置写后校验失败");
|
||||
}
|
||||
|
||||
public static void WriteSha256(string imagePath, IProgress<int>? progress)
|
||||
{
|
||||
imagePath = ImagePathRules.ValidateExistingImage(imagePath);
|
||||
using var stream = new FileStream(imagePath, FileMode.Open, FileAccess.Read, FileShare.Read, 4 * 1024 * 1024, FileOptions.SequentialScan);
|
||||
using var hash = IncrementalHash.CreateHash(HashAlgorithmName.SHA256);
|
||||
var buffer = new byte[4 * 1024 * 1024];
|
||||
long completed = 0;
|
||||
int read;
|
||||
while ((read = stream.Read(buffer, 0, buffer.Length)) > 0)
|
||||
{
|
||||
hash.AppendData(buffer, 0, read);
|
||||
completed += read;
|
||||
progress?.Report((int)(completed * 100 / stream.Length));
|
||||
}
|
||||
var digest = Convert.ToHexString(hash.GetHashAndReset()).ToLowerInvariant();
|
||||
progress?.Report(100);
|
||||
|
||||
var sidecar = imagePath + ".sha256";
|
||||
var temporary = sidecar + "." + Guid.NewGuid().ToString("N") + ".tmp";
|
||||
try
|
||||
{
|
||||
var bytes = Utf8NoBomStrict.GetBytes($"{digest} {Path.GetFileName(imagePath)}\n");
|
||||
using (var output = new FileStream(temporary, FileMode.CreateNew, FileAccess.Write, FileShare.None, 4096, FileOptions.WriteThrough))
|
||||
{
|
||||
output.Write(bytes);
|
||||
output.Flush(flushToDisk: true);
|
||||
}
|
||||
File.Move(temporary, sidecar, overwrite: true);
|
||||
var stored = ReadSidecarDigest(sidecar, Path.GetFileName(imagePath));
|
||||
if (!stored.Equals(digest, StringComparison.Ordinal)) throw new IOException("镜像 SHA-256 摘要写后校验失败");
|
||||
}
|
||||
finally
|
||||
{
|
||||
if (File.Exists(temporary)) File.Delete(temporary);
|
||||
}
|
||||
}
|
||||
|
||||
private static void VerifySidecarIfPresent(string imagePath)
|
||||
{
|
||||
var sidecar = imagePath + ".sha256";
|
||||
if (!File.Exists(sidecar)) return;
|
||||
var expected = ReadSidecarDigest(sidecar, Path.GetFileName(imagePath));
|
||||
using var stream = new FileStream(imagePath, FileMode.Open, FileAccess.Read, FileShare.Read, 4 * 1024 * 1024, FileOptions.SequentialScan);
|
||||
var actual = Convert.ToHexString(SHA256.HashData(stream)).ToLowerInvariant();
|
||||
if (!actual.Equals(expected, StringComparison.Ordinal)) throw new InvalidDataException("镜像内容与 SHA-256 摘要不符，禁止编辑");
|
||||
}
|
||||
|
||||
private static string ReadSidecarDigest(string sidecarPath, string expectedFileName)
|
||||
{
|
||||
if (new FileInfo(sidecarPath).Length > 128 * 1024) throw new InvalidDataException("镜像 SHA-256 摘要文件过大");
|
||||
var bytes = File.ReadAllBytes(sidecarPath);
|
||||
if (bytes.Length >= 3 && bytes[0] == 0xEF && bytes[1] == 0xBB && bytes[2] == 0xBF) throw new InvalidDataException("镜像 SHA-256 摘要必须使用无 BOM UTF-8 格式");
|
||||
|
||||
string content;
|
||||
try
|
||||
{
|
||||
content = Utf8NoBomStrict.GetString(bytes);
|
||||
}
|
||||
catch (DecoderFallbackException exception)
|
||||
{
|
||||
throw new InvalidDataException("镜像 SHA-256 摘要不是有效的 UTF-8 文本", exception);
|
||||
}
|
||||
|
||||
if (content.Length < 68 || content[^1] != '\n' || content.AsSpan(0, content.Length - 1).ContainsAny('\r', '\n'))
|
||||
{
|
||||
throw new InvalidDataException("镜像 SHA-256 摘要文件必须是以 LF 结尾的单行规范格式");
|
||||
}
|
||||
|
||||
var line = content.AsSpan(0, content.Length - 1);
|
||||
var digest = line[..64];
|
||||
if (digest.ContainsAnyExcept("0123456789abcdef") || line[64] != ' ' || line[65] != ' ')
|
||||
{
|
||||
throw new InvalidDataException("镜像 SHA-256 摘要文件格式无效");
|
||||
}
|
||||
|
||||
var storedFileName = line[66..].ToString();
|
||||
if (!storedFileName.Equals(expectedFileName, StringComparison.Ordinal))
|
||||
{
|
||||
throw new InvalidDataException("镜像 SHA-256 摘要中的文件名与当前镜像不一致");
|
||||
}
|
||||
return digest.ToString();
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,75 @@
|
||||
using System.Text.RegularExpressions;
|
||||
|
||||
namespace MatrixImageEditor;
|
||||
|
||||
internal static partial class ImagePathRules
|
||||
{
|
||||
public static string ValidateExistingImage(string imagePath)
|
||||
{
|
||||
var fullPath = ValidateImageNameAndDirectory(imagePath);
|
||||
if (!File.Exists(fullPath)) throw new FileNotFoundException("镜像文件不存在", fullPath);
|
||||
if (Directory.Exists(fullPath + ".sha256")) throw new IOException("同名 SHA-256 摘要路径被文件夹占用");
|
||||
return fullPath;
|
||||
}
|
||||
|
||||
public static string ValidateNewDestination(string sourcePath, string destinationPath)
|
||||
{
|
||||
var source = ValidateExistingImage(sourcePath);
|
||||
var destination = ValidateImageNameAndDirectory(destinationPath);
|
||||
if (destination.Equals(source, StringComparison.OrdinalIgnoreCase)) throw new ArgumentException("另存为必须使用与原镜像不同的文件名");
|
||||
if (File.Exists(destination) || Directory.Exists(destination)) throw new IOException("目标镜像已经存在，请使用新的文件名");
|
||||
|
||||
var sidecar = destination + ".sha256";
|
||||
if (File.Exists(sidecar) || Directory.Exists(sidecar)) throw new IOException("目标镜像的同名 SHA-256 摘要已经存在，请使用新的文件名");
|
||||
return destination;
|
||||
}
|
||||
|
||||
public static string? CleanupNewDestination(string destinationPath)
|
||||
{
|
||||
List<string>? failures = null;
|
||||
foreach (var target in new[] { destinationPath + ".sha256", destinationPath })
|
||||
{
|
||||
try
|
||||
{
|
||||
if (File.Exists(target)) File.Delete(target);
|
||||
}
|
||||
catch (Exception exception)
|
||||
{
|
||||
failures ??= new List<string>();
|
||||
failures.Add($"{Path.GetFileName(target)}：{exception.Message}");
|
||||
}
|
||||
}
|
||||
return failures is null ? null : string.Join("；", failures);
|
||||
}
|
||||
|
||||
private static string ValidateImageNameAndDirectory(string imagePath)
|
||||
{
|
||||
if (string.IsNullOrWhiteSpace(imagePath)) throw new ArgumentException("镜像路径不能为空");
|
||||
|
||||
string fullPath;
|
||||
try
|
||||
{
|
||||
fullPath = Path.GetFullPath(imagePath);
|
||||
}
|
||||
catch (Exception exception) when (exception is ArgumentException or NotSupportedException or PathTooLongException)
|
||||
{
|
||||
throw new ArgumentException("镜像路径格式无效", exception);
|
||||
}
|
||||
|
||||
var fileName = Path.GetFileName(fullPath);
|
||||
if (string.IsNullOrWhiteSpace(fileName)) throw new ArgumentException("镜像文件名不能为空");
|
||||
if (fileName.IndexOfAny(Path.GetInvalidFileNameChars()) >= 0 || fileName != fileName.TrimEnd(' ', '.'))
|
||||
{
|
||||
throw new ArgumentException("镜像文件名包含 Windows 不允许的字符，或以空格、句点结尾");
|
||||
}
|
||||
if (!Path.GetExtension(fileName).Equals(".img", StringComparison.OrdinalIgnoreCase)) throw new ArgumentException("镜像文件名必须以 .img 结尾");
|
||||
if (ReservedWindowsName().IsMatch(Path.GetFileNameWithoutExtension(fileName))) throw new ArgumentException("镜像文件名使用了 Windows 保留名称，请更换名称");
|
||||
|
||||
var directory = Path.GetDirectoryName(fullPath);
|
||||
if (string.IsNullOrEmpty(directory) || !Directory.Exists(directory)) throw new DirectoryNotFoundException("镜像目标文件夹不存在");
|
||||
return fullPath;
|
||||
}
|
||||
|
||||
[GeneratedRegex("^(CON|PRN|AUX|NUL|COM[1-9]|LPT[1-9])(?:\\..*)?$", RegexOptions.IgnoreCase | RegexOptions.CultureInvariant)]
|
||||
private static partial Regex ReservedWindowsName();
|
||||
}
|
||||
@@ -0,0 +1,253 @@
|
||||
using Microsoft.Win32;
|
||||
|
||||
namespace MatrixImageEditor;
|
||||
|
||||
public sealed class MainForm : Form
|
||||
{
|
||||
private readonly TextBox path = new() { ReadOnly = true, Dock = DockStyle.Fill };
|
||||
private readonly Label version = new() { AutoSize = true, Text = "尚未打开镜像" };
|
||||
private readonly TextBox username = new();
|
||||
private readonly TextBox accountPassword = new() { UseSystemPasswordChar = true };
|
||||
private readonly TextBox ssid = new();
|
||||
private readonly TextBox wifiPassword = new() { UseSystemPasswordChar = true };
|
||||
private readonly ComboBox mode = new() { DropDownStyle = ComboBoxStyle.DropDownList };
|
||||
private readonly TextBox address = new();
|
||||
private readonly NumericUpDown prefix = new() { Minimum = 1, Maximum = 32, Value = 24 };
|
||||
private readonly TextBox gateway = new();
|
||||
private readonly TextBox dns = new();
|
||||
private readonly Button open = new() { Text = "打开镜像…", AutoSize = true, MinimumSize = new Size(130, 38) };
|
||||
private readonly Button save = new() { Text = "修改原镜像", Enabled = false, AutoSize = true };
|
||||
private readonly Button saveAs = new() { Text = "另存为…", Enabled = false, AutoSize = true };
|
||||
private readonly ProgressBar progress = new() { Dock = DockStyle.Fill, Visible = false };
|
||||
private string? imagePath;
|
||||
private ImageConfig? loaded;
|
||||
private bool isBusy;
|
||||
private bool watchingDisplaySettings;
|
||||
|
||||
private static readonly Size PreferredLogicalSize = new(960, 760);
|
||||
private static readonly Size MinimumLogicalSize = new(760, 600);
|
||||
|
||||
public MainForm()
|
||||
{
|
||||
var assemblyVersion = typeof(MainForm).Assembly.GetName().Version;
|
||||
Text = $"核桃派镜像配置编辑器 {assemblyVersion?.Major}.{assemblyVersion?.Minor}.{assemblyVersion?.Build}";
|
||||
AutoScaleMode = AutoScaleMode.Dpi;
|
||||
StartPosition = FormStartPosition.Manual;
|
||||
Font = new Font("Microsoft YaHei UI", 10F);
|
||||
AllowDrop = true;
|
||||
mode.Items.AddRange(["自动获取（DHCP）", "静态 IPv4"]);
|
||||
mode.SelectedIndexChanged += (_, _) => UpdateNetworkFields();
|
||||
save.Click += async (_, _) => await SaveOriginalAsync();
|
||||
saveAs.Click += async (_, _) => await SaveAsAsync();
|
||||
open.Click += (_, _) => OpenImageFromDialog();
|
||||
DragEnter += (_, eventArgs) => { if (!isBusy && eventArgs.Data?.GetDataPresent(DataFormats.FileDrop) == true) eventArgs.Effect = DragDropEffects.Copy; };
|
||||
DragDrop += (_, eventArgs) => { if (!isBusy && eventArgs.Data?.GetData(DataFormats.FileDrop) is string[] files && files.Length == 1) OpenImage(files[0]); };
|
||||
Controls.Add(BuildLayout());
|
||||
}
|
||||
|
||||
private Control BuildLayout()
|
||||
{
|
||||
var outer = new TableLayoutPanel { Dock = DockStyle.Fill, Padding = new Padding(24), ColumnCount = 1, RowCount = 6, AutoScroll = true };
|
||||
for (var index = 0; index < 6; index++) outer.RowStyles.Add(new RowStyle(SizeType.AutoSize));
|
||||
var header = new TableLayoutPanel { Dock = DockStyle.Top, AutoSize = true, ColumnCount = 2, Margin = new Padding(0, 0, 0, 12) };
|
||||
header.ColumnStyles.Add(new ColumnStyle(SizeType.Percent, 100)); header.ColumnStyles.Add(new ColumnStyle(SizeType.AutoSize));
|
||||
path.Margin = new Padding(0, 4, 12, 4);
|
||||
open.Margin = new Padding(0);
|
||||
header.Controls.Add(path, 0, 0); header.Controls.Add(open, 1, 0);
|
||||
outer.Controls.Add(header);
|
||||
version.Margin = new Padding(0, 0, 0, 12);
|
||||
outer.Controls.Add(version);
|
||||
outer.Controls.Add(Group("登录账户", [("用户名", username), ("密码", PasswordPanel(accountPassword))]));
|
||||
outer.Controls.Add(Group("Wi-Fi", [("SSID", ssid), ("密码", PasswordPanel(wifiPassword))]));
|
||||
outer.Controls.Add(Group("IPv4", [("方式", mode), ("地址", address), ("前缀", prefix), ("网关", gateway), ("DNS（逗号分隔）", dns)]));
|
||||
var footer = new TableLayoutPanel { Dock = DockStyle.Top, AutoSize = true, ColumnCount = 3, Margin = new Padding(0, 16, 0, 0) };
|
||||
footer.ColumnStyles.Add(new ColumnStyle(SizeType.Percent, 100)); footer.ColumnStyles.Add(new ColumnStyle(SizeType.AutoSize)); footer.ColumnStyles.Add(new ColumnStyle(SizeType.AutoSize));
|
||||
progress.MinimumSize = new Size(200, 28);
|
||||
save.MinimumSize = new Size(150, 40); save.Margin = new Padding(12, 0, 0, 0);
|
||||
saveAs.MinimumSize = new Size(130, 40); saveAs.Margin = new Padding(12, 0, 0, 0);
|
||||
footer.Controls.Add(progress, 0, 0); footer.Controls.Add(save, 1, 0); footer.Controls.Add(saveAs, 2, 0);
|
||||
outer.Controls.Add(footer);
|
||||
return outer;
|
||||
}
|
||||
|
||||
private static GroupBox Group(string title, (string Label, Control Control)[] rows)
|
||||
{
|
||||
var box = new GroupBox { Text = title, Dock = DockStyle.Top, AutoSize = true, Padding = new Padding(16), Margin = new Padding(0, 0, 0, 12) };
|
||||
var table = new TableLayoutPanel { Dock = DockStyle.Fill, AutoSize = true, ColumnCount = 2, GrowStyle = TableLayoutPanelGrowStyle.AddRows };
|
||||
table.ColumnStyles.Add(new ColumnStyle(SizeType.AutoSize)); table.ColumnStyles.Add(new ColumnStyle(SizeType.Percent, 100));
|
||||
foreach (var row in rows)
|
||||
{
|
||||
row.Control.Dock = DockStyle.Fill;
|
||||
row.Control.MinimumSize = new Size(320, 0);
|
||||
row.Control.Margin = new Padding(12, 5, 0, 5);
|
||||
table.Controls.Add(new Label { Text = row.Label, AutoSize = true, Anchor = AnchorStyles.Left, Margin = new Padding(0, 7, 12, 7) }, 0, table.RowCount);
|
||||
table.Controls.Add(row.Control, 1, table.RowCount++);
|
||||
}
|
||||
box.Controls.Add(table); return box;
|
||||
}
|
||||
|
||||
private static Control PasswordPanel(TextBox password)
|
||||
{
|
||||
var panel = new TableLayoutPanel { Dock = DockStyle.Fill, AutoSize = true, ColumnCount = 2 };
|
||||
panel.ColumnStyles.Add(new ColumnStyle(SizeType.Percent, 100)); panel.ColumnStyles.Add(new ColumnStyle(SizeType.AutoSize));
|
||||
var show = new CheckBox { Text = "显示", AutoSize = true };
|
||||
show.CheckedChanged += (_, _) => password.UseSystemPasswordChar = !show.Checked;
|
||||
password.Dock = DockStyle.Fill;
|
||||
password.MinimumSize = new Size(260, 0);
|
||||
password.Margin = new Padding(0, 0, 12, 0);
|
||||
show.Anchor = AnchorStyles.Left;
|
||||
show.Margin = new Padding(0);
|
||||
panel.Controls.Add(password); panel.Controls.Add(show); return panel;
|
||||
}
|
||||
|
||||
private void OpenImageFromDialog()
|
||||
{
|
||||
using var dialog = new OpenFileDialog
|
||||
{
|
||||
Filter = "核桃派镜像 (*.img)|*.img",
|
||||
CheckFileExists = true,
|
||||
CheckPathExists = true,
|
||||
Multiselect = false,
|
||||
ValidateNames = true,
|
||||
};
|
||||
if (dialog.ShowDialog(this) == DialogResult.OK) OpenImage(dialog.FileName);
|
||||
}
|
||||
|
||||
private void OpenImage(string filename)
|
||||
{
|
||||
try
|
||||
{
|
||||
var config = ImageOperations.ReadConfig(filename);
|
||||
ApplyLoadedConfig(Path.GetFullPath(filename), config);
|
||||
}
|
||||
catch (Exception exception) { AppDialog.Error(this, exception.Message, "无法打开镜像"); }
|
||||
}
|
||||
|
||||
private void ApplyLoadedConfig(string filename, ImageConfig config)
|
||||
{
|
||||
imagePath = filename; loaded = config; path.Text = imagePath; version.Text = $"软件版本：{config.SoftwareVersion} 配置校验：正常";
|
||||
username.Text = config.Account.Username; accountPassword.Text = config.Account.Password; ssid.Text = config.Wifi.Ssid; wifiPassword.Text = config.Wifi.Password;
|
||||
mode.SelectedIndex = config.Ipv4.Mode == "static" ? 1 : 0; address.Text = config.Ipv4.Address; prefix.Value = config.Ipv4.Prefix == 0 ? 24 : config.Ipv4.Prefix; gateway.Text = config.Ipv4.Gateway; dns.Text = string.Join(",", config.Ipv4.Dns);
|
||||
save.Enabled = saveAs.Enabled = true; UpdateNetworkFields();
|
||||
}
|
||||
|
||||
private ImageConfig Collect()
|
||||
{
|
||||
if (loaded is null) throw new InvalidOperationException("尚未打开镜像");
|
||||
var config = new ImageConfig
|
||||
{
|
||||
SchemaVersion = loaded.SchemaVersion, Product = loaded.Product, SoftwareVersion = loaded.SoftwareVersion,
|
||||
Account = new AccountConfig { Username = username.Text.Trim(), Password = accountPassword.Text },
|
||||
Wifi = new WifiConfig { Ssid = ssid.Text, Password = wifiPassword.Text },
|
||||
Ipv4 = mode.SelectedIndex == 0
|
||||
? new Ipv4Config { Mode = "dhcp" }
|
||||
: new Ipv4Config { Mode = "static", Address = address.Text.Trim(), Prefix = (int)prefix.Value, Gateway = gateway.Text.Trim(), Dns = dns.Text.Split(',', StringSplitOptions.TrimEntries | StringSplitOptions.RemoveEmptyEntries).ToList() },
|
||||
};
|
||||
ImageConfigCodec.Validate(config); return config;
|
||||
}
|
||||
|
||||
private async Task SaveOriginalAsync()
|
||||
{
|
||||
if (imagePath is null) return;
|
||||
try
|
||||
{
|
||||
var config = Collect();
|
||||
if (AppDialog.Confirm(this, "这会直接修改当前镜像。建议日常使用“另存为”保留原始包。\n\n确定继续吗？", "确认修改原镜像") != DialogResult.Yes) return;
|
||||
var verified = await WriteAndVerifyAsync(imagePath, config);
|
||||
ApplyLoadedConfig(imagePath, verified);
|
||||
AppDialog.Information(this, "配置已保存，镜像与 SHA-256 摘要均已完成写后校验。", "保存成功");
|
||||
}
|
||||
catch (Exception exception)
|
||||
{
|
||||
AppDialog.Error(this, exception.Message, "保存失败");
|
||||
}
|
||||
}
|
||||
|
||||
private async Task SaveAsAsync()
|
||||
{
|
||||
if (imagePath is null) return;
|
||||
using var dialog = new SaveFileDialog
|
||||
{
|
||||
Filter = "核桃派镜像 (*.img)|*.img",
|
||||
DefaultExt = "img",
|
||||
AddExtension = true,
|
||||
ValidateNames = true,
|
||||
CheckPathExists = true,
|
||||
OverwritePrompt = false,
|
||||
FileName = Path.GetFileNameWithoutExtension(imagePath) + "-自定义.img",
|
||||
InitialDirectory = Path.GetDirectoryName(imagePath),
|
||||
Title = "请重命名，以便区分设备或使用地点",
|
||||
};
|
||||
if (dialog.ShowDialog(this) != DialogResult.OK) return;
|
||||
|
||||
string? destination = null;
|
||||
try
|
||||
{
|
||||
var config = Collect();
|
||||
destination = ImagePathRules.ValidateNewDestination(imagePath, dialog.FileName);
|
||||
SetBusy(true);
|
||||
await Task.Run(() => File.Copy(imagePath, destination, overwrite: false));
|
||||
var verified = await WriteAndVerifyAsync(destination, config, alreadyBusy: true);
|
||||
ApplyLoadedConfig(destination, verified);
|
||||
AppDialog.Information(this, "自定义镜像已保存并重新打开，镜像与 SHA-256 摘要均已完成写后校验。", "另存为成功");
|
||||
}
|
||||
catch (Exception exception)
|
||||
{
|
||||
var cleanupError = destination is null ? null : ImagePathRules.CleanupNewDestination(destination);
|
||||
var message = cleanupError is null ? exception.Message : $"{exception.Message}\n\n清理未完成：{cleanupError}";
|
||||
AppDialog.Error(this, message, "另存为失败");
|
||||
}
|
||||
finally { SetBusy(false); }
|
||||
}
|
||||
|
||||
private async Task<ImageConfig> WriteAndVerifyAsync(string target, ImageConfig config, bool alreadyBusy = false)
|
||||
{
|
||||
if (!alreadyBusy) SetBusy(true);
|
||||
try
|
||||
{
|
||||
var reporter = new Progress<int>(value => progress.Value = Math.Clamp(value, 0, 100));
|
||||
return await Task.Run(() =>
|
||||
{
|
||||
ImageOperations.WriteConfig(target, config);
|
||||
ImageOperations.WriteSha256(target, reporter);
|
||||
return ImageOperations.ReadConfig(target);
|
||||
});
|
||||
}
|
||||
finally { if (!alreadyBusy) SetBusy(false); }
|
||||
}
|
||||
|
||||
private void SetBusy(bool value) { isBusy = value; open.Enabled = !value; save.Enabled = saveAs.Enabled = !value && loaded is not null; progress.Visible = value; progress.Value = 0; UseWaitCursor = value; }
|
||||
private void UpdateNetworkFields() { var enabled = mode.SelectedIndex == 1; address.Enabled = prefix.Enabled = gateway.Enabled = dns.Enabled = enabled; }
|
||||
|
||||
protected override void OnShown(EventArgs eventArgs)
|
||||
{
|
||||
base.OnShown(eventArgs);
|
||||
ResponsiveLayout.FitAndCenter(this, PreferredLogicalSize, MinimumLogicalSize, 0.9);
|
||||
if (!watchingDisplaySettings)
|
||||
{
|
||||
SystemEvents.DisplaySettingsChanged += DisplaySettingsChanged;
|
||||
watchingDisplaySettings = true;
|
||||
}
|
||||
}
|
||||
|
||||
protected override void OnDpiChanged(DpiChangedEventArgs eventArgs)
|
||||
{
|
||||
base.OnDpiChanged(eventArgs);
|
||||
BeginInvoke(() => ResponsiveLayout.FitAndCenter(this, PreferredLogicalSize, MinimumLogicalSize, 0.9));
|
||||
}
|
||||
|
||||
protected override void OnFormClosed(FormClosedEventArgs eventArgs)
|
||||
{
|
||||
if (watchingDisplaySettings)
|
||||
{
|
||||
SystemEvents.DisplaySettingsChanged -= DisplaySettingsChanged;
|
||||
watchingDisplaySettings = false;
|
||||
}
|
||||
base.OnFormClosed(eventArgs);
|
||||
}
|
||||
|
||||
private void DisplaySettingsChanged(object? sender, EventArgs eventArgs)
|
||||
{
|
||||
if (!IsDisposed && IsHandleCreated) BeginInvoke(() => ResponsiveLayout.FitAndCenter(this, PreferredLogicalSize, MinimumLogicalSize, 0.9));
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,23 @@
|
||||
<Project Sdk="Microsoft.NET.Sdk">
|
||||
<PropertyGroup>
|
||||
<OutputType>WinExe</OutputType>
|
||||
<TargetFramework>net8.0-windows</TargetFramework>
|
||||
<UseWindowsForms>true</UseWindowsForms>
|
||||
<ApplicationHighDpiMode>PerMonitorV2</ApplicationHighDpiMode>
|
||||
<ImplicitUsings>enable</ImplicitUsings>
|
||||
<Nullable>enable</Nullable>
|
||||
<AssemblyName>核桃派镜像配置编辑器</AssemblyName>
|
||||
<RootNamespace>MatrixImageEditor</RootNamespace>
|
||||
<Version>1.0.1</Version>
|
||||
<AssemblyVersion>1.0.1.0</AssemblyVersion>
|
||||
<FileVersion>1.0.1.0</FileVersion>
|
||||
<PublishSingleFile>true</PublishSingleFile>
|
||||
<SelfContained>true</SelfContained>
|
||||
<RuntimeIdentifier>win-x64</RuntimeIdentifier>
|
||||
<RuntimeFrameworkVersion>8.0.29</RuntimeFrameworkVersion>
|
||||
<IncludeNativeLibrariesForSelfExtract>true</IncludeNativeLibrariesForSelfExtract>
|
||||
<EnableCompressionInSingleFile>true</EnableCompressionInSingleFile>
|
||||
<DebugType>none</DebugType>
|
||||
<DebugSymbols>false</DebugSymbols>
|
||||
</PropertyGroup>
|
||||
</Project>
|
||||
@@ -0,0 +1,76 @@
|
||||
using System.Text.Json;
|
||||
|
||||
namespace MatrixImageEditor;
|
||||
|
||||
internal static class Program
|
||||
{
|
||||
[STAThread]
|
||||
private static int Main(string[] args)
|
||||
{
|
||||
try
|
||||
{
|
||||
if (args.Length > 0)
|
||||
{
|
||||
return RunCommand(args);
|
||||
}
|
||||
ApplicationConfiguration.Initialize();
|
||||
Application.Run(new MainForm());
|
||||
return 0;
|
||||
}
|
||||
catch (Exception exception)
|
||||
{
|
||||
if (Environment.UserInteractive && args.Length == 0)
|
||||
{
|
||||
AppDialog.Error(null, exception.Message, "镜像配置编辑器");
|
||||
}
|
||||
else
|
||||
{
|
||||
Console.Error.WriteLine(exception.Message);
|
||||
}
|
||||
return 1;
|
||||
}
|
||||
}
|
||||
|
||||
private static int RunCommand(string[] args)
|
||||
{
|
||||
if (args is ["--validate", var image])
|
||||
{
|
||||
var config = ImageOperations.ReadConfig(image);
|
||||
var publicInfo = new
|
||||
{
|
||||
valid = true,
|
||||
config.SoftwareVersion,
|
||||
config.Account.Username,
|
||||
config.Wifi.Ssid,
|
||||
config.Ipv4.Mode,
|
||||
config.Ipv4.Address,
|
||||
};
|
||||
Console.WriteLine(JsonSerializer.Serialize(publicInfo));
|
||||
return 0;
|
||||
}
|
||||
if (args is ["--apply", var source, var configPath, var destination])
|
||||
{
|
||||
var sourcePath = ImagePathRules.ValidateExistingImage(source);
|
||||
var destinationPath = ImagePathRules.ValidateNewDestination(sourcePath, destination);
|
||||
var config = ImageConfigCodec.Deserialize(File.ReadAllText(configPath));
|
||||
_ = ImageOperations.ReadConfig(sourcePath);
|
||||
try
|
||||
{
|
||||
File.Copy(sourcePath, destinationPath, overwrite: false);
|
||||
ImageOperations.WriteConfig(destinationPath, config);
|
||||
ImageOperations.WriteSha256(destinationPath, null);
|
||||
_ = ImageOperations.ReadConfig(destinationPath);
|
||||
}
|
||||
catch (Exception exception)
|
||||
{
|
||||
var cleanupError = ImagePathRules.CleanupNewDestination(destinationPath);
|
||||
if (cleanupError is not null) throw new IOException($"{exception.Message}\n清理失败：{cleanupError}", exception);
|
||||
throw;
|
||||
}
|
||||
Console.WriteLine(destinationPath);
|
||||
return 0;
|
||||
}
|
||||
Console.Error.WriteLine("用法：镜像配置编辑器.exe [--validate 镜像 | --apply 原镜像 配置.json 新镜像]");
|
||||
return 2;
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,9 @@
|
||||
# 构建镜像配置编辑器
|
||||
|
||||
目标为 Windows 10/11 x64、.NET 8、自包含单文件。版本同时记录在 `VERSION` 与 `MatrixImageEditor.csproj`。
|
||||
|
||||
```powershell
|
||||
dotnet publish .\MatrixImageEditor.csproj -c Release -r win-x64 --self-contained true -p:PublishSingleFile=true
|
||||
```
|
||||
|
||||
发布后必须用正式 IMG 覆盖读取、另存为、双槽回退、写后 SHA-256、错误产品、未知 schema、截断和错误摘要；另存名称还必须覆盖中文、空格、长路径、Windows 保留名、既有目标和孤立同名摘要。界面在 100%、150%、200% DPI 及低分辨率、1080p、4K 工作区检查输入框、滚动区和全部应用内提示框。全部通过后再将唯一 EXE、版本与摘要放入 `../编辑器程序/`。源码与程序均不得内置发布默认密码，也不得读取项目凭据文件。
|
||||
@@ -0,0 +1,28 @@
|
||||
namespace MatrixImageEditor;
|
||||
|
||||
internal static class ResponsiveLayout
|
||||
{
|
||||
public static void FitAndCenter(Form form, Size preferredLogical, Size minimumLogical, double workingAreaFraction, Screen? screen = null)
|
||||
{
|
||||
screen ??= Screen.FromControl(form);
|
||||
var workingArea = screen.WorkingArea;
|
||||
var scale = Math.Max(form.DeviceDpi, 96) / 96F;
|
||||
var preferred = Scale(preferredLogical, scale);
|
||||
var minimum = Scale(minimumLogical, scale);
|
||||
var maximum = new Size(
|
||||
Math.Max(320, (int)Math.Floor(workingArea.Width * workingAreaFraction)),
|
||||
Math.Max(240, (int)Math.Floor(workingArea.Height * workingAreaFraction)));
|
||||
|
||||
var width = Math.Min(preferred.Width, maximum.Width);
|
||||
var height = Math.Min(preferred.Height, maximum.Height);
|
||||
form.MinimumSize = new Size(Math.Min(minimum.Width, maximum.Width), Math.Min(minimum.Height, maximum.Height));
|
||||
form.Size = new Size(Math.Max(width, form.MinimumSize.Width), Math.Max(height, form.MinimumSize.Height));
|
||||
form.Location = new Point(
|
||||
workingArea.Left + Math.Max(0, (workingArea.Width - form.Width) / 2),
|
||||
workingArea.Top + Math.Max(0, (workingArea.Height - form.Height) / 2));
|
||||
}
|
||||
|
||||
private static Size Scale(Size logical, float scale) => new(
|
||||
Math.Max(1, (int)Math.Round(logical.Width * scale)),
|
||||
Math.Max(1, (int)Math.Round(logical.Height * scale)));
|
||||
}
|
||||
@@ -0,0 +1 @@
|
||||
1.0.1
|
||||
@@ -0,0 +1,9 @@
|
||||
# 镜像配置编辑器 1.0.1
|
||||
|
||||
双击 `核桃派镜像配置编辑器.exe` 即可运行，不需要安装 .NET、写注册表或复制 DLL。支持 Windows 10/11 x64。
|
||||
|
||||
打开 IMG 后可查看账户、Wi-Fi 和 IPv4 设置；密码默认隐藏。“修改原镜像”会先二次确认，“另存为”会提示使用 Windows 合法的新名称并保留原文件。中文、空格和长路径均受支持；保存后会在 IMG 旁生成无 BOM UTF-8 的对应 `.sha256` 并重新验证。主窗口和应用内提示框会随系统缩放、显示器和分辨率自动调整。
|
||||
|
||||
1.0.1 修复了中文另存文件名导致摘要格式错误的问题，并放大、修复了密码输入框和全部应用内对话框。
|
||||
|
||||
本程序不负责写 TF 卡；完成配置后请使用 Rufus 写入 IMG。不要删除或改写正式发布 IMG，日常优先使用“另存为”。
|
||||
@@ -0,0 +1 @@
|
||||
bcee5a87b654999b5649948bbed49b9071ebb09e5e9caef5cc8f22331ee482c3 核桃派镜像配置编辑器.exe
|
||||
@@ -0,0 +1 @@
|
||||
1.0.1
|
||||
Binary file not shown.
Reference in New Issue
Block a user