RSS 上新通知

pt-tools 在 RSS 自动下载之外，还可以把"上新"事件通过 QQ 私聊 或 Telegram 私聊 实时推给你。本指南帮你快速打开这个开关，并把通知质量调到最舒服的状态。

简介

RSS 上新通知是一个独立于"自动下载"的事件流：

路径	触发时机	用途
不通知	-	关闭此 RSS 的通知
全部新种（简略）	RSS feed 拉到一条新条目时立即触发	任何新种都通知我，仅含标题/链接，不消耗站点详情请求
只通知匹配的（详细）	详情页拉完、过滤规则命中时触发	只通知"我真的要追的剧 / 蓝光原盘"，需要详情才能判断
都通知 + 匹配的给详细	上面两路都启用（合并展示）	既不漏种，又能在命中规则时看到完整信息，避免重复通知

通知和自动下载完全独立：你可以"只接收通知不下载"、"只下载不通知"、"两个都开"。

通知通过 ChatOps 的通知通道投递。所以使用本功能前，必须先有一个可用的通知通道，详见：

快速上手（5 步）

第 1 步：准备通知通道

按 ChatOps 快速开始创建至少一个通知通道（QQ 或 Telegram）。

在 ChatOps → 消息通知中确认通道已启用，状态为「已连接」或「运行中」，并且测试消息能收到。

第 2 步：在 RSS 订阅中打开通知

打开站点 → 站点列表，点击站点所在行的「站点配置与 RSS 订阅」按钮，在「RSS 订阅」标签新建或编辑一条订阅，找到对话框下方的「通知」分区：

通知模式：选「全部新种（简略）」/「只通知匹配的（详细）」/「都通知 + 匹配的给详细」，选「不通知」表示关闭
通知通道：选择第 1 步创建的通道
每小时最多：默认 100，超出的通知记为 throttled（见下方「每小时配额」）

保存即可生效——下次 RSS 调度执行时新种会触发通知。

第 3 步（可选）：配置过滤规则用作通知触发器

如果你选了 filtered 或 both，那么需要至少一条 purpose 为 notify 或 both 的过滤规则。

进入规则 → 过滤规则，新建规则，设置「规则用途」：

下载（download）：仅用于自动下载（默认）
通知（notify）：仅用于通知，命中后触发「只通知匹配的」通知
两者（both）：两者都触发

注意：从没有「规则用途」的旧版本升级上来时，已有规则都是「下载」，需要通知的规则要手动改成「通知」或「两者」。

第 4 步（可选）：配置静默时段 / 配额

在通知通道详情的「静默时段」（ChatOps → 消息通知 → 点击通道）：

不打扰的时间范围：HH:MM 格式，例如 23:30 → 07:30
跨午夜支持，开始和结束都留空表示无静默
静默期内的通知会被自动延迟到结束时刻再投递（不是丢弃）
改完点「保存基本信息」

在 RSS 订阅编辑对话框：

每小时最多：默认 100；设为 0 表示不限制

第 5 步：等通知到达 / 排查

下次 RSS 调度（默认每 10 分钟，按订阅的检查间隔）会拉到新种并触发。

打开 ChatOps → RSS 通知日志，可以看到每条通知的：

result：sent / failed / suppressed / pending / throttled
attempts：投递尝试次数
last_error：最近一次错误（用于排查）
payload_json：实际发送的标题 / 正文

Web UI → ChatOps → RSS 通知日志：按结果筛选，展开一行可以看失败原因和推送出去的消息内容

四种通知模式详解

不通知（默认）

说明：关闭此 RSS 的通知功能
适用：只需要自动下载，不需要新种通知

全部新种（简略）

RSS 任何新条目都触发，包含 RSS feed 自带的标题和链接，不会拉详情页，所以信息很简略。

触发时机：RSS feed 拉到 <item> 那一瞬间
数据源：仅 feed 字段（title、link、pubDate）
不消耗站点请求：不会拉详情页，节省请求额度
适用：刷流玩家 / 喜欢"任何上新都看一眼"

通知正文示例：

🆕 [hdsky] Test.Movie.2026.1080p

📅 2026-05-16 12:00
🔗 https://hdsky.me/details.php?id=12345

只通知匹配的（详细）

拉完详情后按规则匹配，只有命中规则的种子才触发通知，但消息含完整详情（大小/免费/规则名）。

触发时机：详情页拉完、用途为「通知」或「两者」的过滤规则命中之后
数据源：详情页（容量、分辨率、免费状态、标签等）
会消耗站点请求：和正常自动下载链路共享
适用：追剧 / 挑蓝光 / 选种（需要详情才能判断）

通知正文示例：

🎯 [hdsky] Test.Movie.2026.1080p

📦 12.34 GB
🆓 免费 (剩余 23h45min)
📌 匹配规则：4K 蓝光原盘
🔗 https://hdsky.me/download.php?id=12345

都通知 + 匹配的给详细

同时启用上面两路。同一条种子如果两路都命中，pt-tools 会自动合并：

先入队"全部新种"那条（简略）
详情拉完后命中规则 → 这条简略的会被改为 suppressed（不发出去），改发"只通知匹配的"那条详细的
结果：同一种子永远只收到 1 条通知；命中规则的那种是详细版本，没命中的是简略版本

适合"想看全部新种，但希望命中关键词的能看到完整信息"的场景。

(rss_id, site_name, torrent_id, notify_kind, conf_id) 上有唯一索引保证幂等： 同一个种子的同一类通知不会被发两遍。

静默时段

适合"白天工作、晚上睡觉"的场景。

位置：通知通道详情的「静默时段」（字段 quiet_hours_start、quiet_hours_end）
格式：HH:MM（24 小时制），全空表示无静默
跨午夜支持：23:30 → 07:30 表示晚 11:30 到次日早 7:30 都安静
不丢消息：静默期内，通知记录写入数据库（result=pending），重试任务会等到静默结束后再投递

静默判断是按通道做的：同一条通知投往多个通道时，只有处于静默的通道延迟，其他通道照常发送。

digest 合并

短时间内大量上新会触发"digest 合并"：

窗口：30 秒，按通道分别计算
阈值：5 条
行为：同一通道攒满 5 条时立即发出，否则在 30 秒窗口结束时发出；多条会合并成一条带编号的摘要

目前没有关闭合并的开关。

失败重试

后台的重试任务周期性检查通知日志：

找出 result='pending' 且已到下次重试时间的记录
用原来的标题和正文重新投递
失败按指数退避重排：5s → 10s → 20s → 40s → 80s
累计尝试 5 次仍失败 → 标记为 failed，last_error 留下最后一次错误

failed 的记录不会被自动重试。需要重投时，在 RSS 通知日志页对这条记录点「重试」；pending 的记录也可以手动重试或取消。

Telegram 内联按钮

filtered 通知（仅 Telegram）会附带两个按钮：

立即下载：按正常的推送流程，把这条种子发到订阅指定的下载器（未指定时用默认下载器）
忽略：把这条通知记录标记为 suppressed，不再重试

按钮点击后：

pt-tools 执行下载或忽略
完成后清空消息上的按钮（防止重复点击）
Telegram 顶部弹出提示"已加入下载队列 #123" / "已忽略 #123" / 错误信息

权限：点按钮的用户必须在该 Telegram 通道的 allowed_users 或 admin_users 列表里；按钮不要求先完成绑定。不在列表里的用户点按钮会收到"您没有权限执行此操作"的提示。

QQ 通道目前不支持内联按钮（OneBot 协议无对应 message segment）。filtered 通知到 QQ 时只有正文。

每小时配额

订阅的「每小时最多」（默认 100）保护你不被一个大批量上新刷屏。

判定窗口：滚动 1 小时（按记录的创建时间）
统计口径：sent + failed + pending（throttled / suppressed 不计）
超限行为：直接写一条 result='throttled' 的记录，不投递、不重试

如果想关闭限流：把它设为 0。从旧版本升级上来的订阅默认是 100，需要主动修改。

通知日志字段速查

排查问题时可以对照 RSS 通知日志页面和数据库表 rss_notification_log 中的这些字段：

字段	含义
`id`	主键
`rss_id`	RSS 订阅的 ID
`site_name`	站点 ID（如 `hdsky`、`mteam`）
`torrent_id`	站点内种子 ID
`notify_kind`	`all` / `filtered`
`notification_conf_id`	用哪个通道发
`matched_filter_rule_id`	filtered 模式下命中的规则 ID（可空）
`result`	`sent` / `failed` / `suppressed` / `pending` / `throttled`
`attempts`	已尝试投递次数
`next_retry_at`	下次允许重投的时间
`last_error`	最近一次失败的错误文本
`payload_json`	实际推送的 title + text
`delivered_at`	第一次成功投递时间
`created_at` / `updated_at`	时间戳

唯一索引：(rss_id, site_name, torrent_id, notify_kind, notification_conf_id)，保证幂等。

部分索引：(result='pending', next_retry_at)，加速重试任务的扫描。

故障排查 FAQ

Q1：完全收不到通知怎么排查？

按下面顺序检查：

订阅的通知模式是否不是「不通知」？
订阅的通知通道是否包含一个已启用的通道？
该通道的静默时段是否包含当前时间？
订阅的每小时最多是否已用完？
打开 RSS 通知日志页，最近是否有 throttled 或 pending 的记录？
通道本身是否正常（消息通知页显示「已连接」或「运行中」，测试消息能收到）？

Q2：日志里很多 `throttled`，正常吗？

热门站点上新峰值很容易刷爆 100/h 的默认配额。

把订阅的「每小时最多」调高（比如 500）
或改成 filtered 模式，配合精细的过滤规则把噪声压低

Q3：重试一直 `failed`，怎么修？

看 last_error：

bot was kicked / blocked → 你把 bot 拉黑了 / 把它踢出群了，去 Telegram 重新启动 bot
connection refused / i/o timeout → 通道发送失败（NapCat 的 WebSocket 半死、Telegram 网络抖动）
rate limit exceeded → Telegram 的服务器端限流，等一会儿再重试

修好底层问题后，在 RSS 通知日志页对失败的记录点「重试」。

Q4：filtered 模式没触发？

确认过滤规则的「规则用途」是「通知」或「两者」
确认规则真的匹配上了种子标题（在过滤规则页面编辑规则，用「测试匹配」试一下）
确认 RSS 订阅关联了这条规则（订阅编辑对话框的「过滤规则」）

Q5：all 模式的同一条种子重复发了好几遍？

不会发生。(rss_id, site_name, torrent_id, notify_kind, conf_id) 唯一索引保证写入幂等。如果你看到重复，多半是 两个不同的 RSS 订阅都订阅了同一个 feed，每个独立计数。

Q6：怎么清空所有通知日志？

先停止 pt-tools 并备份 torrents.db，再执行：

sql

DELETE FROM rss_notification_log;

无外键约束。日志表只用于审计和重试，删光不影响下载。

Q7：QQ 通道也能收 filtered 通知吗？

可以，正文一样。但 QQ 没有内联按钮，所以不会带"立即下载 / 忽略"。

RSS 上新通知 ​

简介 ​

快速上手（5 步） ​

第 1 步：准备通知通道 ​

第 2 步：在 RSS 订阅中打开通知 ​

第 3 步（可选）：配置过滤规则用作通知触发器 ​

第 4 步（可选）：配置静默时段 / 配额 ​

第 5 步：等通知到达 / 排查 ​

四种通知模式详解 ​

不通知（默认） ​

全部新种（简略） ​

只通知匹配的（详细） ​

都通知 + 匹配的给详细 ​

静默时段 ​

digest 合并 ​

失败重试 ​

Telegram 内联按钮 ​

每小时配额 ​

通知日志字段速查 ​

故障排查 FAQ ​

Q1：完全收不到通知怎么排查？ ​

Q2：日志里很多 throttled，正常吗？ ​

Q3：重试一直 failed，怎么修？ ​

Q4：filtered 模式没触发？ ​

Q5：all 模式的同一条种子重复发了好几遍？ ​

Q6：怎么清空所有通知日志？ ​

Q7：QQ 通道也能收 filtered 通知吗？ ​

参考链接 ​