Peach: Local-first video metadata scraper and media manager.
docs(adr): 发布签名与账本备份的决策改号为 ADR-0137、ADR-0138
longmeidao2201f1aa7fa7
diff --git a/.github/workflows/release.yml b/.github/workflows/release.ymlindex c9abeee90..456f25e06 100644--- a/.github/workflows/release.yml+++ b/.github/workflows/release.yml@@ -394,7 +394,7 @@ jobs:needs: validateruns-on: ubuntu-latesttimeout-minutes: 10- # 发布签名私钥放在这个只允许 `v*` 标签部署的 environment 里(ADR-0134)。+ # 发布签名私钥放在这个只允许 `v*` 标签部署的 environment 里(ADR-0137)。environment: releasepermissions:contents: writediff --git a/docs/OPERATIONS.md b/docs/OPERATIONS.mdindex 0fad5f9c6..6040645df 100644--- a/docs/OPERATIONS.md+++ b/docs/OPERATIONS.md@@ -117,7 +117,7 @@ launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/io.github.longmeidao.pea### Windows 应用内更新的发布签名-Windows 独立包的应用内更新校验每个版本 `SHA256SUMS.txt` 的 Ed25519 签名,取舍见 [ADR-0134](adr/0134-release-sums-ed25519-signature.md)。`src/peach/release_signing.py` 的 `PUBLIC_KEYS` 为空时不校验;写入公钥后,这一版起的客户端只装签名验得过的版本。+Windows 独立包的应用内更新校验每个版本 `SHA256SUMS.txt` 的 Ed25519 签名,取舍见 [ADR-0137](adr/0137-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 为空时作业失败,不发布未签名的版本。@@ -441,7 +441,7 @@ Peach 配置页地址是 `/configuration`。从管理菜单或设置弹窗的「### 账本备份与恢复-配置页「应用与维护 → 账本备份」列出 `database/` 与 `generated/organize-backups/` 里所有能恢复的备份,新的在前,每行写明时间、来源(手动,或自动及其用途)和大小。取舍见 [ADR-0134](adr/0134-user-triggered-ledger-backup-and-restore.md)。+配置页「应用与维护 → 账本备份」列出 `database/` 与 `generated/organize-backups/` 里所有能恢复的备份,新的在前,每行写明时间、来源(手动,或自动及其用途)和大小。取舍见 [ADR-0138](adr/0138-user-triggered-ledger-backup-and-restore.md)。- **立即备份**:后台复制当前账本,进度同时显示在任务中心。复制完先做完整性检查,通过才命名为 `ledger.pre-manual-<时间>.db`;没通过的那份直接删掉。手动备份和自动备份同一套保留规则(见「迁移、备份与运维脚本」)。- **从备份恢复**:只能在写入端执行,且数据目录里没有别的任务在跑。确认后依次检查备份的完整性和结构(来自更新版本的备份拒收,较旧的先迁到当前结构),把当前账本另存为 `ledger.pre-restore-<时间>.db`,再把备份写进账本。恢复期间不能启动新任务;任务中心的历史保留恢复前的记录。完成后刷新页面查看恢复后的资料。@@ -810,7 +810,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))。+- `release_signing.PUBLIC_KEYS` 非空时,Windows 更新器下载前先取同版本的 `SHA256SUMS.txt` 与 `SHA256SUMS.txt.sig`,用随包公钥验过签名后,更新包与完整包只按签过名的摘要校验;两个来源都验不过就停在当前版本,提示到发布页手动下载([ADR-0137](adr/0137-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.mdindex 8dae113bd..bacabe018 100644--- a/docs/REUSE.md+++ b/docs/REUSE.md@@ -963,7 +963,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) |+| 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-0137](adr/0137-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/0137-release-sums-ed25519-signature.mdsimilarity index 99%rename from docs/adr/0134-release-sums-ed25519-signature.mdrename to docs/adr/0137-release-sums-ed25519-signature.mdindex 12fdcf512..7902dbc29 100644--- a/docs/adr/0134-release-sums-ed25519-signature.md+++ b/docs/adr/0137-release-sums-ed25519-signature.md@@ -1,4 +1,4 @@-# ADR-0134:Windows 应用内更新校验发布摘要的 Ed25519 签名+# ADR-0137:Windows 应用内更新校验发布摘要的 Ed25519 签名- 状态:已采纳;代码已实施,公钥待维护者生成密钥后写入,写入前行为不变- 日期:2026-11-04diff --git a/docs/adr/0134-user-triggered-ledger-backup-and-restore.md b/docs/adr/0138-user-triggered-ledger-backup-and-restore.mdsimilarity index 98%rename from docs/adr/0134-user-triggered-ledger-backup-and-restore.mdrename to docs/adr/0138-user-triggered-ledger-backup-and-restore.mdindex ebfc5f92e..d64fb16c6 100644--- a/docs/adr/0134-user-triggered-ledger-backup-and-restore.md+++ b/docs/adr/0138-user-triggered-ledger-backup-and-restore.md@@ -1,4 +1,4 @@-# ADR-0134:用户可触发的账本备份与恢复+# ADR-0138:用户可触发的账本备份与恢复- 状态:已采纳- 日期:2026-11-04diff --git a/frontend/src/react/settings/ledger-backup-settings.tsx b/frontend/src/react/settings/ledger-backup-settings.tsxindex 6cec7064d..60c796d4f 100644--- a/frontend/src/react/settings/ledger-backup-settings.tsx+++ b/frontend/src/react/settings/ledger-backup-settings.tsx@@ -1,4 +1,4 @@-/* 「账本备份」:立即备份当前账本,或从一份备份恢复(ADR-0134)。+/* 「账本备份」:立即备份当前账本,或从一份备份恢复(ADR-0138)。** 列表里是两处备份目录里能恢复的全部备份,新的在前:手动备份与写入前的自动备份同一套保留规则。* 备份与恢复都是服务端的后台任务,进行中每 1.5 秒问一次状态,进度同时进任务中心。diff --git a/pyproject.toml b/pyproject.tomlindex 662386411..4d959c181 100644--- a/pyproject.toml+++ b/pyproject.toml@@ -57,7 +57,7 @@ dependencies = ["watchdog==6.0.0","zeroconf==0.153.0","smbprotocol==1.17.0",- # 应用内更新校验发布签名(Ed25519,ADR-0134)。+ # 应用内更新校验发布签名(Ed25519,ADR-0137)。"cryptography==50.0.2",]diff --git a/scripts/sign_release.py b/scripts/sign_release.pyindex be6854706..a4d0c3723 100644--- a/scripts/sign_release.py+++ b/scripts/sign_release.py@@ -1,4 +1,4 @@-"""给发布目录的 `SHA256SUMS.txt` 写 Ed25519 签名,并用客户端的校验代码核对(ADR-0134)。+"""给发布目录的 `SHA256SUMS.txt` 写 Ed25519 签名,并用客户端的校验代码核对(ADR-0137)。私钥从标准输入读,一行一把(32 字节 seed 的 base64);轮换期同时给新旧两把,签名文件各写一行。源码的 `PUBLIC_KEYS` 为空且没给私钥时跳过签名;公钥已随源码发出却没给私钥时拒绝发布,diff --git a/src/peach/api.py b/src/peach/api.pyindex 109a59df9..d1bebc0f9 100644--- a/src/peach/api.py+++ b/src/peach/api.py@@ -208,7 +208,7 @@ WARM_AGGREGATES = (("/api/taste", {"window": "all"}), ("/api/review", {}), ("/apdef _start_ledger_services(settings: PeachSettings, contract, services) -> bool:"""只读核对当前账本后,恢复任务并启动依赖账本的后台服务。"""try:- # 上次从备份恢复没走完:先把账本收拾到确定的状态,再判它能不能用(ADR-0134)。+ # 上次从备份恢复没走完:先把账本收拾到确定的状态,再判它能不能用(ADR-0138)。ledger_backups.recover(settings.db_path)except Exception:LOGGER.exception('账本恢复标记未能处理')diff --git a/src/peach/ledger_backups.py b/src/peach/ledger_backups.pyindex 872678e33..98cc12c22 100644--- a/src/peach/ledger_backups.py+++ b/src/peach/ledger_backups.py@@ -16,7 +16,7 @@(`ORGANIZE_KEEP_RECENT`,`ORGANIZE_MIN_AGE` 为零);整理进行中的那份由 `holding`登记,同一进程里的清退都不碰它。登记不跨进程:手动脚本给 `--keep 0` 时只靠份数保护。-设置页的「立即备份」与「从备份恢复」也在这里(ADR-0134)。手动备份叫+设置页的「立即备份」与「从备份恢复」也在这里(ADR-0138)。手动备份叫`ledger.pre-manual-<时间>.db`,恢复前另存的当前账本叫 `ledger.pre-restore-<时间>.db`,和自动备份同目录、同一套保留规则。恢复不换文件,而是经 SQLite Backup API 写进在用的账本,写入前留下 `ledger.restore.json`;启动时看到它说明上次恢复没走完,由 `recover` 收拾。@@ -248,7 +248,7 @@ def prune(# ----------------------------------------------------------------------------# 手动备份与从备份恢复(ADR-0134)+# 手动备份与从备份恢复(ADR-0138)class BackupRejected(ValueError):diff --git a/src/peach/release_signing.py b/src/peach/release_signing.pyindex 64d97037d..0c49615c3 100644--- a/src/peach/release_signing.py+++ b/src/peach/release_signing.py@@ -1,4 +1,4 @@-"""Windows 独立包更新的发布签名(ADR-0134)。+"""Windows 独立包更新的发布签名(ADR-0137)。每个版本的 `SHA256SUMS.txt` 由发布作业用 Ed25519 私钥签名,签名写在同目录的`SHA256SUMS.txt.sig`,一行一个签名:`<公钥 base64> <签名 base64>`。更新器只认@@ -10,7 +10,7 @@ import base64import re#: 受信任的发布签名公钥(base64,32 字节 Ed25519)。为空时更新器不要求签名;随某一版发出后,-#: 这一版起的客户端只装签名验得过的版本,发布作业缺私钥即失败。轮换见 ADR-0134。+#: 这一版起的客户端只装签名验得过的版本,发布作业缺私钥即失败。轮换见 ADR-0137。PUBLIC_KEYS: tuple[str, ...] = ()SUMS = "SHA256SUMS.txt"SIGNATURE = SUMS + ".sig"diff --git a/src/peach/standalone_update.py b/src/peach/standalone_update.pyindex 8226e0659..aa6335121 100644--- a/src/peach/standalone_update.py+++ b/src/peach/standalone_update.py@@ -191,7 +191,7 @@ def _fetch_small(client, url: str) -> bytes:def signed_release(release: dict) -> dict:- """源码带发布公钥时,更新包与完整包的摘要只取签名验过的 `SHA256SUMS.txt`(ADR-0134)。+ """源码带发布公钥时,更新包与完整包的摘要只取签名验过的 `SHA256SUMS.txt`(ADR-0137)。两个公开源依次尝试;都验不过就不升级,已装版本原样保留。"""diff --git a/tests/test_release_signing.py b/tests/test_release_signing.pyindex a77cbf2a9..673fb2652 100644--- a/tests/test_release_signing.py+++ b/tests/test_release_signing.py@@ -1,4 +1,4 @@-"""发布摘要签名:客户端校验与发布脚本,密钥都在测试里临时生成(ADR-0134)。"""+"""发布摘要签名:客户端校验与发布脚本,密钥都在测试里临时生成(ADR-0137)。"""import base64import contextlibimport io