# 日志与诊断 本页说明异常日志、浏览器错误上报、诊断导出与可选远程诊断的边界。正常取消、缓存回退、来源未命中和任务互斥保留各自状态。 环境与故障证据按同一套采集和分类函数产生,各输出入口按用途取字段:`reporting_identity` 提供程序、构建与主机量级,`diagnostic_exceptions` 提供异常链的结构化错误码和媒体故障类别,`diagnostic_context` 规范浏览器、播放和运行状态。输出入口不自行重新识别同一故障。 | 输出 | 使用范围 | | --- | --- | | 本机日志 | 脱敏异常链、错误码、浏览器与播放现场、请求到达和响应媒体类型 | | 诊断 ZIP | 从本机日志和当前运行状态汇总有界证据;保留采集失败与未取得状态 | | 远程技术诊断 | 仅投影已声明的代码位置、构建身份、结构化错误码与固定故障类别;详细浏览器和播放现场只在本机 | | 版本统计、群体研究 | 复用程序和构建身份,分别遵守既有字段、开关与频率契约 | 桌面制品验收在临时 Peach 数据目录显式关闭版本统计与错误上传,并在首启提交中保持关闭,避免合成测试进入正式遥测。 ## 反馈入口 馆藏处理失败时,重试失败项,再从托盘「导出诊断报告」或系统诊断页「下载诊断报告」取得 ZIP。用户只需提供一个 ZIP。桌面部署下载限运行 Peach 的本机;Docker 部署允许已登录的私有网络客户端下载,拒绝代理转发。网页不可用时,可按 [Docker 诊断导出](DOCKER.md#导出诊断报告) 在容器内生成 ZIP。已登录的同源设备可以上报浏览器错误;开放访问模式不提供匿名远程上报。 错误发生时必须实际记录底层证据。完整问题清单位于 `state/library-processing-.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 系统版本来自内核 | | Python 错误 | 版本、分发方式、平台、Python、CPU 架构、故障环节、分层异常链、Peach 与白名单框架文件名/函数名/行号、结构化错误码;错误文本、变量、源码上下文与用户目录不发送 | | HTTP 5xx | 追加方法、路由模板与关联错误编号;不含实例参数、查询参数、正文、鉴权头或用户网址 | | 媒体工具 | 退出码,以及确定匹配的 AV1 解码器缺失、非法媒体、读写错误、权限、磁盘空间或未知解码器类别;stderr 与媒体名称留在本机 | | 浏览器错误 | 白名单异常类型、Peach 正式脚本行列位置、构建映射 ID、客户端浏览器品牌及主要版本与系统大类 | SQLite 错误复用本机与远程的结构化错误码;能够确定时附缺表、缺列、锁定、只读、损坏或无法打开的固定类别,不发送表名、列名或 SQL。媒体故障在路径脱敏前提取固定类别,子进程异常本身携带的 stderr 也参与分类。系统不支持文件夹对话框时保留本机状态;支持的平台上对话框启动失败仍进入技术诊断。 错误事件提供每实例每版本的诊断定位样本,发生次数通过计数日志求和。每日额度、关闭上传、断网和筛选会造成观测缺失。版本统计使用已联系实例与实例日作为分母,常驻进程跨 UTC 日也会尝试。服务主机环境与浏览器客户端类别分别解释。研究快照与错误事件共用组织的事件额度,版本统计与计数日志按日志字节计量,会话汇总承载日联系计数。参见 [ADR-0132](adr/0132-diagnostics-counts-via-logs-and-sessions.md) 与 [ADR-0157](adr/0157-diagnostic-instances-and-research-receipts.md)。 运行中开启诊断后启动既有后台检查,无需重启;关闭后排队信封按同意代际拒收。缺少可用传输器时,本机回执明确为 `failed`,不长期保留 `queued`。设置页可展开查看字段和规则,常驻信息仅显示最近发送日期;排队或失败不覆盖此前日期。参与状态使用标签。HTTP 2xx 只表示接收端响应,不证明事件已留存,该区别保留在技术回执中。默认诊断不包含研究实例标识、馆藏、容量或播放活动。 `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 和无堆栈的泛化日志不发送,也不计入故障次数。环境条件(数据库磁盘与锁争用、媒体所在的盘掉线、媒体缺失或损坏、权限、空间与媒体工具超时)只计数:计数日志带固定的 `condition` 类别与代码位置,不上传定位事件,也不带错误码、路径或原文,见 [ADR-0158](adr/0158-environment-conditions-are-counted.md)。后台任务的纯文本失败回执仍保留在本机;有异常链的意外失败可发送。SDK 内部日志不进入远程钩子。 `diagnostic_key` 由脱敏技术字段计算,包含版本,排除每次 HTTP 错误编号及技术实例标识。相同代码故障可跨实例对应。新诊断键在额度内立即上传定位事件,全部发生次数每 6 小时、跨 UTC 日或正常退出时合并成计数日志。日志带 `count_schema=2`,`occurrence_count` 为整数增量,`code_location`(`文件:函数`)与 `code_line` 取被捕获异常里最内层的 Peach 栈帧,没有 Peach 栈帧时不带。例如同一故障共发生 10 次,本批日志记 10。`occurrence_day` 为实际发生的 UTC 日期。频率统计对这一版本的计数日志求和,定位事件用于查看异常链与代码位置。旧聚合文件首次读取时补入过去由首次事件承载的一次,迁移标记保证只转换一次。 每机每天最多登记 20 个新的诊断键,最多上传 5 条首次错误事件;额度不足的首次事件推迟到后续定时检查或次日补传,统计日期保持实际发生日。超出 20 个的新故障键改用只到代码位置的粗样本登记为只计数,次数照常提交;环境条件不占这 20 个名额,先在进程内累计,60 秒定时检查或正常退出时并入聚合文件。只计数的新键每天最多登记 100 个。托盘与子服务使用同一文件锁及聚合文件 `state/remote-reporting-frequency.json`,保存技术样本、首次事件是否已上传、当日累计数和已提交数;不读取历史日志。诊断键连续 7 个 UTC 日没有再发生即过期,再次发生时重新上传一条错误事件。首次事件与计数日志先在聚合文件里记为已发送,写入成功后才交给 SDK;聚合文件写不进去时(例如磁盘已满)这一轮什么都不发送,不会把每次发生都当成首次重发。SDK 拒收时撤回记号并再写一次,这次也写不进去只会少计。计数日志提交失败时,跨日前的旧次数不再保留。连接失败、服务端丢弃、强制退出、锁争用或超过登记与保留上限均可能造成缺口,因此这是尽力交付的故障计数,不是完整运行审计。计数日志交给发送队列即视为已提交,队列已满时只在回执里记为 `failed`,不回滚次数。升级到 ADR-0132 之后的版本时,旧聚合文件的键格式不再有效,每台机器上仍在发生的故障会各自重新上传一次首次事件,接收端可能短暂出现一批回归。 `state/remote-reporting-delivery.json` 保存各技术用途最后一批(错误事件、计数日志或版本统计)的本机回执,配置 API 的 `remote_reporting.delivery` 提供相同的脱敏状态。`queued` 仅表示准备入队;`accepted` 表示传输取得 HTTP 2xx,不保证接收端长期保留;`failed` 表示明确拒绝或本机队列/限流阻断;`unknown` 表示未取得可靠结果,网络异常也可能发生在接收之后。HTTP 2xx 同时带限流头时按未知处理。回执不保存服务端正文、请求网址或载荷;旧事件与旧同意版本的回执不能覆盖当前记录。传输回执不把入队计数改写成接收计数,也不触发补传。 开启后自动生成随机 `diagnostic_instance`,保存在诊断选择文件,供日联系、错误事件与计数日志关联。已有开启选择在升级后准备首次上报时补生成。关闭后移除本机标识,再开启生成新值。研究使用独立的 `research_instance`。浏览器故障另外提供 `client_browser`、`client_browser_major` 和 `client_os`,分别表示浏览器品牌、主要版本与系统大类。 两项均通过公开 DSN 发送到 Sentry 托管服务,接收服务会接触连接 IP。事件使用上述随机技术实例标识。日志与会话条目由 Peach 自行组装,传输闸门发送前复查本机同意版本。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 订阅页](https://sentry.io/settings/) 为准。 回归验收使用临时 Peach 数据目录和 SDK 内存接收端。实际接收与发行制品的验收记录保存在仓库外。技术诊断选择见 [ADR-0110](adr/0110-recommended-diagnostics-choice.md)。安装辅助进程和独立包读取媒体时拉起的 `media-read`、`local-image` 子进程只在本机取证,不初始化远程客户端或发送事件,读取失败由父进程归类;应用进程按用户选择发送。 `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_io`、`disk_full`、`sqlite_busy`);其余 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`)、媒体所在的盘或网络卷掉线(`ENXIO`、`ENODEV`、`ENOTCONN`、`ESTALE` 等)、输入缺失(含 SMB 共享上的文件)、权限、空间与媒体工具或媒体读取子进程超时只计数,类别为 `invalid_media`、`io_error`、`media_volume`、`missing_media`、`permission_denied`、`disk_full`、`timeout`;读取方超时离开后子进程写回结果失败不算故障;工具执行文件缺失、解码器能力缺失和未知技术错误继续上报;预览前置条件保留提示和可重试问题项 | | 浏览器取消与扩展 | 主动取消请求的 AbortError 不发起记录请求;后端收到该类型仍仅写本机;扩展 URL 帧不上传,Peach 带构建参数的脚本帧保留行列位置 | | 客户端中途断开 | 响应头策略直接处理 ASGI 消息,文件响应收到断连后停止发送;服务器异常原样交给故障处理器。Starlette 的 ClientDisconnect 留在本机,不当作服务端程序故障 | | 启动、CLI、托盘、更新与回滚 | 未处理的技术故障继续上报;安装辅助进程沿用仅本机诊断边界 | | SDK、无堆栈日志与不透明浏览器错误 | 不递归上报 SDK 自身问题;无法取得 Peach 代码位置的日志和浏览器错误仅保留本机 | 本机策略不清除已有 Sentry 事件,也不控制邮件;邮件摘要与即时通知分别在接收端设置。 两条通道都禁止底层 HTTP 重试与重定向,保持有限发送次数和 DSN 接收范围。传输回执随用户主动导出的 ZIP 提供;ZIP 不包含本机故障聚合样本或研究明细。 ### 馆藏与口味群体研究 「上传馆藏与口味明细」是独立默认关闭的选项,位于「应用与维护 → 数据上传」,与技术诊断使用各自的开关。开关始终可见。设置页由用户生成本机预览,查看实际字段与内容后明确同意,展示数量、原始与压缩大小。服务端要求当前进程生成、10 分钟内有效的一次性预览凭据、同意值与字段版本。安装器提供默认不勾选的独立选项,主动勾选后展示完整字段、用途与风险说明页,继续表示同意。辅助进程保存选择,静默安装保留已有选择。当前上传格式版本为 `6`,同意范围版本为 `5`。已有格式 5、6 的有效开启记录沿用原研究实例和授权记录,读取状态时直接识别。关闭及尚未选择的实例由用户主动开启。 附件 `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`,供判断收藏与评分样本的覆盖范围。 - `capacity`:仅从本机容量日聚合读取近 7 天、30 天的实际观测天数、数据与缓存的当前占用和峰值、已观察到的正增长量、缓存清理量,以及播放活跃天数和活动记录覆盖天数。缓存清理量为自动与手动的实际清理字节合计,不含备份和日志。容量值单位为字节,未取得值为 `null`。没有比较样本时,正增长量也是 `null`;不会把第一次取得的容量当作增长量。播放活跃仅来自馆藏或关注页的明确播放开始,不代表全部日常使用。首次播放记录之前的日期不计活动覆盖,缺失记录不补成 30 天。 schema 6 的手动标签取可见 `web-user` 证据和主动收藏标签,并限定为 `genre_taxonomy.CONTENT_GENRES` 的规范内容名称。自定义备注保留在本机。同编号各文件合为一部作品,喜欢和稍后看取任一文件的选择,播放次数累加,观看比例取已保存观看比例、最远播放位置与累计播放时长比例中的最大值并限制到 1。反馈取时间最新的明确标记。评分沿用 0–100 分,空值和 0 不计评分,不同副本的不同有效评分取均值,每部作品每次快照只贡献一份评分。年代与人物关联用于本机分组。 不发送账号、机器指纹、诊断标识、文件名、路径、媒体、网址、搜索词或逐条浏览/观看记录。当前字段范围经主动同意后,随机生成本实例的 `research_instance`,与诊断标识无关;重新开启研究时更换。该标识作为研究附件对应事件的标签,用于关联同一授权期内的馆藏、容量和参与状态,不加入逐作品列表。标签和规范名称中的网址、绝对路径与凭据样式经过现有脱敏函数。作品组合、评分和分组偏好仍可能与其他资料匹配后再识别;Sentry 会接触连接 IP。移除直接身份信息不构成不可关联或无法识别来源的保证。 预览与后台采集只读 ledger,不读取浏览历史、书签或写入偏好缓存。大预览在代码块展示前 24,000 个字符,可复制或下载完整本机 JSON。预览不是发送,也不会开启上传。同意覆盖每周发送相同范围的最新快照。同意后收起预览说明、数据预览和同意框,预览入口仍可重新打开。上传格式由 `SCHEMA` 标记,同意范围由 `CONSENT_SCHEMA` 标记。扩大数据类别或用途时提升 `CONSENT_SCHEMA` 并重新取得同意。格式调整及现有范围内的字段收紧沿用已保存选择。 后台只有在有效同意和独立接收端同时存在时才读取馆藏明细并初始化研究快照传输;关闭时仅保留已事先明示的最小关闭状态发送资格。快照须包含公共编号作品、偏好分组或已取得的容量/播放活动聚合;没有可分析内容时记为 `waiting-data`,每小时重新检查,不占周传输机会。收集、压缩或入队前失败可以重新准备。每机每 UTC 自然周最多通过一次最终发送门槛,跨进程使用同一文件锁预约;重新选择同意不重置周限次。实际发送后无论明确失败还是结果未知,本周均不再发送,不补传历史快照。空快照不会进入研究样本,分析结果须披露这个筛选口径。 本机 `state/capacity-history.json` 最多保留 90 个 UTC 日,只存容量数值、实际清理量及播放活跃日。采样接受已有测量结果,不为研究投影启动额外目录扫描。数据与缓存当日均取得后,`sample_due` 返回无需完整采样;单项未取得不冒充完整样本。历史损坏与不存在分别表达为 `failed` 与 `unavailable`,不清空原记录或把失败值替换成零。上传的是窗口聚合,不包含本机逐日日期、路径或作品信息。 有效当前字段同意下的研究日采样复用分享服务的后台循环,仅当当日样本不完整时统计数据与缓存的物理分配量,不读取媒体正文,不占用请求中的容量检查;关闭或同意代际变化后停止采样。手动统计和已启用的容量上限检查仍可提供已有测量。研究记录未取得不阻止磁盘余量保护,也不转交错误诊断通道。 `state/library-sharing-attempt.json` 区分 `waiting-data`、`queued`、`accepted`、`failed`、`unknown` 与 `blocked`,`attempted` 表示是否已通过最终发送门槛。当前授权和 UTC 周的回执通过设置 API 的 `last_attempt` 提供,包含 `snapshot_id`、原始与 gzip 字节数以及有界失败原因。发送事件携带同一快照编号和大小,日联系日志使用 `snapshot_*` 属性提供对应证据。授权凭据保留在本机。`accepted` 表示取得 HTTP 2xx,附件下载、校验和归档形成留存证据。 原始 JSON 上限 100 MiB,gzip 附件上限 18 MiB;任一超限均整份拒绝,不发送截断数据。gzip 头不含源文件名和生成时间。传输只接受固定用途事件、固定文件名附件与字段白名单,后台真正发送前复查同意版本。关闭让排队记录失效,已发送数据无法经本机开关撤回。 参与状态使用同一个研究接收项目的 Sentry `log` 条目,不创建每日错误事件或附件,沿用 [ADR-0132](adr/0132-diagnostics-counts-via-logs-and-sessions.md) 的配额边界。启用当日的状态占用当日一次联系机会;之后运行期间每 UTC 日最多联系一次。关闭在本机保存一条最小待发送状态,只包含随机研究标识、状态类别、字段及程序版本、UTC 日期和联系时间等白名单字段;后台实际尝试一次后停发,不包含馆藏、偏好或容量。旧字段范围的用户没有这项资格,不补发旧选择的状态。关闭再开启会替换研究标识,旧授权队列和迟到回执不能改变新授权状态。 `state/research-participation.json` 保存稳定日志编号、排队代际、是否已通过发送门槛和上次投递回执。门槛前排队失败可沿用相同日志编号重新排队;已尝试但失败或结果未知不在当日补传,关闭状态也不再次实际发送。联系日志的属性限定为 `purpose=population-research-participation`、字段/程序版本、实例标识、状态、UTC 日期与周、最近尝试联系时间及日志编号。没有接收端或有效授权时不初始化客户端,历史损坏显示 `failed`,没有记录显示 `not-attempted`。关闭待发送状态只在本机排队,设置 API 不等待网络;研究上传失败不会递归成为技术诊断上报。 维护者另设 `PEACH_LIBRARY_SENTRY_DSN`,两端打包按上文写入包内 `library_dsn`。该 DSN 的项目必须与错误诊断项目不同,同项目配置视为未配置。研究快照作为 Sentry 附件接收,每次也产生一条事件;组织内的事件和附件额度仍共享。见 [Sentry 附件说明](https://docs.sentry.io/platforms/python/enriching-events/attachments/)。 群体分析按 `period` 分开汇总作品持有率、作品评分分布、人物及系列偏好和手动标签;每份快照每部作品只贡献一次持有,实体的 `favorite` 表示主动收藏,`collected` 表示持有相关作品,不能混用。评分使用有效评分人数或数量作分母,不能把未评分当作 0 分,也不能把文件数量当用户数量。每周快照是累计状态,不能跨周累加成新增收藏或播放。新字段范围可按随机研究标识关联同一授权期的快照和联系日志,但研究实例数不是人数,也不覆盖未同意、长期未联系的安装。仅明确收到关闭状态才计为已关闭;离线、卸载、网络失败与未取得回执都不能推断关闭,应展示最近联系时间和未知状态,不能用收到的事件数量冒充当前开启用户总数。结果只代表自愿参与样本,须说明安装覆盖与选择偏差。接收端分析看板不属于客户端上传功能。 ### 维护者研究归档 `scripts/research_archive.py --archive <私有目录>` 操作独立的 `archive.sqlite3`。`import <已下载的附件> --received-at <来源接收时间> --research-instance <事件tag>` 校验并导入原始 gzip。接收时间需包含时区,研究实例来自对应事件。无实例的历史附件按内容摘要独立计样本。每实例每周保留最新接收的一份,重复导入保持幂等。 `summary` 将每实例最新周的作品持有、评分分布、偏好分组与覆盖分母写入归档目录的 `summary.json`。旧无实例样本独立汇总。程序版本取自 `payload.peach`。导入更新或删除会使旧汇总失效,之后重新导出。 `delete-instance <研究实例>` 预演删除该实例全部周快照。`prune --retention-days 30` 预演按接收时间清理到期快照,两者通过 `--apply` 执行。维护者在接收服务留存期内下载并导入,下载源副本另外管理。汇总和归档均按私有研究资料保管。 下次发行使用新错误 DSN。发行维护者在新制品实际收到定位事件、版本日志和计数日志后停用旧错误密钥,并记录切换时间和接收证据。组织额度和计费周期以订阅接口记录为准。接收端错误与研究项目使用 `[Remove] [Anything] from [$user.geo]` 清理后续事件地理信息。 ## 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 编码器。真实媒体的失败记录、文件指纹与重试结果保存在仓库外的私有诊断记录中。