自动删种功能

pt-tools 提供自动删种功能，帮助用户在长时间刷流过程中自动管理磁盘空间，避免硬盘被撑满。

功能概述

自动删种功能定时检查下载器中的种子状态，根据用户配置的规则自动删除满足条件的种子及数据文件，释放磁盘空间。

核心特点：

安全优先：默认只管理 pt-tools 自己推送的种子，不碰用户手动添加的
H&R 保护：自动识别带有 H&R 要求的种子，在未满足做种时长前不会删除
灵活条件：支持做种时间、分享率、不活跃时间等多种删除条件，支持 AND/OR 组合
磁盘保底：磁盘空间保护机制（默认开启），空间不足时自动拦截新种子推送并按优先级清理存量
推送拦截：RSS 自动下载和手动推送在磁盘空间低于阈值时自动停止，防止撑爆硬盘
Scope 严格隔离：清理操作严格遵守管理范围设置，紧急清理也不会越界删除范围外的种子
多下载器安全：每个下载器独立管理，通过数据库记录精确匹配

配置说明

在 Web 管理界面的「规则 → 自动清理」页面配置：打开「自动删种」卡片中的「启用自动删种」后，其余选项才会显示。

基本设置

配置项	默认值	说明
启用自动删种	关	总开关
检查间隔	30 分钟	执行清理任务的时间间隔，最小 5 分钟
删除时连数据文件一起删	开	删除种子时是否同时删除下载的数据文件

管理范围

提供三种模式，决定哪些种子会被自动删种管理：

模式	说明	安全性
仅本应用推送的种子（默认）	通过数据库记录精确匹配，只管理 pt-tools 推送并记录在案的种子	⭐⭐⭐ 最安全
按标签匹配	管理下载器中带有指定标签的所有种子	⚠ 手动添加相同标签的种子也会被管理
下载器中所有种子	管理下载器中的全部种子	⚠⚠ 包括非本应用添加的种子

建议：始终使用「仅本应用推送的种子」模式。其他模式仅在您完全理解风险后使用。

Scope 隔离保证：无论使用哪种管理范围，自动删种（包括紧急清理）都严格遵守所选范围，不会越界删除范围外的种子。例如选择「仅本应用推送的种子」时，即使磁盘空间极度紧张触发了紧急清理，也绝对不会删除您手动添加到下载器的种子。

删除条件

当种子满足配置的条件时，会被标记为可删除。

条件	说明	示例
做种时间超过	做种时长达到 N 小时后可删	72 小时
分享率达到	分享率 ≥ N 后可删	2.0
不活跃超过	做种超过 N 小时且当前上传速度为 0 时可删	48 小时
免费到期仍未下完的种子自动删除	免费期结束且未下载完的种子	开/关

条件关系：

OR 模式（默认）：满足任意一个条件即可删除。适合快速释放空间。
AND 模式：所有配置的条件都必须同时满足才会删除。更加保守，适合希望充分利用种子价值的场景。

「免费到期仍未下完的种子自动删除」单独判断，不受条件关系影响：开启后，免费期已过且未下完的种子在 AND 模式下也会被删除。

设置为 0 的条件不参与判断。例如做种时间设为 72 小时、分享率设为 0，则只按做种时间判断。

磁盘空间保护

配置项	默认值	说明
启用磁盘空间保护	开
最低剩余空间	50 GB	剩余空间低于此值时触发保护机制

磁盘空间保护提供双重保护：

推送拦截（入口防护）：RSS 自动下载和手动推送在检测到下载器磁盘空间低于阈值时，自动跳过推送，不再往下载器塞新种子。同一批次中一旦检测到空间不足，会立即停止处理剩余种子。
紧急清理（存量清理）：自动删种定时检查时，如果磁盘空间低于阈值，即使种子没有满足上面的删除条件，也会在管理范围内按综合评分从高到低强制删除。以下因素都会提高评分：
- 已暂停
- 分享率高
- 做种时间长
- 不活跃（当前上传速度为 0）
- 体积大（释放空间多）

注意：紧急清理严格遵守管理范围设置。如果管理范围内的可删种子不足以腾出所需空间，系统不会越界删除范围外的种子。此时推送拦截机制会阻止新种子进入，防止磁盘被进一步占满。

保护规则

以下种子即使满足删除条件也不会被删除：

规则	默认值	说明
保护下载中的种子	关	正在下载或校验中的种子不删
保护 H&R 种子	开	未满足站点 H&R 做种时长要求的种子不删
最短保种时间	24 小时	添加不满 N 小时的种子不删
保护标签	空	带有指定标签的种子不删（输入标签后回车，可添加多个）

执行逻辑

RSS 推送流程（入口防护）

1. RSS 定时任务触发，解析 RSS 获取种子列表
2. 下载 .torrent 文件到本地
3. 遍历待推送的种子文件：
   a. 检查种子是否过期/已推送/已存在
   b. 检查磁盘空间（如启用保护）：
      - 空间充足 → 推送种子到下载器
      - 空间不足 → 跳过当前种子，停止处理剩余种子

自动删种流程（存量清理）

1. 遍历所有已配置的下载器
2. 获取下载器中的种子列表
3. 按管理范围过滤出"可管理"的种子（严格遵守 scope）
4. 排除受保护的种子（下载中/H&R/保护标签/最短保种时间）
5. 评估删除条件（按 AND/OR 模式判断）
6. 检查磁盘空间（如启用保护）：
   - 空间充足 → 只删除满足条件的种子
   - 空间不足 → 在管理范围内按评分强制删除直到空间恢复
7. 执行删除 + 更新数据库 + 记录日志

H&R 保护

H&R（Hit & Run）是部分 PT 站点的规则，要求用户下载种子后必须做种一定时长，否则会受到处罚。

工作原理：

pt-tools 在下载种子时会记录站点返回的 H&R 标记和要求的做种时长
自动删种时会检查数据库中的 H&R 信息；内置站点定义声明了 H&R 规则的站点，即使种子没有单独的 H&R 标记，也会按站点规则计算要求的做种时长
如果种子有 H&R 要求且当前做种时间未达标，该种子会被保护，不会被删除
无 H&R 要求的站点和种子不受影响

注意：并非所有站点都提供 H&R 信息。如果站点未返回 H&R 标记、内置站点定义中也没有 H&R 规则，pt-tools 无法自动识别。建议同时设置合理的最短保种时间作为额外保障。

多下载器安全

当配置了多个下载器时：

每个下载器独立处理，互不影响
「仅本应用推送的种子」模式通过数据库中的 downloader_name 字段精确匹配种子到对应的下载器
不会出现下载器 A 的种子被当作下载器 B 的种子处理的情况

常见配置示例

场景 1：日常刷流（推荐）

适合大多数用户的保守配置：

配置项	值
管理范围	仅本应用推送的种子
条件关系	OR
做种时间	72 小时
分享率	2.0
免费到期删除	开
保护 H&R	开
最短保种时间	24 小时
磁盘保护	开，最低 50 GB

场景 2：磁盘空间紧张

优先保证磁盘不满：

配置项	值
管理范围	仅本应用推送的种子
条件关系	OR
做种时间	48 小时
分享率	1.0
不活跃时间	24 小时
磁盘保护	开，最低 50 GB

场景 3：追求高分享率

只有充分利用后才删除：

配置项	值
管理范围	仅本应用推送的种子
条件关系	AND
做种时间	168 小时（7 天）
分享率	3.0
保护 H&R	开
最短保种时间	48 小时
磁盘保护	开，最低 100 GB

AND 模式下，种子必须同时做种超过 7 天且分享率达到 3.0 才会被删除。建议搭配磁盘保护并设置较大的保底空间，防止高分享率目标导致种子大量堆积撑满硬盘。

暂存种子文件清理（.torrent 中间文件）

注意区分：本节说的是 pt-tools 本地暂存目录里的 .torrent 中间文件，不是上面「自动删种」管理的 qBittorrent 做种任务。两者是完全独立的两套清理机制。

清理对象

RSS 下载种子后，会先把 .torrent 文件写入本地暂存目录（{下载目录}/{tag}/，文件名形如 siteName-torrentID.torrent），再推送给下载器。长期运行下，如果某些种子一直推送失败、被跳过或者对应的 RSS 订阅已经不再处理，这些暂存文件会不断堆积，占用磁盘（对应 Issue #450）。

本节描述的清理机制，只针对这些本地暂存的 .torrent 文件，不会触碰下载器里的任何数据。

触发时机

每个站点每轮 RSS 推送任务结束时自动执行一次，不需要单独开启「自动删种」总开关。无论本轮推送是正常处理完全部种子、因磁盘保护中途停止，还是因为部分种子过大被跳过，清理都会执行（内部通过 defer 保证）。

清理策略

遍历暂存目录中该站点的 .torrent 文件，逐个判断，满足以下任一条件即删除：

条件	说明
数据库中无对应记录	孤立文件，直接删除
数据库中已标记为推送成功（已推送）	属于推送后的残留副本，删除
重试次数已达最大重试次数	判定为不可恢复，删除
未推送，但文件修改时间超过「保留时长」	长期卡在待推送状态，视为老化文件，删除
未推送，且文件较新（仍在保留期内）	仍在正常重试窗口，保留

为什么用文件 mtime 而不是数据库的最后检查时间：RSS 每轮任务都会刷新数据库里种子的最后检查时间，如果按这个字段判断老化，会导致"每轮都被看到、但一直推送不出去"的种子永远不会老化，这正是历史堆积问题的根因。改用文件系统的修改时间后，已经堆积很久的旧文件在下一轮任务里就能被正确识别并清理。

配置项

复用「全局设置」→「暂存种子清理」中已有的暂存种子保留时长（小时）（RetainHours，默认 24 小时）作为暂存文件的老化阈值，无需额外配置。

保留时长设为 0 时，暂存清理关闭，保持旧版本行为，向后兼容。
其他数值下，文件修改时间早于「当前时间 - 保留时长」即视为老化。

边界与安全说明

暂存清理只删除本地 .torrent 中间文件，绝不会删除下载器中已下载或正在做种的数据。即使某个文件在数据库里标记为已推送，删除的也只是本地这份暂存副本，下载器里的任务不受影响。
已知局限：暂存清理挂在 RSS 推送流程上执行。如果某个站点的 RSS 订阅已被删除或停用，其对应目录下遗留的 .torrent 不会再有任务触发清理，需要手动删除，或者重新添加该 RSS 订阅以触发一次清理。

与超大种子跳过的关联

Issue #450 同时修复了"超大种子触发磁盘保护后会阻塞后续种子推送"的问题：现在遇到超大种子会跳过并继续处理剩余种子（原因记录在种子的 last_error 中），不再中断整轮推送。被跳过的种子对应的 .torrent 会保留在暂存目录中，等待磁盘空间恢复后重试，最终同样由上述 mtime 老化机制清理。

工作目录统一清理（.pt-tools）

与前两节的区别：上面的「自动删种」管理的是下载器里的做种任务；「暂存种子文件清理」挂在单个站点的 RSS 推送流程上、只处理当前订阅的 tag 目录。本节的「工作目录统一清理」是一套独立的、按需触发的机制，一次性清理整个 ~/.pt-tools 工作目录下堆积的日志、暂存种子、旧备份，并扫描 downloads 下的全部 tag 子目录（不依赖当前是否还有对应的 RSS 订阅），补上了「订阅删除后残留目录够不到」的清理盲区。

清理对象

统一清理只在 ~/.pt-tools 工作目录下三个固定白名单目录内操作：

类别	目录	清理内容
`logs`	`~/.pt-tools/logs`	已轮转的日志备份（`all-.log`、`debug-.log.gz` 等），保留策略与日志滚动配置（保留份数/天数）一致
`staging`	`~/.pt-tools/downloads`	该目录下所有 tag 子目录里已无意义的 `.torrent`（已推送/孤立/达最大重试/超保留期）
`backups`	`~/.pt-tools/backups`	旧的配置备份 `.json`，按修改时间倒序保留最近 N 份*（默认 5），其余删除

staging 类别的判定规则与「暂存种子文件清理」相同（复用 RetainHours / MaxRetry 配置；RetainHours<=0 时改用默认的 24 小时，该类别不会关闭），差别在于统一清理扫描的是白名单根 ~/.pt-tools/downloads 下的全部 tag 子目录，而不局限于当前 RSS 订阅。

红线：绝对不会删除的文件

以下文件是硬编码红线，无论在哪个类别、无论何种参数，都永远不会被删除：

数据库：torrents.db 及其 torrents.db-wal、torrents.db-shm
加密密钥：secret.key（丢失将导致所有站点 cookie 无法解密）
正在写入的日志 base 文件：all.log、debug.log、info.log、error.log（只删轮转出来的备份，不删正在写入的本体）

此外还有一条目录红线：如果你把「全局设置」里的「种子下载目录」（DownloadDir）配成了 ~/.pt-tools 之外的绝对路径（例如挂载的数据盘），统一清理一律不碰那个目录——staging 清理的扫描根固定是 ~/.pt-tools/downloads，绝不读取 DownloadDir 配置来扩大清理范围。

两个入口

命令行：`pt-tools clean`

参数	默认值	说明
`--dry-run`	`true`	预览模式，只列出将删除的文件而不实际删除
`--confirm`	`false`	确认执行真实删除（破坏性操作，未加此项时一律只预览、不删除）
`--category`	空	限定清理类别 `logs,staging,backups`，逗号分隔；留空表示全部三类
`--keep-backups`	`5`	`backups` 类别保留的最近份数

bash

# 预览将清理的内容（默认，安全，不会删除任何文件）
pt-tools clean

# 只预览 logs 类别
pt-tools clean --category logs

# 真实删除（破坏性，需显式确认）
pt-tools clean --confirm

# 真实删除并保留最近 10 份备份
pt-tools clean --confirm --keep-backups 10

若显式要求真实删除（--dry-run=false）却没有加 --confirm，命令会拒绝执行并提示需要 --confirm 确认，避免误删。

Web 界面：`/cleanup` 页「清理工作目录」

在 Web 管理界面「规则 → 自动清理」页面底部的「清理工作目录 (.pt-tools)」卡片：

勾选要清理的清理项（日志文件 / 暂存种子文件 / 旧配置备份，默认全选）
设置「保留最近备份数量」（默认 5；填 0 时也按 5 份保留）
点击「预览可清理项」→ 以表格展示各类别可删除数量与可释放空间，并标注受保护/跳过项（此时不会删除任何文件；预览总是覆盖全部三类，并按保留 5 份备份计算）
点击「立即清理」→ 弹出二次确认框（明确提示数据库、密钥等受保护项不会被删除、操作不可撤销）→ 确认后才真正删除，并展示删除结果

安全机制

统一清理默认以最安全的方式运行，每一次删除都要通过多重校验：

默认不删：CLI 默认 --dry-run（只预览）；Web 端「预览优先」，可以先预览，真正删除必须显式点击「立即清理」并二次确认。
白名单校验：每一个候选删除路径都会先 EvalSymlinks 解析软链，再用 filepath.Rel 判定是否仍落在三个白名单根之内；越界（.. 逃逸、绝对路径逃逸）即拒绝并记录，绝不删除。
允许根自身的软链防护：三个白名单根本身也会先解析软链——如果某个根（例如 downloads）被做成了指向外部盘的软链、解析后越出 ~/.pt-tools，则该类别整体拒绝清理并记录告警，绝不在其下删任何文件。
红线二次保险：即使某个候选侥幸落在白名单内，还会再叠加一次红线文件名校验（torrents.db/wal/shm、secret.key、日志 base 文件），命中即拒绝。
单文件失败不中断：任何单个文件因命中红线或越界被拒绝，只会记录到「跳过」项，不会中断本次其余文件的清理。

自动删种功能 ​

功能概述 ​

配置说明 ​

基本设置 ​

管理范围 ​

删除条件 ​

磁盘空间保护 ​

保护规则 ​

执行逻辑 ​

RSS 推送流程（入口防护） ​

自动删种流程（存量清理） ​

H&R 保护 ​

多下载器安全 ​

常见配置示例 ​

场景 1：日常刷流（推荐） ​

场景 2：磁盘空间紧张 ​

场景 3：追求高分享率 ​

暂存种子文件清理（.torrent 中间文件） ​

清理对象 ​

触发时机 ​

清理策略 ​

配置项 ​

边界与安全说明 ​

与超大种子跳过的关联 ​

工作目录统一清理（.pt-tools） ​

清理对象 ​

红线：绝对不会删除的文件 ​

两个入口 ​

命令行：pt-tools clean ​

Web 界面：/cleanup 页「清理工作目录」 ​

安全机制 ​

自动删种功能

功能概述

配置说明

基本设置

管理范围

删除条件

磁盘空间保护

保护规则

执行逻辑

RSS 推送流程（入口防护）

自动删种流程（存量清理）

H&R 保护

多下载器安全

常见配置示例

场景 1：日常刷流（推荐）

场景 2：磁盘空间紧张

场景 3：追求高分享率

暂存种子文件清理（.torrent 中间文件）

清理对象

触发时机

清理策略

配置项

边界与安全说明

与超大种子跳过的关联

工作目录统一清理（.pt-tools）

清理对象

红线：绝对不会删除的文件

两个入口

命令行：`pt-tools clean`

Web 界面：`/cleanup` 页「清理工作目录」

安全机制