Peach: Local-first video metadata scraper and media manager.
日志与诊断
本页说明异常日志、浏览器错误上报、诊断导出与可选远程诊断的边界。正常取消、缓存回退、来源未命中和任务互斥保留各自状态。
环境与故障证据按同一套采集和分类函数产生,各输出入口按用途取字段:reporting_identity 提供程序、构建与主机量级,diagnostic_exceptions 提供异常链的结构化错误码和媒体故障类别,diagnostic_context 规范浏览器、播放和运行状态。输出入口不自行重新识别同一故障。
| 输出 | 使用范围 |
|---|---|
| 本机日志 | 脱敏异常链、错误码、浏览器与播放现场、请求到达和响应媒体类型 |
| 诊断 ZIP | 从本机日志和当前运行状态汇总有界证据;保留采集失败与未取得状态 |
| 远程技术诊断 | 仅投影已声明的代码位置、构建身份、结构化错误码与固定故障类别;详细浏览器和播放现场只在本机 |
| 版本统计、群体研究 | 复用程序和构建身份,分别遵守既有字段、开关与频率契约 |
桌面制品验收在临时 Peach 数据目录显式关闭版本统计与错误上传,并在首启提交中保持关闭,避免合成测试进入正式遥测。
反馈入口
馆藏处理失败时,重试失败项,再从托盘「导出诊断报告」或系统诊断页「下载诊断报告」取得 ZIP。用户只需提供一个 ZIP。桌面部署下载限运行 Peach 的本机;Docker 部署允许已登录的私有网络客户端下载,拒绝代理转发。网页不可用时,可按 Docker 诊断导出 在容器内生成 ZIP。已登录的同源设备可以上报浏览器错误;开放访问模式不提供匿名远程上报。
错误发生时必须实际记录底层证据。完整问题清单位于 state/library-processing-<job_id>.issues.jsonl。通用问题清单不能还原被丢弃的 FFmpeg 错误;没有原始记录的历史失败需要重试取证。
诊断 ZIP 对 JSON 状态文件最多读取完整的 16 MiB,解析后按字段脱敏。每个状态文件的导出内容最多 96 KiB;需要缩减时,先保留任务标识、状态、阶段和计数,再纳入步骤、问题预览与其他字段。缩减后的集合最多保留前 20 项,文本最多保留 4000 字符,嵌套最多 8 层;字段放不下时继续减少集合项数。JSONL 问题清单读取尾部 96 KiB,只导出可完整解析的近期记录;截断的首条记录、损坏记录和超出脱敏后大小上限的记录不导出。媒体名称、路径及凭据沿用字段脱敏。
report.json 的 logs 清单记录各文件的 source_bytes、exported_bytes、status 与 truncated。JSON 字段缩减会标记 projected,并记录未纳入的顶层字段数 omitted_fields、前 64 个顶层字段中集合的原始数量 collection_counts;顶层数组使用 collection_count。JSONL 使用 skipped_records 记录读取范围内未导出的记录数,截断的首条记录不计入该数。空 JSON、损坏 JSON、超出读取上限、无有效记录等情况只记录清单状态,不生成空文件。
| 清单状态 | 含义 |
|---|---|
included |
已导出有效内容;是否缩减另见 truncated 和 projected |
empty_json / empty_jsonl |
JSON 为空白内容,或 JSONL 为零字节 |
unreadable_json / invalid_json_shape |
JSON 无法解析,或顶层不是对象、数组 |
json_size_limit / json_depth_limit |
JSON 超出完整读取上限,或解析、脱敏时嵌套过深 |
json_projection_limit |
JSON 字段缩减后仍无法在大小上限内保留有效内容 |
no_complete_records |
JSONL 读取范围内没有可导出的完整记录 |
证据链
| 环节 | 持久证据与核验 |
|---|---|
| 启动、CLI、托盘 | 配置及可选依赖加载前安装异常钩子;主线程、后台线程、unraisable、asyncio 和 warning/error 日志写入 errors-*.log,原生故障写入 crash-*.log;不可写时使用备用目录 |
| HTTP 请求 | 未处理异常与 HTTP 5xx 记录 traceback、方法、路由模板、状态码和 error_id;响应头 X-Peach-Error-ID 与记录关联;请求参数、正文和鉴权头不作为上下文采集 |
| 后台任务 | 异常记录任务键、job/run 编号、线程与 traceback;显式返回失败的操作记录失败消息;暂停、互斥和取消沿用任务协议 |
| 抽帧、拼图、探测 | 保留退出码、超时、采样位置、时长、工具来源、色彩重试和有界 stderr;media-probe、preview、frame-capture、frame-tile 与 library-preview 覆盖各入口 |
| 图片有效性 | Pillow 完整解码确认图片;纯色小 JPEG 可用,残片、非零退出和陈旧输出不能算生成成功 |
| 外部来源、下载 | 来源授权、限流、冷却与未命中使用领域状态;意外失败使用现有异常日志和任务回执;ZIP 包含来源健康状态与时间,来源响应原文留在本机 |
| 关注检查、媒体代理 | follow-check 与 follow-media 本机事件记录来源、来源及条目编号、失败阶段、操作和可用的上游状态码;媒体事件区分帖子来源与资源来源,异常链与代码位置随支持包导出。地址、凭据和私人路径统一脱敏,不记录上游响应正文,不扩大远程诊断字段 |
| 更新与回滚 | 安装、回滚失败保留 traceback;ZIP 包含启动准备、更新状态、源码更新日志、托盘重启日志及近期迁移日志 |
| 隧道 | ZIP 包含 cloudflare-tunnel.log 与脱敏运行状态 |
| 浏览器 | 保存消息、堆栈、脚本文件名、行列、页面与浏览器标识;查询参数不进入页面字段;同源、有效登录、每分钟条数和请求体积门槛有回归 |
| 媒体工具 | 诊断报告与 ZIP 检查实际版本、可执行性及 AV1 软件解码器;工具失败在本机保留既有错误分类,包括缺失媒体、权限、磁盘余量、无效媒体与解码器不可用,完整路径脱敏不影响该分类;/healthz 只使用轻量路径检查,不执行外部工具 |
本机诊断快照
report.json 汇总以下技术证据。系统诊断页下载时携带当前浏览器快照;托盘和 CLI 导出从近期本机错误日志提取已记录的浏览器与播放上下文。未记录的浏览器环境标为 unavailable,不能据此判断浏览器或编码不受支持。
| 范围 | 字段与来源 |
|---|---|
| 程序与系统 | 程序版本、分发方式、冻结构建提交与时间、源码检出的提交、Python、操作系统版本与 Windows 版本类型、架构、进程关系、逻辑核数、内存档位、活动线程数、SQLite 和关键运行依赖版本;源码提交不证明运行中的进程已加载该版本 |
| 配置与存储 | 监听地址类别与端口、托管方式、同步和隧道开关、代理环境是否存在、数据盘总量与余量、运行目录存在状态、媒体预览和播放加速偏好 |
| 浏览器 | User-Agent、客户端提示中的品牌、完整版本、平台版本与架构、语言、时区、安全上下文、联网状态、Cookie 与本地存储可用性、视口、像素比、触控点、逻辑核数、浏览器提供的内存档位和可读取的 WebGL 图形厂商与渲染器;详细客户端提示最多等待一秒,受限或不支持时保留原因 |
| 播放能力 | 原生 canPlayType() 和 MSE 对 H.264、HEVC、AV1、VP9、AAC、AC-3、Opus 的能力声明;MediaSource 和 MediaCapabilities 是否存在。能力声明不能证明具体媒体已成功解码 |
| 播放失败 | 原生错误码与原因、网络和就绪状态、播放位置、时长、尺寸、缓冲区、播放设置、源协议、同源状态,以及最近八次媒体请求的状态、耗时与字节数 |
| 服务端播放 | 媒体请求到达记录、Range、播放方案、文件响应实际声明的媒体类型、已缓存的编码与像素格式、时长、文件世代及硬件策略和已有探测结果;诊断不另读媒体或触发转码 |
| 检查与任务 | 数据库及迁移详细状态、访问保护、端口状态、近期失败任务编号与时间、脱敏挂载状态、来源健康状态及既有处理、更新和交付回执 |
浏览器和播放上下文只写本机日志,不进入远程上报入口。分享包不包含账号、Cookie、凭据、完整媒体地址、URL 查询串、媒体名称或馆藏清单。记录有字段白名单和大小上限;日志按既有尾部上限导出,汇总最多八份浏览器快照和二十条播放记录。没有完成的请求不会出现在 Resource Timing 中,应结合服务端到达记录判断。工具不可用、存储读取失败、能力 API 不支持与尚未探测分别保留状态或原因。
同一份浏览器环境每分钟记录一次,环境快照独立于每分钟二十条错误的预算;频繁刷新不会占用错误记录名额。显式下载保留当前客户端的快照。
项目日志与 ZIP 的 server_timezone 记录服务主机的实际时区名称、UTC 偏移及带偏移的本地时间;浏览器的 timezone 和 utc_offset_minutes 独立记录访问设备的实际环境。偏移以 UTC 以东为正,例如 UTC+8 为 480。日志 at 使用 UTC 便于排序,server_timezone.local_time 表示对应本地时间;不能用服务主机时区代替客户端时区。时区名称未取得时保留偏移、本地时间和读取失败状态,不能填入推测时区。任务恢复调度器使用 UTC 仅用于固定间隔调度,不决定诊断环境的时区。
访问日志保留已知媒体路由、API 路由、HTTP 版本与响应状态码;URL 查询串整体移除,未知路径继续隐藏。206 只表示范围响应已发出,不能证明浏览器完成了解码。
可选远程诊断
安装器、首次设置和设置页「应用与维护」提供「发送版本统计与错误诊断(推荐)」单个选项,默认勾选,同时控制版本统计与错误诊断,可取消勾选或在设置页关闭。静默安装保留已有选择。选项保存在本机 state/remote-reporting.json;没有记录时两项默认开启,已保存的关闭选择持续生效,损坏或只开启一项的记录均不发送。不写 ledger。缺少接收端时页面明确提示不会发送,仍可保存选择。
| 类别 | 发送内容与筛选 |
|---|---|
| 版本统计 | Peach 版本、分发方式(windows-app、macos-app、docker、wheel、source)、操作系统类型与版本、CPU 架构与逻辑核数、内存档位、Python 版本、运行环境、源码/独立包形态与公开构建提交号,每机 UTC 自然日最多一次,以一条日志和一条会话汇总发送;在进程启动时尝试,没有安装标识,不能据此统计独立用户。内存取最近的常见容量档;Docker 内的系统版本是宿主内核,Docker Desktop 的宿主系统由内核名称区分 |
| Python 错误 | 版本、分发方式、平台、Python、CPU 架构、故障环节、分层异常链、Peach 与白名单框架文件名/函数名/行号、结构化错误码;错误文本、变量、源码上下文与用户目录不发送 |
| HTTP 5xx | 追加方法、路由模板与关联错误编号;不含实例参数、查询参数、正文、鉴权头或用户网址 |
| 媒体工具 | 退出码,以及确定匹配的 AV1 解码器缺失、非法媒体、读写错误、权限、磁盘空间或未知解码器类别;stderr 与媒体名称留在本机 |
| 浏览器错误 | 白名单异常类型、Peach 正式脚本的行列位置与公开构建映射 ID;没有可定位堆栈的错误与扩展脚本不发送 |
SQLite 错误复用本机与远程的结构化错误码;能够确定时附缺表、缺列、锁定、只读、损坏或无法打开的固定类别,不发送表名、列名或 SQL。媒体故障在路径脱敏前提取固定类别,子进程异常本身携带的 stderr 也参与分类。系统不支持文件夹对话框时保留本机状态;支持的平台上对话框启动失败仍进入技术诊断。
错误事件表示某台机器在某个版本里第一次遇到这个诊断键,发生次数在计数日志里。每日额度、关闭上传、断网和筛选会造成观测缺失;未收到事件不能解释为没有故障。版本统计每日一次且不含安装标识,不能当作独立用户数、日活或故障率分母。错误事件附带的是服务主机环境,不能据此推断访问页面的客户端系统或浏览器。研究快照是普通事件,与错误事件共用组织的事件额度;版本统计与计数日志按日志字节计量,会话汇总不计费(ADR-0132)。
purpose 区分 version-statistics、technical-diagnostics 与独立研究通道的 population-research。故障视图使用 level:error purpose:technical-diagnostics,生产故障可再加 environment:production。版本统计在日志中查询 purpose:version-statistics,各版本占比也显示在接收端的 Releases 页;故障次数在日志中查询正文 Peach diagnostic count,按 diagnostic_key、occurrence_day 或 sentry.release 分组对 occurrence_count 求和;它是数值属性,查询与仪表盘里写作 sum(tags[occurrence_count,number])。没有用途标签的历史事件须单独审阅,不按缺失字段推断来源;ADR-0132 之前的版本仍以 info 事件 Peach started 发送版本统计,应排除在故障视图与告警条件之外。
environment 只接受 production、development、test;独立包与普通源码部署默认 production,Git 隔离工作树默认 development,可用 PEACH_REPORTING_ENVIRONMENT 明确指定。runtime 为 packaged 或 source;dist 使用构建提交号,不发送本机目录、主机名或自由文本标识。标准测试入口关闭本进程遥测,并向子进程传递 PEACH_REPORTING_TEST_MODE=1,在最终 HTTP 请求边界阻止两条通道真实外发;内存接收端仍可验证最终载荷。
异常链按 Sentry 的原因在前、外层在后保存,每层保留自己的帧。框架帧只接受 asyncio、anyio、starlette、httpx、sqlite3、urllib3,只投影模块与代码位置;日志入口仍要求包含 Peach 帧。SQLite 故障附带整数错误码与 SQLITE_* 错误名,不含 SQL、表名或错误原文。
同一异常实例及同一 traceback 被多个取证入口观察时只计一次;同一实例重新抛出形成新的 traceback 时仍计数。浏览器没有 stack 但提供正式包文件名和正整数行列时,也可定位;缺少这些证据的泛化错误留在本机。
正式前端构建在 build/sentry/browser/ 生成匹配的 JavaScript、source maps 与确定性 Debug ID,公开 web/dist 只包含正式 JS/CSS,页面路由不分发 maps。构建插件禁用遥测和自动上传。维护者在项目根运行 npm --prefix frontend run build 生成本次构建映射;只有显式配置 SENTRY_AUTH_TOKEN、SENTRY_ORG 和 SENTRY_PROJECT 后运行 npm --prefix frontend run sentry:upload 才上传。上传前核对私有 JS 与分发 JS 逐字节一致、map 与 Debug ID 对应。映射包含应用及依赖的构建源码,不包含运行日志、馆藏或本机绝对路径。Windows/macOS Release 在各自构建后执行相同上传入口;凭据只进入上传步骤,配置缺失时明确跳过。实际映射是否可用于 Sentry 定位须以接收端的新事件验收,构建成功不等于线上符号化成功。
正常取消、来源未命中/暂不可用、HTTP 4xx、互斥、普通 warning 和无堆栈的泛化日志不发送,也不计入故障次数。后台任务的纯文本失败回执仍保留在本机;有异常链的意外失败可发送。SDK 内部日志不进入远程钩子。
diagnostic_key 由脱敏技术字段计算,包含版本但排除每次 HTTP 错误编号;相同代码故障可跨机器对应,不是安装标识。新的诊断键在额度内立即上传一条错误事件,代表 1 次发生;之后同一台机器上的重复发生只累计在本机,每 6 小时、跨 UTC 日或正常退出时合并成计数日志。计数日志的 occurrence_count 是整数增量,例如首次事件代表 1 次,随后又发生 9 次,下一条计数日志记 9,合计 10;occurrence_day 是实际发生的 UTC 日期。错误事件数不代表发生频率,接收端的问题趋势图也不是真实触发趋势,频率以计数日志求和为准。
每机每天最多登记 20 个新的诊断键,最多上传 5 条首次错误事件;额度不足的首次事件推迟到后续定时检查或次日补传,统计日期保持实际发生日。托盘与子服务使用同一文件锁及聚合文件 state/remote-reporting-frequency.json,保存技术样本、首次事件是否已上传、当日累计数和已提交数;不读取历史日志。诊断键连续 7 个 UTC 日没有再发生即过期,再次发生时重新上传一条错误事件。SDK 接受入队后更新已提交数;计数日志提交失败时,跨日前的旧次数不再保留。连接失败、服务端丢弃、强制退出、锁争用或超过登记与保留上限均可能造成缺口,因此这是尽力交付的故障计数,不是完整运行审计。计数日志交给发送队列即视为已提交,队列已满时只在回执里记为 failed,不回滚次数。升级到 ADR-0132 之后的版本时,旧聚合文件的键格式不再有效,每台机器上仍在发生的故障会各自重新上传一次首次事件,接收端可能短暂出现一批回归。
state/remote-reporting-delivery.json 保存各技术用途最后一批(错误事件、计数日志或版本统计)的本机回执,配置 API 的 remote_reporting.delivery 提供相同的脱敏状态。queued 仅表示准备入队;accepted 表示传输取得 HTTP 2xx,不保证接收端长期保留;failed 表示明确拒绝或本机队列/限流阻断;unknown 表示未取得可靠结果,网络异常也可能发生在接收之后。HTTP 2xx 同时带限流头时按未知处理。回执不保存服务端正文、请求网址或载荷;旧事件与旧同意版本的回执不能覆盖当前记录。传输回执不把入队计数改写成接收计数,也不触发补传。
两项均通过公开 DSN 发送到 Sentry 托管服务,接收服务会接触连接 IP。客户端不发送 IP 字段、用户身份、设备标识、观看记录、媒体信息、凭据、完整日志或诊断 ZIP。日志与会话条目由 Peach 自行组装,不经过 SDK 的日志与会话通道,主机名、SDK 名称与追踪上下文不进入载荷;传输闸门只放行带当前同意凭据的这两类条目。SDK 发送队列不写入磁盘,本机聚合文件仅存技术投影和次数;后台发送前复查本机同意版本。关闭或重新选择会清除未提交聚合,并让排队旧事件失效;已在途或已接收的请求无法撤回。本机 ZIP 导出独立可用。
接收端由维护者配置:源码运行使用 PEACH_SENTRY_DSN 或检出根的 sentry.json;Windows、macOS 打包与 Docker 镜像由 scripts/write_reporting_config.py 从同名环境变量(Docker 为同名构建参数)写入包根 sentry.json,镜像里位于 wheel 的 peach/_resources/,容器运行时设置的同名环境变量优先。发行流水线从 GitGud 项目 CI/CD 变量 PEACH_SENTRY_DSN 与 PEACH_LIBRARY_SENTRY_DSN 读取,两者为受保护变量、环境作用域 release;缺失或不合法时发行构建失败,本地构建写空值,安装后显示上传服务未配置。只接受 Sentry 的公开 HTTPS DSN(含 US / DE 区域),不需要 API token。没有 DSN 时不会创建 SDK 客户端。SDK 自动框架集成、自带的日志与会话采集、性能追踪和指标均关闭。账号套餐和总量以 Sentry 订阅页 为准。
回归验收使用临时 Peach 数据目录和 SDK 内存接收端。实际接收与发行制品的验收记录保存在仓库外。技术诊断选择见 ADR-0110。安装辅助进程只在本机取证,不初始化远程客户端或发送事件;应用进程按用户选择发送。
asyncio 连接清理只在同时满足以下条件时识别为连接重置收尾:OSError 的 winerror 为 10054(对端已重置连接)或 10022(Proactor 收尾时 shutdown 报 WSAEINVAL),回调为标准库 _ProactorBasePipeTransport._call_connection_lost,调用栈只含该回调与 asyncio.events._run,且没有关联异常。处理器核对真实 Proactor transport 处于清理状态,关闭 socket、解除服务端登记并完成关闭状态;不重复通知协议。成功记录 classification=connection-cleanup 与 cleanup_recovered=true,仅保留本机证据。收尾自身失败则保留原始异常链、上报技术故障并交给默认处理器;不能确认对象状态时也沿用默认处理器。没有全局修改 Python 类或替换事件循环。
Windows Proactor 在 accept 完成前客户端已断开时报 Accept failed on a socket(OSError,winerror 为 64)。这一类只写本机记录,classification=accept-aborted、listener_closed=true,不远程上报,也不交给默认处理器重复写 ERROR。CPython 3.14.7 在处理器返回后会关闭该监听 socket;peach serve(主服务与 HTTP 重定向监听都由它启动)随即按原地址新建一份监听,交给 uvicorn 管理,记录里 listener_rearm=true。新连接沿用 uvicorn 的协议工厂与连接登记,停机时照常收尾;已建立的连接和同一服务端的其他地址不受影响。重新绑定在约 2.5 秒内重试 3 次,仍失败时以 classification=accept-listener-lost 上报技术故障并让服务有序退出,由托盘重新拉起;未经 peach serve 启动、拿不到 uvicorn 服务端时 listener_rearm=false,只留本机记录。其他 accept 失败不重新监听,仍按技术故障上报并交给默认处理器。
本机记录保留异常与标准库帧,并补充回调、协议类、可识别的服务端类别和 TLS 标志;这些上下文字段不进入远程载荷,不访问连接地址、请求内容或对象文本。资源收尾使用 CPython 3.14.7 的私有对象协议,升级需验证实际 socket、asyncio.Server、重复关闭与收尾失败。原始竞争时序在 33 次回环实验中未复现;合成故障验证了资源实际关闭与服务端释放,不能据此推断原始客户端来源。
远程错误筛选核验
核验覆盖异常钩子、日志、后台任务、来源、HTTP、媒体、浏览器、启动与更新入口。筛选依据结构化状态和实际异常继承关系,不按错误原文、任意同名类或所有网络异常统一过滤。
整片转码的 TranscodeUnavailable 携带最后一次尝试的有界工具证据与退出码,并保留进程启动异常链。日志入口使用相同的媒体投影规则,只发送结构化退出码与已识别的 media_failure 类别;工具原文、媒体路径和尝试参数不进入远程事件。主动取消、超时和已识别的媒体输入条件仅保留本机记录。
| 状态 | 本机与远程处理 |
|---|---|
| 任务取消、暂停、互斥、计费与磁盘策略门槛 | 保留本机异常和任务回执,不占用错误上传额度;文件锁等待超时同样按互斥处理 |
| SQLite 磁盘与锁 | SQLITE_IOERR*、SQLITE_FULL 属于磁盘或文件系统条件,SQLITE_BUSY、SQLITE_LOCKED 是会重试的锁争用,均留在本机;其余 SQLite 错误继续上报 |
| 来源冷却、动作预算、授权、未命中、明确的临时故障 | 复用来源异常与分类,保留本机状态;来源解析错误和未知失败继续上报 |
| HTTP 客户端错误 | 识别直接状态码、httpx 响应及 urllib HTTPError;4xx 留在本机,未分类的 5xx 继续上报;0 不作为 HTTP 状态码。httpx 连接与读取超时属于来源暂不可用,留在本机 |
| 路由主动返回的上游不可用 | 路由以 HTTPException 主动返回的 502、503、504 留在本机;未处理异常形成的 500 继续上报 |
| warning 与重试日志 | 低于 error 的日志留在本机;error/critical 携带 Peach 栈时上报 |
| 媒体输入与环境条件 | 坏媒体(含工具报 Invalid argument)、读写错误(Input/output error、EIO)、输入缺失、权限、空间与媒体工具或媒体读取子进程超时留在本机;读取方超时离开后子进程写回结果失败不算故障;工具执行文件缺失、解码器能力缺失和未知技术错误继续上报;预览前置条件保留提示和可重试问题项 |
| 浏览器取消与扩展 | 主动取消请求的 AbortError 不发起记录请求;后端收到该类型仍仅写本机;扩展 URL 帧不上传,Peach 带构建参数的脚本帧保留行列位置 |
| 客户端中途断开 | 响应头策略直接处理 ASGI 消息,文件响应收到断连后停止发送;服务器异常原样交给故障处理器。Starlette 的 ClientDisconnect 留在本机,不当作服务端程序故障 |
| 启动、CLI、托盘、更新与回滚 | 未处理的技术故障继续上报;安装辅助进程沿用仅本机诊断边界 |
| SDK、无堆栈日志与不透明浏览器错误 | 不递归上报 SDK 自身问题;无法取得 Peach 代码位置的日志和浏览器错误仅保留本机 |
本机策略不清除已有 Sentry 事件,也不控制邮件;邮件摘要与即时通知分别在接收端设置。
两条通道都禁止底层 HTTP 重试与重定向,保持有限发送次数和 DSN 接收范围。传输回执随用户主动导出的 ZIP 提供;ZIP 不包含本机故障聚合样本或研究明细。
馆藏与口味群体研究
「上传馆藏与口味明细」是独立默认关闭的选项,位于「应用与维护 → 数据上传」,与技术诊断使用各自的开关。开关始终可见。设置页由用户生成本机预览,查看实际字段与内容后明确同意;预览数量、大小与排除的个人数据合并为一段说明。服务端要求当前进程生成、10 分钟内有效的一次性预览凭据、同意值与字段版本。单独操作开关或开启错误诊断不构成馆藏上传同意,关闭不要求预览。安装器提供默认不勾选的独立选项,短标签概括内容与风险;主动勾选后展示可滚动的完整字段、用途与风险说明页,继续表示同意,返回可取消选择。辅助进程只保存选择,不读取馆藏或初始化 SDK。静默安装保留已有选择。字段版本为 4,其他版本的同意无效。
附件 peach-library-taste.json.gz 无损压缩以下完整 JSON:
schema、peach、period:字段版本、Peach 版本和 UTC 自然周。library:每个规范作品编号一条;存在用户信号时附评分、喜欢、不喜欢或已看、稍后看、累计播放次数、观看比例与手动标签。无反馈的作品只发编号,供跨部署统计收藏覆盖。无编号条目不进入逐作品列表。preferences:出演者、创作者、厂牌、系列、手动标签、五年发行年代段与时长段,均在本机分组。每个分组包含name,以及存在对应馆藏时的works(有编号去重作品)和uncoded(无编号条目)。两种范围分别包含collected、liked、disliked、watched与ratings(0–100 分评分到数量的直方图),不得相加当成作品数量。主动收藏的实体另有favorite: true。明确登记的男优不参与人物偏好。时长段0、1、2、3分别为小于 30 分钟、30–90 分钟、90–150 分钟、150 分钟及以上。coverage:active_files、coded_files、coded_works、uncoded_items,供判断收藏与评分样本的覆盖范围。
标签仅取设置页逐条添加的 web-user 证据,遵守隐藏标签偏好;实体收藏中的标签是用户主动选择,也保留。自动刮削、技术标签及从浏览行为推断的标签不参与本投影。同编号各文件合为一部作品:喜欢和稍后看取任一文件的选择,播放次数累加,观看比例取已保存观看比例、最远播放位置与累计播放时长比例中的最大值并限制到 1;反馈取时间最新的明确标记。评分沿用 0–100 分,空值和 0 不计评分,不同副本的不同有效评分取均值,每部作品每次快照只贡献一份评分。年代与人物关联仅用于本机分组,不逐作品重复发送。
不发送账号、设备或安装标识、文件名、路径、媒体、网址、搜索词或逐条浏览/观看记录。标签和规范名称中的网址、绝对路径与凭据样式经过现有脱敏函数。作品组合、评分和分组偏好仍可能跨次关联,或与其他资料匹配后再识别;Sentry 会接触连接 IP。界面的「匿名处理」指移除直接标识,不构成不可关联或无法识别来源的保证。关联上传与知道真实姓名是不同的判断,两者均不能作绝对保证。
预览与后台采集只读 ledger,不读取浏览历史、书签或写入偏好缓存。大预览在代码块展示前 24,000 个字符,可复制或下载完整本机 JSON。预览不是发送,也不会开启上传;同意覆盖每周发送相同字段的最新快照。同意后收起预览说明、数据预览和同意框;预览入口仍可重新打开,已开启时不重复要求同意。契约改变须推进 SCHEMA 并重新取得同意。
后台只有在有效同意和独立接收端同时存在时才读取明细并初始化 SDK。快照须至少包含一部公共编号作品或一个偏好分组;没有可分析内容时记为 waiting-data,每小时重新检查,不占周传输机会。收集、压缩或入队前失败可以重新准备。每机每 UTC 自然周最多通过一次最终发送门槛,跨进程使用同一文件锁预约;重新选择同意不重置周限次。实际发送后无论明确失败还是结果未知,本周均不再发送,不补传历史快照。空快照不会进入研究样本,分析结果须披露这个筛选口径。
state/library-sharing-attempt.json 区分 waiting-data、queued、accepted、failed、unknown 与 blocked,attempted 表示是否已通过最终发送门槛。设置 API 的 last_attempt 只提供当前 UTC 周的回执,跨周不改写原记录。accepted 仅证明取得 HTTP 2xx;未取得 HTTP 回执、网络中断和历史无回执记录均不解释为接收成功。旧字段版本、旧 UTC 周与旧同意版本的队列不能发送;旧尝试回执不能覆盖新尝试。
原始 JSON 上限 100 MiB,gzip 附件上限 18 MiB;任一超限均整份拒绝,不发送截断数据。gzip 头不含源文件名和生成时间。传输只接受固定用途事件、固定文件名附件与字段白名单,后台真正发送前复查同意版本。关闭让排队记录失效,已发送数据无法经本机开关撤回。
维护者另设 PEACH_LIBRARY_SENTRY_DSN,两端打包按上文写入包内 library_dsn。该 DSN 的项目必须与错误诊断项目不同,同项目配置视为未配置。研究快照作为 Sentry 附件接收,每次也产生一条事件;组织内的事件和附件额度仍共享。见 Sentry 附件说明。
群体分析按 period 分开汇总作品持有率、作品评分分布、人物及系列偏好和手动标签;每份快照每部作品只贡献一次持有,实体的 favorite 表示主动收藏,collected 表示持有相关作品,不能混用。评分使用有效评分人数或数量作分母,不能把未评分当作 0 分,也不能把文件数量当用户数量。每周快照是累计状态,不能跨周累加成新增收藏或播放。没有跨周期标识,但不能据此宣称明细无法关联;每机每周一次也不能识别同一人多安装。结果只代表自愿参与样本,须说明安装覆盖与选择偏差。接收端分析看板不属于客户端上传功能。
ZIP 内容
系统诊断页的诊断报告和刮削记录均在后台生成,进度按实际读取的候选与来源快照显示;可以取消,刷新页面后可继续查看同一服务中的任务。完成后通过下载链接读取文件。生成与 ZIP 合并分块写入临时文件,取消时清理未完成产物;重新生成会回收该管理器上一份产物。服务重启后需要重新生成。
普通诊断报告自动合并压缩后不超过 100 MiB 的详细刮削记录,超限时保留摘要并提示按番号单独导出。刮削记录可填写最多 20 个番号,留空读取近期作品,包含来源字段、候选、当前归属与复核决定;只读现存资料。自动错误取证只附刮削摘要,不后台生成完整刮削记录。
后台导出接口为 GET/POST /api/diagnostics/exports、POST /api/diagnostics/exports/{job_id}/cancel 与 GET /api/diagnostics/exports/{job_id}/download,均沿用登录与本机管理检查,写请求核对同源。状态为 idle、running、cancelling、complete、cancelled 或 failed;下载只接受当前已完成任务的标识。
GET /api/diagnostics/bundle 直接返回常规日志与诊断摘要;详细刮削记录通过后台导出生成。
report.json:系统和版本信息、检查结果、媒体工具能力、来源健康摘要及文件收集回执。Windows 上runtime.windows_browsing记系统代理开关、是否绕过本机地址和默认浏览器的程序标识,不记代理地址;recent_origin_mismatches列出最近 8 次来源检查对不上时的请求形态。logs/<目录序号>/:托盘、服务、重启、首次扫描、源码更新、隧道、错误及崩溃日志;固定日志包含近期自然月分段。页面操作被接口以 400 拒收时(例如手动取封面时馆藏未找到番号),拒收原因写入errors-*.log的http-request记录,只留本机,不远程上报。processing/:馆藏处理状态与近期问题清单、启动准备、自动更新、独立包更新及隧道状态。updates/:近期更新迁移日志。covers/:发现页逐番号的封面处理结果(feed-cover-attempts/<番号>.json)与资料任务状态;资料缓存本身留在本机。scraping/:来源摘要,以及符合合并上限的字段候选、归属和来源快照;凭据与媒体路径经过脱敏。
写请求的来源检查以浏览器标注的 Sec-Fetch-Site: same-origin 为准,标成 cross-site 一律拒绝,其余比较 Origin 与本机或隧道地址。比较对不上时,不论放行与否都写一条 origin-mismatch 到 errors-*.log:协议、主机类别(回环、私网、公网或主机名)、端口与逐项是否一致、Sec-Fetch-*、转发头是否出现与 User-Agent;不记 Origin 和 Host 原文。同一形态一分钟只记一条。
每个文件读取尾部最多 96 KiB;错误日志最多 8 份、崩溃日志最多 4 份、处理问题清单最多 8 份、迁移日志最多 2 份、封面处理结果按修改时间取最近 500 份。截断和读取失败进入收集回执,单个不可读文件不影响其他证据。JSON 与 JSONL 分别解析,正在写入的残行不进入共享报告。日志保留周期沿用半年及自然月分段策略。
ZIP 不包含 ledger、配置文件、私钥、登录 Cookie 或媒体文件。路径、网址、地址、凭据字段及命令行凭据值脱敏,字典键同样脱敏:<资产编号>:<路径> 形态的键保留编号前缀,脱敏后同名的键追加 #2 等序号;处理记录中的媒体名称与 path 字段整值隐藏,只保留资产编号,不带出库清单。故障注入的默认日志落在测试进程临时目录。
媒体工具
AV1 抽帧需要可用的软件解码器。scripts/build_ffmpeg_windows.sh 静态编入固定版 dav1d;完整源码归档、许可证和 SHA256 清单通过 media_tool_bundle.py --validate-only 核验。
发行验收使用内嵌的合成 AV1 片段,在 CPU 上完成解码和抽帧,不依赖机器显卡或 AV1 编码器。真实媒体的失败记录、文件指纹与重试结果保存在仓库外的私有诊断记录中。