# Rust RSS 追番服务 使用 Rust 独立设计实现的 RSS 订阅与下载自动化项目，采用 **GPL-2.0-only**。 功能方向参考 [ani-rss](https://github.com/wushuo894/ani-rss)，没有移植其 Java 业务代码或前端资源；本项目不是上游的官方 Rust 版本。 当前为后端 MVP：蜜柑搜索 / 手动 RSS → 订阅管理 → RSS/Atom 预览 → 持久化任务 → qBittorrent 提交与状态同步。 现有 Actix 示例接口继续保留。 ## 运行 ```sh cargo run --locked ``` 默认监听 `127.0.0.1:8080`，自动创建 `data/ani.db` 并运行数据库迁移。 当前 API 供本机使用，没有用户认证；监听地址固定为回环地址。 首次运行需要下载 Cargo 依赖。已在 Rust 1.93.1 上进行编译验证。 按需配置环境变量，参见 [.env.example](.env.example)。程序不自动读取 `.env`： ```sh export QBIT_URL='http://127.0.0.1:8081' export QBIT_USERNAME='admin' export QBIT_PASSWORD='你的密码' export QBIT_SAVE_PATH='/downloads' cargo run --locked ``` qBittorrent 需要启用 Web UI。`QBIT_SAVE_PATH` 是下载器看到的路径。 `QBIT_*` 只在数据库尚无下载器实例时导入一次，并选为全局下载器。已有实例时，重启或修改这些环境变量不会覆盖保存的实例或选择。 全新安装不设置 `QBIT_URL` 时，仍可管理订阅、预览和生成未分配任务；首次通过接口选中下载器后绑定这些任务。清空环境变量不会停用数据库中已选中的下载器。 程序启动后立即执行一轮检查，之后默认每 300 秒检查一次；`POLL_INTERVAL_SECONDS` 最小为 10。 ## 使用流程 ### 从蜜柑发现订阅 ```sh curl -G 'http://127.0.0.1:8080/api/sources/mikan/search' --data-urlencode 'q=葬送' curl 'http://127.0.0.1:8080/api/sources/mikan/series/3141' curl 'http://127.0.0.1:8080/api/sources/mikan/resolve' \ -H 'Content-Type: application/json' \ -d '{"url":"https://mikanani.me/Home/Bangumi/3141"}' ``` 搜索返回各季度的独立候选及关键词 RSS。详情返回整部番剧 RSS、字幕组 RSS、站点信息和可用封面地址。 将详情中的字幕组 `rss_url` 传给 `resolve`，可以获得对应字幕组候选。 `resolve` 返回的 `subscription` 对象可直接作为下面预览、保存接口的请求体；默认禁用，`season=1` 只是初始值，需核对季度、偏移和筛选规则。 候选中的来源 ID、字幕组 ID 和范围用于发现流程；当前订阅保存标题、RSS 与规则，尚不单独持久化这些来源元数据。 关键词 RSS 可能跨多部作品，`resolve` 返回 `scope=keyword`、提示和 RSS 地址，`subscription=null`，不会生成单番剧草稿。 建议选择具体番剧；若手工使用关键词 RSS，需先用规则将内容限定为一部作品并预览。 搜索、查看详情、解析链接和预览均不创建下载任务。发布条目通过 RSS 预览获取，不从详情 HTML 重复解析。 这阶段提供后端 API，尚无搜索管理页面或蜜柑账号同步。 ### 网站代理 ```sh export WEBSITE_PROXY_URL='http://127.0.0.1:7897' # 或 socks5h://127.0.0.1:7897，让代理解析目标域名 export MIKAN_BASE_URL='https://mikanani.me' cargo run --locked ``` 网站客户端支持 HTTP、HTTPS、SOCKS5 和 SOCKS5H 代理 URL，可在 URL 内携带编码后的用户名和密码。 `socks5` 本地解析目标域名，`socks5h` 由代理解析。配置在启动时读取，修改后重启。 **不继承** `HTTP_PROXY`、`HTTPS_PROXY`、`ALL_PROXY` 或 `NO_PROXY`；未设置 `WEBSITE_PROXY_URL` 时直连。 可用 `WEBSITE_DIRECT_HOSTS` 设置逗号分隔的显式直连域名/IP/CIDR，例如 `localhost,127.0.0.1,::1`，默认没有例外。 每次重定向重新应用代理及例外；代理失败返回错误，不自动直连。 蜜柑搜索、详情、封面、RSS 和种子元数据请求共用网站策略。封面返回本应用地址，由后端获取，浏览器无需直连蜜柑。 当前仅识别蜜柑同源 `/images/` 下的封面，支持 PNG/JPEG/WebP/GIF；其他图片布局会显示无封面。 qBittorrent 控制连接独立且始终直连；BT 传输由下载器控制。容器中的 `127.0.0.1` 指容器自身。 网站基址必须是无路径、查询参数或凭据的 HTTP(S) origin；粘贴解析仅接受该站点的公开搜索/番剧页面或 RSS。 ### 预览、保存和启用 1. 预览真实的 RSS 地址，查看匹配结果。预览不会保存订阅或提交下载。 ```sh curl -s http://127.0.0.1:8080/api/preview \ -H 'Content-Type: application/json' \ -d '{ "title": "示例番剧", "rss_url": "https://example.com/anime.xml", "season": 1, "episode_offset": 0, "include": ["1080p"], "exclude": ["合集"], "enabled": false }' ``` 2. 将相同 JSON 提交到 `POST /api/subscriptions` 保存订阅。订阅默认禁用。 3. 确认预览结果后，向 `PUT /api/subscriptions/{id}` 提交完整 JSON，将 `enabled` 改为 `true`。 4. 等待自动检查，或使用 `POST /api/run` 立即执行一轮 RSS 检查和下载同步。 5. 使用 `GET /api/jobs` 查看状态、失败原因和重试时间。 首次启用会考虑 RSS 当前返回的全部匹配条目，尚未实现“仅从当前最新集开始”。 `include` 为不区分大小写的关键词“全部满足”，`exclude` 为“任意命中则排除”，不是正则表达式。 修改订阅规则只影响后续扫描；已入队任务保留创建时的季度、集数和资源地址。禁用订阅会暂停未提交任务。 ## API | 方法 | 路径 | 用途 | | --- | --- | --- | | GET | `/api/status` | 版本及下载器是否配置，不返回凭据 | | GET / POST | `/api/downloaders` | 列出 / 创建下载器实例，响应不返回密码 | | PUT | `/api/downloaders/active` | `{"downloader_id":"实例 ID"}` 选择接收新任务的全局下载器 | | POST | `/api/downloaders/{id}/claim-legacy-jobs` | 将升级后尚无归属的旧任务明确关联到恢复的原实例 | | GET / POST | `/api/destinations` | 列出 / 创建本地媒体目的地 | | PUT | `/api/destinations/active` | `{"destination_id":"目的地 ID"}` 设置全局目的地 | | GET / POST | `/api/destinations/{id}/mappings` | 查看历史映射 / 新增映射版本 | | GET | `/api/destinations/{id}/entries?path=相对目录` | 只读浏览目录，省略 path 为根目录 | | GET | `/api/sources/mikan/search?q=关键词` | 番剧搜索和关键词 RSS | | GET | `/api/sources/mikan/series/{id}` | 番剧、字幕组及对应 RSS | | GET | `/api/sources/mikan/series/{id}/cover` | 经网站网络策略获取封面 | | POST | `/api/sources/mikan/resolve` | `{"url":"蜜柑地址"}` → 订阅候选 | | POST | `/api/preview` | 临时预览，不写库、不下载 | | GET / POST | `/api/subscriptions` | 列出 / 创建订阅 | | GET / PUT / DELETE | `/api/subscriptions/{id}` | 查询 / 完整替换 / 删除订阅 | | GET | `/api/subscriptions/{id}/preview` | 预览已保存订阅，包含去重判断 | | POST | `/api/subscriptions/{id}/scan` | 扫描并入队，要求订阅已启用 | | GET | `/api/subscriptions/{id}/releases` | 最近最多 500 条扫描记录 | | GET | `/api/jobs` | 最近最多 500 个任务 | | GET | `/api/jobs/{id}/files` | 读取已保存的文件清单与核对状态 | | POST | `/api/jobs/{id}/files/check` | 发现文件清单（首次）并核对本地文件是否存在 | | POST | `/api/jobs/{id}/retry` | 手动重试 failed / missing 任务 | | POST | `/api/run` | 执行完整扫描及下载同步 | 后台处理与手动执行互斥；处理期间修改订阅或再次执行会返回 `409`，稍后重试即可。 删除订阅为软删除，保留去重与任务记录，不删除下载器任务或媒体文件。已提交任务仍会同步状态。 ## 下载器实例与切换 ```sh curl 'http://127.0.0.1:8080/api/downloaders' \ -H 'Content-Type: application/json' \ -d '{"name":"NAS qBittorrent","kind":"qbittorrent","connection":{"url":"http://nas:8081","username":"admin","password":"你的密码","save_path":"/downloads"}}' # 将返回的 id 填入下面的 downloader_id。 curl -X PUT 'http://127.0.0.1:8080/api/downloaders/active' \ -H 'Content-Type: application/json' -d '{"downloader_id":"返回的实例 ID"}' ``` 创建实例不会自动切换全局选择。任务在扫描入队的同一个事务中保存 `downloader_id`；已有归属的排队任务、重试和重启恢复都使用原实例。 切换后继续同步原实例；一个实例连接失败会报告该实例 ID，并继续处理其他实例，不把连接失败标成任务丢失。 原实例的地址与写入路径不随全局选择改变。本阶段只实现多个 qBittorrent 实例，不提供实例编辑/删除；第二种工具与凭据维护接口另行扩展。 实例凭据保存在 SQLite 数据库中，尚未加密；数据库及其备份应按含凭据的配置文件管理。列表和创建响应只返回 `password_configured`。 ### 从旧版本升级 升级迁移为旧任务增加实例归属字段。首次导入时，应提供**旧任务实际使用的原 `QBIT_*` 配置**，应用会将它与旧任务关联；不能在升级时把这些值替换成另一台下载器。 若升级时没有提供原配置，历史任务保留 `legacy_unassigned=true`，不会自动绑定以后新选中的实例；`/api/status` 的 `legacy_unassigned_jobs` 及运行报告会提示数量。 恢复原实例后，显式调用 `POST /api/downloaders/{原实例ID}/claim-legacy-jobs` 才建立关联。该操作仅认领没有归属的旧任务，不迁移已有归属，也不立即提交下载；后续同步先核对原实例的任务。 ## 全局媒体目的地与本地文件核对 先配置并选中下载器，再创建一个本地目的地，配置该下载器的写入路径映射，最后激活目的地： ```sh curl 'http://127.0.0.1:8080/api/destinations' \ -H 'Content-Type: application/json' \ -d '{"name":"番剧目录","kind":"local","root_path":"/mnt/nas/anime"}' curl 'http://127.0.0.1:8080/api/destinations/目的地ID/mappings' \ -H 'Content-Type: application/json' \ -d '{"downloader_id":"下载器ID","download_root":"/downloads/anime"}' curl -X PUT 'http://127.0.0.1:8080/api/destinations/active' \ -H 'Content-Type: application/json' -d '{"destination_id":"目的地ID"}' ``` `root_path` 是 Rust 应用所在环境可访问的绝对目录；`download_root` 是同一个位置在下载器环境中的绝对路径。 配置映射不会挂载、复制或上传文件，也不会创建这些目录。两个路径必须实际指向同一批文件。 同一时刻所有新任务统一使用全局目的地，订阅不能覆盖。切换目的地或下载器前，必须存在所需映射，否则返回 `400`，不会静默使用默认目录。 每次 `POST mappings` 都追加一个版本；新任务使用最新版本，旧任务保留 `destination_id`、`mapping_id` 和 `download_save_path`。 目的地读取根目录和已有映射版本保持不变；更改读取根需创建新目的地。即使任务尚未提交、后来重试或应用重启，也不重新解释其存储位置。 同一下载器里已存在相同 hash，但保存路径与任务快照不一致时，任务报告冲突，不复用错误位置的下载、不自动移动种子。 未启用目的地时继续使用原下载器 `save_path`，保持旧配置可用。旧任务不会自动绑定后来创建的目的地；没有可靠位置的任务核对为 `unchecked`。本阶段没有旧任务目的地补录或文件迁移接口。 ```sh curl -G 'http://127.0.0.1:8080/api/destinations/目的地ID/entries' --data-urlencode 'path=Series' curl -X POST 'http://127.0.0.1:8080/api/jobs/任务ID/files/check' curl 'http://127.0.0.1:8080/api/jobs/任务ID/files' ``` 首次核对向原下载器读取文件清单，并核实其保存路径与快照一致。清单使用 [qBittorrent 文件接口](https://github.com/qbittorrent/qBittorrent/wiki/WebUI-API-%28qBittorrent-5.0%29#get-torrent-contents) 提供的相对文件名和大小，排除优先级为 0 的文件；不从发布标题猜文件名。 清单成功保存后，后续核对直接访问记录的本地路径，下载器离线也能执行。清单不会随下载器外部改名或移动而自动改写；本阶段不提供清单刷新或路径迁移。 核对由上述 POST 接口显式触发，后台下载同步暂不自动扫描文件系统。 | 状态 | 含义 | | --- | --- | | `unchecked` | 尚未核对，或未记录目的地、种子元数据/已选文件尚不可用 | | `present` | 成功访问并找到所有记录的普通文件 | | `absent` | 成功访问根目录，至少一个记录的文件不存在 | | `unavailable` | 根目录不可访问、权限不足、路径越界、映射不匹配或首次读取下载器清单失败 | 汇总时 `unavailable` 优先于 `absent`；每个文件分别记录结果。响应含本次尝试时间 `checked_at` 和最后成功核对时间 `last_success_at`，失败不会抹去后者。 存在状态独立于下载状态；文件缺失不会触发重下载或删除。返回预期/观察大小供查看，`present` 不保证大小一致或内容完整，也不将下载标记为完成。 目录浏览最多返回 1000 项，达到上限时 `truncated=true`；单个任务清单上限 5000 项。不读取文件内容、不提供播放。 本地访问通过 [cap-std 的目录能力接口](https://docs.rs/cap-std/4.0.3/cap_std/fs/struct.Dir.html) 限定在配置根目录内。相对路径拒绝绝对地址、`..`、盘符和反斜杠；符号链接不能越出根目录。根目录若离线而仍保留可访问的空挂载点，本阶段不具备挂载状态识别能力。 P2 仅支持进程可访问的本地目录。SMB 应用直连属于 P3，尚未实现。 ## 当前规则与恢复行为 - 支持常见 `[03]`、`- 03`、`EP03`、`第03话`、`S01E03` 以及 `03v2` 标题。 - 合集、分数集数、模糊或冲突的集数标记为 `needs_review`；目前可通过调整源或规则解决，尚无人工集数映射接口。 - RSS enclosure、Atom enclosure、磁力链接及 `.torrent` 链接可作为资源入口；尚未覆盖所有站点私有 XML 扩展。 - 支持 BitTorrent v1 磁力链接（十六进制或 Base32）及 v1/hybrid 种子；纯 v2 尚不支持。 - 同一订阅内按资源地址及“季度 + 集数”去重。相同集数有多个版本时采用 RSS 中先出现的条目，尚不自动洗版。 - 保存原始资源标题、地址、识别结果、过滤原因；种子文件按原始 info 字节计算 hash，并保存实际提交的种子数据。 - 下载前先持久化 hash 和提交意图，再调用下载器。超时或重启后先查询 qBittorrent，按 hash 核对，不盲目重复提交。 - 网络失败按 30 秒起、最多一小时的退避间隔重试；实际执行时间还受扫描周期影响。无效种子进入 `failed`，需手动重试。 - 已提交任务若从下载器消失，标记为 `missing`，不会自动重新下载。完成任务记录保留，不因再次扫描而重建。 - RSS/种子响应限制为 4 MiB，请求超时 30 秒。下载器 Cookie 与 RSS 请求使用不同客户端。 - 蜜柑 HTML 上限 8 MiB，封面上限 4 MiB；成功搜索/详情缓存 60 秒、最多 64 项，最多同时执行 4 个蜜柑请求，超限返回 `429`。HTTP 重定向最多 5 次。 - 无搜索结果返回空列表；页面无法识别、访问受限及上游失败返回 `502`，不会伪装成空列表。公开页面结构变化可能需要更新蜜柑适配器。 本地事务不能与下载器 API 组成原子事务。恢复依赖原下载器实例中的稳定 info hash 和下载器去重；同一数据库仅运行一个服务实例。使用全局选择接口切换不会改变恢复目标。 ## 结构与验证 ```text src/api.rs HTTP 接口 src/domain.rs 订阅、资源、任务模型与输入校验 src/parser.rs 标题与集数识别 src/feeds.rs RSS/Atom 获取、解析、过滤 src/mikan.rs 蜜柑搜索、详情、订阅候选与封面 src/media.rs 本地文件访问、路径校验与媒体数据结构 src/media_store.rs 目的地、版本化映射、文件清单与核对记录持久化 src/storage.rs SQLite 持久化与去重 src/downloader.rs 种子标识与 qBittorrent 适配 src/service.rs 扫描、任务恢复与后台调度 migrations/ 数据库迁移 tests/fixtures/ 人工构造的 RSS 测试样本 ``` ```sh cargo fmt --check cargo test --locked cargo clippy --locked --all-targets -- -D warnings ``` 集成测试使用回环地址上的模拟蜜柑 / RSS / 代理 / qBittorrent 服务和临时 SQLite 数据库，不连接真实下载器、不下载媒体。 覆盖过滤、保守集数解析、重复扫描、数据库重开、提交成功但响应失败后的恢复、下载器不可用、禁用订阅、任务移除与 API CRUD。 新增覆盖中文搜索编码、不同季度、字幕组 ID、RSS 候选到保存、访问限制页面、封面与缓存、代理认证及跨域重定向、直连例外和代理失败处理。 下载器归属测试覆盖切换时已排队任务、同 hash 不同实例、单实例离线、重试、重启，以及真实旧版 SQLite 数据库升级后的显式归属恢复。 P2 使用临时本地文件与模拟下载器，覆盖目的地/映射版本快照、实际提交路径、同 hash 不同路径冲突、文件四态、成功核对时间保留、下载器离线核对、目录浏览与路径/符号链接限制。没有连接真实 NAS 或下载器。 已实现全局媒体目的地与本地文件存在核对。后续将支持 SMB 应用直连、第二种下载工具、MySQL、管理页面和部署。 ## 许可证 本项目按 GNU General Public License version 2 only 发布，完整条款见 [LICENSE](LICENSE)。 新增 Rust 源文件使用 `SPDX-License-Identifier: GPL-2.0-only` 标识。第三方依赖遵循各自许可证。