Peach: Local-first video metadata scraper and media manager.
运行与配置
本文讲在自己电脑上运行 Peach 时要知道的事:第一次怎么设置、配置页在哪、怎么从其他设备访问、怎么装 FFmpeg、哪些操作会真的删除文件。
用 Windows 测试包的,先看 Windows 测试版;从源码运行的,按下面的步骤安装。文末「维护者参考」是给在源码上开发、打包和发布的人看的,普通使用可以跳过。
从源码运行(Windows、macOS)
需要 Git 和 uv。Python 下限为 3.14,项目由 .python-version 固定运行版本,uv 会自动下载缺少的解释器。
在 PowerShell 7(Windows)或 zsh(macOS)中依次执行:
- 克隆仓库:
git clone https://github.com/peach-mitao/peach.git peach-app。 - 进入项目目录:
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 拉起的服务;本机是账本读取端且新版本带有本机未应用的迁移时不安装,并用通知说明要先在写入端更新。
发布侧的设置:
- 私钥在 GitHub 仓库
releaseenvironment 的 secretSPARKLE_ED_PRIVATE_KEY,该 environment 只允许v*标签部署;维护者另有离线备份。ad-hoc 签名下无法轮换,丢失后已装客户端只能手动重装。导入 Mac 钥匙串用 Sparkle 发布包的generate_keys -f <私钥文件>。 - 同一 environment 需要 R2 的 secret
PEACH_R2_ACCESS_KEY_ID、PEACH_R2_SECRET_ACCESS_KEY、PEACH_R2_ENDPOINT与变量PEACH_R2_BUCKET。 - 仓库变量
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 的检查会报更新源不可用。 - 第一个带公钥的版本须手动安装一次;之后的版本才能经 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 为空时作业失败,不发布未签名的版本。
启用步骤由维护者完成,顺序不能颠倒:
- 在主检出运行
scripts/sign_release.py --generate-key <私钥文件>:私钥只写进该文件,已存在就拒绝覆盖,输出里只有公钥。私钥文件放进离线备份。 - 用
gh secret set PEACH_RELEASE_SIGNING_KEY --env release从标准输入写入私钥。 - 发布一个版本,确认 Release 资产里有
SHA256SUMS.txt.sig。 - 公钥写进
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,按问答完成设置。
两种方式都会创建数据目录、准备数据库、生成本机证书和访问口令,并写出设置文件。
首次设置页
首次设置分为欢迎、媒体目录、访问范围和确认四步。返回上一步会保留填写内容;提交校验失败时回到对应步骤。欢迎页可选择「使用已有数据」,恢复流程和完成页使用同一套分栏框架。
首次设置页会问:
- 媒体目录:按媒体库分组,每个媒体库可设置名称、图标、来源色和处理方式,并添加多个文件夹。旁边的「选择文件夹」会弹出系统的文件夹选择框;也可以选择稍后添加媒体库。
- 数据目录:数据库、封面、预览图和缓存都放在这里,馆藏较大时会占用数十 GB。Windows 版默认在系统盘的
%LOCALAPPDATA%\Peach\peach-data,系统盘空间紧张时请选其他磁盘上的文件夹;装好以后也可以在配置页迁移。 - 谁可以访问:「只有这台电脑」或「同一局域网的设备」。
- Peach 代理,以及高级设置中的端口和局域网名称。
- 访问密码(可选):留空时,能连到 Peach 的设备不用登录就能进入。
- 是否立即扫描和诊断反馈;稍后添加媒体库时不触发扫描。
提交后进入 Peach,右下角会出现一份安装教程,列出馆藏、采集凭证、浏览器历史、关注、关注凭证和复核几项。每一项都可以跳过(短时间内能撤销),全部完成或跳过后教程自动消失。教程进度只保存在当前浏览器里。选了导入浏览器历史的,会先打开口味页。
首次设置页由一条只监听本机回环地址的临时服务提供(默认端口 8900),提交成功后托盘自动切换到正式服务,不用重启托盘。它的端口、返回码和切换过程见「维护者参考」里的「首次设置的内部流程」。
终端 peach init
在终端里直接运行 peach init(不带参数)会进入问答:
- 数据目录。
- 一个或多个本地媒体目录:答完一个会接着问「再加一个」,直接回车结束。重复或互相包含的文件夹会被退回。
- 谁可以访问(只有这台电脑/同一局域网的设备)。
- 端口。
- 局域网访问地址。
每一题直接回车就用默认值。连续三次输入无效会退出,并且不写任何文件。答完后会问「现在扫描 <目录>?」(默认是),最后打印下一步和扫描摘要。
终端问答只能添加本地文件夹。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 存放数据的目录)按下面的顺序找:
- 环境变量
PEACH_DATA_ROOT。 - 项目目录旁边的
peach-data/(最多向上找四层,所以主检出、工作树和打包出的dist/Peach都能找到同一个)。 - 都没有,就是「未配置」。
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 GB 余量。
- 确认后 Peach 暂停后台任务、停止服务并退出托盘;无桌面服务只停网页服务,看守进程留着做迁移。同一磁盘内直接改名;跨磁盘时 Windows 用资源管理器的复制(带进度和取消),macOS 逐个复制,复制完逐项核对文件数与大小。
- 数据库里指向数据目录的预览图与追更证据路径改到新位置;默认位置与原位置各留一份
state/data-root.txt指向新位置,开机自启与桌面图标按新位置重写。 - 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」里卸载:
- 先选择范围。默认保留数据;勾选「完全卸载」会同时删除设置、本地数据库、观看记录、凭据和缓存。
- 确认后,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 的公开部分,不含任何私钥。
- 取得证书:
- 手机、平板:用相机扫二维码直接下载,不用先登录。二维码 10 分钟内有效,页面开着时会自动更新;Peach 重启后旧二维码作废。
- 电脑:点「下载证书」,或复制
peach-local-ca.crt这一个文件。
- 在设备上安装并信任它:
- iPhone/iPad:用 Safari 打开,允许下载描述文件,到「设置 → 通用 → VPN 与设备管理」安装,再到「设置 → 通用 → 关于本机 → 证书信任设置」打开完全信任。
- Android:到「设置 → 安全 → 加密与凭据 → 安装证书 → CA 证书」选择下载的文件,菜单名称因厂商而异。
- Windows 双击文件,安装到「受信任的根证书颁发机构」;macOS 在「钥匙串访问」里设为「始终信任」。
- 在设备的证书详情里核对 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 公网入口」默认关闭。必须先设置访问密码才能启动;没有密码时它会被停掉并保持关闭。
临时链接
- 设好访问密码后,点「启动公网入口」。
- 页面显示 cloudflared 生成的随机地址
https://<id>.trycloudflare.com,用它访问。https://try.cloudflare.com/只是介绍页。 - 停止公网入口或退出 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 测试包不支持这种方式,配置页也不会显示这一块。
- 在 Cloudflare Zero Trust 的 Networks → Tunnels 里新建一条 Cloudflared 隧道,复制它的隧道令牌(Token)。
- 给这条隧道加一个 Public hostname,主机名用自己的域名。Service 填本机的 HTTPS 地址:源码部署是
https://<局域网 IP>:443(macOS 按实际 TLS 端口)。再在 Additional settings 里把 Origin Server Name 填成<mdns_name>.local,并把项目 CA 填进 CA Pool,否则本机自签证书过不了校验。 - 在配置页「Cloudflare 公网入口」里切到「命名隧道」,填公开主机名和隧道令牌,点「保存配置」。令牌只写进设置文件的
[tunnel] token,页面不会再显示它,数据库、日志和/healthz里也没有它。换令牌时填新的;留空表示沿用已保存的那一份。 - 建议在 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:
- 显式设置的环境变量。
- Windows 独立程序目录下的
tools/ffmpeg/bin,或 macOS 应用的Contents/Resources/tools/ffmpeg/bin。 - 数据目录下的
tools/ffmpeg/bin。 - 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 anchorio.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 手机、生产服务是否已重启。