Skip to content

armgit / peach

Public Imported from GitHub
0

Peach: Local-first video metadata scraper and media manager.

docs(update): 记录发布摘要签名的决策、启用步骤与复用取舍

longmeidaodf181f14ec50
diff --git a/docs/OPERATIONS.md b/docs/OPERATIONS.md
index 8cb9d7077..52ac18098 100644
--- a/docs/OPERATIONS.md
+++ b/docs/OPERATIONS.md
@@ -115,6 +115,21 @@ launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/io.github.longmeidao.pea
3. 仓库变量 `SPARKLE_APPCAST_ENABLED` 为 `true` 时,每个版本标签在 GitHub Release 公开后运行 `sparkle-appcast` 作业:官方 `generate_appcast` 生成两个架构的 appcast,`scripts/sparkle_appcast.py` 补写迁移号并核对版本、下载地址与大小,官方 `sign_update --verify` 核对签名,最后上传到 `https://downloads.peach.video/sparkle/macos-<架构>.xml`。没有 appcast 时,Sparkle 的检查会报更新源不可用。
4. 第一个带公钥的版本须手动安装一次;之后的版本才能经 Sparkle 更新。在真机按 ADR-0130「未取得的证据」逐项验收。
+### Windows 应用内更新的发布签名
+
+Windows 独立包的应用内更新校验每个版本 `SHA256SUMS.txt` 的 Ed25519 签名,取舍见 [ADR-0134](adr/0134-release-sums-ed25519-signature.md)。`src/peach/release_signing.py` 的 `PUBLIC_KEYS` 为空时不校验;写入公钥后,这一版起的客户端只装签名验得过的版本。
+
+`release.yml` 的 `release` 作业生成 `SHA256SUMS.txt` 后,把 `release` environment 的 secret `PEACH_RELEASE_SIGNING_KEY` 经标准输入交给 `scripts/sign_release.py`,签名文件 `SHA256SUMS.txt.sig` 随 Release 上传。源码已有公钥而 secret 为空时作业失败,不发布未签名的版本。
+
+启用步骤由维护者完成,顺序不能颠倒:
+
+1. 在主检出运行 `scripts/sign_release.py --generate-key <私钥文件>`:私钥只写进该文件,已存在就拒绝覆盖,输出里只有公钥。私钥文件放进离线备份。
+2. 用 `gh secret set PEACH_RELEASE_SIGNING_KEY --env release` 从标准输入写入私钥。
+3. 发布一个版本,确认 Release 资产里有 `SHA256SUMS.txt.sig`。
+4. 公钥写进 `PUBLIC_KEYS`,经 PR 合入。
+
+轮换时把新公钥追加进 `PUBLIC_KEYS`,secret 里一行一把放新旧两把私钥;仍要自动升级的客户端都认得新公钥后,再删旧私钥和旧公钥。
+
### GitLab 发布与下载后端
GitLab 兼容平台使用 `.gitlab-ci.yml`。唯一版本入口支持 `--gitlab-host` 指定主机,默认入口使用 GitHub。主线发布判据要求同一提交最新的 push 流水线成功,且 Linux、Windows、macOS 和 wheel 验收任务全部成功;缺少原生系统任务时拒绝打标签。主线上的三个平台验收只跑改动域与平台敏感用例([ADR-0119](adr/0119-mainline-changed-scope-release-full-suite.md))。版本提交 `chore(release): 版本 X` 的主线流水线同时是发布演练:三平台全量、媒体工具、Windows 与 macOS 构建、Windows 冒烟和 Docker 镜像都跑一遍,只是不发布。`--ship` 等演练全部成功才打标签;标签流水线核对同一提交的演练已通过,只重新构建并发布([ADR-0121](adr/0121-release-rehearsal-and-atomic-publication.md))。GitHub 的 `release.yml` 用同一套判据,迁回 GitHub 时不用改流程。CLI 传输复用官方 glab,不在仓库或命令参数里存访问令牌。
@@ -784,6 +799,7 @@ Windows 托盘在取得单实例锁后启动独立监视器。监视器用 Win32
- 独立包的版本检查读取 GitHub 公开发行记录与 R2 公开清单,选择可下载的最高版本;同版本优先 GitHub。R2 制品必须具有 SHA-256,发行说明统一指向 GitHub。任一来源不可用时仍检查另一来源,两个来源都未取得时显示检查失败。
- 更新包、完整包和轻量安装器的工具包下载失败或校验不符时,尝试另一公开源的同版本、同文件名;每次都按原发布记录的大小与 SHA-256 校验。备源不能替换为其他版本或放宽校验,两个来源都失败时保留错误状态。
+- `release_signing.PUBLIC_KEYS` 非空时,Windows 更新器下载前先取同版本的 `SHA256SUMS.txt` 与 `SHA256SUMS.txt.sig`,用随包公钥验过签名后,更新包与完整包只按签过名的摘要校验;两个来源都验不过就停在当前版本,提示到发布页手动下载([ADR-0134](adr/0134-release-sums-ed25519-signature.md))。
- 版本号只在 `src/peach/__init__.py::__version__` 里定义,采用 pre-1.0 SemVer。Git 提交是构建标识,`vX.Y.Z` 标签是发布点,推到 GitHub 就触发 Release 工作流(见「桌面入口与发布」)。
- 版本号在发布时才动,一次发布加一格,所以每个 `X.Y.Z` 都有一份能下载的制品。
diff --git a/docs/REUSE.md b/docs/REUSE.md
index 62a456c9f..7221916a0 100644
--- a/docs/REUSE.md
+++ b/docs/REUSE.md
@@ -960,6 +960,7 @@ A 盘垃圾隔离使用短名称 `peach-purge-<32 位 UUID>.peach-quarantine`,
| Windows 托盘恢复 | Windows 自带 `OpenProcess`、`GetProcessTimes`、[`WaitForSingleObject`](https://learn.microsoft.com/en-us/windows/win32/api/synchapi/nf-synchapi-waitforsingleobject)、`GetExitCodeProcess`;Python 3.12+ 标准库 `ctypes` / `subprocess`,无新增依赖或分发体积 | `tray_lifecycle` 保留明确退出意图、创建时间校验、3 次 / 5 分钟预算与重启交接。pystray 0.19.5 的 `_message_handlers` 接收 `WM_STOP` / `WM_ENDSESSION`,已核对安装包源码;Windows 临时进程实验证明强制退出能恢复,明确退出不会恢复。原生 API 随受支持的 Windows 维护;pystray 使用项目固定版本。不采用 Task Scheduler `RestartOnFailure`:它只管理任务启动的实例,桌面快捷方式与现有重启脚本不归其管理;不新增 psutil 运行时依赖,进程句柄已覆盖等待与退出码。已知边界是监视器随整棵进程树被终止时不能恢复。 |
| macOS 菜单栏 | `pyobjc-framework-Cocoa==12.2.2`(MIT)提供 AppKit / Foundation / PyObjCTools / objc | 附件应用策略、18 pt template 图、服务归属与菜单动作 |
| macOS 应用内更新 | [Sparkle 2.10.1](https://github.com/sparkle-project/Sparkle/releases/tag/2.10.1)(MIT)官方发布包,地址与 SHA-256 固定在 `scripts/sparkle-macos.json`;框架放 `Contents/Frameworks`,由 pyobjc `objc.loadBundle` 加载;appcast 由官方 `generate_appcast` 生成、`sign_update --verify` 核对 | 读取端的迁移拦截、安装前保存任务进度与停服务、设置页偏好映射到定时检查、appcast 的迁移号与发布门槛(`scripts/sparkle_appcast.py`)。非沙盒应用用不到 XPC 服务,取件时删除并按 ad-hoc 由内向外重签;不开 Hardened Runtime。不自写 DMG 下载、挂载与替换,也不在 Linux 上用 Python 重新实现 EdDSA 签名与 appcast 生成:官方工具只需一个仅标签运行的 macOS 作业。取舍与未验证项见 [ADR-0130](adr/0130-macos-sparkle-in-app-update.md) |
+| Windows 更新的发布签名 | `cryptography==50.0.2`(Apache-2.0 / BSD)的 Ed25519;原是 smbprotocol 的传递依赖,独立包已带,改为直接声明 | 签名对象选每个版本已有的 `SHA256SUMS.txt`,签名文件一行一个「公钥 签名」以便多钥轮换,下载前校验,发布作业缺私钥时拒绝发布(`release_signing.py`、`scripts/sign_release.py`)。不用 minisign、signify、SSHSIG 或 GPG:客户端要多带解析器或外部工具,只验一种文件不值得。不复用 Sparkle 私钥:那把公钥无法轮换。取舍见 [ADR-0134](adr/0134-release-sums-ed25519-signature.md) |
| macOS 拖放安装镜像 | [dmgbuild 1.6.7](https://github.com/dmgbuild/dmgbuild)(MIT,Python ≥3.10,macOS)直接写 Finder 元数据;仅安装于 `build` extra。纯 Python wheel 约 35 KB,依赖 `ds-store`、`mac-alias`;固定传递版本见 `uv.lock` | 已读取固定版的文件复制、背景多分辨率合成与图标布局实现;背景渲染复用 resvg-py 0.5.0,无运行时新增依赖。Peach 提供 640×420 拖放布局、双分辨率背景和应用内许可证;[APFS 设置](https://dmgbuild.readthedocs.io/en/latest/settings.html#filesystem)保留签名资源的 Unicode 文件名。单元验证配置与图片尺寸,macOS 原生回归与发布验收实际挂载镜像,检查严格签名、资源字节及软链。磁盘镜像创建依赖 macOS 的 hdiutil;无需 Finder 自动化权限,挂载或文件系统失败会终止构建 |
| 人脸取景 | `opencv-python-headless==5.0.0.93`(Apache-2.0)的 `cv2.FaceDetectorYN` + opencv_zoo 定版模型 `face_detection_yunet_2023mar.onnx`(MIT,opencv_zoo 提交 `48b10fa5`,sha256 `8f2383e4…52fa4`,232 KB,随安装包放 `tools/face-models/`,没带时放 `peach-data/tools/yunet/`,不进 Git);MetaTube SDK `6a5e6128c725187aeaf921d48ed7d9cd9f30671b` 的主脸聚类只作算法参考 | 头像/封面离线脚本共用 `peach.face_detect`(主脸、归一化焦点与 sidecar)。`detect` 按长边 320/640/1280 各检一次、分数取中位数;`main_face` 先筛掉分数落后最好那张 0.1 以上的框,再取最大。不用 Haar 级联(OpenCV 5 wheel 里没有、检出率低)与 Pigo v1.4.6(有无脸误报)。[实测](SOURCING.md#人脸与水印实测) |
| 人脸比对 | 同一 OpenCV 的 `cv2.FaceRecognizerSF` + opencv_zoo 定版模型 `face_recognition_sface_2021dec.onnx`(Apache-2.0,同一提交,sha256 `0ba9fbfa…34e79`,与 LFS 指针的 oid 一致,37 MB,随安装包放 `tools/face-models/`,没带时放 `peach-data/tools/sface/`,不进 Git) | `peach.face_match` 提特征、算余弦,阈值用 SFace 官方的 0.363;补头像后继拿图库候选与单人封面截到的脸比(ADR-0056),小脸先放大再检(ADR-0070)。检脸用 `peach.face_detect`,取模型先认随包那份(`bundled_model`,校验 SHA-256,进程内按文件大小与修改时间缓存结论),再走同一条 `fetch_model`;随包文件由 `scripts/fetch_face_models.py` 取齐并附两个目录的 LICENSE,Docker 镜像用 `ADD --checksum` 取同一组文件。不引 `face_recognition`/dlib(要编译、体积大)与 InsightFace(模型限非商用、需 onnxruntime)。[实测](SOURCING.md#人脸与水印实测) |
diff --git a/docs/adr/0134-release-sums-ed25519-signature.md b/docs/adr/0134-release-sums-ed25519-signature.md
new file mode 100644
index 000000000..12fdcf512
--- /dev/null
+++ b/docs/adr/0134-release-sums-ed25519-signature.md
@@ -0,0 +1,78 @@
+# ADR-0134:Windows 应用内更新校验发布摘要的 Ed25519 签名
+
+- 状态:已采纳;代码已实施,公钥待维护者生成密钥后写入,写入前行为不变
+- 日期:2026-11-04
+- 关系:补充 [ADR-0012](0012-version-and-update-boundary.md) 的更新边界、[ADR-0120](0120-standalone-update-client-compatibility.md) 的旧客户端兼容门槛与 [ADR-0127](0127-verified-release-artifact-promotion.md) 的晋级发布;macOS 的 Sparkle 签名见 [ADR-0130](0130-macos-sparkle-in-app-update.md),两者密钥分开
+- 参考:javm(MIT)提交 `db840dd` 与其 `docs/decisions/0035-auto-update.md`:发布清单 Ed25519 签名、公钥打进安装包、校验失败回退不升级。只借做法,不含其代码
+
+## 背景
+
+Windows 独立包的应用内更新由 `standalone_update.prepare` 完成:`release_updates.check` 合并 GitHub Releases API 与 `downloads.peach.video/releases.json` 两个来源,选出最高版本,给出更新包与完整包的地址、大小和 `sha256:` 摘要;下载后只核这份摘要。摘要与安装包来自同一渠道,渠道被篡改时(发布资产被替换、镜像被改写、受信任证书下的中间人)摘要会跟着一起换,校验拦不住。
+
+两个来源的现状决定了签名对象:
+
+- `releases.json` 由 `scripts/release_r2.py` 写,只在 GitGud 发布流程(`publish_gitlab_release.py`)里调用。10-28 发版回到 GitHub 后它不再更新,撰写时停在 0.50.0。签它保护不到当前任何一次更新。
+- GitHub API 的资产行和 `digest` 由 GitHub 生成,Peach 签不了。
+- 每个版本都有 `SHA256SUMS.txt`:`release.yml` 的 `release` 作业用 `sha256sum ./*.zip ./*-setup.exe ./*.dmg` 生成并上传,覆盖完整包、应用更新包、工具包、安装包与 DMG;`release_r2.py` 也给 R2 的每个版本目录写一份同格式的文件。
+
+## 决策
+
+**一、签名对象是每个版本的 `SHA256SUMS.txt`。** 签名写在同目录的 `SHA256SUMS.txt.sig`,与摘要文件一起作为 Release 资产上传。签名覆盖文件的原始字节,前面加固定前缀 `peach-release-sha256sums-v1\n`,同一把私钥签出的别的内容不会被当成发布摘要。签原始字节不需要规范化 JSON。文件名带版本号,旧版本的摘要文件列不出新版本的包;解压后 `build-info.json` 的版本还要与发布版本一致(已有检查)。
+
+签名文件一行一个签名:`<公钥 base64> <签名 base64>`,都是 32 字节公钥与 64 字节签名的标准 base64。客户端只看公钥在受信任集合里的行,其余行跳过,所以轮换期可以并列新旧两把私钥的签名。
+
+**二、公钥随源码发布。** `src/peach/release_signing.py` 的 `PUBLIC_KEYS` 是受信任公钥的元组,打包进独立包。格式与 Sparkle 的 `SUPublicEDKey` 相同(32 字节 Ed25519 公钥的 base64)。元组为空时更新器不要求签名,行为与之前一致;非空时这一版起的客户端只装签名验得过的版本。
+
+**三、客户端在下载前校验。** `PUBLIC_KEYS` 非空时,`standalone_update.prepare` 在建事务目录、下载任何包之前取 `SHA256SUMS.txt` 与 `.sig`。两份文件按 `release_updates.download_sources` 的顺序,先取选中包所在的来源、再取另一个公开源的同版本目录,各自不超过 1 MB。有一个来源验得过,就用签过名的摘要替换更新包与完整包的 `asset_digest`、`full_digest`,API 行和 `releases.json` 给的摘要不再采信。工具包的摘要来自更新包内的 `update-manifest.json`,更新包验过之后它也随之可信。
+
+两个来源都验不过,或摘要里没有选中的包,`prepare` 报「发布签名校验未通过,已停止更新;请到发布页手动下载新版本」,进入现有的 `error` 状态。已装版本、数据目录与事务目录都不动,用户可以重试,也可以从 `release_url` 手动下载。
+
+校验放在 `prepare` 而不放在 `check`:`check` 被设置页与定时检查频繁调用,也被 ADR-0120 的 `update_compat.py` 拿旧版本代码原样调用。留在 `prepare` 里,定时检查不多发请求,兼容门槛也不需要签名私钥。代价是设置页可能先显示「有新版本」,点下载后才报签名错误;这只发生在渠道被篡改或发布出错时。
+
+**四、发布端在 `release` 作业里签名。** 作业改用只允许 `v*` 标签部署的 `release` environment,私钥放在 secret `PEACH_RELEASE_SIGNING_KEY`(32 字节 seed 的 base64,与 Sparkle 私钥同一格式),经标准输入交给 `scripts/sign_release.py`,不落盘、不进日志。脚本的门槛:
+
+| 源码的 `PUBLIC_KEYS` | secret | 结果 |
+| --- | --- | --- |
+| 空 | 空 | 跳过签名,只上传摘要,与之前一致 |
+| 空 | 有 | 签名并用这次的公钥自验;用于第一个带公钥版本之前先发签名 |
+| 非空 | 空 | 失败,不创建 Release:这一版起的客户端再也装不上未签名的版本 |
+| 非空 | 有 | 每把私钥的公钥都须在 `PUBLIC_KEYS` 里,签完用客户端的 `verify` 按源码公钥核对 |
+
+**五、轮换。** 允许多把公钥并存:
+
+1. 生成新密钥;新公钥追加进 `PUBLIC_KEYS`,secret 里同时放新旧两把私钥(一行一把),签名文件各写一行。
+2. 等仍要自动升级的客户端都升到带新公钥的版本(下限与 ADR-0120 的 `OLDEST_CLIENT` 同样显式决定),secret 只留新私钥,`PUBLIC_KEYS` 删掉旧公钥。
+3. 旧私钥泄露时直接删旧公钥并停用旧私钥;只认旧公钥的客户端要手动装一次新版本,变更日志写明受影响的版本。
+
+**六、过渡期。** 已装的 0.54.0 及更早版本、以及 `PUBLIC_KEYS` 为空时构建的版本不读 `.sig`,照旧按摘要升级;多出的两个 Release 资产不影响它们选包(`update_compat.py` 门槛照常运行)。第一个 `PUBLIC_KEYS` 非空的版本必须本身已签名,由第四条门槛保证。带公钥的客户端只会装比自己新的版本,它们都在门槛之后发布,所以不存在需要放行的未签名旧版本,客户端也不设「缺签名则放行」的分支,否则剥掉签名就能绕过。
+
+R2 目录目前没有 `.sig`:带公钥的客户端在 GitHub 不可达时,经 R2 的那条路会因签名缺失而停在当前版本。R2 的 `releases.json` 本已停在 0.50.0,恢复 R2 发布时须一并上传签名文件。
+
+**七、防护边界。** 签名挡得住发布资产被替换、镜像被改写和传输途中的篡改,挡不住能在 `release` environment 里运行标签工作流的人:他拿得到私钥,签出的版本客户端照样认。仓库与 environment 的访问控制仍是信任根的一部分。
+
+## 依赖
+
+Ed25519 用已锁定的 `cryptography==50.0.2`。它原是 `smbprotocol` 的传递依赖,Windows 独立包里已经带着;现在在 `pyproject.toml` 直接声明并登记导入归属。[REUSE](../REUSE.md) 里 `certs.py` 不用 `cryptography` 的理由是证书生命周期策略与 CA 安装方式,与签名校验无关。
+
+## 已拒绝方案
+
+- **签整份 `releases.json`。** 当前发布流程不写它,GitHub API 的行也不归 Peach 生成;签了也保护不到在用的来源,还要先定 JSON 的规范化字节。
+- **在 `check` 里校验。** 见第三条:定时检查每次多两个请求,ADR-0120 的兼容门槛要为旧客户端代签,私钥就得进构建作业。
+- **复用 Sparkle 的私钥。** 不用新配 secret,但 ADR-0130 写明那把公钥在 ad-hoc 签名下无法轮换;Windows 的信任根绑上去,泄露时两个平台一起失效,也失去本 ADR 的轮换能力。
+- **minisign、signify 或 SSHSIG 格式。** 能用现成命令行验签,但客户端要多带一个解析器或外部工具;这里只需验一种文件,`cryptography` 已在包里。
+- **GPG 签名。** 客户端要带 GnuPG 或 OpenPGP 解析库,密钥管理也比单个 Ed25519 seed 重。
+
+## 需要维护者授权或决定的步骤
+
+代码 PR 不生成、不保存、不上传正式私钥,也不改 GitHub secret。维护者按顺序完成:
+
+1. 生成密钥对:在主检出运行 `scripts/sign_release.py --generate-key <私钥文件>`,私钥只写进该文件,输出只有公钥。私钥文件放进离线备份,不进仓库与数据根。
+2. 把私钥写进 GitHub `peach-mitao/peach` 的 `release` environment secret `PEACH_RELEASE_SIGNING_KEY`(用 `gh secret set` 从标准输入读)。
+3. 发布一个版本,确认 Release 资产里有 `SHA256SUMS.txt.sig`。
+4. 把公钥写进 `PUBLIC_KEYS`,经 PR 合入。之后的版本由第四条门槛保证带签名。
+
+## 未取得的证据
+
+- **独立包里的 `cryptography` 能否导入 Ed25519。** `release_signing` 的导入写在函数里,PyInstaller 的静态分析会收集;`smbprotocol` 本已带入 `cryptography`。本地没有构建 Windows 独立包验证:未取得。
+- **`release` 作业实跑签名。** 门槛逻辑由单元测试用临时密钥演练;GitHub 上带 secret 的实跑要等维护者配置后的第一次发版:未取得。
+- **`release` environment 的保护规则。** 运维文档写明只允许 `v*` 标签部署;是否另有需要人工批准的规则(会让标签作业等待):未取得。