Skip to content

armgit / peach

Public Imported from GitHub
0

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

docs(adr): 记录订阅源与追更检查按源到期的取舍

longmeidaof8c947ceed8e
diff --git a/CHANGELOG.md b/CHANGELOG.md
index a15842529..caa7ae1ca 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -21,6 +21,12 @@ Removed / Fixed / Security。
## [未发布]
+### 变更
+
+- **关注**:订阅源拉取改为每半小时看一次到期的订阅,各订阅错开时间拉取,每个仍是 6 小时一次;以前同时添加的订阅总在同一时刻一起拉,有时还会隔一轮才拉到。
+- **关注**:JavDB 进入冷却时,订阅源拉取整轮只记一条失败,其余订阅等冷却结束后自动重拉,不再一整轮都写着「来源正在冷却」、再等 6 小时。
+- **关注**:自动检查更新按来源活跃度放慢:近 7 天有更新的按设定间隔检查,久未更新的逐级放慢,最长一天一次;站点限流时这一轮跳过的来源不再记成检查失败。
+
### 修复
- **关注**:库外作品的封面被删后重新取图,会把上次装图时记下的高清地址一并列入候选。想看里的作品和素人档、MGS 作品,在详情页点「立即重试」或等定时补图,都能取回原来那张高清图,不再报「没有找到可用的官方封面」。
diff --git a/docs/REUSE.md b/docs/REUSE.md
index 62a456c9f..2904f2118 100644
--- a/docs/REUSE.md
+++ b/docs/REUSE.md
@@ -872,6 +872,7 @@ A 盘垃圾隔离使用短名称 `peach-purge-<32 位 UUID>.peach-quarantine`,
- Iwara 视频作者订阅复用 [yt-dlp 的 Iwara 提取器](https://github.com/yt-dlp/yt-dlp/blob/9b58cb33d0cd3e823c8d8732f6adce8faa1f37e3/yt_dlp/extractor/iwara.py)(Unlicense,固定 revision `9b58cb33d0cd3e823c8d8732f6adce8faa1f37e3`)的 profile→用户 ID→videos 分页模型与 `X-Version` 文件接口签名;[gallery-dl 的 Iwara 提取器](https://github.com/mikf/gallery-dl/blob/882c8d0bb5c5a3ed4e88726d2f42a1cb7db59bf2/gallery_dl/extractor/iwara.py)(GPL-2.0,固定 revision `882c8d0bb5c5a3ed4e88726d2f42a1cb7db59bf2`)用于交叉核对 `apiq.iwara.tv`、视频文件字段与格式清单,不复制其实现。两者在 2026-10-23 获取时均维护中,Python 客户端可跨平台运行;完整下载器包含 Peach 不使用的下载、账户缓存与大量站点能力,因此只复用公开协议模型和 Unlicense 签名算法,不新增依赖。HTTP 复用现有 `curl_cffi`:匿名只读 POC 中普通 HTTP 对 API 返回 403,Chrome 传输取得作者资料、视频列表两页、详情与三档格式,五次请求约 4.9 KB、4.7 秒,未读取凭据或下载媒体。Peach 保留 DTO、关注状态、历史游标、凭据隔离及媒体代理;可选 `access_token` 仅发送到固定 API,不同步。列表只保存稳定视频页地址,短效文件地址与清晰度仅在播放缓存中保留;外部播放器、权限不足、空历史页、限流与结构错误分别处理。用法见 [Iwara 视频作者订阅](SOURCING.md#iwara-视频作者订阅)。
- Iwara 封面复用 `/follow-image` 的同源缓存,官方缩略图经正式 HTTPX 传输实测取得 200 `image/jpeg`;来源图标采用官网声明且实测为 PNG 的 `/logo.png`。官方头像专用解析路径未取得,作者头像沿用首字母回退;作者主页的用户名与署名复用既有官方别名学习。部分迁移视频没有可用时长或原画分辨率,字段保留未知,播放仍优先选择 `Source` 原画。标签模型另核对 [IwaraTool API 字段说明](https://github.com/Moeary/IwaraTool/blob/1e98c96c422a169699c0d16bcab49b8a7f5238d5/docs/API_zh.md)(MIT,固定 revision `1e98c96c422a169699c0d16bcab49b8a7f5238d5`,仅核对协议,不复制代码);匿名 `/tags` 与八条视频的 28 个标签均为 `id/type/sensitive` 模型。仅 `type=general` 明确进入 Peach 的通用词表,其他类型与缺少类型的原词保留,原始类型另存 `source_tag_types`,不按词形推断。
- 关注检查分两阶段:列表阶段落 partial 行,详情补全按 provider 额度只补新行和未补齐行。「补齐过」由连接器的 `ENRICHED_MARK` 声明、判据登记在 `follow_store._ENRICHED_PREDICATES`。
+- 定时关注检查只查到期的来源,按已有的 `last_checked_at` 与条目时间现算(`follow_check.due_for_check`),不加列、不起第二套调度;订阅源复用同一个 `FollowUpdateScheduler`,只多一个 `tick_minutes`(ADR-0132)。
- 关注原始证据复用 Python 标准库 `hashlib.sha256` 与既有 `write_immutable`。快照文件名由检查时间和完整说明的摘要组成;说明含正文 SHA-256、脱敏请求地址及候选数量,因此相同正文的不同游标或筛选结果各有独立证据。相同快照可重复保存,已有文件内容冲突仍拒绝覆盖;历史证据按账本保存的相对路径读取,无迁移或新增依赖。临时账本回归遍历登记表中的全部追更来源,覆盖正文、地址及候选数量的独立变化,并经 FANBOX 连接器验证相同正文的历史补足和重复检查。
- 单来源失败边界覆盖取回、整页存储和历史补足;证据内容冲突保留错误,已提交的条目继续保留,其他来源继续检查。Web 与 CLI 共用 `follow_check.run_check` 的失败结果,不把证据冲突记成成功。
- 关注检查失败在本机 `follow-check` 事件中保留来源、来源编号、失败阶段、请求页及异常链;只记录登记来源键与技术状态,不复制作者名称或来源地址。单来源错误仍按既有任务结果返回。
diff --git a/docs/SOURCING.md b/docs/SOURCING.md
index 4505f9c2e..36d3ee889 100644
--- a/docs/SOURCING.md
+++ b/docs/SOURCING.md
@@ -1366,6 +1366,8 @@ Feed 只回答一个问题:**最近出了哪些番号**。它不下载、不
页面只送演员 id,地址由服务端现拼;账本里没有这位就新建 `performer` 实体(ADR-0083)。
- 限流照库内采集:主机间隔 3 秒、403 就整源停下,冷却判据在 `scraping_access`,见「javdb、AVBase 与 JavBus 的限流与封禁」。
不要因为 Feed 是后台任务就另开一套。
+ - 定时拉取每 30 分钟看一次谁到期,每个源按 id 在 6 小时窗口里占一个相位(`feeds.next_fetch`)。撞上冷却时整轮只记一条失败,
+ 其余源不再请求、顺延到冷却结束(ADR-0132)。
- **加 `?sort_type=4` 拿到的页面一条作品都解不出**,同一轮里不带参数的请求仍是完整页。所以演员页伪 Feed 一律用不带查询串的地址。
- 标题栏 `<span class="actor-section-name">` 是这一页挂的名字,常把几种写法用逗号连成一串(`涼森玲夢, 涼森れむ`);
另一个 `section-meta` 写着「N 部影片」。一位女优常有两页,
diff --git a/docs/adr/0132-feed-and-follow-checks-stagger-by-source.md b/docs/adr/0132-feed-and-follow-checks-stagger-by-source.md
new file mode 100644
index 000000000..33efd9b12
--- /dev/null
+++ b/docs/adr/0132-feed-and-follow-checks-stagger-by-source.md
@@ -0,0 +1,48 @@
+# ADR-0132:订阅源与追更检查按源到期,来源冷却只记一次
+
+- 状态:已采纳
+- 日期:2026-11-03
+- 关系:补充 [ADR-0042](0042-feeds-discover-codes-not-files.md) 第八条的定时机制;存量后继的派发节奏仍按 [ADR-0097](0097-feed-check-dispatches-avatar-stock.md) 跟着定时拉取走
+
+## 背景
+
+用户反馈订阅一多,订阅源拉取和追更检查常撞上限流或冷却:任务中心的问题详情里,一整轮都写着「来源正在冷却,请稍后重试」。2026-11-03 对照本机账本只读核对:
+
+- **订阅源一轮的失败只有一个原因。** 10-21 和 11-02 两次整轮失败都是 1 条「拒绝访问」加 10 条「正在冷却」:第一个请求就被 JavDB 403,之前几小时没有别的任务问过 JavDB。403 的触发原因未取得。冷却第一档只有 15 分钟,但 11 个源全被按「现在 + 6 小时」排到下一轮。
+- **周期会漂。** `feeds.settle` 按「拉完那一刻 + 间隔」排下次,调度也是每 6 小时一跳,下一跳总比到期早一点。10-21 以来 18 轮定时拉取里有 4 轮一个源都没拉,那几个源实际 12 小时才拉一次。同一时刻加的源永远在同一跳一起到期。每轮最多 20 个源,订阅 100 个时每个源要 30 小时以上才轮到一次。
+- **追更每小时全查。** 105 个来源一轮最长约 14 分钟(逐源合计 837 秒),其中约四成最近一条已在 30 天以前。被限流冷却跳过的来源记成 `ok=False`,算进「N 个来源检查失败」,还会让调度层按倍数推迟下一轮。
+
+## 决策
+
+**一、订阅源按相位排下次。** 每个源在自己的间隔窗口里有一个由 id 决定的相位(黄金比例散列)。`feeds.next_fetch` 取「现在 + 间隔」附近、落在这个相位上的时刻,过渡那一轮的间隔在半个到一个半间隔之间,之后稳定为一个间隔,不再随拉取时刻漂移。升级不迁移数据:已有的源第一跳照旧一起拉,拉完各自回到相位。
+
+**二、调度每 30 分钟看一次谁到期。** `FollowUpdateScheduler` 收 `tick_minutes`,订阅源用 `feeds.TICK_MINUTES`,设置里显示的仍是每个源的周期。到期的源按 `next_fetch_at` 先到先拉。没有到期源的那一跳不起任务,任务中心不留空跑的一行。连续失败的退避从这一跳的间隔算起。
+
+**三、来源冷却整轮只记一次。** 拉取前先看这个地址所属的来源是否在冷却(`scraping_access.paused_until`)。本轮撞上 403 的那一条照常记失败,`next_fetch_at` 排到冷却结束,原因后面补一句「其余 N 个源顺延到冷却结束后再拉」。其余源不再请求、不进结果,只把下次时间挪到冷却结束,上次的结论不改。一开始就在冷却(别的任务撞出来的)时,用第一个源那一行说明,不发请求。本趟预算耗尽(`SourceBudgetExhausted`)不算来源冷却。
+
+**四、存量后继隔 6 小时派一次。** 定时那几轮里,本轮新发现的番号照旧当场派取资料;旧壳重试、补封面、缺头像的存量女优与想要作品重试,一个进程里隔 `web_feeds.STOCK_INTERVAL`(6 小时)才派一次。手动检查不受限制。
+
+**五、追更定时检查按来源活跃度放慢。** 定时那一跳只查到期的来源(`follow_check.due_for_check`)。最近一条条目(发布时间,没有就用第一次见到的时间)在 7 天内的按设置里的间隔查,7~30 天乘 3,30~90 天乘 12,更早或一条都没有的一天一次,任何一档都不比基础间隔密。判据放宽半个基础间隔,避免和订阅源一样漂移。手动检查、点名检查、往回翻页与续跑冻结的那一批不按到期筛。不加列,按 `last_checked_at` 与条目时间现算。
+
+**六、追更冷却跳过不算失败。** 站点限流冷却中、这一轮没问的来源返回 `status="skipped"`,不进结果、不动 `last_checked_at`,下一跳照常到期。整轮结果带 `deferred` 计数。
+
+## 理由
+
+- 两次整轮失败都发生在第一个请求上,错峰拦不住;能改的是后果:一个 403 不该变成 11 条失败,冷却 15 分钟也不该让订阅等 6~12 小时。
+- 相位比随机抖动收敛得快,也不需要迁移:随机抖动要好几轮随机游走才铺开,而且每次拉取的间隔都在变;相位排法一轮就铺开,之后间隔恒定。
+- 存量后继本来各有逐条节流(12 小时重试、指纹记性),每跳派一次不会重复问同一条,但会把补头像这类本地计算与网络请求的派发次数放大十几倍。新番号不受影响,发现到取资料的延迟不变。
+- 追更按活跃度降频,用的是已经在账本里的时间,不需要新状态。本机样本里每日来源检查从约 2520 次降到约 1170 次。
+
+## 被否决的方案
+
+- **跨任务的 JavDB 总请求预算(令牌桶)。** `library_processing.SOURCE_LIMITER` 已经让资料处理、想要、新作资料与订阅拉取共用一条 3 秒间隔的队列,冷却记录也是同一份。样本里「拉取后几分钟想要采集开跑」是串行派发,没有并发撞车;403 落在第一个请求上,预算拦不住。
+- **追更按 provider 并行。** 最大的一组(rule34xxx 25 个来源)就占 462 秒,并行后一轮最多从约 14 分钟降到约 8 分钟。降频后平均一轮约 6.5 分钟,并行还要改进度显示与写入并发,收益不抵复杂度。没有 429 或主机限速的证据,追更也不另接 `HostLimiter`。
+- **给追更来源加 `next_check_at` 列。** 到期可以由已有的检查时间与条目时间现算;存一份还要在每条返回路径上维护,冷却跳过时也要记得不写。
+- **订阅源下次时间加随机抖动。** 见理由第二条。
+
+## 后果
+
+- 订阅源对 JavDB 的请求回到设计频率:11 个源每小时约 1.8 次,均匀分在各跳里,不再一次 11 个;漂移修掉后比改动前实际的约 0.9 次多。订阅 100 个源时约每小时 17 次,仍远低于 3 秒间隔的每分钟 20 次。
+- 定时调度状态里的「上次运行」每 30 分钟更新一次;`last_checked` 是这一跳拉了几个源,空跳为 0。
+- 设置页「自动检查更新」一行说明了按活跃度放慢的规则。
+- rule34xxx 每轮会重复补全约 281 条始终补不齐的详情,是追更请求最多的地方,不在本 ADR 范围。