# 运行与配置 本文讲在自己电脑上运行 Peach 时要知道的事:第一次怎么设置、配置页在哪、怎么从其他设备访问、怎么装 FFmpeg、哪些操作会真的删除文件。 用 Windows 测试包的,先看 [Windows 测试版](TESTING_DESKTOP.md);从源码运行的,按下面的步骤安装。文末「维护者参考」是给在源码上开发、打包和发布的人看的,普通使用可以跳过。 ## 从源码运行(Windows、macOS) 需要 Git 和 [uv](https://docs.astral.sh/uv/getting-started/installation/)。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 的项目目录安装构建依赖: ```sh MACOSX_DEPLOYMENT_TARGET=11.0 uv sync --locked --extra build --extra macos ``` 先在构建目录安装固定工具链;下面以 Apple Silicon 为例,Intel 将 `arm64` 换成 `x86_64`: ```sh ./.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: ```sh ./.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 后在终端执行下面的命令,再打开应用: ```sh 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;推送普通提交不会触发安装包构建。发版从只读审阅和依赖检查开始,重型验证前完成复核并冻结输入;集成、运行核验与定版按[发版检查](TESTING.md#每次发版检查)执行,打标签统一使用 `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。升级后托盘第一次启动时,已开启的旧启动项会就地补上这两项,其余键不变;在配置页保存开机自启也会重写。两种方式都在下次登录生效。要立即生效,先从菜单退出,再运行: ```sh 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](https://sparkle-project.org/) 框架(`Contents/Frameworks/Sparkle.framework`,版本与摘要固定在 `scripts/sparkle-macos.json`),取舍见 [ADR-0130](adr/0130-macos-sparkle-in-app-update.md)。`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](adr/0137-release-sums-ed25519-signature.md)。`src/peach/release_signing.py` 的 `PUBLIC_KEYS` 为空时不校验;写入公钥后,这一版起的客户端只装签名验得过的版本。 `release.yml` 的 `release` 作业生成 `SHA256SUMS.txt` 后,把 `release` environment 的 secret `PEACH_RELEASE_SIGNING_KEY` 经标准输入交给 `scripts/sign_release.py`,签名文件 `SHA256SUMS.txt.sig` 随 Release 上传。源码已有公钥而 secret 为空时作业失败,不发布未签名的版本。 启用步骤由维护者完成,顺序不能颠倒: 1. 在主检出运行 `scripts/sign_release.py --generate-key <私钥文件>`:私钥只写进该文件,已存在就拒绝覆盖,输出里只有公钥。私钥文件放进离线备份。 2. 用 `gh secret set PEACH_RELEASE_SIGNING_KEY --env release` 从标准输入写入私钥。 3. 发布一个版本,确认 Release 资产里有 `SHA256SUMS.txt.sig`。 4. 公钥写进 `PUBLIC_KEYS`,经 PR 合入。 轮换时把新公钥追加进 `PUBLIC_KEYS`,secret 里一行一把放新旧两把私钥;仍要自动升级的客户端都认得新公钥后,再删旧私钥和旧公钥。 ### GitLab 发布与下载后端 GitLab 兼容平台使用 `.gitlab-ci.yml`。唯一版本入口支持 `--gitlab-host` 指定主机,默认入口使用 GitHub。主线发布判据要求同一提交最新的 push 流水线成功,且 Linux、Windows、macOS 和 wheel 验收任务全部成功;缺少原生系统任务时拒绝打标签。主线上的三个平台验收只跑改动域与平台敏感用例([ADR-0119](adr/0119-mainline-changed-scope-release-full-suite.md))。版本提交 `chore(release): 版本 X` 的主线流水线同时是发布演练:三平台全量、媒体工具、Windows 与 macOS 构建、Windows 冒烟和 Docker 镜像都跑一遍,只是不发布。`--ship` 等演练全部成功才打标签;标签流水线核对同一提交的演练已通过,只重新构建并发布([ADR-0121](adr/0121-release-rehearsal-and-atomic-publication.md))。GitHub 的 `release.yml` 用同一套判据,迁回 GitHub 时不用改流程。CLI 传输复用官方 glab,不在仓库或命令参数里存访问令牌。 平台共享 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 `,由启动器通过 `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](adr/0127-verified-release-artifact-promotion.md)。 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 缓存入口,按 `/<归档名>` 定位文件。标签流水线使用发布桶的 `_sources/` 前缀;维护者填充缓存前须核对锁文件的原始 SHA-256,缓存同样计入桶容量预算。下载缓存失败时尝试锁定的上游地址;任一来源的哈希不符立即拒绝,不能放宽清单。未配置缓存的对应源码包直接使用上游。 GitHub 发版时,`release.yml` 的 `r2-mirror` 作业在 Release 公开后下载它的制品、`SHA256SUMS.txt` 与签名,交给 `scripts/release_r2.py` 原样上传到 R2,逐个从 `https://downloads.peach.video` 完整下载核对后改写 `releases.json`。凭据用 `release` environment 里与 Sparkle appcast 相同的 R2 secret 和变量。镜像只留最新三个版本:新版本登记进索引后删除更老的版本目录,GitHub 上的同版本制品不受影响;比保留版本还旧的版本拒绝上传。连不上 GitHub 的客户端靠这份索引更新,作业失败时它们停在上一个镜像版本,重跑这个作业即可。 GitGud 只做备份,不跑验收。`gitgud-mirror.yml` 在 master 和版本标签推送后,用 `ci.skip` 把同一个 ref 推到 GitGud,不强推,两边分叉就报错停下。Release 发布后,`release.yml` 的 `gitgud-backup` 按标签手动触发它。制品由 GitGud 自己的 Linux runner 上传,因为从 GitHub Actions 上传超过 100 MB 的文件会被 GitGud 前面的 Cloudflare 以 413 拒绝。工作流把 `.github/gitgud-backup.gitlab-ci.yml` 作为唯一的 `.gitlab-ci.yml` 推到 GitGud 的 `release-backup` 分支,用 API 带上 `PEACH_BACKUP_TAG` 触发流水线并等它结束。流水线从 GitGud 上同步过去的 master 取脚本,运行 `scripts/publish_gitlab_release.py --github-release <标签>`:下载 GitHub Release 的制品、`SHA256SUMS.txt` 与签名,按 GitHub 记录的 SHA-256 逐个核对,存进 GitGud 包仓库并登记 Release,摘要与签名原样保存。GitGud 上已有这一版的 Release 时直接跳过。旧版本在 Actions 里手动运行这个工作流补存,填写版本标签即可。凭据是仓库 secret `GITGUD_MIRROR_TOKEN`,即 GitGud 上带 `api` scope、Maintainer 角色的项目访问令牌,过期后两个作业都会失败。项目机器人令牌不能再建新的项目令牌,新建或续期要用项目所有者账号在网页上操作。R2 只留最近三个版本,GitHub Release 与 GitGud 保留全部版本。 可选的 `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](adr/0120-standalone-update-client-compatibility.md)。 双后端发布复用官方 `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 与新作」中,女优名称可显示为中文化(译名)、日语原文、英文(罗马音)、日语原文(本地语言)或本地语言(日语原文),例如「楓カレン(枫花恋)」,英文界面下是「楓カレン (Karen Kaide)」。本地语言跟界面语言走,罗马音取自人物资料页或登记的拉丁别名;缺少对应写法时显示原文。偏好保存在数据库,其他设备读取同一份设置;保存失败时保留原选择。切换只调整当前所选艺名的写法,缺少对应时保留当前名称,不更改人物名称、别名原文或作品署名。手动添加的别名在两种语言下都会列出,没有对应写法时照原样显示。 第一次打开 Peach 有两种方式,结果相同: - **托盘(推荐)**:运行托盘程序后,浏览器会打开首次设置页。 - **终端**:运行 `peach init`,按问答完成设置。 两种方式都会创建数据目录、准备数据库、生成本机证书和访问口令,并写出设置文件。 ### 首次设置页 首次设置分为欢迎、媒体目录、访问范围和确认四步。返回上一步会保留填写内容;提交校验失败时回到对应步骤。欢迎页可选择「使用已有数据」,恢复流程和完成页使用同一套分栏框架。 首次设置页会问: 1. 媒体目录:按媒体库分组,每个媒体库可设置名称、图标、来源色和处理方式,并添加多个文件夹。旁边的「选择文件夹」会弹出系统的文件夹选择框;也可以选择稍后添加媒体库。 2. 数据目录:数据库、封面、预览图和缓存都放在这里,馆藏较大时会占用数十 GB。Windows 版默认在系统盘的 `%LOCALAPPDATA%\Peach\peach-data`,系统盘空间紧张时请选其他磁盘上的文件夹;装好以后也可以在配置页迁移。 3. 谁可以访问:「只有这台电脑」或「同一局域网的设备」。 4. Peach 代理,以及高级设置中的端口和局域网名称。 5. 访问密码(可选):留空时,能连到 Peach 的设备不用登录就能进入。 6. 是否立即扫描和诊断反馈;稍后添加媒体库时不触发扫描。 提交后进入 Peach,右下角会出现一份安装教程,列出馆藏、采集凭证、浏览器历史、关注、关注凭证和复核几项。每一项都可以跳过(短时间内能撤销),全部完成或跳过后教程自动消失。教程进度只保存在当前浏览器里。选了导入浏览器历史的,会先打开口味页。 首次设置页由一条只监听本机回环地址的临时服务提供(默认端口 8900),提交成功后托盘自动切换到正式服务,不用重启托盘。它的端口、返回码和切换过程见「维护者参考」里的「首次设置的内部流程」。 ### 终端 `peach init` `peach` 命令行的输出跟系统显示语言:中文系统显示中文,其余显示英文;设置环境变量 `PEACH_LANGUAGE=zh-CN` 或 `PEACH_LANGUAGE=en` 可以指定。日志固定用英文。 在终端里直接运行 `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`。 ### 设置文件在哪 设置文件固定是 `/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 后,已配置的写入端自动完成数据库迁移、本地确定性资料修复与后台补全,无需手动启动补修。结构和资料处理前保留数据库备份;人工填写、复核结果与人工规范名受保护,存在身份冲突的项目保留复核记录。只读设备不执行这些写入。迁移前整份备份数据库,耗时随数据库大小;迁移期间网页照常打开,页面顶部显示「正在更新本地数据库」与备份进度,需要数据库的内容暂时读不到,完成后提示刷新页面。 在任务中心调整自动修复速度后,同一写入端已排队和之后派发的自动修复批次沿用该速度;选择保存在数据目录中,重启后仍生效,不改变其他任务的默认速度。未单独调整时,自动修复采用新任务的默认速度。 本版更新器允许读取端安装结构兼容的程序;若提示结构待迁移,先升级写入端并同步账本,再安装读取端更新,安装及失败恢复均不回写账本。仍使用旧更新器的读取端须先完成写入端升级及同步;旧助手在迁移被拒后仍可能写回自己的账本备份,当前程序无法追溯修改已经运行的旧助手。 资料和图片缓存按规则版本与来源变化失效。需要重新读取媒体的项目遵守媒体库处理方式、预览设置和读取成本:免费来源可自动处理,额外流量项目延后。处理会保存进度;影片所在目录读不到或资料来源冷却时延后,到时间自动重新派发。失败按退避自动重派,连续失败五次后停下,可在「应用与维护 → 自动修复」重试;旧版本留下的失败只在点重试后重新派发。容量触线时整批暂停,同样点重试后继续。用户取消的任务保持取消。正常升级无需打开该面板。设计见 [ADR-0154](adr/0154-upgrade-repair-item-state.md)。 应用提供新版本、更新准备完成及页面需要刷新的提示。首次未设置自动更新时,每天检查版本;明确关闭过的设置继续保留。下载、重启安装与页面刷新分别沿用用户选择,不因提示自动打断当前操作。独立包在新程序通过启动检查后才恢复后台任务;安装失败恢复程序、数据库、配置与任务检查点。 「自动修复」可下载本地复核记录。`GET /api/client-updates` 只读取本机快照,不触发外部版本检查;接口与权限见[路由清单](ROUTES.md)。设计与规则版本边界见 [ADR-0126](adr/0126-upgrade-effective-repairs.md)。 ### 容量保护与显示尺寸补测 「应用与维护」先显示各类数据占比和手动清理,再提供默认开启的容量保护总开关。关闭后保留各项设置,停止容量检查和自动清理;手动清理仍可使用。上限使用整数 `GiB`,设置保存在本机 `state/storage-policy.json`,不写入同步账本。磁盘保留空间留空时按每块磁盘总量的 5% 保留,最低 1 GiB、最高 40 GiB;数据与缓存上限留空表示不设总量上限,不强制使用统一的 10 GiB。 后台任务的检查点查系统盘、数据根、全部独立配置目录、临时目录与外部缓存目录所在卷的实际余量;播放与浏览只查它们实际会写的系统盘、`generated` 与临时目录所在卷,别的卷快满不挡播放。缓存与数据按实际分配量统计,硬链接按设备与文件身份只计一次,删除后仍有硬链接保留的文件不计入释放量;统计期间被删、被占用的单个文件跳过,不作废整轮统计。显式配置的目录链接按其目标读取,内部目录链接不跟随;分类图仍按目录项的文件大小统计。 磁盘余量在每个检查点实时读取。总量要逐文件统计,只在后台线程里做,请求与任务检查点都读最近一次读数,不展开目录;间隔按变化速度分开:Peach 缓存与外部缓存每 5 分钟统计一次,整个数据目录每天一次,进程启动 5 分钟后才开始统计数据目录。读数保存在 `state/storage-budget-readings.json`,重启后与托盘任务、命令行共用,未到间隔不重新统计;同一类统计同一时刻只有一个进程在跑,统计失败 1 分钟后重试。只改上限数值不作废读数;手动清理、自动清理、迁移后,开始早于它的统计结果不再发布。尚无读数时只由磁盘余量把关;预估写入量的检查(如升级前备份)按读数加上预计写入量判断。在途步骤和统计间隔可能造成超过设置上限,不能将此设置当作文件系统配额。 超过余量或总量上限时,自动清理先按最新读数重算缺口,再分层删除可重建的产物:先 HLS 分段,再转码副本,最后能从本机封面、头像重新缩小的缩略图;同层按修改时间从旧到新,分段与转码副本命中时会刷新修改时间,所以先删的是最久没用的。最近 10 分钟内用过的、正在写入的临时文件与删不掉的文件跳过。清完仍不够时 5 分钟内不再重走缓存目录。播放请求只排一次后台清理,不在请求里走缓存目录。预览图、下载的封面与资料、外部缓存不自动清理。 清理后仍超过总量上限时,只暂停刮削、补修、抽帧等让数据增长的后台任务,播放、浏览与网络媒体缓存照常;只有播放会写的卷余量低于保留值时才停止写入播放缓存,ffprobe 等只读探测不受影响。统计失败或外部缓存目录失联时,后台任务暂停,不把未知当作零;播放照常并按实时余量把关。设置页的「已暂停」只来自后台任务的检查点。 手动迁移前先停止 Peach,完整保留数据目录中的 `state`、账本、人工资料和凭据;迁移后更新 `PEACH_DATA_ROOT` 或 `[directories]`,Docker 更新卷映射,再启动服务。独立目录、挂载目标或目录链接发生变化时,旧容量统计和暂停回执失效,页面需重新统计,容量闸门重新测量;扫描期间目录变化则中止本次统计。没有目录身份的旧版统计也需重新取得。系统不会猜测新目录或改写媒体账本路径。 外部缓存迁移后需更新容量设置中的路径;手动填写的目录链接保留其原路径,重定向后按新目标检查。旧目录不可访问时暂停受保护写入,不使用其父目录余量代替,也不将占用算成零。跨系统迁入的旧路径保留在表单中供修改,仍可关闭容量保护。NAS 仅能取得 Peach 进程可见的文件系统余量,不代表已核实存储池、快照、克隆共享块或 NAS 独立用户配额。 自动清理的缩略图只限有来源签名且本机原图仍在的封面、头像 WebP;原始媒体、账本、人工资料、预览图、原图与备份保留,旧备份仍可通过原有分类入口手动清理。外部缓存目录为空时,页面用已保存的本机 CloudDrive 地址和令牌读取目录,需“查看系统设置”权限,填入表单后保存生效;远程服务、目录不可访问或未配置时可手动填写 Peach 可访问的映射目录。外部缓存按真实占盘监测;Peach 不删除 CloudDrive 等程序的缓存,也不能修复它们内部的容量记账。 只为已启用的数据、缓存或外部缓存总量上限统计对应目录;未设置总量上限时不展开目录,未测占用保留为空。后台统计按间隔复查真实磁盘余量,途中触线就中断,不在遍历中清理或重扫。 SAR 显示尺寸按独立升级规则自动补测已登记的视频,只领取免费来源和有既有有效尺寸的待办,沿用任务中心暂停、重试与断点。仅运行探测,不启动全库抽帧;尺寸变化时只标记该作品的旧预览需重建。成功检查点绑定资产位置、路径、账本大小和修改代际,旧全库重探回执没有代际证据时不直接视为新规则成功。备份写入前及分页过程中检查所需空间;容量拒绝不阻断其他本地资料服务。 容量推荐需要按馆藏规模和已观测使用情况分组的研究样本。当前未提供群体容量模型,不将当前用量乘固定百分比伪装成群体推荐。容量与播放活跃日的观测范围、授权和发送规则见[诊断与群体研究](DIAGNOSTICS.md)。 ### 设置文件出问题时 - **已经有设置文件**:`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> [根目录]` 把一个目录里的文件登记进数据库。它只新增记录、刷新大小和修改时间,不改人工确认过的信息,也不删除记录。 目录已设置归属用途且开启「新文件沿用此规则」时,新登记的文件按最近一层规则关联;已有冲突保留,见[目录浏览](DIRECTORY_BROWSING.md)。 - 不给根目录时,扫描这个来源在 `[media.locations]` 里声明的全部目录。 - 给了根目录时,它必须在某个声明的目录之内(macOS 上是挂载点之内),否则会被拒绝,因为登记进去的路径无法换算回本机路径。 - 扫描按完整目录段跳过已确认的 NAS 回收站、快照和系统元数据目录;不将任意 `@` 或点开头目录视为系统目录。平台名称和规则来源见[系统目录复用记录](REUSE.md)。 ### 长时任务断点续跑 任务中心为本机执行的任务提供「暂停」「继续」「取消」。暂停保留当前任务和已保存结果;在途步骤尚未停稳时显示「正在暂停」。继续沿用原任务,取消则等待所属线程和子进程退出,再显示「已取消」,保留已完成结果并停止后续工作。父任务的操作覆盖全部后继,包括列表中未展开的任务。文件替换等提交步骤先完整提交,再响应控制请求。云下载在远端执行,操作以渠道实际支持的能力为准。 播放触发的文件头修复、发现页资料读取和诊断导出同样登记在任务中心。媒体子进程可暂停、继续和取消,暂停时长不计入处理超时。支持断点恢复的任务在重启后保留暂停意图;没有恢复入口的即时任务在服务关闭后结算,不留下无法继续的排队任务。 活动任务显示蓝色 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 通知需另行配置;已明确关闭的设置保留。监控使用系统文件事件和去抖队列,空闲时等待事件,不定期遍历媒体目录;网络盘不递归监控。已收到、还在等文件写完的路径记在状态目录的 `push-discovery-pending.json`,重启后接着登记。未收到通知或服务停机期间新增的文件不会自动补扫,由「同步新增文件」补齐。 推送发现登记了一部新影片、或云下载入库并整理完成时,打开着的 Peach 页面会弹一条 toast,点「打开」进入这部作品。通知随任务列表轮询读取,最多晚 10 秒。扫描、「同步新增文件」和批量补全登记的作品不弹;同番号有云下载任务的,等它整理完成再弹一次;一轮到了 3 部以上时合成一条。通知只在服务进程内存里,重启后不补弹。 本机移动事件和已记录的系统文件身份可保留改名、同卷移动后的影片 ID、人工资料和个人记录。文件身份随本地扫描和登记积累;升级前没有身份记录、停机时已经发生的移动,以及跨卷复制,不能仅凭同名或同大小自动认作原片。旧路径仍存在的副本与硬链接分别登记。改名时换了编码、文件身份对不上的影片,扫描按番号认回:同一媒体目录下这个番号的在库影片只有一部且旧文件已不在,新文件所在目录也只有这一部同番号视频,就沿用原记录与它的标签、封面和个人记录,时长与分辨率重新探测([ADR-0131](adr/0131-scan-relocates-missing-row-by-code.md))。 一趟任务的结论、「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.` 和 `media.storage_roots.` 持久保存身份。路径、挂载、来源及读取策略归根目录,名称与图标归媒体库。`media.locations` 等路径表是兼容投影,手动配置以身份表为准,字段与升级依据见 [ADR-0115](adr/0115-library-and-storage-root-identity.md)。 每个媒体库还可以设来源色和处理方式。来源色给这个库的卡片和列表行铺一层淡色,默认不上色。处理方式有三档:「自动补全」缺什么联网补什么;「仅使用本地资料」只读本地 NFO 和同目录图片,仍读取视频信息、生成九宫格,不联网补资料、封面和人物图片;「自定义」逐项选择步骤。配置里写作 `color`、`policy`(`auto` 不写)和自定义时的 `stages`,定时扫描、增量入库和重试都按作品所属媒体库遵守,依据见 [ADR-0116](adr/0116-library-processing-policy.md)。 路径配置首次保存时按原同名分组写入稳定身份,写入前把原文件留成 `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 部署](DOCKER.md#配置文件与路径)。 - 两项使用相同的媒体来源键,例如 `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](adr/0050-settings-modal-holds-values-pages-hold-work.md))。 扫描与采集逐项保留结果。文件抽帧失败、资料请求超时等单项问题记入清单,继续处理其余文件与后续阶段;所有阶段结束后,有问题的任务显示「处理已结束,部分项目需处理」,可查看全部内容或仅重试未完成项。状态保存、数据库等公共环节异常导致的中断单独显示。未取得发行资料的视频仍可在「全部内容」浏览;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 接入](CLOUDDRIVE_API.md)。 启动弹窗同时显示视频文件数、文件名或已有资料可识别的 JAV 文件数与去重后的部数。尚无登记视频的目录分批列出,只识别名称、不打开媒体内容、不写入账本;统计过程中可直接开始扫描,关闭弹窗后不再请求后续批次。新任务沿用同进程 5 分钟内该范围的预检结果,随后用实际扫描更新;账本中已有的记录优先。首次网盘预检的耗时取决于挂载工具列目录的速度;文件名没有番号的 JAV 要在读取配套资料后补充识别。明细里的每部平均预估只针对本次待补资料,缓存齐全的影片不进入这个均值。右下「管理媒体库」链接关闭弹窗并进入媒体库设置,可在那里调整各目录的读取选项。 文件名不必只写番号。番号后面跟片名、女优或字幕说明(`CAWD-987 片名`、`GVH-520【中文字幕】片名`)时,取文件名里第一段「厂牌-至少三位序号」;FC2 商品号(`+++ FC2-PPV-1234567 片名 前編`)写在文件名任意位置都能识别。内置规则认不出的命名,在「媒体库与入库 → 番号识别规则」里每行写一条正则表达式:对完整文件名搜索、不分大小写,番号写在命名组 `(?…)` 里,没有命名组时取第一个括号;取出的部分仍须符合番号格式。规则保存在账本里,各设备共用,保存时检查语法。「处理」时对还没有番号的视频先按这些规则识别,再按内置规则识别;已有番号不会被改写。启动弹窗的预检只按内置规则统计。 本机的 `state/library-processing-traffic.json` 保存近期同类用量。视频探测和单帧读取按媒体目录分开积累;资料采集按待访问来源、封面需求和直连/代理分组。至少取得 3 个有效样本后采用最近 50 次的平均值,后续同类工作随之校准;失败、零下载及计量不完整的资料采集不作为正常样本。首次使用无历史时仍采用默认计划值。 常用的本机设置: - 「通用 → 开机自启」:开机后启动 Peach、静默启动(开机后只显示托盘图标,不打开网页)、在桌面创建快捷方式。 - 「网络与访问 → Peach 代理」:选系统代理、直连或自定义地址。默认外网 HTTP 请求与采集来源选「Peach 代理」时共用这里的设置,来源选「直接连接」则使用直连。保存后新建客户端按新设置运行,已有任务与长连接沿用创建时的配置。覆盖范围及本机、网盘和独立工具边界见[来源连接设置](SOURCING.md)。 ### CloudDrive 配置 115 和 PikPak 网盘由 CloudDrive2 挂成本机的盘,Peach 把它当普通文件夹读取。挂载步骤、来源 ID、macOS 上的路径对应、缓存与读取设置,以及新文件自动入库,都在 [CloudDrive 配置与调优](CLOUDDRIVE.md)。配置页里的「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](adr/0138-user-triggered-ledger-backup-and-restore.md)。 - **立即备份**:后台复制当前账本,进度同时显示在任务中心。复制完先做完整性检查,通过才命名为 `ledger.pre-manual-<时间>.db`;没通过的那份直接删掉。手动备份和自动备份同一套保留规则(见「迁移、备份与运维脚本」)。 - **从备份恢复**:只能在写入端执行,且数据目录里没有别的任务在跑。确认后依次检查备份的完整性和结构(来自更新版本的备份拒收,较旧的先迁到当前结构),把当前账本另存为 `ledger.pre-restore-<时间>.db`,再把备份写进账本。恢复期间不能启动新任务;任务中心的历史保留恢复前的记录。完成后刷新页面查看恢复后的资料。 - **中断处理**:写入账本前会在账本目录留下 `ledger.restore.json`。恢复被打断(断电、强制结束)后,下次启动服务或运行 `peach migrate upgrade` 时先处理它:当前账本完整就保留;不完整就用已经迁好的暂存 `ledger.restore-staging.db` 补完恢复;暂存也不能用就退回恢复前另存的那份。结果显示在「账本备份」里,同时写入 `ledger.restore-result.json`。 - 账本损坏、服务读不出资料时,「账本备份」照常可用,恢复在后台进行,进度只在这一页显示。 容器的数据目录是宿主机挂载的卷,在容器里迁移会离开卷,重建容器时数据丢失,所以设置页不提供迁移,改为列出在宿主机上迁移的步骤和命令,见 [Docker 部署](DOCKER.md#迁移数据目录)。 ### 卸载 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-.log`;Python 可捕获的原生崩溃栈写入 `crash-.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://.local:<端口>`。测试包用 HTTP,不加密。 - **源码部署**:托盘在 80 端口提供 HTTP、在 443 端口提供 HTTPS,浏览器打开 `https://.local`。发布的局域网 IPv4 地址默认自动选择,也可以用启动参数或 `PEACH_LAN_ADDRESS` 指定。 `` 是设置文件 `[server].mdns_name` 的值,Peach 会在局域网里广播这个名字。 ### IPv6 `host` 为 `0.0.0.0` 或 `::` 时,Peach 在同一个套接字上接收 IPv4 和 IPv6 连接;系统没有 IPv6 时只监听 IPv4。`peach serve --ipv4-only` 保持只监听 IPv4。 - mDNS 在服务确实接收 IPv6 时,为 `.local` 同时发布 A 记录和 AAAA 记录。AAAA 取与发布的 IPv4 同一块网卡上的全球单播和 ULA 地址,不含链路本地地址;运营商更换前缀后,下一轮地址复查(20 秒)重新发布。 - IPv6 地址可以从公网直接路由,所以 Peach 只接受回环、链路本地、ULA(`fc00::/7`)以及与本机网卡同一 /64 前缀的 IPv6 连接,其他 IPv6 来源收到 403。IPv4 来源的判断不变。 - macOS 源码部署的 80/443 由 pf 只转发 IPv4,两条服务带 `--ipv4-only`,不发布 AAAA 记录。 - 证书只签发局域网 IPv4 地址。用 `https://[]` 直接访问会报证书不匹配,用 `https://.local` 访问不受影响。 ### 访问密码与登录 - 访问密码在首次设置页或配置页「网络与访问 → 访问密码」里设置,可以留空。留空时,能连到 Peach 的设备不用登录就能进入。终端 `peach init` 默认不设访问密码。 - 已有部署如果没有访问密码设置,登录页继续使用访问口令。已登录的本机浏览器可以在配置页设置自己的密码,或明确关闭登录要求。 - 修改密码需要当前密码;关闭密码还要勾选确认访问范围。修改或关闭立即生效,其他浏览器的登录会失效,当前设备保持登录 30 天。 - 登录页勾选「保持登录」保持 30 天;不勾选只在这次浏览器会话内有效,最长 12 小时。刷新页面不会延长有效期。 - 配置页「网络与访问 → 已登录的设备」列出每个登录过的浏览器:浏览器与系统、来源网段、最近活动,当前浏览器标为「本机」。在运行 Peach 的电脑上可以撤销其中一台,或撤销本机以外的全部;修改或关闭密码仍会让全部设备退出。 - 密码以 scrypt 哈希保存在本机 `/secrets/access.json`,设备记录在同目录的 `browser-sessions.json`,只存登录令牌的摘要,不存令牌本身和完整 IP。两者都不进数据库,也不参与同步。 - 升级前登录、仍在有效期内的浏览器不会被登出:它下一次访问时补进设备列表,此后同样可以撤销。 安全模型的完整说明见 [安全说明](../SECURITY.md)。 ### 访问口令 脚本和 API 调用使用访问口令,放在 `X-Token` 请求头里。 - 非回环地址上启动服务必须有访问口令,首次初始化会自动生成。 - 口令保存在 `/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 这类公开证书)。证书和私钥都在本机 `/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://.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 填成 `.local`,并把项目 CA 填进 CA Pool,否则本机自签证书过不了校验。 3. 在配置页「Cloudflare 公网入口」里切到「命名隧道」,填公开主机名和隧道令牌,点「保存配置」。令牌只写进设置文件的 `[tunnel] token`,页面不会再显示它,数据库、日志和 `/healthz` 里也没有它。换令牌时填新的;留空表示沿用已保存的那一份。 4. 建议在 Cloudflare Access 里给这个主机名配一条身份策略。这一层完全在 Cloudflare 后台配置,Peach 不读取也不管理;Peach 自己的访问密码仍然是启动隧道的前提,两道门同时存在。 整个站点都拒绝搜索引擎收录:每个响应都带 `X-Robots-Tag: noindex, nofollow, noarchive`,`/robots.txt` 不用登录也能读到 `Disallow: /`,主页面和登录页另有 ``。这一项不能关闭。 ## 播放与转码 视频画质按显示尺寸的长边分档:3000 及以上为 4K,2000–2999 为 2K,1800–1999 为 1080P,1200–1799 为 720P,其余为低画质。已有视频以已测尺寸自动修正符合旧规则的分档,无需重读文件。需要还原时,`scripts/revert_auto_landing.py --source upgrade:quality-resolution` 先列计划,再用 `--apply --backup` 执行;尺寸或画质已变化的行不还原。 浏览器能直接播放的格式(例如常见的 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 秒。 - `.ts`、`.m2ts`、`.mts` 起播前先探测编码:视频是 H.264(`yuv420p`/`yuvj420p`),或浏览器报了能力的 HEVC,就整片换封装成 MP4(视频复制,音轨不是 AAC 时转 AAC),产物和其他换封装缓存一样文件名带 `-copy`,换一次后命中缓存,受容量保护清理;解不了的编码仍走 HLS 转码分片。换封装要等整个文件复制完才开始播放。 - 能保留的码流尽量保留: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 软件解码。 - 「应用与维护 → 视频播放」的「画质上限」默认原画,可选 1080p、720p、480p,按短边计(竖屏片子的 720p 是宽 720)。只管重新编码的整片与 HLS 分片:短边超过上限才缩小,同时把峰值码率压到 8、4、2 Mbit/s;直接播放和只换封装的片子保持原画。帧在显存里的 CUDA、VAAPI、QSV 全硬件链分别用 `scale_cuda`、`scale_vaapi`、`vpp_qsv`,其余用软件 `scale`;AMF、QSV、VAAPI 改用带峰值的 VBR。档位存在 `media-processing.json` 的 `playback_max_height`(`0/1080/720/480`),换档后新缓存的文件名带档位,原画沿用原来的缓存。 - 同时最多进行 2 个转码或探测,单次最长 1 小时,关掉播放页会取消对应的任务。 - 网盘来源(115、PikPak、光鸭云盘、OneDrive 与其他已挂载网盘)的视频通过媒体库配置中声明的挂载目录播放,哪些来源按网盘处理以 `resources/media-sources.json` 登记的 `cloud` 为准。能不能播,以在 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 按显卡序号逐个探测;QSV 优先让解码、缩放和编码都留在 Intel 显卡上,以 Windows 服务方式运行时建不出这条链,改为 D3D11VA 解码后交给 QSV 编码。偏好通过 `/api/media-processing` 的 GET/POST 读写,`preview_acceleration` 和 `playback_acceleration` 分别接受 `auto/software`,`playback_max_height` 接受 `0/1080/720/480`;省略的字段保持现值。这个接口与时间轴缩略图的 `/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 图片轨。已有产物只读,时间轴采集遇到可用预览会跳过。命名、读取范围和缺少时间索引时的处理见[已有时间轴预览](VIDEO_PREVIEWS.md)。 ## 文件整理 在「数据管理 → 整理」选择来源。右侧路径框可直接输入目录,旁边的文件夹按钮在运行 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,也不代表其他挂载方式已经验证。 ### 垃圾文件 「垃圾文件」复核覆盖已配置物理媒体来源的各种文件类型,在线网址不在其中。检查复用同一套评分,先核对原文件名、目录、时长、体积与相邻正片,再决定是否隔离。 | 流程 | 检查与处理顺序 | | --- | --- | | 添加媒体库、全量扫描 | 登记与配套文件识别 → 按本次目录检查 → 允许自动读取的媒体探测 → 重判 | | 推送发现、单文件登记 | 登记与配套文件识别 → 检查该资产 → 允许自动读取的媒体探测 → 重判 | | 云下载 | 落地并绑定正片 → 检查下载范围 → 探测并重判 → 采集资料与预览 → 重判 → 按模板整理 → 派发后继任务 | | 补全资料、补全预览 | 检查当前范围 → 探测并重判 → 读取本地资料与生成预览 → 刷新活动资产 → 联网采集适用资料 | | 仅采集资料 | 检查已有证据 → 读取配套资料 → 重判 → 联网采集;不读取视频或抽帧 | | 手动整理、维护脚本 | 执行整理和生成九宫格前检查;独立探测脚本在探测前后检查;整理预览与只读盘点保持只读 | 探测沿用来源的计费与代理保护,不为垃圾检查额外读取媒体。探测后先接回能确定归属的个人记录,再重判垃圾。没有有效时长的视频只进复核。抽帧跳过在线来源、STRM、ISO 和开了流量保护的目录,免费网盘目录与本地一样处理;作品卡上对单部影片点「补全预览」时,流量保护目录先确认,再只为这一部读取。完整处理在关闭视频预览时跳过抽帧。失败任务保留检查点与问题记录,重试复用已登记资产、测量值与整理日志;资料或整理失败时不派发该下载的后继任务。资料采集的问题全是来源限流或拒绝访问时,其余资料已落库,文件照常整理,任务记为完成并在详情里写明哪项等来源恢复后重新采集;混有其他问题时照旧失败。有码作品的 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`。第一步的 `interface_language`(`auto` 或已登记的界面语言)在新建账本时写进同步设置,接到已有账本时不改。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` 并发布 `.local:<端口>`;托盘打开页面和健康检查始终走回环。源码部署由 `build_service_specs(tls_dir=..., mdns_hostname=...)` 构建 HTTP 跳转与 HTTPS 入口,TLS 材料没齐就等下一轮。mDNS 名由这里传进规格,不读 import 时的值。 - 首次扫描不在引导服务里跑,因为那个进程在切换时就会被停掉。表单勾了「现在扫描」只写一个一次性标记 `/state/first-scan.request`(内容是来源 ID),托盘切换完成后读取并删除它,用子进程跑 `peach scan <来源>`,输出在 `/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` 自己清掉: ```bash 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@ · 托盘构建 <构建提交>,落后 N 个提交`。数不出来(身份未取得、提交不在本检出历史里)按陈旧处理,重建范围收窄到 `src/peach/`。 - 「同步开发进度」在 `ahead`/`current`/`error`/`unconfigured` 下走本地重建;健康轮询另外每 5 分钟读一次本地 HEAD 自动触发,同一个 HEAD 只自动试一次,首次设置没完成时不触发。 - 重建流程是:完整测试 → 暂存构建 → 检查打包的迁移资源 → 备份 → 替换。任一步失败只发通知,旧托盘和服务继续运行,通知里写明卡在哪一步,日志在 `/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 异常退出恢复](#macos-异常退出恢复)。 适用于代码已经在检出里、只需要让运行中的托盘重新加载、不换二进制的情况。 - 不要用 Computer Use 点托盘。`python scripts/restart_windows_tray.py` 按精确的 EXE 路径找到 pystray 隐藏窗口,发送正常停止消息,等托盘自己关掉子服务,再静默启动新托盘,并确认新托盘接管了两个服务。 - 找不到唯一的窗口或退出超时就拒绝执行,绝不强杀后另起。旧托盘退出后,要等它名下的子服务退干净才起新托盘。端口被不归旧托盘管的 `serve` 进程占着时,开工前就拒绝并报出它们的 PID,因为换托盘换不掉它们。 - 托盘把自己拉起的子服务放进 kill-on-close Job:托盘被 `Stop-Process -Force` 之类强杀时,整棵 `serve` 子树一起退出,不会留下孤儿进程继续占着 80/443 跑旧代码。托盘每轮健康检查发现端口没响应会补拉;看到健康但不归自己的服务只记 warning,不接管。启动与补拉记录在 `/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 数据库结构与迁移不一致等未就绪项写进日志和启动通知。 - 新托盘把这几步写进 `/state/runtime-prepare.json`,命令读回来一起报告。stdout 是一行 JSON,`ok` 为 false 时退出码 1:被闸门拒绝、依赖同步失败、迁移失败或服务未就绪都算。 - 托盘菜单的「重启服务」:依赖一致时只重启子服务,在子服务停着时迁移;依赖与 `uv.lock` 不一致时分离地拉起 `restart_windows_tray.py --source --force` 整体重启托盘,输出追加在 `/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 提交号在 `/state/source-sync-build//` 构建 → 让暂存包自己跑一次 `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](adr/0137-release-sums-ed25519-signature.md))。 - 版本号只在 `src/peach/__init__.py::__version__` 里定义,采用 pre-1.0 SemVer。Git 提交是构建标识,`vX.Y.Z` 标签是发布点,推到 GitHub 就触发 Release 工作流(见「桌面入口与发布」)。 - 版本号在发布时才动,一次发布加一格,所以每个 `X.Y.Z` 都有一份能下载的制品。 - **依赖升级**:定版前完成[每次发版检查](TESTING.md#每次发版检查)的依赖升级批次,包括适用的兼容修改、派生产物、完整验证与本地集成;暂不能升级的保留具体原因和失败证据。定版后发现需要改依赖时,先保存发行说明草稿,撤回本轮尚未提交的版本修改,完成升级后重新定版。 - **定版**:在干净的 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` 的 `Unreleased` 一节定成这个版本号(每行「English / 中文」,Release 正文英文在前、中文与下载段折叠,见 `scripts/changelog.py`)。区间只改了文档、技能和测试时直接拒绝,因为那样打出的包和上一个标签完全相同。minor 及以上的版本还须先在 `src/peach/release_notices.py` 写好这一版的更新公告,缺了也直接拒绝([ADR-0152](adr/0152-release-notice-after-upgrade.md))。公告的 `features` 连同 `refs` 里的 issue 或 PR 编号会写成 Release 正文开头的重点,旧版本检查更新时只显示这一组。`--bump` 只写文件不提交,并打印定版的那一节供人检查;不带 `--apply` 只打印计划。 - **发布**:确认之后运行 `python scripts/release_tag.py --ship --apply`,一次完成剩下四步:提交 `src/peach/__init__.py` 与 `CHANGELOG.md`(消息 `chore(release): 版本 <新版本>`)、推送 master、每 30 秒查一次这个提交的 Test 工作流、变绿后创建并推送 annotated tag。打标签后继续等 GitHub Release 把 README 下载直链对应的制品全部上传完,再单独提交 `docs(readme): 下载直链指向 <标签>` 并推送;等待期间 README 仍指向上一版,中断后用 `--point-readme --apply` 补做。默认最多等 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` 为真时才输出一句,其余情况什么都不打印。已问记录在 `/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 份,Peach 配置「保留期限」里可选 2、5、10、20,存在本机 `state/retention.json`)「24 小时内」「比 `ledger.db` 新」三类全部保留,其余连同 `-wal`/`-shm` 删除。Windows 托盘每次启动自动执行;`scripts/prune_ledger_backups.py` 手动运行时默认只列计划,`--apply` 才删除;数据库 `integrity_check` 不是 ok 时拒绝清退,退出码 2。每份备份一百多 MB,5 天不清就是 7 GB。 - 整理备份自动清退:下载后整理与手动整理写入前各留一份整库备份,放在 `/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`。 - `/logs` 里的 `*.log` 默认保留半年,不限大小(`peach.log_retention.sweep`,托盘在启动任何子进程之前运行;天数在「保留期限」里可选 30、90、183、365,同样存在 `state/retention.json`):超过保留期没写过的文件整份删除;还在写的文件按自然月分段,上次写入在更早月份的改名成 `<名字>.until-<最后写入日期>.log`,再过保留期删除。子进程直接追加 stdout,不经过 `logging`,所以按文件处理,不按行处理。 - 更新与打包产物自动清退:托盘每次启动只保留最近 2 份 `dist/Peach/Peach.pre-source-sync-*.exe` 备份,并删掉 `/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 手机、生产服务是否已重启。