Skip to content

armgit / peach

Public Imported from GitHub
0

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

134 KB
Raw Blame

运行与配置

本文讲在自己电脑上运行 Peach 时要知道的事:第一次怎么设置、配置页在哪、怎么从其他设备访问、怎么装 FFmpeg、哪些操作会真的删除文件。

用 Windows 测试包的,先看 Windows 测试版;从源码运行的,按下面的步骤安装。文末「维护者参考」是给在源码上开发、打包和发布的人看的,普通使用可以跳过。

从源码运行(Windows、macOS)

需要 Git 和 uv。Python 下限为 3.14,项目由 .python-version 固定运行版本,uv 会自动下载缺少的解释器。

在 PowerShell 7(Windows)或 zsh(macOS)中依次执行:

  1. 克隆仓库:git clone https://github.com/peach-mitao/peach.git peach-app。
  2. 进入项目目录:cd peach-app。后续命令均在此目录执行。

Windows 安装依赖:uv sync --locked --python 3.14。完成后启动托盘:& .\.venv\Scripts\peach-tray.exe。

macOS 安装依赖:uv sync --locked --python 3.14 --extra macos。完成后启动托盘:./.venv/bin/peach-tray。

托盘会打开浏览器中的首次设置页。源码运行不需要下载 Windows 安装包。

macOS 独立测试包

在 macOS 的项目目录安装构建依赖:

MACOSX_DEPLOYMENT_TARGET=11.0 uv sync --locked --extra build --extra macos

先在构建目录安装固定工具链;下面以 Apple Silicon 为例,Intel 将 arm64 换成 x86_64:

./.venv/bin/python -X utf8 scripts/setup_macos_media_tools.py --root "$PWD/build/macos-media-toolchain"
export PATH="$PWD/build/macos-media-toolchain/env/bin:$PATH"
./.venv/bin/python -X utf8 scripts/build_macos_media.py --tool ffmpeg --arch arm64 --output build/media-macos/arm64/ffmpeg
./.venv/bin/python -X utf8 scripts/build_macos_media.py --tool untrunc --arch arm64 --output build/media-macos/arm64/untrunc
./.venv/bin/python -X utf8 scripts/fetch_cloudflared_macos.py --arch arm64 --destination build/media-macos/arm64/cloudflared
./.venv/bin/python -X utf8 scripts/fetch_sparkle_macos.py --destination build/media-macos/arm64/sparkle

构建包含 Python、页面、迁移、资源和自包含工具的应用与 DMG:

./.venv/bin/python -X utf8 scripts/build_macos_standalone.py

产物在 dist/macos.noindex/<架构>/,构建副本避开 Spotlight 索引;日常使用只保留 Applications 里的应用,测试结束卸载已挂载的安装镜像。Apple Silicon 使用 arm64,Intel 使用 x86_64;分别用对应架构的 Python 与依赖构建。--target-arch 显式指定目标,解释器架构不匹配会停止,两个包不混合原生扩展,也不直接合并成 universal2。Intel 构建可在 Intel Mac 或 Rosetta 下的 x86_64 Python 环境完成;Rosetta 验收不能代替 Intel 真机和较旧 macOS 的验收。

随包工具与许可证位于 Contents/Resources/tools/ffmpeg/bin、Contents/Resources/tools/untrunc,人脸检出与比对模型位于 Contents/Resources/tools/face-models,cloudflared 位于 Contents/MacOS。构建时 scripts/fetch_face_models.py 按固定提交下载两个模型与许可证并逐个校验 SHA-256,缓存在 build/face-models。工具先独立签名,再签整个应用,资源目录允许同时保存工具清单和说明。它们不依赖 Homebrew;FFmpeg、x264、dav1d 和修复用 FFmpeg 库静态链接,动态依赖仅允许 macOS 系统库。scripts/smoke_macos_media.py 在系统 PATH 下使用合成 H.264/AAC 与 AV1 样片验证工具查找、探测、抽帧、转码、缺 moov 修复和完整解码。该修复验收覆盖同编码参照样片,不代表任意损坏媒体都能恢复。

每种架构同时生成 ffmpeg-macos-<架构>-corresponding-source.zip 与 untrunc-macos-<架构>-corresponding-source.zip,必须与 DMG 同版本发布;归档包含完整上游源码、固定哈希、许可证、构建脚本、配置和环境记录。构建拒绝缺失、哈希不符、架构不符或依赖开发机动态库的工具。cloudflared 固定官方 2026.9.0,归档 SHA-256 采用 GitHub Release 资产 API 的 digest,来源登记在 scripts/cloudflared-macos.json;发布正文的旧校验值不作为这两个 macOS 归档的锁。

源码开发外壳 build_macos_app.py 默认输出到 dist/macos-source.noindex/,依赖本机 venv 与 LaunchAgent;不要把它当作独立应用安装。

构建脚本读取随包 Mach-O 的系统版本下限,填入 LSMinimumSystemVersion 并重新签名。构建解释器也必须支持目标系统;Homebrew Python 可能要求构建机的系统版本。watchdog 等本机编译扩展若命中旧缓存,需带部署目标和对应的 ARCHFLAGS,通过 uv sync --locked --extra build --extra macos --no-cache --reinstall-package watchdog --no-binary-package watchdog 重编,再核对产物报告的 minimum_macos。

打开匹配架构的 DMG,把 Peach.app 拖入 Applications,再打开应用完成首次设置。菜单栏提供打开页面、重启、查看日志、导出诊断报告、检查更新和退出入口;数据默认保存在 ~/Library/Application Support/Peach/peach-data,可用 PEACH_DATA_ROOT 指定独立目录。

菜单栏「版本与更新」>「检查更新」由下文的 Sparkle 在应用内安装新版本。配置页「检查更新」只认本机架构的 DMG,有新版本时给出该 DMG 的下载键,下载后同样拖入 Applications 覆盖旧版本,数据目录与设置保留;0.53.0 及更早的版本只能这样手动替换。卸载时先在配置页关闭开机自启并退出 Peach,再把应用移到废纸篓;需要完全卸载时,再删除配置页「卸载 Peach」列出的数据目录。

测试包没有公证,从浏览器或聊天软件下载后带有隔离属性,较新的 macOS 会提示「Peach 已损坏,无法打开」,「隐私与安全性」里也不出现「仍要打开」。拖入 Applications 后在终端执行下面的命令,再打开应用:

sudo /usr/bin/xattr -rd com.apple.quarantine "/Applications/Peach.app"

提示输入密码时,输入这台 Mac 的登录密码;输入过程中屏幕不显示字符。这条命令只移除 Peach 的隔离标记;手动拖入新版本后需要再运行一次,经 Sparkle 安装的新版本不需要。命令写全路径 /usr/bin/xattr,避开 Python 包装的同名命令;sudo 覆盖应用不归当前用户所有的情况。

首次设置页只在数据目录里没有 config.toml 时出现。这台 Mac 之前装过 Peach 时,应用会沿用原有设置直接打开首页;要重新设置,先退出 Peach,把整个 peach-data 目录移到别处再打开。

安装镜像使用 APFS 文件系统,保留已签名资源的 Unicode 文件名及应用扩展属性。浅桃色背景固定左侧 Peach、右侧 Applications 的拖放布局,隐藏工具栏与边栏,背景同时提供标准与 Retina 分辨率。许可证保留在应用的 Contents/Resources/LICENSE,安装窗口只显示两个入口。

版本提交触发 Release 演练,在 Apple Silicon 与 Intel 原生 runner 分别构建,再由干净 runner 下载并挂载 DMG,验证签名、架构和独立运行。标签核对同一提交的成功演练与摘要,发布已验收的相同文件。两种 DMG 与 Windows 安装包全部通过后,才一同上传到 GitHub 预发布,统一生成 SHA-256 清单。手动运行工作流只验收候选制品,不创建 Release;推送普通提交不会触发安装包构建。发版从只读审阅和依赖检查开始,重型验证前完成复核并冻结输入;集成、运行核验与定版按发版检查执行,打标签统一使用 scripts/release_tag.py。

macOS 异常退出恢复

菜单栏的异常退出恢复交给 launchd,不移植 Windows 的监视器。配置页打开「开机自启」后,~/Library/LaunchAgents/io.github.longmeidao.peach.tray.plist 写入 KeepAlive = {SuccessfulExit = false} 与 ThrottleInterval = 30;源码部署的 install_macos_agent.py install 写同一份设置,来源是 src/peach/desktop_startup.py。

退出方式 退出结果 launchd
菜单「退出 Peach」 退出码 0 不拉起
注销、关机 会话结束 不拉起
已有一个 Peach 在运行 退出码 0 不拉起
设置文件无效、迁移失败等启动失败 由 launchd 启动时按 0 退出,原因写进 logs/tray.log 不拉起
崩溃(SIGSEGV、SIGBUS、SIGABRT 等) 信号终止 拉起
强制退出、kill 信号终止 拉起

首次设置未完成时菜单栏照常运行,退出方式同上。启动失败重来结果相同,按非 0 退出会让 launchd 反复重试,所以托盘先核对 launchd 报的 pid 是自己,再按 0 退出;终端里手动运行仍返回 1。菜单回调里的 Python 异常由 PyObjC 事件循环弹出错误面板:选「继续」照常运行,选「退出」按 0 退出,都不触发拉起。

运行满 30 秒后崩溃会立即拉起;启动后 30 秒内反复崩溃时,每 30 秒最多拉起一次,launchd 不限次数。拉起后的菜单栏沿用启动项的 --silent 或 --show,后者会再打开一次浏览器。子服务与托盘同属一个进程组,按 launchd 默认行为在托盘退出时一并结束,新托盘重新启动服务。要彻底停止,用菜单退出,或运行 launchctl bootout gui/$(id -u)/io.github.longmeidao.peach.tray。

恢复只覆盖 launchd 启动的进程:

  • 开机自启关闭时写 KeepAlive = false。SuccessfulExit 隐含 RunAtLoad,保留它会让关掉的自启在登录时照样启动,所以此时没有恢复。
  • 独立包双击 Peach.app 由 LaunchServices 启动,不归 launchd 管理,崩溃后需要手动重开。登录时由启动项拉起的那一次有恢复;从菜单退出后再双击打开,到下次登录前都没有恢复。Peach 不为双击启动另设监视进程。
  • 源码外壳双击执行 launchctl kickstart,进程归 launchd,开机自启开着时同样恢复。

launchd 使用登录时载入的 plist。升级后托盘第一次启动时,已开启的旧启动项会就地补上这两项,其余键不变;在配置页保存开机自启也会重写。两种方式都在下次登录生效。要立即生效,先从菜单退出,再运行:

launchctl bootout gui/$(id -u)/io.github.longmeidao.peach.tray
launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/io.github.longmeidao.peach.tray.plist

macOS 应用内更新(Sparkle)

应用随包带 Sparkle 2 框架(Contents/Frameworks/Sparkle.framework,版本与摘要固定在 scripts/sparkle-macos.json),取舍见 ADR-0130。src/peach/sparkle_update.py 的 PUBLIC_ED_KEY 决定是否启用:有值时构建写入 SUPublicEDKey 与更新源地址;清空后构建不写这些键,菜单栏「检查更新」改回版本检查与系统通知。

菜单栏「版本与更新」>「检查更新」交给 Sparkle:下载本机架构的 DMG、核对 EdDSA 签名,在用户确认后退出 Peach、替换应用并重新打开,替换时移除新应用的隔离标记。设置页的自动更新开关与检查频率同步到 Sparkle 的定时检查;不自动下载安装。安装前先让任务保存进度、停掉 Peach 拉起的服务;本机是账本读取端且新版本带有本机未应用的迁移时不安装,并用通知说明要先在写入端更新。

发布侧的设置:

  1. 私钥在 GitHub 仓库 release environment 的 secret SPARKLE_ED_PRIVATE_KEY,该 environment 只允许 v* 标签部署;维护者另有离线备份。ad-hoc 签名下无法轮换,丢失后已装客户端只能手动重装。导入 Mac 钥匙串用 Sparkle 发布包的 generate_keys -f <私钥文件>。
  2. 同一 environment 需要 R2 的 secret PEACH_R2_ACCESS_KEY_ID、PEACH_R2_SECRET_ACCESS_KEY、PEACH_R2_ENDPOINT 与变量 PEACH_R2_BUCKET。
  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-0137。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)。版本提交 chore(release): 版本 X 的主线流水线同时是发布演练:三平台全量、媒体工具、Windows 与 macOS 构建、Windows 冒烟和 Docker 镜像都跑一遍,只是不发布。--ship 等演练全部成功才打标签;标签流水线核对同一提交的演练已通过,只重新构建并发布(ADR-0121)。GitHub 的 release.yml 用同一套判据,迁回 GitHub 时不用改流程。CLI 传输复用官方 glab,不在仓库或命令参数里存访问令牌。

平台共享 Runner 的系统由管理员提供。注册页面列出 Windows 和 macOS,表示可以接入这些系统上的 Runner;不能据此判断平台提供相应云主机。临时原生 Runner 只接入受保护主线和版本标签,使用项目专属标签,验收后停止并注销。Mac 的 Intel 构建需要真实 x86_64 Python 和依赖;在 Apple Silicon 上通过 Rosetta 验收时,应明确记录未覆盖 Intel 真机。

Windows 原生 Runner 在深目录中检出项目时,需为 Git 启用 core.longpaths=true,供检出与清理阶段处理 npm 缓存。设置可限定到 Runner 的任务环境,通过 GIT_CONFIG_COUNT 与对应的 GIT_CONFIG_KEY_<索引>、GIT_CONFIG_VALUE_<索引> 条目传递;已有条目按索引追加。宿主系统的长路径开关与 Git 设置分别核对。

用计划任务常驻 Windows 原生 Runner 时,任务设置的 Priority 取 4,例如 New-ScheduledTaskSettingsSet -Priority 4;已注册的任务可以读出对象,把 Settings.Priority 改成 4,再用 Set-ScheduledTask -InputObject 写回。省略时默认 7,gitlab-runner 与所有作业子进程以 BelowNormal 的 CPU 优先级、Low 的 I/O 优先级和 2 级内存优先级运行。Runner 与开发会话共用这台机器,别的会话跑全量测试时,作业里的 vitest 工作进程、首次设置后的服务就绪探测和快捷方式 COM 调用拿不到 CPU 与磁盘,因等待超时失败,全量回归也会超过作业时限。设置只对新启动的进程生效:在没有作业运行时重启该任务,再核对 gitlab-runner 进程的优先级类为 Normal。

计划任务的「失败后重启」(RestartCount、RestartInterval)只在任务启动失败时生效,gitlab-runner 进程自己退出后不会被拉起,主线的 Windows 作业就一直排着没人接。所以任务的动作是 runner 目录里的入口脚本 run-runner.ps1:它按可执行文件路径查找本目录的 gitlab-runner.exe,已经在跑就直接退出,没在跑才拉起,这样不会让同一个 token 跑两个 runner。触发器保留「登录时」,另加一个每 5 分钟重复、不设结束时间的时间触发器,MultipleInstances 设为 IgnoreNew。runner 退出后最多 5 分钟就会被拉回来。

计划任务使用 pythonw.exe 调用 scripts/run_gitlab_runner.py --root <runner目录>,由启动器通过 CREATE_NO_WINDOW 运行原有 run-runner.ps1。PowerShell 的 -WindowStyle Hidden 不能保证不触发 Windows Terminal 托管,后台入口不直接以控制台程序作为计划任务动作。启动器日志保存在 runner 目录的 runner-launcher.log,runner 输出仍沿用 runner.log。

版本标签须受保护。版本提交的演练完成三平台回归、固定来源媒体工具、Windows 完整包与拆分包、macOS 双架构 DMG、安装升级和镜像验收,再登记候选。标签核对相同提交、验证任务与文件摘要后发布已验收产物,不重新构建。publish-release 上传 R2 并创建 GitLab Release,publish-docker 排在它成功之后推送同一 image ID 的镜像;最终回收演练暂存。发布作业失败时重试同一作业,标签不动。项目流水线使用 PEACH_DOWNLOAD_BACKEND=both,同一份制品分别保存在 R2 与 GitGud Generic Package Registry;不把会过期的 job artifacts 当作永久下载地址。独立部署可明确选择 r2 或 gitgud 单后端。候选和发布顺序见 ADR-0127。

Linux 发布任务使用官方 uv Python 3.14 容器,并在获取制品工具前核对解释器版本;源码归档使用 tarfile 的 data 过滤器解压。CI 的 .npm/ 与 .uv-cache/ 属于生成缓存,不计入源码工作区变化。

Windows 安装覆盖与任务恢复验收允许 GitHub Actions,以及受保护版本标签或版本提交演练上的 GitLab smoke-windows 作业;主机已有 Peach 安装登记时拒绝执行。所有程序、账本与任务夹具均放在临时目录,安装与卸载完成后核对登记清理。fetch_cloudflared.ps1 的相对输出路径按 PowerShell 当前工作位置解析,下载仍须通过固定 SHA-256 校验。

GitGud 的 Linux 平台 Runner 不提供 Docker 守护进程,Docker 镜像由 docker-build 作业在 Windows 原生 Runner 构建,宿主须运行 Docker Desktop。作业核对标签与版本,用 smoke_docker.py 验收临时容器,镜像留在本机;演练里验收完就删除。标签流水线上,publish-docker 等 publish-release 成功后才推送版本号与 edge 两个标签,所以 edge 只会指向已经完整发布的版本。DOCKERHUB_USERNAME 与 DOCKERHUB_TOKEN 放入受保护且隐藏的 CI 变量,环境作用域为 release;令牌只授予仓库读写。登录写入作业专用的临时 DOCKER_CONFIG,结束时登出并删除,不改动宿主用户的 Docker 登录。

媒体工具源码可通过 PEACH_SOURCE_CACHE_BASE 指定 HTTPS 缓存入口,按 <SHA-256>/<归档名> 定位文件。标签流水线使用发布桶的 _sources/ 前缀;维护者填充缓存前须核对锁文件的原始 SHA-256,缓存同样计入桶容量预算。下载缓存失败时尝试锁定的上游地址;任一来源的哈希不符立即拒绝,不能放宽清单。未配置缓存的对应源码包直接使用上游。

可选的 r2 后端使用独立 Standard 桶与 HTTPS 自定义域名。PEACH_R2_ACCESS_KEY_ID、PEACH_R2_SECRET_ACCESS_KEY、PEACH_R2_ENDPOINT 放入受保护且隐藏的 CI 变量,环境作用域为 release;PEACH_R2_BUCKET 和 PEACH_R2_PUBLIC_BASE 指定发布目标。S3 传输复用 rclone,版本文件禁止覆盖;每份文件必须从公开入口完整下载并核对大小及 SHA-256 后,才更新公开版本索引和 Release 链接。

GitLab 演练通过 R2 暂存传递媒体工具、Windows 发行目录、macOS 镜像和 Docker 验收回执,job artifacts 保存 JSON 清单。中转需要上述 R2 变量;构建与验收任务使用 release 环境的 prepare 或 verify 动作,只有受保护版本标签与受保护 master 上的版本提交演练能取得凭据。候选保留到桌面与镜像都发布成功,由 publication-cleanup 回收;失败时保留供重试。构建期 rclone 按当前操作系统和 CPU 架构从官方固定版本归档安装并核对 SHA-256。

暂存对象位于 _ci/<项目 ID>/<流水线 ID>/<提交 SHA>/<产物组>/<作业 ID>/,纳入同一桶预算。完整上传后在同一前缀的 completed/ 登记不可变完成清单;重试优先恢复已经完成的同流水线产物,传输失败不当作未构建。seal-release 登记版本、提交、成功任务与文件摘要。标签通过 GitLab API 核对同一提交的成功主线演练,再下载其相同文件;路径限定在对应输出目录,不接收软链接或路径穿越。macOS 仅传两种架构的 DMG、对应源码、build-info.json 与 SHA256SUMS.txt,不传展开应用。所有构建和独立制品验收成功后才写正式版本目录和公开索引;桌面与镜像都发布成功后只回收该演练前缀。失败候选保留供重试,不覆盖已有公开版本。

上传期间的完成构建保存在 CI_BUILDS_DIR/.peach-upload-resume/ 的独立身份目录。R2 部分上传失败后,同机重试核对备份大小与 SHA-256,继续传到原作业前缀;完整上传清单登记后回收本组备份。机器更换且没有完整远端清单时需重新构建,不拼接未知来源文件。

Windows 轻量安装器缺少本地工具包时,先从 R2 下载当前版本的工具;连接失败或内容校验失败时,尝试 GitHub 的同版本文件。两个来源均须匹配安装器内置清单的大小与 SHA-256,不能混用其他版本。发布完成后,用 scripts/smoke_split_update.py 的 --prepare-with-app --online 在空缓存中运行实际制品,核对联网取得的工具能否重建完整程序。GitLab Release 的下载表使用 R2,资产区另列 GitGud 副本,文档链接指向对应版本标签。

已装的独立包用自己的代码读新版本的发布条目与更新包,发版时改不了。build-windows 拆包后运行 scripts/update_compat.py,用 0.48.0 起每个已发布版本标签里的更新代码原样读这一版:选不中新版本、读不了工具清单,或清单里有旧版不认得、运行时又补不齐的工具时,作业失败,不上传任何文件。本机测试用合成制品跑同一道核对,检出须带发布标签。客户端只准备自己认得、清单里也有的工具;应用更新包用不了时改下同版本完整包。0.47.3 及更早的版本读不了 0.48 起的清单,需手动运行一次完整安装包。依据见 ADR-0120。

双后端发布复用官方 glab packages upload,将安装包、工具包、对应源码与 SHA-256 清单保存在 peach-release/<版本标签>/。上传前验证本地文件与 R2 发行清单一致,上传后检查 GitGud 服务端记录的大小与 SHA-256;同版本同名同内容直接复用,内容不同则保留原文件并停止。R2 保留原下载路径,GitGud Release 的备用直链使用 /gitgud/<文件名>,避免与主要下载入口冲突。两份存储均就绪后才登记 Release;官网继续优先从 Cloudflare 下载。

R2 公网下载流量免费,存储与请求按账户共享额度计费。预算告警只通知,不会停止服务;R2 后端不提供零费用硬封顶。要求绝不产生按量费用的部署应使用不绑定按量计费的下载服务,不启用 R2 自动发布。

演练入口读取本桶真实占用和暂存范围,构建清单齐备后、安装冒烟前计算暂存与公开副本的精确峰值,候选登记和上传时仍复查;默认超过 8 GB 时停止,保留已有文件。未知新版体积在构建前不视为已知容量。PEACH_R2_MAX_BYTES 可明确调整该桶预算;此检查不能限制同账户其他桶,也不代替请求量计费保护。版本文件设置长期缓存,公开版本索引只缓存一分钟。

Mac 与 Windows 托盘的首层只显示简短状态与提醒数量,展开状态子菜单按行查看服务和媒体来源。长地址与路径会缩略,子菜单中的「查看完整配置」保留完整设置入口;提醒消失后会随下一轮健康检查更新。

单机设置默认关闭账本复制,不需要 Windows、SMB、LaunchAgent 或系统端口转发。各台电脑各自保存数据;共享馆藏仍按下文的双机复制配置,离线修改不能自动合并。已有数据目录不会自动导入。

这条构建路径使用本地 ad-hoc 签名,未完成 Developer ID 签名和 Apple 公证,不作为已签名发行包发布。DMG 只分发应用,不安装系统服务;需要集中部署系统组件时再评估 PKG。独立包内含媒体工具与 cloudflared,工具位置与验证见「macOS 独立测试包」;源码开发外壳使用本机环境。应用内更新由随包的 Sparkle 完成,启用条件见「macOS 应用内更新(Sparkle)」。

首次运行与设置文件

在网页设置的「JAV 与新作」中,可将女优名称显示为中文或日文原文。偏好保存在数据库,其他设备读取同一份设置;保存失败时保留原选择。切换只调整当前所选艺名的写法,缺少对应时保留当前名称,不更改人物名称、别名原文或作品署名。

第一次打开 Peach 有两种方式,结果相同:

  • 托盘(推荐):运行托盘程序后,浏览器会打开首次设置页。
  • 终端:运行 peach init,按问答完成设置。

两种方式都会创建数据目录、准备数据库、生成本机证书和访问口令,并写出设置文件。

首次设置页

首次设置分为欢迎、媒体目录、访问范围和确认四步。返回上一步会保留填写内容;提交校验失败时回到对应步骤。欢迎页可选择「使用已有数据」,恢复流程和完成页使用同一套分栏框架。

首次设置页会问:

  1. 媒体目录:按媒体库分组,每个媒体库可设置名称、图标、来源色和处理方式,并添加多个文件夹。旁边的「选择文件夹」会弹出系统的文件夹选择框;也可以选择稍后添加媒体库。
  2. 数据目录:数据库、封面、预览图和缓存都放在这里,馆藏较大时会占用数十 GB。Windows 版默认在系统盘的 %LOCALAPPDATA%\Peach\peach-data,系统盘空间紧张时请选其他磁盘上的文件夹;装好以后也可以在配置页迁移。
  3. 谁可以访问:「只有这台电脑」或「同一局域网的设备」。
  4. Peach 代理,以及高级设置中的端口和局域网名称。
  5. 访问密码(可选):留空时,能连到 Peach 的设备不用登录就能进入。
  6. 是否立即扫描和诊断反馈;稍后添加媒体库时不触发扫描。

提交后进入 Peach,右下角会出现一份安装教程,列出馆藏、采集凭证、浏览器历史、关注、关注凭证和复核几项。每一项都可以跳过(短时间内能撤销),全部完成或跳过后教程自动消失。教程进度只保存在当前浏览器里。选了导入浏览器历史的,会先打开口味页。

首次设置页由一条只监听本机回环地址的临时服务提供(默认端口 8900),提交成功后托盘自动切换到正式服务,不用重启托盘。它的端口、返回码和切换过程见「维护者参考」里的「首次设置的内部流程」。

终端 peach init

在终端里直接运行 peach init(不带参数)会进入问答:

  1. 数据目录。
  2. 一个或多个本地媒体目录:答完一个会接着问「再加一个」,直接回车结束。重复或互相包含的文件夹会被退回。
  3. 谁可以访问(只有这台电脑/同一局域网的设备)。
  4. 端口。
  5. 局域网访问地址。

每一题直接回车就用默认值。连续三次输入无效会退出,并且不写任何文件。答完后会问「现在扫描 <目录>?」(默认是),最后打印下一步和扫描摘要。

终端问答只能添加本地文件夹。115 和 PikPak 网盘请在首次设置页或配置页添加,见下面的「CloudDrive 配置」。

给了任何参数、加了 --no-input,或者不是在终端里运行时,peach init 不问问题,直接按默认值和 --data-root、--host、--port、--mdns-name、--mount local=/mnt/media 这些参数生成。这样写出的设置文件带 local、115、pikpak 三个示例来源。已经有数据库时它不会重建,会提示改用 --from-existing。

设置文件在哪

设置文件固定是 <Peach 数据目录>/config.toml。Peach 数据目录(Peach 存放数据的目录)按下面的顺序找:

  1. 环境变量 PEACH_DATA_ROOT。
  2. 项目目录旁边的 peach-data/(最多向上找四层,所以主检出、工作树和打包出的 dist/Peach 都能找到同一个)。
  3. 都没有,就是「未配置」。

Windows 测试包默认使用 %LOCALAPPDATA%\Peach\peach-data。首次设置选择其他数据目录时,默认数据目录的 state/data-root.txt 会记录所选绝对路径;托盘、子服务和再次启动均沿此记录读取设置。该文件只保存本机路径,Peach 数据库和媒体留在各自目录。记录不可读、路径无效或循环时会报错。

已有配置却出现首次设置页时,选择「使用已有数据」,填入原数据目录,例如 E:\Peach\peach-data。此目录须包含有效的 config.toml 和 Peach 数据库;连接成功后,普通启动也沿用该位置。没有位置记录的任意自选目录无法在升级时自动发现,需要选择一次;不必重新初始化或删除数据。

已经通过 --data-root 进入馆藏的部署,在线更新的新版本会将正在使用的目录记入空的默认默认数据目录,随后可以普通启动。默认数据目录已有配置、Peach 数据库或目录记录时,继续保留其选择。

恢复接口 POST /api/setup/restore 接收 {"data_root":"绝对路径"},沿用首启的本机和同源守卫。成功返回完成页字段及 restored=true;失败返回 400,原因位于 errors.data_root。

同一个设置项的优先级:环境变量 > 设置文件 > 内置默认值。

升级后的自动处理

升级并启动 Peach 后,已配置的写入端自动完成数据库迁移、本地确定性资料修复与后台补全,无需手动启动补修。结构和资料处理前保留数据库备份;人工填写、复核结果与人工规范名受保护,存在身份冲突的项目保留复核记录。只读设备不执行这些写入。

本版更新器允许读取端安装结构兼容的程序;若提示结构待迁移,先升级写入端并同步账本,再安装读取端更新,安装及失败恢复均不回写账本。仍使用旧更新器的读取端须先完成写入端升级及同步;旧助手在迁移被拒后仍可能写回自己的账本备份,当前程序无法追溯修改已经运行的旧助手。

资料和图片缓存按规则版本与来源变化失效。需要重新读取媒体的项目遵守媒体库处理方式、预览设置和读取成本:免费来源可自动处理,额外流量项目延后。处理会保存进度;失败可在「应用与维护 → 自动修复」重试,用户取消的任务保持取消。正常升级无需打开该面板。

应用提供新版本、更新准备完成及页面需要刷新的提示。首次未设置自动更新时,每天检查版本;明确关闭过的设置继续保留。下载、重启安装与页面刷新分别沿用用户选择,不因提示自动打断当前操作。独立包在新程序通过启动检查后才恢复后台任务;安装失败恢复程序、数据库、配置与任务检查点。

「自动修复」可下载本地复核记录。GET /api/client-updates 只读取本机快照,不触发外部版本检查;接口与权限见路由清单。设计与规则版本边界见 ADR-0126。

设置文件出问题时

  • 已经有设置文件:peach init 会拒绝运行并返回 3,加 --force 才会覆盖。覆盖前先复制一份 config.toml.bak,它是唯一记着这台电脑配置的文件。
  • 设置文件有语法错误:peach serve、peach migrate、peach status 会拒绝运行,并报出文件路径和出错的行,不会悄悄用默认值跑出一个错误的状态。这时 peach init --force 仍然能用,是唯一的自救入口。
  • 没有设置文件:peach serve 照常启动,页面会提示先运行 peach init,/healthz 返回 configured=false。
  • [media] 下直接写盘符键(例如 R = '...'):peach serve 会拒绝启动,并提示改写成 [media.mounts]。

扫描一个目录

peach scan <来源ID> [根目录] 把一个目录里的文件登记进数据库。它只新增记录、刷新大小和修改时间,不改人工确认过的信息,也不删除记录。

目录已设置归属用途且开启「新文件沿用此规则」时,新登记的文件按最近一层规则关联;已有冲突保留,见目录浏览。

  • 不给根目录时,扫描这个来源在 [media.locations] 里声明的全部目录。
  • 给了根目录时,它必须在某个声明的目录之内(macOS 上是挂载点之内),否则会被拒绝,因为登记进去的路径无法换算回本机路径。
  • 扫描跳过 #recycle 和名称以 @ 开头的 NAS 系统目录;同名前缀的普通文件仍按文件类型处理。

长时任务断点续跑

任务中心为本机执行的任务提供「暂停」「继续」「取消」。暂停保留当前任务和已保存结果;在途步骤尚未停稳时显示「正在暂停」。继续沿用原任务,取消则等待所属线程和子进程退出,再显示「已取消」,保留已完成结果并停止后续工作。父任务的操作覆盖全部后继,包括列表中未展开的任务。文件替换等提交步骤先完整提交,再响应控制请求。云下载在远端执行,操作以渠道实际支持的能力为准。

播放触发的文件头修复、发现页资料读取和诊断导出同样登记在任务中心。媒体子进程可暂停、继续和取消,暂停时长不计入处理超时。支持断点恢复的任务在重启后保留暂停意图;没有恢复入口的即时任务在服务关闭后结算,不留下无法继续的排队任务。

活动任务显示蓝色 CPU、紫色 GPU 与青色网络标签。CPU 百分比以执行端可用计算容量为 100%,计入已登记的工作线程与所属子进程;共享原生线程无法准确归属时不计入。macOS 按原生线程 ID 读取时间,Linux 与 Docker 同时考虑 CPU 亲和性和当前命名空间可见的 cgroup v1/v2 配额。无法读取容量时显示「未取得」。

逐任务 GPU 显示所属子进程最忙引擎的使用率。Windows 使用系统引擎计数器;Linux 使用驱动提供的 DRM fdinfo 引擎时间,Docker 需要映射 GPU 设备并允许读取任务进程信息。macOS、未提供 DRM 引擎时间的驱动、设备未映射、权限不足,以及共享 GPU 活动无法准确归属的情况显示「未取得」并说明原因。网络显示已观测的下载速度,挂载与 SMB 的缓存、预读以及未计量的外部请求显示「未取得」,不以零值代替。首次读取显示「采样中」。CPU 或 GPU 达到 50%、下载达到 10 MiB/s 时,同色标签加深,仅作显示提示。已取消的任务显示红色标签。

后台任务把任务标识、处理范围、完成集合和计数保存在本机。服务重启时接回同一条任务记录,继续未完成的部分。用户暂停的任务保持暂停;明确取消会撤销恢复。失败、限流或未取得的结果保留原有重试与冷却规则,不作为成功项目跳过。

扫描与采集的「取消任务」与任务中心的取消使用同一枚图标,确认后先显示正在取消,等当前在途步骤退出后结算。已登记影片、资料、预览和候选保留,取消的任务不会在重启后自动继续;数据管理页的扫描与采集卡片显示「已取消上次任务」,可以重新发起一趟任务。命令行发起的馆藏处理被取消时返回退出码 130。

任务还在运行时点击同步,卡片提示当前任务的发起方式,并说明要等它完成或取消。保存媒体库设置会重启 Peach:有扫描与采集任务在运行时先确认。在服务内运行的任务(网页、定时或启动时发起)随重启中断,重启后从中断处继续;已暂停的任务保持暂停;命令行或托盘发起的任务在独立进程中运行,不受重启影响。勾选「保存后扫描并补全资料」时,新的扫描排在当前任务之后。

日常使用「同步新增文件」:枚举目录发现尚未登记的文件,仅补全新增及待处理影片的资料和预览。已知路径跳过逐文件属性读取,不重复刮削已有影片;它仍需枚举目录,不能替代文件删除检查。「更多同步方式」分为日常同步和独立的「全库维护」,后者检查全部文件并复用已有资料和预览,可单独执行扫描、资料或预览步骤。

待补全数量汇总首次登记、尚未完成处理的视频,目录扫描、文件监控和云下载完成后的登记共用此集合;图片、附属文件和重复登记不计入。日常菜单的「补全待处理影片」只处理已登记的这一组。每趟范围保存到断点,后来入库的影片留到下一趟;失败项仍可从原任务定向重试。来源离线不等同于删除。

没有保存过推送发现设置时,本地文件监控默认开启,CloudDrive 通知需另行配置;已明确关闭的设置保留。监控使用系统文件事件和去抖队列,空闲时等待事件,不定期遍历媒体目录;网络盘不递归监控。未收到通知或服务停机期间新增的文件可由「同步新增文件」补齐。

推送发现登记了一部新影片、或云下载入库并整理完成时,打开着的 Peach 页面会弹一条 toast,点「打开」进入这部作品。通知随任务列表轮询读取,最多晚 10 秒。扫描、「同步新增文件」和批量补全登记的作品不弹;同番号有云下载任务的,等它整理完成再弹一次;一轮到了 3 部以上时合成一条。通知只在服务进程内存里,重启后不补弹。

本机移动事件和已记录的系统文件身份可保留改名、同卷移动后的影片 ID、人工资料和个人记录。文件身份随本地扫描和登记积累;升级前没有身份记录、停机时已经发生的移动,以及跨卷复制,不能仅凭同名或同大小自动认作原片。旧路径仍存在的副本与硬链接分别登记。改名时换了编码、文件身份对不上的影片,扫描按番号认回:同一媒体目录下这个番号的在库影片只有一部且旧文件已不在,新文件所在目录也只有这一部同番号视频,就沿用原记录与它的标签、封面和个人记录,时长与分辨率重新探测(ADR-0131)。

一趟任务的结论、「7 天内不再问」、问题清单和完整记录收在同一块提示里。结束的任务可在完整记录旁「导出完整问题清单」,下载包含全部分页记录的 JSON。导出期间任务或记录变化会停止导出,取消或失败不会下载半份文件;缺少原始问题记录时提示导出诊断日志。「归档」收起这块提示,完整记录和任务历史仍保留;归档后留一条可「撤销」的提示,刷新页面后不再显示。

任务 保存与恢复的单位
扫描文件 来源根、待遍历目录和目录内的已提交文件批次;保留文件数、字节数与字幕配对资料
读取配套资料、采集元数据与预览 已读取的本地证据、已写入的候选与已登记预览;保留完成影片和问题记录
拉取关注更新、历史回抓 固定来源集合、成功来源与已提交页码;从头回抓任务沿用本次保存的页码
新作订阅、想要资料、发现卡资料 已完成来源或番号、已保存资料与封面;发现卡同时保留已消耗请求与流量预算
后继任务、下载后处理 原有持久队列与同一条任务记录;批量资料与样张保存原始番号集合和成功项目
时间轴缩略图、媒体修复 已核验产物、带文件身份的检查结论与累计计数
链接检查、关注来源查找、口味读取 已完成链接、检索行或浏览器资料;保留结果和处理范围
文件整理与回滚 固定整理计划、同一批次的逐项日志与待回滚记录
资源检查、资源清理、链接清理 已完成来源、已处理记录与清理回执;删除前仍复核当前状态
amane 桥环境准备 uv 缓存和已安装依赖;中断的安装命令重新核对锁文件

检查点在结果成功保存后提交。中断时尚未提交的文件批次、来源页、单部影片或写入事务可以重做,已提交结果继续复用。外部请求本身无法从半个响应恢复。检查点损坏或结果文件未取得时会报告问题;此前没有保存的进度无法追溯恢复。

命令行扫描中断后,用相同来源和根目录再次运行即可接回断点;完整扫描结束会清除该断点,下一次扫描重新检查目录。scripts/scrape_codes.py 默认续跑同一批次,候选 CSV 和旁边的 .resume.json 一起保留;指定 --out 时沿用原输出路径。批次参数必须一致,--no-resume 用于开始新批次。其它探测、拼图和封面批处理继续按已保存的测量值、产物或成功日志选取待办。

媒体来源状态

服务在后台读取挂载目录的首个条目,空目录可读也算在线。正常来源每 600 秒检测,异常来源每 60 秒检测;首次失败隔一秒复查,连续两次失败才确认故障。提示分别说明没有权限读取、目录不存在、目标不是目录或目录读取失败。

/api/sources 返回周期快照和检测时间;正在检测或探测未返回时,online 为 null,页面保留来源可用状态。故障面板的「刷新状态」读取最新快照,后台按上述间隔重新探测。实际播放和扫描仍即时检查目录。/healthz 的 media_mounts 摘要与托盘显示来源名和故障原因;挂载故障不触发正常服务重启。探测线程最多四个,同一目录有未返回的探测时不重复启动。

媒体库与存储根目录

媒体库保存名称和图标,可以包含多个存储根目录。配置页与首次设置中的「目录所属媒体库」明确指定归属;名称相同的媒体库保持独立。修改同一库的名称或图标会同步到其全部目录,调整目录顺序不会改变身份。

media.library_catalog.<library_id> 和 media.storage_roots.<root_id> 持久保存身份。路径、挂载、来源及读取策略归根目录,名称与图标归媒体库。media.locations 等路径表是兼容投影,手动配置以身份表为准,字段与升级依据见 ADR-0115。

每个媒体库还可以设来源色和处理方式。来源色给这个库的卡片和列表行铺一层淡色,默认不上色。处理方式有三档:「自动补全」缺什么联网补什么;「仅使用本地资料」只读本地 NFO 和同目录图片,仍读取视频信息、生成九宫格,不联网补资料、封面和人物图片;「自定义」逐项选择步骤。配置里写作 color、policy(auto 不写)和自定义时的 stages,定时扫描、增量入库和重试都按作品所属媒体库遵守,依据见 ADR-0116。

路径配置首次保存时按原同名分组写入稳定身份,写入前把原文件留成 config.pre-media-identity.toml,以后的保存不覆盖它。也可用 scripts/upgrade_media_identity.py --data-root <数据根> 预演,核对后加 --apply 显式升级;脚本备份配置并原子写入,不打开 ledger。重复执行保留身份。真实配置升级按部署授权执行,先在隔离配置验证。

已有目录更换位置时,选择「重定位此目录,保留文件记录」;它保留账本前缀并更新本机挂载位置。选择「添加另一目录」创建独立根目录。移除目录声明保留文件及个人记录,文件删除仍使用各自的确认入口。目录重定位应指向同一批文件,不能用已有 ID 接管另一批内容。

每个根目录的离线状态按 root_id 返回。多目录媒体库中的一项目录离线,只影响该目录中的作品;来源筛选仅在所有根目录离线时禁用该来源。资源清理继续保留现有在线保护条件。

在 macOS 上对应 Windows 路径:[media.mounts]

在首次设置或配置页中添加媒体目录,填写这台设备能读取的目录,例如 macOS 的 /Volumes/Media、Linux 的 /mnt/media 或 Docker 容器内的 /media。Peach 自动保存数据库所需的路径配置。已有目录改位置时,修改这一行的媒体目录并选择重定位;内部路径的对应关系由 Peach 保留。

以下字段说明供手动编辑配置或在多台 Peach 之间对应已有媒体目录时参考。

Peach 数据库中每部影片的 path 字段都使用 Windows 格式,例如 R:\media\x,即使服务运行在 macOS 或 Linux 上。这个值是数据库里的字符串;本机没有对应盘符时,Peach 需要用以下两项配置找到实际文件。Docker 配置见 Docker 部署。

  • 两项使用相同的媒体来源键,例如 local、115。
  • [media.locations] local = 'R:\media' 表示数据库中的文件路径以 R:\media 开头,不要求 macOS 或 Linux 存在这个目录。
  • [media.mounts] local = '/Volumes/<卷名>/media' 表示本机实际读取的目录。数据库中的 R:\media\x 会转换成 /Volumes/<卷名>/media/x。
  • 一个来源有多个目录时,两项都写数组,目录数量和顺序必须相同。

Windows 的 [media.mounts] 可以留空,此时直接使用账本前缀;重定位目录时同样执行挂载映射。macOS 和 Linux 仍然使用两项配置;缺少对应实际目录时,该根目录显示离线,媒体记录保留,但无法读取文件。把 [media.locations] 的值改成 POSIX 路径不会同步修改已有影片记录,也无法替代这一步转换。媒体来源键写错或写成盘符时,配置会被拒绝。

临时诊断时可以用环境变量覆盖,例如 PEACH_MEDIA_MOUNTS=local=/mnt/res,115=/mnt/115。

两台电脑之间的复制

[replication] enabled 决定这台电脑是否参与两台电脑之间的数据库复制,默认 false。只有一台电脑时保持关闭即可,这时所有功能都可写,/healthz 的 ledger_sync 显示 disabled。开启后的行为见「维护者参考」里的「两台机器之间的同步」。

已在运行的电脑补写设置文件

已经在运行、但还没有设置文件的电脑,用 peach init --from-existing:

  • 它只写设置文件,不建数据库,也不动 peach-data/ 里已有的任何文件。
  • 它把当前实际生效的配置写进设置文件。推断不出的项(局域网 writer 地址、SMB 主机与账号)会留空并逐条打印出来,请用 --writer-origin、--smb-host、--smb-user 等参数在同一条命令里一次给全,不要事后手改。
  • --from-existing 写出的复制开关是 true,全新 init 写的是 false。
  • 用 init --from-existing --force 重写一份读不出来的设置文件时,它写的是内置默认值加环境变量,不继承旧文件的内容。命令会先打印这一点;旧文件里自定义过的 mDNS 名、writer 地址和 SMB 信息,要在同一条命令里重新给一遍。

不运行 --from-existing 就会使用内置默认值,至少这些会变:mDNS 名、macOS 的来源挂载表、reader 的 writer 地址与代理、SMB 主机与账号、复制开关(默认关)。Peach 数据目录、数据库路径、Windows 盘符和监听端口不变。

配置页

「网络与访问」显示本机地址、手机连接地址及可用的备用 IP 地址。地址协议来自实际服务;HTTPS 使用配置的名称地址。独立桌面部署可选择本机或局域网访问,并修改局域网名称;文件管理的部署按启动配置显示。勾选关闭访问密码时,新密码与确认输入框收起,保存时仍验证当前密码。

馆藏处理等待外部资料或封面较久时,卡片与常驻任务浮窗提供「跳过这部」。指令核对当前任务与资产,当前请求结束后在安全点继续下一部;已取得的结果保留,跳过项进入可重试清单。任务浮窗用关闭键隐藏,拖动不会收起;提示与操作在宽度足够时同行。

Peach 配置页地址是 /configuration。从管理菜单或设置弹窗的「Peach 配置」,或托盘菜单「配置 Peach」进入。页面分成「媒体库与入库」「来源与订阅」「下载渠道」「网络与访问」「应用与维护」五组。来源凭据、作品资料站点与资源搜索索引器放在「来源与订阅」,该分区也可进入采集来源与登录状态;本机端口放在「网络与访问」。

  • 只有在运行 Peach 的这台电脑上、并且服务由托盘管理时才能修改。其他设备的管理菜单里没有这一项,设置里会写明要去哪台电脑改。
  • 这台电脑可以用配置的 .local 名字、回环地址或服务绑定的 IP 打开配置页。Peach 按连接两端的 IP 判断是不是本机。
  • 「选择文件夹」会在运行 Peach 的这台电脑上弹出系统的文件夹选择框(Windows 资源管理器、macOS Finder),同样只对本机开放。
  • 保存后托盘会重新载入设置,本机服务会重启。
  • 源码部署的托盘服务保持固定的 HTTPS 地址和端口;Windows 测试包可以在配置页修改端口。

媒体修复在「数据管理」页,订阅源在「关注管理」页的「订阅源」页签(分工见 ADR-0050)。

扫描与采集逐项保留结果。文件抽帧失败、资料请求超时等单项问题记入清单,继续处理其余文件与后续阶段;所有阶段结束后,有问题的任务显示「处理已结束,部分项目需处理」,可查看全部内容或仅重试未完成项。状态保存、数据库等公共环节异常导致的中断单独显示。未取得发行资料的视频仍可在「全部内容」浏览;JAV 分类按番号和发行资料筛选。需要选择处理范围时,使用「更多同步方式」中的仅扫描、仅补资料或仅补预览图。

同一 Windows 规范路径存在多条历史记录时,扫描在问题清单中列出路径和记录编号,其他文件继续入库。冲突记录的身份、资料、个人记录和处置状态分别保留;枚举确认文件仍在时只刷新这些记录的观测时间。自动发现可登记同目录的其他文件,直接登记冲突文件则报告具体冲突。重复记录需复核,重新扫描不会自动合并或删除它们。

媒体目录、NFO 与配套图片的单次读取限时 20 秒,超时会结束读取子进程并记录问题;本趟任务不反复读取已失败的目录。单个视频的九宫格共用 120 秒处理时限,失败后继续下一部影片与外部资料采集。用户暂停、磁盘空间不足、账本或结果保存失败会中断任务并保留检查点。未登记成功的目录需要重新扫描;已登记影片的问题可按清单重试。

文件在磁盘上被移除后,可到数据管理页下方的「资源同步」检查账本记录。该分区要求至少一个可扫描来源配置了根目录;清理前核对检查结果并确认。带个人记录的失联作品保留为已消失,其余清理规则见资源同步的确认说明。

采集预估同时显示资料与预览产物的预计新增磁盘占用、临时文件峰值,以及各输出盘的可用空间。封面按番号去重,资料快照和九宫格按待执行范围估算;缓存命中和已完成工作不重复计入。占用依据本地缓存大小中位数估算,没有样本时使用计划值。各盘分别保留 1 GiB 运行余量,空间不足显示差额;容量读取失败显示未取得。网盘挂载缓存与预读无法准确测量时单独提示,不能据此认定网盘缓存也可容纳。

应用资料采集器每次会话最多 6,000 次请求、1 GiB 下载和 4 小时,另有来源限速、冷却及单项截止时间。应用采集流水线运行期检查数据盘 1 GiB 底线;独立封面、探测和九宫格脚本采用各自的磁盘参数,封面与九宫格默认 40 GiB。流量和磁盘预估本身不改变这些限制。

右下角的扫描与采集进度浮窗可收起详情,也可点「隐藏任务提示」关闭;隐藏后后台任务继续执行。当前页签会记住这趟任务的隐藏选择,刷新、换页及暂停后继续均保持隐藏。在「管理 → 数据管理 → 扫描与采集」卡片点击「显示进度浮窗」即可恢复。新任务自动显示,隐藏期间任务完成仍有一次完成提示;失败详情保留在数据管理页。

「扫描与采集」启动前按待处理项显示流量约值;运行中的任务面显示已用流量与预计总流量,可展开查看带网盘图标的各盘明细。资料下载按番号去重,扣除已齐全的字段、可用封面、有效缓存和来源近期确认无结果的请求,并采用现有 HTTP 下载预算;外部采集器另行估算。配套文件检查完毕后,按实际取得的字段和核查范围更新预估,完成的工作从待下载量中扣除。网盘读取按对应 CloudDrive 账号的数据代理配置分别汇总;跟随系统或尚未匹配账号的目录单独保留连接状态,不计入已确认代理合计。“代理保护”限制自动读取视频,不决定网盘的连接方式。本地磁盘读取不计入网络流量;资料站下载按来源连接设置另列。挂载读取量受缓存和预读影响,浏览器与外部采集器的流量也无法完整统计,读数作估算参考。新目录尚未登记的文件在扫描后更新预估,暂停和应用重启保留同一任务的累计值。

媒体库设置中的「CloudDrive 代理」只显示已添加媒体库对应的账号,按精确挂载点或推送路径前缀绑定;多个媒体库共用同一账号时放在同组。API 代理用于列目录和查询文件信息,数据代理用于读取视频及配套文件。先在下载设置中保存 CloudDrive2 地址与 API 令牌;令牌需要“查看云盘”权限,保存还需要“修改云盘”权限,自动识别挂载点需要“查看挂载点”权限。页面进入、重新聚焦和点击「重新读取」时取得 CD 当前配置;有未保存编辑时,聚焦不覆盖表单。保存会立即写入 CloudDrive 并读回确认,影响该账号的其他消费者。代理密码不回显,留空保留,勾选后可清除。保存前检查整个账号配置的修订号;官方接口没有原子条件写入,其他客户端恰好在检查与保存之间修改仍有竞争窗口。请求超时或回读失败时,先重新读取核对,不自动重发。HTTP/SOCKS5 表示配置了代理入口,具体节点计费仍取决于代理工具的规则和 TUN。更多接口的适用性见 CloudDrive 官方 API 接入。

启动弹窗同时显示视频文件数、文件名或已有资料可识别的 JAV 文件数与去重后的部数。尚无登记视频的目录分批列出,只识别名称、不打开媒体内容、不写入账本;统计过程中可直接开始扫描,关闭弹窗后不再请求后续批次。新任务沿用同进程 5 分钟内该范围的预检结果,随后用实际扫描更新;账本中已有的记录优先。首次网盘预检的耗时取决于挂载工具列目录的速度;文件名没有番号的 JAV 要在读取配套资料后补充识别。明细里的每部平均预估只针对本次待补资料,缓存齐全的影片不进入这个均值。右下「管理媒体库」链接关闭弹窗并进入媒体库设置,可在那里调整各目录的读取选项。

文件名不必只写番号。番号后面跟片名、女优或字幕说明(CAWD-987 片名、GVH-520【中文字幕】片名)时,取文件名里第一段「厂牌-至少三位序号」;FC2 商品号(+++ FC2-PPV-1234567 片名 前編)写在文件名任意位置都能识别。内置规则认不出的命名,在「媒体库与入库 → 番号识别规则」里每行写一条正则表达式:对完整文件名搜索、不分大小写,番号写在命名组 (?<code>…) 里,没有命名组时取第一个括号;取出的部分仍须符合番号格式。规则保存在账本里,各设备共用,保存时检查语法。「处理」时对还没有番号的视频先按这些规则识别,再按内置规则识别;已有番号不会被改写。启动弹窗的预检只按内置规则统计。

本机的 state/library-processing-traffic.json 保存近期同类用量。视频探测和单帧读取按媒体目录分开积累;资料采集按待访问来源、封面需求和直连/代理分组。至少取得 3 个有效样本后采用最近 50 次的平均值,后续同类工作随之校准;失败、零下载及计量不完整的资料采集不作为正常样本。首次使用无历史时仍采用默认计划值。

常用的本机设置:

  • 「通用 → 开机自启」:开机后启动 Peach、静默启动(开机后只显示托盘图标,不打开网页)、在桌面创建快捷方式。
  • 「网络与访问 → Peach 代理」:选系统代理、直连或自定义地址。默认外网 HTTP 请求与采集来源选「Peach 代理」时共用这里的设置,来源选「直接连接」则使用直连。保存后新建客户端按新设置运行,已有任务与长连接沿用创建时的配置。覆盖范围及本机、网盘和独立工具边界见来源连接设置。

CloudDrive 配置

115 和 PikPak 网盘由 CloudDrive2 挂成本机的盘,Peach 把它当普通文件夹读取。挂载步骤、来源 ID、macOS 上的路径对应、缓存与读取设置,以及新文件自动入库,都在 CloudDrive 配置与调优。配置页里的「CloudDrive 缓存建议」是它的摘要。

存储空间与迁移数据目录

配置页「应用与维护 → 存储空间」列出数据目录、所在磁盘的剩余空间,以及「统计占用」后各类数据的大小。统计在后台进行,几十 GB 的数据目录要一两分钟,进度条按上次统计的文件数估算。统计结果是一张环形图(各类占比)、一根磁盘占用条(Peach、其他文件、可用)和逐类列表,每类都写明是什么、能否清理以及原因。

可以清理的几类行首有勾选框,勾选后点「清理所选」,或点「全部清理」:

类别 清理什么 之后
数据库备份 database/ 与 generated/organize-backups/ 里的 ledger.pre-*.db,每处保留最近一份 无法恢复,当前数据库校验不通过时拒绝清理
播放缓存 generated/transcodes/ 里的整片转码与 generated/stream-segments/ 再次播放时重新生成;重建的文件头(.mp4hdr)保留
缩略图 generated/cover-thumbs/ 与 generated/avatar-thumbs/ 浏览时重新生成
日志 logs/ 里已归档的 *.until-*.log 与 crash-*.log 正在写入的日志保留

缩略图是封面与头像的小尺寸副本,由本机已有的原图缩小而来;预览图是从视频抽帧生成的九宫格、海报与进度条预览,重建要重新读取整部影片,网盘里的影片会重新下载,所以只统计不清理。封面与网络资料要重新联网下载,导入资料、任务与复核记录、媒体工具和登录状态都无法由 Peach 重建,同样只统计不清理。

「更改位置」把整个数据目录迁到别的文件夹。安装版、从托盘启动的源码运行(Windows、macOS)和无桌面服务(python -m peach.server)都支持:

  1. 先统计占用,再选一个空文件夹(或新建一个)。不能选磁盘根目录、程序目录、媒体目录,或与当前数据目录互相包含的位置;跨磁盘迁移时,目标磁盘要比数据目录多出 1 GB 余量。
  2. 确认后 Peach 暂停后台任务、停止服务并退出托盘;无桌面服务只停网页服务,看守进程留着做迁移。同一磁盘内直接改名;跨磁盘时 Windows 用资源管理器的复制(带进度和取消),macOS 逐个复制,复制完逐项核对文件数与大小。
  3. 数据库里指向数据目录的预览图与追更证据路径改到新位置;默认位置与原位置各留一份 state/data-root.txt 指向新位置,开机自启与桌面图标按新位置重写。
  4. Peach 在新位置重新打开(无桌面服务在新位置重新拉起网页服务),原位置的数据随后删除。暂停的任务自动继续。

任一步失败都留在原位置继续使用,原因显示在「存储空间」里;跨磁盘复制失败时,新位置已复制的部分会删掉。原位置有文件删不掉时会列出路径,确认新位置正常后手动删除。

源码运行时,默认位置是项目旁边的 peach-data;原位置留下的 state/data-root.txt 让默认位置和显式的 PEACH_DATA_ROOT 都跟到新位置。直接运行 peach serve 时没有看守进程接手,不能在设置页迁移:改用托盘或无桌面服务启动,或退出 Peach,手动移动数据目录,再把 PEACH_DATA_ROOT 指向新位置。

账本备份与恢复

配置页「应用与维护 → 账本备份」列出 database/ 与 generated/organize-backups/ 里所有能恢复的备份,新的在前,每行写明时间、来源(手动,或自动及其用途)和大小。取舍见 ADR-0138。

  • 立即备份:后台复制当前账本,进度同时显示在任务中心。复制完先做完整性检查,通过才命名为 ledger.pre-manual-<时间>.db;没通过的那份直接删掉。手动备份和自动备份同一套保留规则(见「迁移、备份与运维脚本」)。
  • 从备份恢复:只能在写入端执行,且数据目录里没有别的任务在跑。确认后依次检查备份的完整性和结构(来自更新版本的备份拒收,较旧的先迁到当前结构),把当前账本另存为 ledger.pre-restore-<时间>.db,再把备份写进账本。恢复期间不能启动新任务;任务中心的历史保留恢复前的记录。完成后刷新页面查看恢复后的资料。
  • 中断处理:写入账本前会在账本目录留下 ledger.restore.json。恢复被打断(断电、强制结束)后,下次启动服务或运行 peach migrate upgrade 时先处理它:当前账本完整就保留;不完整就用已经迁好的暂存 ledger.restore-staging.db 补完恢复;暂存也不能用就退回恢复前另存的那份。结果显示在「账本备份」里,同时写入 ledger.restore-result.json。
  • 账本损坏、服务读不出资料时,「账本备份」照常可用,恢复在后台进行,进度只在这一页显示。

容器的数据目录是宿主机挂载的卷,在容器里迁移会离开卷,重建容器时数据丢失,所以设置页不提供迁移,改为列出在宿主机上迁移的步骤和命令,见 Docker 部署。

卸载

Windows 测试包在 Peach 配置「应用与维护 → 卸载 Peach」里卸载:

  1. 先选择范围。默认保留数据;勾选「完全卸载」会同时删除设置、本地数据库、观看记录、凭据和缓存。
  2. 确认后,Peach 会退出托盘、关闭自己的服务、结束仍在程序目录里运行的残留进程,再移除开机自启和整个程序目录。删除会重试三次,仍失败才报错。

哪些会保留:

  • 原始媒体文件,任何情况下都保留。
  • 手工复制的 config.toml.bak 和其他 Peach 不认识的文件。
  • 完全卸载删除的是设置文件、Peach 自己生成的设置备份(config.previous.toml、config.pre-media-identity.toml,以及 config.toml.<说明>-<日期>-<时刻> 形式的备份)和列出的数据库、缓存、凭据等目录。数据目录放在别处、用了目录链接,或者和媒体目录重叠时,需要自己手动检查和清理。

文件被占用而删除失败时,弹窗会给出日志位置:临时目录里的 peach-uninstall.log,里面写着原因和失败的路径。

源码安装不能自动卸载:先在配置页关闭开机自启、退出托盘,再按页面列出的路径手动删除。Git 工作区不会被自动删除。

健康检查

/healthz 用来确认服务是否在运行:

  • 不带参数时报告服务存活,并提供数据库、迁移、配置、工具、挂载与访问安全的分项状态;挂载异常属于警告,服务仍返回 200。
  • /healthz?ready=1 还会检查配置、页面、数据库查询和数据库迁移校验,没准备好时返回 503。
  • 返回内容里的 configured 表示这台电脑有没有设置文件,ledger_sync 表示这台电脑在两机复制里的角色(writer、reader 或 disabled)。

源码部署的托盘(Windows,以及配置了 TLS 的 macOS)同时运行一个 HTTP 服务和一个 HTTPS 服务。HTTP 那个只负责把浏览器引到 HTTPS 地址,所以 HTTP 口的 /healthz 正常只能说明它自己活着。

托盘菜单的状态行会逐个列出每个服务,例如 HTTP 正常 · HTTPS 异常(状态码 503),异常时附上最近一次失败的原因。

本机诊断

托盘「导出诊断报告」和系统诊断页「下载诊断报告」提供脱敏 ZIP。Windows 托盘导出完成后可打开目录、打开文件或关闭窗口,macOS 菜单栏导出后在访达中选中报告;启动失败时,弹窗给出自动保存的报告位置。报告包含版本、系统信息、选定日志的末尾和可取得的系统检查;配置文件、凭据、Peach 数据库和媒体不进入报告。日志中的网址、本机路径、IP、邮箱和常见凭据字段会脱敏,发送前仍应检查报告内容。

独立包支持 Peach.exe --diagnostic-report,无需启动服务即可保存报告;指定目标文件时放在该参数后,已有文件不会覆盖。源码环境可用 python -m peach.support_bundle 取得同类报告。默认报告与错误日志保存在数据目录的 logs,目录不可写时使用系统临时目录下的 Peach/logs。

主线程、后台线程、未处理协程和本机浏览器错误写入 errors-<PID>.log;Python 可捕获的原生崩溃栈写入 crash-<PID>.log。Windows 独立启动失败的记录包含失败 API 名称和系统错误码。操作系统在 Python 启动前阻止程序、进程被直接终止或磁盘完全不可写时,程序自身可能无法留证,应保留系统提示和完整弹窗。

本机下载接口为 /api/diagnostics/bundle,需通过现有登录检查;浏览器错误接口 /api/diagnostics/client-error 仅接受本机同源请求,支持首启与登录页,每分钟最多记录 20 次,每次请求最多 16 KiB。

在安装 Peach 的电脑上运行 peach doctor,逐项查看版本、配置、Peach 数据库迁移、工具路径、数据目录写入、媒体挂载、端口和最近一次任务失败。peach doctor --json 输出同一份脱敏报告,供本机诊断 API /api/diagnostics 使用。

Peach 配置「应用与维护 → 运行信息」可打开 /diagnostics。库健康提供识别失败、补资料失败、缺封面、缺时长计数,展开后可打开作品、复制当前清单。每类最多返回 500 条,保留总数;没有番号的作品使用编号。失败来自最近处理任务的问题记录,暂停与未命中记录不计为失败;记录损坏时显示未取得。

minnano-av 与 javdb 使用实际解析并核对身份后落库的记录,显示上次成功时间与冷却截止。一天内有成功证据且未在冷却时显示正常;旧记录保留时间,当前状态为未取得。打开诊断不发起来源抓取。

独立包默认诊断配置端口;源码环境有完整 TLS 材料时诊断托盘的 HTTPS 入口(Windows 443、macOS 8443)。直接启动服务时,可用 --host 与 --port 指定实际监听地址。

failed 表示需要处理,命令退出码为 1;warning 或 unknown 保留具体原因,退出码为 0。诊断只在数据目录创建并清理临时写入探针,不执行迁移或修复。端口正在使用时只报告占用状态,进程归属需另行核对。公开 /healthz 只提供状态与原因,完整工具路径只在本机诊断中显示。

访问地址、密码与证书

从哪个地址打开

  • Windows 测试包:选「只有这台电脑」时打开 http://127.0.0.1:<端口>;选「同一局域网的设备」时,其他设备打开 http://<mdns_name>.local:<端口>。测试包用 HTTP,不加密。
  • 源码部署:托盘在 80 端口提供 HTTP、在本机局域网 IPv4 地址的 443 端口提供 HTTPS,浏览器打开 https://<mdns_name>.local。局域网地址默认自动选择,也可以用启动参数或 PEACH_LAN_ADDRESS 指定。

<mdns_name> 是设置文件 [server].mdns_name 的值,Peach 会在局域网里广播这个名字。

访问密码与登录

  • 访问密码在首次设置页或配置页「网络与访问 → 访问密码」里设置,可以留空。留空时,能连到 Peach 的设备不用登录就能进入。终端 peach init 默认不设访问密码。
  • 已有部署如果没有访问密码设置,登录页继续使用访问口令。已登录的本机浏览器可以在配置页设置自己的密码,或明确关闭登录要求。
  • 修改密码需要当前密码;关闭密码还要勾选确认访问范围。修改或关闭立即生效,其他浏览器的登录会失效,当前设备保持登录 30 天。
  • 登录页勾选「保持登录」保持 30 天;不勾选只在这次浏览器会话内有效,最长 12 小时。刷新页面不会延长有效期。
  • 配置页「网络与访问 → 已登录的设备」列出每个登录过的浏览器:浏览器与系统、来源网段、最近活动,当前浏览器标为「本机」。在运行 Peach 的电脑上可以撤销其中一台,或撤销本机以外的全部;修改或关闭密码仍会让全部设备退出。
  • 密码以 scrypt 哈希保存在本机 <Peach 数据目录>/secrets/access.json,设备记录在同目录的 browser-sessions.json,只存登录令牌的摘要,不存令牌本身和完整 IP。两者都不进数据库,也不参与同步。
  • 升级前登录、仍在有效期内的浏览器不会被登出:它下一次访问时补进设备列表,此后同样可以撤销。

安全模型的完整说明见 安全说明。

访问口令

脚本和 API 调用使用访问口令,放在 X-Token 请求头里。

  • 非回环地址上启动服务必须有访问口令,首次初始化会自动生成。
  • 口令保存在 <Peach 数据目录>/secrets/auth-token,终端运行 peach token 查看。
  • 在运行 Peach 的电脑上打开配置页「网络与访问 → 访问口令」,点「更换口令」,新口令立即生效,不用重启。新口令只在页面上显示这一次,之后用 peach token 查看。终端运行 peach token --rotate 也能换,但要重启服务才生效。
  • 口令由启动参数 --token 或环境变量 PEACH_TOKEN 指定时,配置页不能换,要改启动配置。
  • 换口令后,旧口令、脚本、API 调用和 ?t= 链接立即失效。设了访问密码时,用密码登录的浏览器不受影响;没设访问密码、登录页认口令的部署,其他浏览器全部退出,要用新口令重新登录,当前浏览器保持登录。修改访问密码不影响访问口令。
  • 开启两台电脑之间的复制时,换完口令要把口令文件复制到另一台。
  • 登录由 /login 表单换成 HttpOnly cookie。?t=<口令> 查询参数只在一次性场合用,它会把口令留在访问日志和浏览历史里。

让其他设备信任 HTTPS 证书

源码部署用本机自签的 CA 签发 HTTPS 证书(.local 名字无法使用 Let's Encrypt 这类公开证书)。证书和私钥都在本机 <Peach 数据目录>/secrets/tls/。

托盘启动或本机地址变化时检查叶子证书的覆盖范围、到期时间及颁发者密钥标识(AKI)。缺少 AKI 的存量叶子会使用原 CA 补签并保留备份,已安装的 CA 信任继续有效,无需手动重建 CA 或重装信任;符合条件的叶子不会重复补签。运行期和 TLS 设置脚本均显式签入 SKI、AKI,以满足严格 TLS 校验。

在运行 Peach 的电脑上打开配置页「网络与访问 → 其他设备信任 HTTPS 证书」,那里有 CA 证书的 SHA-256 指纹、到期日、下载按钮和手机扫码用的二维码。下载的只有 peach-local-ca.crt 的公开部分,不含任何私钥。

  1. 取得证书:
    • 手机、平板:用相机扫二维码直接下载,不用先登录。二维码 10 分钟内有效,页面开着时会自动更新;Peach 重启后旧二维码作废。
    • 电脑:点「下载证书」,或复制 peach-local-ca.crt 这一个文件。
  2. 在设备上安装并信任它:
    • iPhone/iPad:用 Safari 打开,允许下载描述文件,到「设置 → 通用 → VPN 与设备管理」安装,再到「设置 → 通用 → 关于本机 → 证书信任设置」打开完全信任。
    • Android:到「设置 → 安全 → 加密与凭据 → 安装证书 → CA 证书」选择下载的文件,菜单名称因厂商而异。
    • Windows 双击文件,安装到「受信任的根证书颁发机构」;macOS 在「钥匙串访问」里设为「始终信任」。
  3. 在设备的证书详情里核对 SHA-256 指纹,要与配置页显示的一致。在电脑上也可以用 openssl x509 -noout -fingerprint -sha256 -in peach-local-ca.crt 核对。

Android 浏览器常常打不开 .local 地址。这时在运行 Peach 的电脑上改用局域网 IP 打开配置页,二维码会换成 IP 地址。

每台运行 Peach 的电脑有自己独立的 CA。换了一台电脑提供服务,设备上要装那台电脑的 peach-local-ca.crt。

Windows 上 TLS 私钥禁用了权限继承,只允许实际运行服务的账户、SYSTEM 和 Administrators 读取。

macOS 打不开 .local 地址

浏览器打开 .local 地址返回 503、终端直连却正常时,通常是系统代理把请求截走了:代理解析不了 mDNS 名字。

在 macOS 系统代理的例外列表里加上 *.local、localhost、127.0.0.1 和本机局域网网段:

  • 设置:networksetup -setproxybypassdomains
  • 检查:scutil --proxy 输出里的 ExceptionsList

代理客户端重新设置系统代理后,这个列表可能被清空,需要再加一次。

从外网访问:Cloudflare 公网入口

配置页「网络与访问」里的「Cloudflare 公网入口」默认关闭。必须先设置访问密码才能启动;没有密码时它会被停掉并保持关闭。

临时链接

  1. 设好访问密码后,点「启动公网入口」。
  2. 页面显示 cloudflared 生成的随机地址 https://<id>.trycloudflare.com,用它访问。https://try.cloudflare.com/ 只是介绍页。
  3. 停止公网入口或退出 Peach 后,这个地址失效;下次启动会换一个新地址。

需要注意:

  • 这只适合临时预览,不是稳定域名,也没有团队账号或 Cloudflare Access 这一层。
  • 随机地址只保存在数据目录的状态文件里。不要把它存进书签、文档或公开配置。
  • cloudflared 需要能出站访问 TCP/UDP 7844 端口。被防火墙或代理挡住时页面会显示失败;已经显示了随机地址,不代表连接已经成功。
  • Windows 测试包自带经过 SHA-256 校验的 cloudflared.exe。源码运行需要自己安装官方 cloudflared,Peach 按设置文件的 tunnel.binary、环境变量 PEACH_CLOUDFLARED、PATH 的顺序查找。
  • 源码部署时,Cloudflare 连的是本机实际的 HTTPS 服务,并带上项目 CA 和 mDNS 名字做校验;测试包连的是本机回环的 HTTP 端口。

命名隧道(仅源码部署)

命名隧道的地址固定,重启后不变。Windows 测试包不支持这种方式,配置页也不会显示这一块。

  1. 在 Cloudflare Zero Trust 的 Networks → Tunnels 里新建一条 Cloudflared 隧道,复制它的隧道令牌(Token)。
  2. 给这条隧道加一个 Public hostname,主机名用自己的域名。Service 填本机的 HTTPS 地址:源码部署是 https://<局域网 IP>:443(macOS 按实际 TLS 端口)。再在 Additional settings 里把 Origin Server Name 填成 <mdns_name>.local,并把项目 CA 填进 CA Pool,否则本机自签证书过不了校验。
  3. 在配置页「Cloudflare 公网入口」里切到「命名隧道」,填公开主机名和隧道令牌,点「保存配置」。令牌只写进设置文件的 [tunnel] token,页面不会再显示它,数据库、日志和 /healthz 里也没有它。换令牌时填新的;留空表示沿用已保存的那一份。
  4. 建议在 Cloudflare Access 里给这个主机名配一条身份策略。这一层完全在 Cloudflare 后台配置,Peach 不读取也不管理;Peach 自己的访问密码仍然是启动隧道的前提,两道门同时存在。

整个站点都拒绝搜索引擎收录:每个响应都带 X-Robots-Tag: noindex, nofollow, noarchive,/robots.txt 不用登录也能读到 Disallow: /,主页面和登录页另有 <meta name="robots">。这一项不能关闭。

播放与转码

浏览器能直接播放的格式(例如常见的 MP4)不需要额外软件。Windows 安装版和绿色版携带 FFmpeg、ffprobe 与修复损坏 MP4 索引用的 untrunc。源码部署缺少这些工具时,Windows x64 可在配置页「应用与维护」→「运行信息」点「安装」:Peach 从最新发布下载同一份 tools-ffmpeg.zip 或 tools-untrunc.zip,经 Peach 代理设置出网,按发布摘要校验整包、按包内清单校验每个文件,再解压到数据目录的 tools/ffmpeg、tools/untrunc,装好后那一行显示版本。下载中断或校验不符时已有文件不变,再点一次即重新下载;已装且校验相符时不重复下载。macOS 与 Linux 没有发布的工具包(macOS 应用与 Docker 镜像自带工具),源码部署仍按页面上的官方下载入口自行安装,或加入 PATH。首次设置缺少 OpenSSL 时也会给出下载入口。

Peach 按下面的顺序找 FFmpeg 和 ffprobe:

  1. 显式设置的环境变量。
  2. Windows 独立程序目录下的 tools/ffmpeg/bin,或 macOS 应用的 Contents/Resources/tools/ffmpeg/bin。
  3. 数据目录下的 tools/ffmpeg/bin。
  4. PATH。

untrunc 按相同顺序查找,对应目录为 tools/untrunc。独立程序优先使用随包验证的版本;环境变量仍可显式指定工具路径。

人脸检出(YuNet)与比对(SFace)模型随 Windows 完整安装包、完整免安装 ZIP、macOS 应用和 Docker 镜像分发,离线即可用。Peach 先读 PEACH_FACE_MODELS 指向的目录(Docker 镜像设为 /app/tools/face-models),再读独立程序的 tools/face-models,两处都按 SHA-256 校验;不在或校验不符时改用数据目录 tools/yunet、tools/sface 里的那份,再没有才联网下载。随包那份不会复制到数据目录。轻量安装包和应用更新包不带模型,由安装器或更新器按需下载 tools-face-models.zip。

播放时:

  • 浏览器不支持的 AVI、MKV 等格式,Peach 会转成兼容的 MP4 缓存起来再播放,不会改动原始文件。第一次播放前会先探测文件,最长 20 秒。
  • 能保留的码流尽量保留:H.264(yuv420p/yuvj420p)视频不重新编码,AAC 音频直接复制,其他音频转成 AAC。需要重新编码视频时,自动模式依次尝试硬解加硬编、软解加硬编、全软件;Windows 使用 NVIDIA(scale_cuda + NVENC),Linux 使用可用 VAAPI 节点,macOS 使用 VideoToolbox。macOS 硬件编码通过实际合成帧探测,并禁止系统软件编码冒充硬件;H.264 输出采用 6 Mbit/s。AV1 硬解显式使用 FFmpeg 原生 av1 解码器,设备不支持时回退 dav1d 软件解码。
  • 同时最多进行 2 个转码或探测,单次最长 1 小时,关掉播放页会取消对应的任务。
  • 115 和 PikPak 的视频通过媒体库配置中声明的挂载目录播放。能不能播,以在 Peach 里实际打开一个已知视频为准。

Peach 配置「媒体库与入库 → 视频预览」中的「抽帧解码方式」与「应用与维护 → 视频播放」中的「转码方式」分别保存为运行 Peach 那台电脑的偏好,两者互不影响,均可选择「自动(硬件优先)」或软件。抽帧设置控制封面、九宫格与时间轴;扫描、读 NFO 和时长探测不依赖 GPU。播放设置只控制 Peach 服务端的整片与 HLS 转码,浏览器直接播放时自行选择解码方式。保存无需重启,对新任务生效;已生成的有效缓存继续使用,运行中的 FFmpeg 不被强行中断。macOS 抽帧在同一超时预算内尝试 VideoToolbox,Windows 抽帧对 H.264、HEVC、VP9、AV1 尝试 D3D11VA,Linux 对同一范围尝试第一个可用 VAAPI 渲染节点,失败后都回退软件;视频编码格式探测按文件大小和修改时间缓存。Windows 播放的自动档依次探测 NVENC、AMF、QSV 编码,三者都不可用时用 D3D11VA 解码再交给 libx264;AMF 只接受 AMD 显卡上的 D3D11 设备,Peach 按显卡序号逐个探测。偏好通过 /api/media-processing 的 GET/POST 读写,preview_acceleration 和 playback_acceleration 分别接受 auto/software;省略的字段保持现值。这个接口与时间轴缩略图的 /api/thumbnail-jobs 和 /api/configuration/* 一样只接受运行 Peach 的电脑发来的请求,其他设备即使已登录或处于开放访问也返回 403。PEACH_TRANSCODE_BACKEND 可用于管理员诊断,支持 auto/software/nvenc/amf/qsv/vaapi/videotoolbox,显式 software 会保持禁用硬件。

卡片悬停预览请求的 /stream 不带流会话,取消不了,也看不到浏览器断开。片源需要整片转码且没有现成缓存时,这条请求直接回 415,不启动 FFmpeg;详情与沉浸模式带会话播放,关闭时按会话结束转码。

播放器进度条可以复用视频旁的 Jellyfin Trickplay、Emby/Roku/Plex 导出的 BIF、WebVTT 图片索引、HLS 和 DASH 图片轨。已有产物只读,时间轴采集遇到可用预览会跳过。命名、读取范围和缺少时间索引时的处理见已有时间轴预览。

文件整理

在「数据管理 → 整理」选择来源。右侧路径框可直接输入目录,旁边的文件夹按钮在运行 Peach 的电脑上打开目录选择窗口;远程访问或系统选择窗口不可用时,直接输入路径。路径留空表示整个来源,指定目录时包含其子目录。路径须属于所选来源;切换来源会清空路径。

整理会清除文件名中的装饰符号、emoji、替代字符 �、私用区字符和不可见噪声,保留正常文字、常用标点、单位、序号和扩展名。不能形成有效名称的条目保留原名;整段乱码文字不猜测还原。两份模板都留空时只清理名称,填写模板时同时按模板改名或归入目录。目录模板以指定路径为起点,路径留空时以来源根为起点。

先点「预览」核对范围和逐文件变化,再确认执行。修改路径、来源或模板后须重新预览。目标已存在的条目跳过,已执行批次可用「回滚上一批」恢复名称、位置和账本路径。PikPak 界面仅提供预览,改名仍需官方核验通道。

PikPak 官方核验通道使用「推送发现」中该媒体根对应的唯一 CloudDrive 路径前缀,支持自定义盘符与子目录。缺少映射或同一媒体根对应多条映射时拒绝执行。WebDAV 账号根由 CloudDrive 返回,认证直链须匹配 PikPak 官方域名和账号内路径;每批操作限于样本所属的媒体根。

资源同步与删除

哪些操作会删除文件、哪些不会,请在动手前看清楚。

资源同步

在 CloudDrive2 或文件管理器里整理过网盘目录之后,要在「管理 → 资源同步」里手动对账一次。Peach 不会在后台悄悄删除任何记录。

  • 对账分两步:先「检查文件」,再「清理失效条目」。检查只读盘、不改任何东西,每个来源报出文件已不在盘上的记录、空文件夹和读不了的目录,另外报出不再被引用的缓存。
  • 对账会核对已配置的本地和网盘来源。离线的来源整个跳过;某个目录读不了时,保留它的记录并在结果里报告。
  • 馆藏很大时扫描要很久,所以它作为后台任务运行,并逐个来源报告进度。
  • 确认清理后,文件已不在盘上的记录分两档。 在库条目里带个人记录(喜欢、打分、稍后看、播放列表、观看历史、寻找更好版本)的标「已消失」并保留,新版本入库时按位置、番号或「创作者 + 文件名 + 时长」接回这些记录;其余的永久删除,含回收站里的,不进回收站,无法恢复。 检查报告分开报两档计数,确认框写明哪一档不可撤销(ADR-0087)。删除前逐条重新确认文件确实不在,文件又出现了的记录保留并在结果里列出。
  • 数据管理页的「文件已丢失的记录」列表列出全部已消失条目和它们带的个人记录,可以手动接到某个文件,也可以彻底删除;彻底删除不可撤销。
  • 清理只认最近一次检查的结果:之后又检查过一次,或者服务重启过,就要重新检查。
  • 空文件夹自底向上删除,每个来源的根目录保留;CloudDrive 上列不出内容的空目录同样算空。
  • 对账只清理没有馆藏再引用的生成文件:快照、海报、照片缩略图、转码缓存、播放分段、按文件生成的头像,以及共享的番号封面。演员等资料的头像和 Logo、采集证据、复核用的 CSV 不在自动清理范围内。
  • 只清理当前数据库所在数据目录里的缓存,范围之外的一律跳过。
  • 每次清理在任务中心留下一条「资源同步清理」记录。
  • 条目详情里的「同步删除」只核对这一个目录:缺失的记录里带个人记录的标为已消失,其余移入回收站,两档都能在 8 秒内撤销。

回收站

  • 移入回收站的条目可以在回收站里「还原」。
  • 在回收站里「彻底删除」选中项,或者「清空回收站」,都会永久删除媒体文件和对应的馆藏记录,无法恢复。
  • rclone FUSE 挂载上的媒体会直接删除,避免部分后端的远端改名退化为复制。若媒体已删但账本事务失败,回收站记录会保留;再次清空可移除这条残留记录,无法回滚已完成的远端文件删除。
  • 飞牛 OS 文件管理器的原生 115 远程挂载可在 Linux 挂载表中表现为 fuse.rclone;此时适用上述行为。这里的 rclone 是该环境的底层文件系统类型,不表示用户另外部署了 rclone、CloudDrive2 或 OpenList,也不代表其他挂载方式已经验证。

垃圾文件

「垃圾文件」复核覆盖已配置物理媒体来源的各种文件类型,在线网址不在其中。检查复用同一套评分,先核对原文件名、目录、时长、体积与相邻正片,再决定是否隔离。

流程 检查与处理顺序
添加媒体库、全量扫描 登记与配套文件识别 → 按本次目录检查 → 允许自动读取的媒体探测 → 重判
推送发现、单文件登记 登记与配套文件识别 → 检查该资产 → 允许自动读取的媒体探测 → 重判
云下载 落地并绑定正片 → 检查下载范围 → 探测并重判 → 采集资料与预览 → 重判 → 按模板整理 → 派发后继任务
补全资料、补全预览 检查当前范围 → 探测并重判 → 读取本地资料与生成预览 → 刷新活动资产 → 联网采集适用资料
仅采集资料 检查已有证据 → 读取配套资料 → 重判 → 联网采集;不读取视频或抽帧
手动整理、维护脚本 执行整理和生成九宫格前检查;独立探测脚本在探测前后检查;整理预览与只读盘点保持只读

探测沿用来源的计费与代理保护,不为垃圾检查额外读取媒体。探测后先接回能确定归属的个人记录,再重判垃圾。没有有效时长的视频只进复核。仅补预览限定本地来源;完整处理在关闭视频预览时跳过抽帧。失败任务保留检查点与问题记录,重试复用已登记资产、测量值与整理日志;资料或整理失败时不派发该下载的后继任务。资料采集的问题全是来源限流或拒绝访问时,其余资料已落库,文件照常整理,任务记为完成并在详情里写明哪项等来源恢复后重新采集;混有其他问题时照旧失败。有码作品的 JavDB 标签只用来换更细的类别:来源链这一趟已给出标签时,JavDB 取不到不算问题。

  • 判断为垃圾的文件只会被移入回收站,不会直接删除。
  • 点「不是垃圾」会记下这个文件的判断(可以撤销),它会出现在「已排除」视图里。这个判断只针对这一个文件,不会把整个域名或来源列入白名单。
  • 自动隔离要求达到自动线,并保护人工保留、喜欢、观看或播放列表等个人记录、已配对字幕、文件自身的作品番号和本次绑定的下载正片。写入前再次核对当前资产;已离开馆藏的条目不进入后续采集或整理。
  • 无关键词的极短附件可凭同目录长正片、数量及跨目录测量值进入复核;这类结构证据与「域名加序号」命名不能单独触发自动隔离。还原后确认要保留的文件,可同时标记「不是垃圾」。
  • 云下载落地目录里,正片以外、名字不带本片番号的文件按下载包附带文件计分:网址文本、图片等可直接达到自动线;短视频须有测量值,且正片远长于它;压缩包只进复核。带本片番号的封面、截图、分卷和 poster、fanart 这类作品图不算附件。同名同体积的小文件出现在三个以上带番号的发行包目录时,也计为垃圾证据。

维护脚本 scripts/trash_junk.py 默认生成候选清单;永久删除使用 --purge --review-csv, 复核 CSV 每行包含 id、path、size、decision、confidence、why。 只有 decision=delete 且置信度至少 0.95 的行进入删除,执行还需 --apply --backup。 评分只决定复核顺序,不能单独决定永久删除;文件的路径或体积变化时整批拒绝。 安装附件、网页脚本和未探测时长的推广短片也进入复核;字幕与 NFO 不进入垃圾队列。 剧情词不构成广告证据,种子、作品图集与创作者资料须按文件内容判断。

缓存目录

generated/avatar-thumbs 是头像的缩小版(长边 640),每台电脑自己生成,不参与同步也不需要备份。整个目录删掉只会让下一次打开索引页慢一些,缺失时页面显示原图。导入一批新头像后,可以运行 scripts/build_entity_thumbs.py 提前生成。

人物资料页的「更换头像」支持本机图片、图片地址和已有候选。输入支持 JPEG、PNG、WebP、AVIF、GIF、BMP、TIFF、ICO 与 JPEG 2000;动图及多页图片使用第一帧,EXIF 方向在服务端转正,透明区域保留。图片完整解码后转换为静态 JPEG 或 PNG,框选预览与安装使用相同的转换规则。单张原图及转换结果均不超过 16 MiB;未支持的格式、无法识别的内容、损坏数据和像素尺寸过大分别提示原因。原文件保持不动;本机图片的转换预览留在候选缓存,点击「用这一块」或「整张使用」才安装为头像。

维护者参考

以下内容给在源码上开发、打包、发布和维护两台机器的人看。

首次设置的内部流程

  • 首次设置的「Peach 代理」支持跟随环境、直连和自定义 HTTP/SOCKS 代理。自定义地址与端口沿用配置页校验,凭据存于所选数据目录的本机 secrets;读题接口只返回连接方式和是否已保存地址。Docker 中填写回环代理地址时提示改用容器可访问的宿主机地址。配置页「网络与访问」可随时修改。
  • GET /api/setup/questions 的 peach_proxy 包含 mode、proxy_saved、needs_selection;docker 表示部署是否为 Docker。POST /api/setup 的 peach_proxy 接收 {mode, proxy},mode 为 environment、direct 或 proxy,缺省为 environment。校验错误放在 errors.peach_proxy。代理设置先于 config.toml 和首扫请求写入磁盘,保证托盘切换后使用所选连接方式。
  • 托盘启动时读一次设置文件,由 tray.needs_setup() 判断:没有 config.toml 且没有数据库才算需要首次设置。不用 PeachConfig.configured 判断:托盘的单实例锁一启动就会在 Peach 数据目录下建出 state/,一次失败的启动就可能让下一次误判成已配置;反过来,没有 config.toml 的老部署数据库还在,不能被拖进首次设置。
  • 需要设置时,托盘不构建正常的服务规格(全新机器上 build_service_specs() 会因为缺 TLS 材料抛 FileNotFoundError),而是启动 peach serve --setup --host 127.0.0.1 --port <设置里的端口,默认 8900> --no-mdns --no-ledger-sync,再把浏览器打开到 http://127.0.0.1:<端口>/。这条引导服务没有 TLS,口令强制为空,安全边界就是回环绑定地址。
  • 首页是首次设置表单:GET / 回一张薄壳(routes_pages.setup_shell()),表单由页面包 /dist/peach-pages.js 画出,题目与提交都走下面两条 JSON 接口。完成态的入口带 /?onboarding=1;选了导入浏览器历史则先去 /taste?onboarding=1。安装教程通过专用状态接口读取各项的实际状态。
  • Docker 全新数据卷不跑 peach init:peach.server 以 serve --setup 监听容器端口,设置文件出现后换成正常服务(ADR-0149)。守卫改按 web_local_access.local_client 收本机与私有网络、不带代理转发头的来源,403 正文带 docker: true;完成前 /api/ 与写请求按同一判定拦下。读题不出 data_root、host、port、mdns_name,提交里带了也不认;media_dir 默认 /media,另给 data_root(固定的数据目录)与 access_preset(已按 PEACH_ACCESS_PASSWORD 写下访问密码)。完成后 url 与 redirect 都是当前地址下的 /?onboarding=1,POST /api/setup/restore 回 404。首次设置服务的 /healthz?ready=1 回 200 与 setup: true。
  • 两条接口共用守卫(routes_pages._setup_guard):已配置 404,非回环来源 403,独立包地址栏主机名不是回环写法 403;提交另查 Origin(403)与设置文件已存在(409)。两条都在 /api/ 下,错误一律回 JSON。
    • GET /api/setup/questions 给出画表单要的数据:questions 按 onboarding.questions() 的顺序列出每题的 key、label、help(说明行列表)、default、required、advanced(是否折进「高级设置」)、input(text、number、choice、folders)、prefix、suffix,host 另带按页面顺序排好的 options,mdns_name 另带 visible_when: {"host": "2"};另有 media_sources、media_source_default、media_root(非 Windows 的对应路径格,Windows 为 null)、cloud(提示、帮助链接与缺失的挂载软件 dependencies)、windows、standalone,以及三个开关的初始值 access_enabled(host 默认是局域网就开)、scan_now、history_guide。
    • POST /api/setup 收同名字段:media_dir 是 {path, location, root} 行列表(location 缺省为 local),access_enabled、scan_now、history_guide 是布尔,选了「只有这台电脑」可不传 mdns_name。400 回 {"error", "errors"}:errors 按题目 key,访问密码在 access_password,media_dir 与提交的行一一对应、没错的行是空串;整表不成立(超过 100 行)时只有一句,长度与行数不等。apply 失败回 400,错误在 data_root。200 回 url、scan_requested、history_guide、standalone、redirect(独立包为入口地址,其余为 null,跳转时长由前端定)与运行信息 facts(同 /api/configuration 的 facts)。
  • 建目录(database、generated、sources、state、secrets、logs、tools、review)、迁移数据库、生成 CA 与口令、写设置文件,都由 onboarding.apply() 完成;CLI 和设置页调用同一个函数,只是输出方式不同。问答的题目、默认值和写文件逻辑在 src/peach/onboarding.py。
  • 网页不展示数据库路径输入,media_root 为 null。media_dir 行中的 root 可省略或留空,服务端按媒体目录补齐;已有行提交原 root 时保留它。媒体目录与已有配置唯一匹配时复用原前缀,新目录自动生成前缀,并用目录名作为媒体库名称。
  • Windows 上 peach init 写出的 [media.locations] local 直接是那些目录,[media.mounts] 为空;macOS 上配置的目录是 R:\media(第二个起 R:\media2……),本机目录按同样顺序写进 [media.mounts] local。复制、writer 镜像、SMB 一律不问,保持关闭或留空。
  • 切换由 tray.SetupGate 负责,Windows 托盘与 macOS 菜单栏共用。它挂在健康轮询里(Windows 10 秒、macOS 5 秒),每轮重新 settings_file.load_config();不再需要设置时,停掉引导服务,按新 Peach 数据目录构建正常规格并启动,托盘进程本身不重启。
  • 独立测试包按设置在高位端口提供 HTTP:本机模式绑定 127.0.0.1 且不发布 mDNS,局域网模式绑定 0.0.0.0 并发布 <mdns_name>.local:<端口>;托盘打开页面和健康检查始终走回环。源码部署由 build_service_specs(tls_dir=..., mdns_hostname=...) 构建 HTTP 跳转与 HTTPS 入口,TLS 材料没齐就等下一轮。mDNS 名由这里传进规格,不读 import 时的值。
  • 首次扫描不在引导服务里跑,因为那个进程在切换时就会被停掉。表单勾了「现在扫描」只写一个一次性标记 <Peach 数据目录>/state/first-scan.request(内容是来源 ID),托盘切换完成后读取并删除它,用子进程跑 peach scan <来源>,输出在 <Peach 数据目录>/logs/tray-scan.out.log。配置页保存时勾选扫描也走这个标记。
  • 配置页的数据走 /api/configuration,保存时先把旧文件复制成 config.previous.toml,再写入并留重载标记,由托盘接手。文件夹选择走 /api/pick-folder。
  • wheel 把 web、migrations、resources 装进 peach/_resources。scripts/smoke_wheel.py 在仓库外用安装了 wheel 的解释器运行;CI 的消费任务只下载制品,不检出源码。测试只用临时 Peach 数据目录。
  • Win32 窗口创建前必须启用 Per-Monitor V2 DPI;正常操作不弹模态 MessageBox,更新检查在后台线程执行,并用 pystray 原生的非模态通知反馈。

桌面入口与发布

  • Windows 日常入口是当前用户「启动」文件夹里唯一的 Peach.lnk,指向项目内的 dist\Peach\Peach.exe。桌面快捷方式和开机自启在配置页「开机自启」一组里开关,由 src/peach/desktop_startup.py 写入;scripts/manage_tray_startup.ps1 只用于发布包排障。
  • dist/Peach/Peach.exe 是本机打包入口,不是可以拷走的独立发行版:托盘只打包了自己,服务进程仍由项目 venv 的 peach.exe 运行(_peach_executable() 从 exe 所在位置逐级向上找 .venv\Scripts\peach.exe),不要把它描述成绿色版。
  • macOS 日常入口是 LaunchAgent io.github.longmeidao.peach.tray,由 python scripts/install_macos_agent.py(install/status/uninstall)管理。.app 外壳的 bundle ID 是 io.github.longmeidao.peach.app,80/443 的转发在 pf anchor io.github.longmeidao.peach。三个标识都取自 src/peach/appid.py;setup_macos_port80.sh 里的 shell 字面量由 tests/test_tray.py 保证一致。macOS 源码菜单栏的构建入口是 build_macos_app.py。
  • 标识变更要在 Mac 上跑一遍下面的命令才生效,遗留的 LaunchAgent 与 pf anchor 由 install 自己清掉:
launchctl bootout gui/$(id -u)/gg.lmd.peach.tray || true
python scripts/install_macos_agent.py install
sudo sh scripts/setup_macos_port80.sh install
python scripts/install_macos_agent.py status
launchctl print gui/$(id -u)/io.github.longmeidao.peach.tray | grep -E '^\s+pid'
launchctl print gui/$(id -u)/gg.lmd.peach.tray            # 期望「Could not find service」
sudo pfctl -a io.github.longmeidao.peach -s nat
curl -s --noproxy '*' -o /dev/null -w '%{http_code}\n' http://peach.local/healthz
curl -s --noproxy '*' -o /dev/null -w '%{http_code}\n' https://peach.local/healthz

验收四项:菜单栏只有一个 Peach 图标,status 报「已加载」;launchctl print 的 pid 就是那个菜单栏进程;pfctl -s nat 列出 80 → 8900、443 → 8443 两条 rdr;两条 /healthz 都返回 200。peach.local 换成本机 [server].mdns_name 的值。

  • 构建入口是 scripts/build_windows.ps1:先用 scripts/generate_brand_assets.py 生成方形 Logo 与多尺寸 .ico,再构建单一的 dist/Peach/Peach.exe。不带参数运行是托盘,serve/migrate 运行 CLI。
  • 对外测试包由 .github/workflows/release.yml 构建:build_windows.ps1 -Standalone 用 PyInstaller onedir 生成完整的 Windows 程序目录,压缩后由不检出源码的消费任务运行 scripts/smoke_desktop.py。冒烟测试会完成首次设置、以 0.0.0.0 重启、从本机局域网地址读 /healthz、确认 mDNS 已装配,并用访问密码登录。v<__version__> 标签与版本不一致会失败;制品验收通过后才创建 GitHub 预发布并附 SHA256。workflow_dispatch 只生成和验收制品。
  • 安装包由 build_windows.ps1 -Installer 在同一个程序目录上调 Inno Setup 6 的 ISCC 编译 scripts/installer/peach.iss,产物是 dist/Peach-<版本>-windows-x64-setup.exe;找 ISCC 的顺序是 PEACH_ISCC、PATH、两个默认安装位置。默认安装到当前用户的 %LOCALAPPDATA%\Programs\Peach,可选择独立、可写且不与数据目录重叠的程序目录。覆盖安装前由随包临时运行时执行 --installer-prepare,通知采集任务保存进度并暂停,随后停止托盘,覆盖程序并迁移实际数据目录中的已有 Peach 数据库,最后释放安装保护。安装期间的新采集请求进入等待;安装完成或取消后,仍在运行的 Peach 会续跑,已退出则在下次启动时恢复。卸载走 --installer-uninstall,撤销启动项与桌面图标并保留数据。约定与 AppId 在 src/peach/desktop_installer.py。
  • 独立包构建会把固定版本的官方 cloudflared-windows-amd64.exe 放在 Peach.exe 旁边,并用 scripts/cloudflared-windows.json 里的 SHA-256 校验。构建前运行 scripts/fetch_cloudflared.ps1,或给 build_windows.ps1 -CloudflaredPath 一个哈希相同的文件。源码运行不携带这个二进制。
  • 每个包都带构建身份:build_windows.ps1 在调用 PyInstaller 前把 {commit, version, built_at} 写进 build/windows/build-info.json,再用 --add-data 放到包根,本机托盘与独立测试包共用。构建机没有 git 或源码不是检出时 commit 为 null,构建照常。peach.buildinfo.frozen_build() 只在 sys.frozen 时读它;文件缺失或格式不对返回 None,托盘照常启动,只是认为自己身份未取得。
  • PyInstaller 的资源直接在 sys._MEIPASS 下,没有源码树的 src/ 这一层;打包后的 migrate、Web 与品牌资源都要从这里解析,不能在 config.py 里固定取 parents[2]。
  • 本机托盘会自己发现「比检出旧」并重建。判据是构建提交与本地检出的差距,不是与 GitHub 的差距:这台机器的提交先落在本地再推远端,「落后远端」永远不成立。
    • VersionManager.build_age() 用 rev-list --count <构建提交>..HEAD 数出落后多少,版本菜单显示成 master@<HEAD> · 托盘构建 <构建提交>,落后 N 个提交。数不出来(身份未取得、提交不在本检出历史里)按陈旧处理,重建范围收窄到 src/peach/。
    • 「同步开发进度」在 ahead/current/error/unconfigured 下走本地重建;健康轮询另外每 5 分钟读一次本地 HEAD 自动触发,同一个 HEAD 只自动试一次,首次设置没完成时不触发。
    • 重建流程是:完整测试 → 暂存构建 → 检查打包的迁移资源 → 备份 → 替换。任一步失败只发通知,旧托盘和服务继续运行,通知里写明卡在哪一步,日志在 <Peach 数据目录>/logs/windows-source-sync.log。
    • 独立测试包和源码运行的托盘不走这条路:测试包用配置页的在线更新,源码入口提示源码已是最新。
  • 发布流程(定版、变更日志、打标签和什么时候该发)见「版本、更新与自我重启」。

刷新源码运行态:restart_windows_tray.py

Windows 托盘独立于启动它的终端和智能体运行。启动、重启与异常恢复由当前会话的 Windows 桌面进程承接父身份;关闭 Codex、Claude 或终端不会停止托盘。入口先只读探测当前 Peach 数据目录的单实例锁;已有托盘时按启动参数打开页面或静默退出。首次启动从 Job 中交接时,父进程不占用单实例锁,新托盘取得锁后启动子服务。Peach 数据目录、源码路径和启动参数保持一致;未取得桌面进程或 Windows 拒绝创建时明确报错,不在启动器的私有 Job 中继续运行。

桌面进程及托盘可以保留系统管理的共享 Job。子进程由 PROC_THREAD_ATTRIBUTE_PARENT_PROCESS 指定的桌面进程提供 Job 继承关系,独立性按关闭启动器私有 Job 后仍存活来验收。一次性交接标记由托盘入口消费,适用于源码、目录包及 onefile 引导进程;子服务不继承该标记。创建被拒绝时仅重试一次显式脱离,错误保留 API 与系统错误码。退出 Windows 会话及系统 Job 自身结束属于系统生命周期。

独立启动取证记录调用者、桌面与子进程 PID 及 Job 成员状态、调用进程直接 Job 的原始限制值与已识别标志。失败上下文进入脱敏诊断报告;无法取得的 Job 句柄链和归属明确标为未取得,不推断 Job 所有者,也不要求管理员权限枚举系统句柄。

Windows 托盘在取得单实例锁后启动独立监视器。监视器用 Win32 进程句柄等待托盘退出,核对进程创建时间,避免 PID 复用;意外退出(包括未登记退出意图的零退出码)按 2、5、10 秒延迟恢复,5 分钟内至多 3 次。恢复保持当前 Peach 数据目录和源码入口,以静默模式启动。新托盘的监视器就绪后完成交接;导入或启动失败计入同一重试预算。手动启动的新实例会取消旧实例尚未执行的恢复。达到上限后保持停止,需检查日志后手动启动。

菜单退出、更新、卸载、外部停止消息和系统会话结束都会登记退出意图并停止监视器。正常重启由重启脚本负责拉起,监视器不参与依赖同步与换包。tray-lifecycle.log 每行是一条 JSON,包含 UTC 时间、实例标识、托盘及监视器 PID、启动父进程、退出意图、外部消息发送者 PID、异常退出码和恢复结果。强制结束进程时,记录的操作者为 unknown,不能从退出码判断是谁关闭了它。

监视器与托盘共用当前用户权限,不注册计划任务或 Windows 服务。监视器自身被结束、整棵进程树被结束或系统关机时不能自动恢复。监视器启动失败写入 tray.log;日志不可写时保留退出和服务清理行为。macOS 由 launchd 负责,见 macOS 异常退出恢复。

适用于代码已经在检出里、只需要让运行中的托盘重新加载、不换二进制的情况。

  • 不要用 Computer Use 点托盘。python scripts/restart_windows_tray.py 按精确的 EXE 路径找到 pystray 隐藏窗口,发送正常停止消息,等托盘自己关掉子服务,再静默启动新托盘,并确认新托盘接管了两个服务。
  • 找不到唯一的窗口或退出超时就拒绝执行,绝不强杀后另起。旧托盘退出后,要等它名下的子服务退干净才起新托盘。端口被不归旧托盘管的 serve 进程占着时,开工前就拒绝并报出它们的 PID,因为换托盘换不掉它们。
  • 托盘把自己拉起的子服务放进 kill-on-close Job:托盘被 Stop-Process -Force 之类强杀时,整棵 serve 子树一起退出,不会留下孤儿进程继续占着 80/443 跑旧代码。托盘每轮健康检查发现端口没响应会补拉;看到健康但不归自己的服务只记 warning,不接管。启动与补拉记录在 <Peach 数据目录>/logs/tray.log。
  • --swap-from <暂存包> 在旧托盘退出后、新托盘启动前顺手换掉二进制,这是整个换包过程中唯一一个目标文件没有被进程占用的时机。换生产二进制请用 deploy_windows_tray.py,不要单独调用它。
  • 找不到打包托盘的窗口时,命令自动改走源码托盘:find_source_tray_windows() 按同一窗口类名加「命令行含 peach.tray」认出源码托盘,restart_source_tray() 照原命令行(含 --show/Peach 数据目录)在托盘退出后重新启动,不换包也不备份。--source 显式跳过打包入口。
  • 重启自动准备运行环境(ADR-0091),不用手工补依赖、跑迁移:
    • 任务闸门:开工前只读查本机 task_run 里还在跑的行。追更任务(followup_key 非空)和定时任务重启后会续跑,放行;手动、CLI 等续跑不了的任务在跑时拒绝重启,--force 越过。进程已死的行只列出,不拦。
    • 依赖:源码部署(有 uv.lock 与 .venv、能找到 uv)在旧托盘和子服务退净之后、新托盘启动之前跑 uv sync --locked --all-extras --inexact --no-install-project,已一致时不动。同步前还有别的进程在用项目 venv(例如 8099 调试 serve)就拒绝重启并报出 PID:Windows 上被加载的 .pyd 换不掉。
    • 迁移:新托盘在第一次拉起子服务之前,对本机写者的 Peach 数据库跑 peach migrate upgrade --yes,migrate 自己先留 ledger.pre-migrate-<时间>.db。读者、Peach 数据库不存在、首次设置未完成时不迁移。
    • 就绪:子服务起来后托盘再问 /healthz?ready=1,Peach 数据库结构与迁移不一致等未就绪项写进日志和启动通知。
    • 新托盘把这几步写进 <Peach 数据目录>/state/runtime-prepare.json,命令读回来一起报告。stdout 是一行 JSON,ok 为 false 时退出码 1:被闸门拒绝、依赖同步失败、迁移失败或服务未就绪都算。
  • 托盘菜单的「重启服务」:依赖一致时只重启子服务,在子服务停着时迁移;依赖与 uv.lock 不一致时分离地拉起 restart_windows_tray.py --source --force 整体重启托盘,输出追加在 <Peach 数据目录>/logs/tray-restart.out.log。脚本拒绝或没起来时通知写明原因,退回只重启子服务。

源码环境改字

页面地址加 ?edit 开启文字编辑,悬停文字显示编辑范围,点文字在原位修改,回车或点别处保存、Esc 取消。 按钮和链接的文字使用贴在文字位置的输入框。切换控件正常响应点击,Alt 点击修改文字;「暂停编辑」可继续操作页面。 静态文案写回 web/index.html、frontend/src 或馆藏上传与处理模块中选定的来源;同一文字有多个位置时需选择来源。清空静态文字即可删除这段文案。 馆藏处理的动态句子显示 {problems} 等占位符,只修改周围文字,保留每个占位符。数量随任务变化,不能借此修改馆藏数据。 保存直接写回源码,无需导出。React 文案自动构建,Python 文案由源码托盘重载服务,完成后自动刷新当前地址并保留 ?edit。浮条显示保存、构建与重载状态;生效失败时保留源码修改,提供「重试生效」。服务重载前检查任务是否可续跑,无法续跑的任务仍在运行时拒绝重载。 保存前校验源文件摘要,备份位于 build/copy-editor/backups/。前端在临时目录构建,产物齐全才替换页面资源;构建日志位于 build/copy-editor/build.log。Python 自动重载要求运行源码托盘。 「导出修改」提供一份额外的修改记录,不承担源码保存。

工具脚本位于 scripts/dev/,不作为网页资产分发;冻结的发布包不提供改字端点。 演示站的 ?edit 只保存当前浏览器的文案草稿,可导出,普通访问不应用草稿。

换掉生产托盘二进制:deploy_windows_tray.py

适用于生产入口的 EXE 本身要换成新构建的情况。换生产入口是发布动作,执行前需要人工确认,脚本不代替这次确认。

  • 在主检出里用项目 venv 的 Python 运行 python scripts/deploy_windows_tray.py。步骤:拒绝脏检出 → 按 HEAD 提交号在 <Peach 数据目录>/state/source-sync-build/<commit>/ 构建 → 让暂存包自己跑一次 migrate status → 停旧托盘,原地替换 dist/Peach/Peach.exe(旧文件留成 Peach.pre-source-sync-<时间>.exe),起新托盘 → 用项目 CA 严格校验读取生产 HTTPS 口的 /healthz。
  • 验收看是谁在回话。独立发行版由冻结进程响应,核对 build_commit 等于打包提交。源码部署由项目 venv 的进程响应(src/peach/tray.py 的 _peach_executable() 选择子服务入口),build_commit 为 None;这时核对生产入口文件的 sha256 等于暂存包。
  • 两种验收都不看版本号:版本号一次发布才加一格,同一个版本号下有很多个构建。
  • 结果打印成一份 JSON,step 说明停在哪一步。新托盘起不来或接管不了两个服务时,自动换回备份并重开旧托盘。--staged <路径> 复用已经打好的包,跳过构建。
  • 不要就地构建 dist/Peach/:运行中的托盘占用着那个文件,PyInstaller 清目录会遇到 WinError 5。

两台机器之间的同步

  • 「同步开发进度」走 GitHub,「同步数据库」走 SMB 共享,两者不能合并成一个按钮:任何一边连不上都不该拖住另一边。HTTP/HTTPS 服务只观察角色,不自动复制。
  • replication.enabled 开启时:建同步观察器、探测并挂载 SMB、托盘出现两个 Ledger 菜单项、追更凭据写入共享副本。关闭时这些都不发生,/healthz 的 ledger_sync 是 disabled,写接口全开。
  • 手动同步先用 sync.resolve() 只读判断这次会不会真的复制。offline 不是结论:macOS 重启后 SMB 共享不会自动挂回来,托盘按 SHARED_SMB_HOST/SHARED_SMB_SHARE/SHARED_SMB_USER 补挂一次再判断,真挂不上才报告。
  • 补挂用 osascript 的 mount volume,而且必须先查钥匙串:没有对应记录时 NetFS 不报错,而是弹出认证框一直等,后台操作既卡到超时,又在用户面前弹出密码框。钥匙串记录按主机名存,同一台机器的 IP 和 mDNS 名是两条不同的记录。
  • 补挂后仍是 offline,以及 conflict/in-sync,都直接报告,不停服务;确定要复制时才停掉自己创建的服务,用 SQLite backup API 加原子替换复制,最后恢复服务。
  • 「由本机接管数据库写入」只在共享盘不可达时走捷径:macOS smbfs 上的共享源必须以 immutable 的已关闭快照读取,共享目标不能由 SQLite 直接打开事务连接,健康端口不归本托盘时拒绝接管。
  • 生成的图片走 Syncthing 单向同步,和数据库、和 Git 是三条互不替代的通道:Windows send-only、Mac receive-only,五个文件夹 snapshots/posters/avatars/logos/covers。Mac 侧根目录在 peach-data/artifacts/(不要把指向它的符号链接设成同步目录),Trash Can 版本保留 30 天。
  • .stignore 不跨设备同步,两端每个目录各放一份。方向固定,在 Mac 上生成的图片不会回到 Windows。
  • 两台机器的访问口令要一致:reader 取 writer 的复核结果时发的是自己的口令。
  • 两台机器的本机 CA 各自独立,secrets 按设计不共享。
  • 双机广播名分别取各机的 server.mdns_name,必须不同;读取 /healthz 的 mdns 核对实际名称。PEACH_MDNS_NAME 只作临时覆盖。

版本、更新与自我重启

  • 独立包的版本检查读取 GitHub 公开发行记录与 R2 公开清单,选择可下载的最高版本;同版本优先 GitHub。R2 制品必须具有 SHA-256,发行说明统一指向 GitHub。任一来源不可用时仍检查另一来源,两个来源都未取得时显示检查失败。

  • 更新包、完整包和轻量安装器的工具包下载失败或校验不符时,尝试另一公开源的同版本、同文件名;每次都按原发布记录的大小与 SHA-256 校验。备源不能替换为其他版本或放宽校验,两个来源都失败时保留错误状态。

  • release_signing.PUBLIC_KEYS 非空时,Windows 更新器下载前先取同版本的 SHA256SUMS.txt 与 SHA256SUMS.txt.sig,用随包公钥验过签名后,更新包与完整包只按签过名的摘要校验;两个来源都验不过就停在当前版本,提示到发布页手动下载(ADR-0137)。

  • 版本号只在 src/peach/__init__.py::__version__ 里定义,采用 pre-1.0 SemVer。Git 提交是构建标识,vX.Y.Z 标签是发布点,推到 GitHub 就触发 Release 工作流(见「桌面入口与发布」)。

  • 版本号在发布时才动,一次发布加一格,所以每个 X.Y.Z 都有一份能下载的制品。

  • 依赖升级:定版前完成每次发版检查的依赖升级批次,包括适用的兼容修改、派生产物、完整验证与本地集成;暂不能升级的保留具体原因和失败证据。定版后发现需要改依赖时,先保存发行说明草稿,撤回本轮尚未提交的版本修改,完成升级后重新定版。

  • 定版:在干净的 master 主检出上运行 python scripts/release_tag.py --bump auto --apply。它按上一个版本标签到 HEAD 的区间定档(bump_part_for():主题以 feat 开头、带破坏性标记 !,或 migrations/ 有新文件时推 minor,其余推 patch;1.0 要手工 --bump major 并另立 ADR,见 ADR-0012),写入 __version__,并把 CHANGELOG.md 的未发布一节定成这个版本号。区间只改了文档、技能和测试时直接拒绝,因为那样打出的包和上一个标签完全相同。--bump 只写文件不提交,并打印定版的那一节供人检查;不带 --apply 只打印计划。

  • 发布:确认之后运行 python scripts/release_tag.py --ship --apply,一次完成剩下四步:提交 src/peach/__init__.py 与 CHANGELOG.md(消息 chore(release): 版本 <新版本>)、推送 master、每 30 秒查一次这个提交的 Test 工作流、变绿后创建并推送 annotated tag。默认最多等 30 分钟,用 --timeout 修改。不带 --apply 只打印步骤。

  • --ship 在动手前检查:不在 master、变更日志缺这一节、标签已被占用、工作区除了那两份定版文件还有别的改动,任何一条成立就拒绝(标签指向发布提交,夹带什么就等于发布什么)。Test 结束不是绿色就立刻停,这时标签还没打。

  • 标签流水线第一步就跑仓库根与 frontend 两份 npm 审计;新公布的高危漏洞会让已打出的标签什么也发不了。所以 --bump --apply 写文件前、--ship 在 Test 转绿之后打标签之前,都先用 scripts/npm_audit.py 的同一判据复查一次,有高危漏洞就停,版本文件与标签都不动。

  • 等 Test 期间能确定等不到结果的也立刻停,不耗到超时:GitLab 必需任务(verify-linux、verify-windows、verify-macos、wheel-smoke)已失败;任务排着队没人接,且带这些 tags 的 runner 都不在线或已暂停(读 runner 列表要维护者权限;读不到,或列表里查不到带这些 tags 的 runner 时,按排队满 5 分钟仍未开始判停);推送 5 分钟后仍没有 Test 记录。报错写明任务名、tags 和已等时长。GitHub 只对自建 runner 任务做同样判断,托管 runner 排队照常等。处理好之后再跑一次 --ship --apply 接着走。

  • 中途停下(断网、CI 还在跑、超时)就再运行一次同一条命令:每一步都先看当前状态,已提交的不重复提交,已推送的不重复推送,Test 没绿绝不打标签。

  • 单独补打标签用 python scripts/release_tag.py:默认只检查本地与 GitHub master 一致、这个提交最新的 Test 全绿、CHANGELOG.md 有这个版本的一节、标签不存在;加 --apply 才创建 annotated tag 并只推送这个标签。适用于发布提交已推送、只差标签的情况。变更日志那一节是硬性要求,缺了先用 --bump 起草。版本标签不覆盖,下一版先改 __version__。推送失败留下本地标签时,先确认归属再人工处理,不强推。Release 工作流会再检查标签提交在 master 历史里、同一提交的 Test 已通过,然后核对成功演练的产物并创建预发布。打标签代表公开预发布,不等于替换本机生产入口。

  • 已确认的发布提交推送后,若 master 继续推进,用 python scripts/release_tag.py --release-sha <完整提交 SHA> 核对固定提交的发布计划,确认输出后加 --apply 补打标签。这个模式从选定提交读取版本与变更日志,并在创建标签前再次核对主线归属、同一提交最新的绿色 Test 和标签占用;只推送标签,保留当前 master。它不能与 --bump、--ship 或 --verify-sha 合用。

  • 什么时候该发:scripts/agent_worktree.py integrate 不改版本号,只报当前值,并输出 release 字段(scripts/changelog.py 的 due())。due 为真时提出发布,理由在 why。节奏是每周一次、条目攒够提前、破坏性变化和安全修复不等周期(DUE_DAYS = 7、DUE_ENTRIES = 10)。只数使用者看得见的变更条目,不数提交。DUE_ENTRIES 是没有样本时的保守起点,due() 每次都报出实际条目数与分组,积累几次真实发布后再校准。

  • 会话收尾提醒:scripts/release_due.py --hook-event 挂在 Claude 的 .claude/settings.json 与 Codex 的 .codex/hooks.json 的 Stop 钩子上(两边约定一致:stdin 收 JSON、stdout 回 systemMessage、退出码 0)。只有在主检出、在 master、工作区干净、这个 master sha 还没问过,并且 due 为真时才输出一句,其余情况什么都不打印。已问记录在 <Peach 数据目录>/state/release-due.json,master 前进后才会再问。手工查看用不带参数的 python scripts/release_due.py,它只读,不改记录。

  • 钩子用 uv run --no-project 找解释器,同一条命令在两个平台都能用。--no-project 不能省:release_due.py 只用标准库;如果让 uv 识别项目,它会在一个有 pyproject.toml 但还没建 venv 的检出里建一个空 venv,scripts/test.ps1 随后会优先选中它,测试连 filelock 都导入不了。tests/test_release_due.py 会把配置里的命令原样执行一遍,并检查工作目录没有多出 .venv。需要 uv 在 PATH 上,推荐 winget install --id astral-sh.uv,不要把远端脚本直接管道进 shell。

  • 公开文字检查:scripts/check_public_text.py --hook-event 挂在 Claude 的 PreToolUse(Bash、PowerShell)上,同样用 uv run --no-project。命令里没有 gh pr|issue create|edit|comment 或改评论的 gh api 时直接放行;有就把命令连同 --body-file、-F body=@ 引用的文件,对照本机账本(mode=ro)检查。成串列出番号、人物或标题片段时退出码 2,理由交给模型改写。agent_worktree.py integrate 对 PR 正文和分支提交说明做同一检查,覆盖不走钩子的 Codex。没有账本的机器放行;确需多列时正文写一行 peach-public-text: <理由>。手工检查用 python scripts/check_public_text.py <文件>。

  • 「检查更新」只 fetch 和比较;「同步开发进度」只做 merge --ff-only,不 stash、不 rebase、不 --force:并行工作树和主检出共用同一个对象库与 reflog,任何改写历史的操作都会波及其他分支。工作区有改动或两边分叉时,原样报告交给人处理。本地不落后远端或连不上远端时,按构建身份判断打包托盘要不要重建(见「桌面入口与发布」);这条路径不拦有改动的工作区,因为构建用的就是检出里的代码。

  • 快进涉及 tray.py/menubar.py/versioning.py/certs.py/netwatch.py/config.py/pyproject.toml 时,只重启子服务不够,托盘要用 launchctl kickstart -k 重启自己:先 stop_owned() 再 kickstart,前提是 launchd 报的 pid 等于自己的 pid。

网络与服务细节

  • 对本机服务的 HTTP 探测必须设 trust_env=False:代理客户端会设置系统级 HTTP 代理,httpx 默认通过 urllib.getproxies() 读取它,探测 127.0.0.1 的请求会被送进代理、由代理返回 503,服务活着却被判为「未运行」。实现在 peach.tray.ServiceManager.healthy,由 test_health_check_never_goes_through_a_proxy 守门,新写的健康检查同样要这样做。
  • peach serve 按平台发布固定的 mDNS 主机名,源码里不写死任何家庭 IP,并保留 Zeroconf() 在所有合格网卡上监听。mDNS 验收要包含单元测试、运行时 health、DNS-SD、主机名解析和真实局域网客户端。
  • FastAPI 是唯一的 Web 服务器,不要恢复平行的 http.server 或动态 legacy loader。
  • 切换服务前检查 80、443、8900 端口和实际的进程归属。
  • 长任务只能停止自己拥有、且命令行匹配的 Python/FFmpeg 进程树,禁止结束整台机器上的 FFmpeg。
  • FFmpeg 解析不回退到 Stash 的私有目录。转码由 TranscodeService 负责,走和普通播放相同的 Range 端点;探测与每次转码都受 2 槽并发闸门、1 小时总时限和 stream session 取消保护。
  • 115/PikPak 的 B:/A: 盘符对不同 Windows token 的可见性不同,最终以 Peach 对已知作品的 /stream 实测为准。

迁移、备份与运维脚本

  • 真实迁移前依次执行:SQLite 备份、asset/tag 计数、PRAGMA integrity_check、迁移版本检查、服务冒烟测试。已应用与待应用的迁移只认 peach migrate status 的输出。
  • 已应用的迁移文件不能修改,任何后续变更都要新增一个版本。已应用的迁移被改写会造成校验和漂移,只能用迁移前备份重放、逐条比对差异为 0 后再校正 schema_migration。
  • 数据库备份自动清退:ledger.pre-*.db(含设置页的手动备份 pre-manual 与恢复前另存的 pre-restore)由 peach.ledger_backups 管理,「最近 5 份」「24 小时内」「比 ledger.db 新」三类全部保留,其余连同 -wal/-shm 删除。Windows 托盘每次启动自动执行;scripts/prune_ledger_backups.py 手动运行时默认只列计划,--apply 才删除;数据库 integrity_check 不是 ok 时拒绝清退,退出码 2。每份备份一百多 MB,5 天不清就是 7 GB。
  • 整理备份自动清退:下载后整理与手动整理写入前各留一份整库备份,放在 <Peach 数据目录>/generated/organize-backups/,文件名是 ledger.pre-download-<任务>-<时间>.db 与 ledger.pre-organize-<时间>-<任务>.db。每次写备份后按同一套规则清退这个目录,只留最近 5 份(ORGANIZE_KEEP_RECENT),不按年龄保留(ORGANIZE_MIN_AGE 为零):一波下载一小时能整理四十个文件,24 小时窗口会攒下几十 GB。正在被整理引用的那份由 ledger_backups.holding 登记,Web 服务进程里的清退都跳过;目录里的其他文件名不动。手动查看或清理用 scripts/prune_ledger_backups.py --organize,同样默认只列计划,--apply 才删除;登记不跨进程,整理进行中不要给 --keep 0。
  • <Peach 数据目录>/logs 里的 *.log 统一保留半年,不限大小(peach.log_retention.sweep,托盘在启动任何子进程之前运行):半年没写过的文件整份删除;还在写的文件按自然月分段,上次写入在更早月份的改名成 <名字>.until-<最后写入日期>.log,再过半年删除。子进程直接追加 stdout,不经过 logging,所以按文件处理,不按行处理。
  • 更新与打包产物自动清退:托盘每次启动只保留最近 2 份 dist/Peach/Peach.pre-source-sync-*.exe 备份,并删掉 <Peach 数据目录>/state/source-sync-build/ 里不属于待应用记录的暂存构建(WindowsUpdateInstaller.sweep_artifacts);build_windows.ps1 成功后删掉 PyInstaller 工作目录 build/windows/app;单文件托盘每次启动删掉 %TEMP% 里超过一天、不属于自己的 _MEI* 解压残留(sweep_onefile_extractions,托盘被结束进程时 PyInstaller 不会自己清理,每份 40–80 MB)。自动清理只认这几种命名:Peach.exe 本体、手工放进 dist/ 的目录、build/release-*、attic/ 都不碰,手工构建的残留要自己删。
  • 可重建缓存的删除范围由当前数据库路径决定:生产库只能清理同一个 peach-data 下的缓存,临时库只能清理它的临时目录,范围之外一律跳过。测试里的清空回收站必须用临时 Peach 数据目录,漏配会删到真实封面。
  • 资源同步使用后台作业并逐来源报告进度,避免同步全库扫描阻塞请求;同一目录只枚举一次,目录元数据并发固定为 8,不重跑全库,也不盲信旧结果。
  • 运维脚本被导入时不能产生文件、网络或数据库副作用。scrape_codes.py 默认写可续跑的复核 CSV;clean_names.py 先预览,--apply 必须同时给出 --backup <路径>,备份写完后当场校验完整性(peach.scripting.open_for_write)。
  • 追更的合集判据只作用于新抓到的候选。收紧阈值后用 scripts/prune_follow_compilations.py 扫描存量:默认只列清单并写一份复核 CSV,--apply 先备份成 ledger.pre-follow-compilations-*.db 再删除,已保存成 asset 的条目一律不动。没探过详情页的旧行拿不到署名,判据数不到它们。
  • 文件名只按数据库里已确认的番号规范化,不从文件名重新猜番号。只改大小写时经同目录临时名中转;去广告后重名的,用 (2) 起的后缀两份都保留。
  • generated/cover-fetch-log.csv 是来源、尺寸和结果的证据,不随图片一起清理。图片丢失时用 scripts/fetch_jav_covers.py --restore-successes 按成功记录里的原 URL 恢复并原子替换;失败的仍记为失败,不拿缩略图顶替封面。
  • 封面候选必须限定在当前作品的主封面节点:作品页混有数百张关联作品、剧照和演员头像,禁止对整页图片 URL 逐张量尺寸。
  • FC2CMADB 的文章存档只作为官方商品页的镜像证据:标题与保守翻译后的标签写进候选 CSV,和最新的 JAV 元数据批次一起进入 /review,不自动写入数据库。封面把列表的 w276 换成确认存在的 w1200,再走 fetch_jav_covers.py --fc2-only 的解码、宽度、磁盘和原子写入检查,失败的逐条记日志。
  • 批准官方标签时必须用 (asset_id, tag) 冲突更新来源与置信度:asset_tag 的唯一约束会让 INSERT OR IGNORE 保留旧来源,结果值已存在却不显示「官方」。
  • 「不是垃圾」写入的是按 asset 的可撤销 junk_file 复核决定。垃圾判断里推广名、目录与创作者位置的证据跨类型共用,视频另外参考时长、体积和同番号长版。

前端与验证口径

  • 数据库里的元数据不能插值进 inline JavaScript 事件属性:真实厂牌名里的撇号会直接造成 Firefox 语法错误。
  • 前端 API 包装必须先检查 HTTP 状态再返回 JSON:只读冲突时写接口返回 409 和错误 JSON,当成普通成功处理会清空选择并重载,用户只看到条目原样回来。批量处置和详情反馈必须保留当前选择并显示失败原因。
  • 验证结果分开报告:静态/单元/API、桌面浏览器、390×844 手机、生产服务是否已重启。