qbitlarr

# qBitlarr **语言：** 简体中文 **一款连接 Prowlarr 和 qBittorrent 的桥梁，提供 REST、MCP 和 CLI 支持。** 适用于已经运行 Plex、Jellyfin 或 Emby 的用户，希望以轻量级方式让朋友、家人或 LLM 代理请求电影和电视节目，而无需给予他们 qBittorrent 访问权限，也无需运行完整的 Sonarr + Radarr 堆栈。 qBitlarr 是一个小型 FastAPI 服务： - 接受自然语言标题、IMDb ID 或 IMDb / 豆瓣 / AlloCiné 链接。 - 确定标题，然后搜索您的 Prowlarr 索引器。 - 使用有偏好的可配置质量偏好对版本进行排序，并显示前几个版本供您选择。 - 在您的 qBittorrent 中排队您的选择（或在 `auto` 模式下自动选择）。 - 通过 REST、MCP 和 CLI 公开所有内容，以便于与 Claude Desktop、Cursor、ChatGPT 自定义工具、Telegram 机器人、Shell 脚本、cron 作业或您自己的代理集成。 适用于任何 HTTP 客户端、Claude/Cursor/ChatGPT via MCP 或 `qbitlarr` CLI。 ## 架构  可编辑的 REST / MCP / CLI 图表源：[docs/architecture.svg](docs/architecture.svg)。 ## Docker Compose 中运行的内容 - `qbitlarr` - FastAPI 服务，运行在 `http://localhost:8000` - `prowlarr` - 捆绑的 Prowlarr，运行在 `http://localhost:9696` - `flaresolverr` - 捆绑的 FlareSolverr，运行在 `http://localhost:8191` qBittorrent **未** 捆绑。 通过 `QBIT_URL`、`QBIT_USERNAME`、`QBIT_PASSWORD` 将 qBitlarr 指向现有的 qBittorrent - 桌面版、NAS、种子盒或独立容器。 ## qBittorrent 设置 qBitlarr 需要现有的 qBittorrent 安装，因为每个人都将媒体保存在不同的位置：桌面应用程序、NAS、种子盒或独立容器。qBitlarr 仅通过其 Web UI API 与 qBittorrent 通信。 在启动 qBitlarr 之前： 1. 在您应该运行下载的位置安装 qBittorrent。 2. 在 qBittorrent 中，打开 **首选项 / 选项 → Web UI** 并启用 Web 用户界面。 3. 设置或确认 Web UI 用户名和密码。 4. 将这些值放入 `.env` 中： ```sh QBIT_URL=http://host.docker.internal:8080 QBIT_USERNAME=您的网络界面用户名 QBIT_PASSWORD=您的网络界面密码 ``` 当 qBittorrent 在与 Docker Compose 相同的机器上运行时，请使用 `http://host.docker.internal:8080`。如果 qBittorrent 在 NAS、种子盒或其他计算机上运行，请使用该机器的局域网 URL 代替，例如 `http://192.168.1.50:8080`。不要在 `.env` 中为已安装的 qBittorrent 使用 `localhost`；在 Docker 中，`localhost` 指的是 qBitlarr 容器本身。 ## 快速入门 ```sh cp .env.example .env # 编辑 .env：设置 QBIT_URL、QBIT_USERNAME、QBIT_PASSWORD 从您的 qBittorrent Web UI # 1. 首先启动 Prowlarr，以便您可以获取其 API 密钥 docker compose up -d prowlarr flaresolverr # 2. 打开 http://localhost:9696，完成首次运行设置，添加索引器， # 然后从设置 -> 常规 -> 安全复制 API 密钥 # 3. 将密钥放入 .env 中作为 PROWLARR_API_KEY # 4. 启动其余部分 docker compose up -d --build # 5. 试试看 curl -X POST http://localhost:8000/handle \ -H 'Content-Type: application/json' \ -d '{"user_message":"tt0045877"}' ``` 对于也检查依赖项并 ping Prowlarr 和 qBittorrent 的操作： ```sh curl 'http://localhost:8000/health?deep=true' ``` ## 使用感受 一旦 qBitlarr 与您的代理（或您正在使用 CLI）连接，您就可以像与知道您的媒体设置的普通朋友一样与它交谈： 对于电影请求，qBitlarr 直接接受 IMDb 链接和 ID，也可以解析支持的豆瓣电影链接或 ID 以及 AlloCiné 电影链接或 ID 到相同的基于 IMDb 的流程。如果豆瓣或 AlloCiné 电影无法安全解析，qBitlarr 请求 IMDb 而不是猜测。 以下示例使用 [The Hitch-Hiker (1953)](https://www.imdb.com/title/tt0045877/)，这是一部公共领域电影，由国会图书馆在其 [公共领域电影国家电影登记册](https://www.loc.gov/free-to-use/public-domain-films-from-the-national-film-registry/) 集中列出。权利可能因司法管辖区和特定的修复、配乐、字幕或版本而有所不同。 <table> <tr> <td width="42.5%" align="center" valign="middle"> <img src="docs/screenshots/telegram-imdb-release-picker.jpg" height="430" alt="Telegram 示例：分享 The Hitch-Hiker 的 IMDb 页面，选择版本，并查看 qBitlarr 下载进度。"> </td> <td width="57.5%" align="center" valign="middle"> <img src="docs/screenshots/telegram-title-release-picker.jpg" height="430" alt="Telegram 示例：搜索标题，选择正确的电影，选择版本，并查看 qBitlarr 下载进度。"> </td> </tr> </table> *截图仅供参考。左侧：IMDb 链接或 ID 直接进入版本选择和下载进度。右侧：标题搜索 `The Hitchhiker 1953` 返回四个标题选择；选择 The Hitch-Hiker (1953) 打开相同的版本选择器和进度视图。演示标题是公共领域示例；权利可能因司法管辖区和特定的修复、配乐、字幕或版本而有所不同。* > **您：** *下载 The Hitchhiker 1953。* > **代理：** 您指的是哪一个？ > 1. The Hitchhiker's Guide to the Galaxy (2005) > 2. The Hitch-Hiker (1953) > 3. An American Hippie in Israel (1972) > 4. The Hitch Hiker (2004) > **您：** *点击 The Hitch-Hiker (1953)。* > **代理：** 选择要下载的版本： > 1. WEB-DL · H.264 · 5.3 GB > 2. 1.2 GB 选项 > 3. WEB-DL · H.264 · 5.3 GB > 4. BluRay · H.264 · 5 GB > 5. BluRay · H.264 · 8.7 GB > **您：** *点击 1.2 GB 版本。* > **代理：** 好的，我将添加下载。 > **代理：** ⬇️ The Hitch-Hiker (1953) [1080p]<br> > 🟩🟩🟩🟩⬜⬜⬜⬜⬜⬜ 36%<br> > 💾 421.9 MB / 1.1 GB<br> > ⚡ 速度：558.4 KB/s<br> > ⏱️ 预计时间：5 分 24 秒 > **您：** *下载 tt0045877* > **代理：** 由于 IMDb ID 已经确定了电影，qBitlarr 跳过了标题选择器，直接打开版本按钮。 在幕后，每个请求都解析为一个标题：IMDb / 豆瓣 / AlloCiné 链接或 ID 直接锁定标题，而普通关键词则与维基数据匹配。如果多个标题匹配，qBitlarr 返回标题选择，让聊天适配器可以将其呈现为按钮；选择一个继续到版本选择器。如果没有任何匹配，qBitlarr 请求 IMDb 链接而不是猜测。 一旦标题固定，它会排名版本并以结构化的按钮和表格返回前几个选择；在 `auto` 模式下，它直接排队最好的一个。 说 *"4K"*、 *"Remux"* 或 *"720p HEVC"* 可以覆盖默认质量。 状态以原始数据 (`qbitlarr_list_downloads` / `qbitlarr_get_download_status`) 或聊天-ready 表情符号进度卡 (`qbitlarr_render_*`) 返回； 有关刷新和完成通知的详细信息，请参见 [连接到代理](#连接到代理)。 ### 小贴士：直接从电影应用或网站分享 使用 qBitlarr 的最快方法是跳过输入标题： 1. 在 IMDb、豆瓣、AlloCiné 或任何支持的电影 URL 的网站上找到您想要的内容。 2. 点击分享图标 → 选择您的代理所在的聊天应用（Telegram、WhatsApp、Discord、Signal、iMessage 等）。 3. 代理接收到类似 `https://www.imdb.com/title/tt0045877/` 的 URL，解析为规范的 IMDb 流程，并自动识别标题 - 无需输入，无需拼写陷阱，无需歧义。 像 `tt0045877` 这样的原始 IMDb ID 也以相同的方式工作，如果您有现成的 ID。qBitlarr 还接受 `douban:1292052` 和 `allocine:25801` 以获取支持的电影 ID。它解析这些 ID 并直接跳转到该确切标题的排名版本选择器 - 无需标题匹配步骤。 ## 何时使用此功能与 Sonarr / Radarr 使用 **Sonarr/Radarr** 如果您想要一个库管理器：跟踪剧集、升级策略、自动监控新版本、具有 30 个旋钮的质量配置文件。 使用 **qBitlarr** 如果您只需要： *"朋友说一个电影名称 → 一小时后它出现在 Plex 上。* 没有库，没有监控，没有配置文件 UI。一个服务，四个环境变量，搞定。 ## 合理使用 qBitlarr 是一个自动化桥梁。它不提供内容、索引器、跟踪器或法律建议。仅在您有权访问的索引器和媒体上使用它。 ## 在 Prowlarr 中设置索引器 如果这是您第一次遇到 **Prowlarr**：它是一个 *索引器聚合器*。它连接到许多 torrent 站点（称为“索引器”），并为 qBitlarr 提供一个统一的搜索 API。没有它，qBitlarr 必须知道如何与数十个具有自己特殊性的不同站点通信 - Prowlarr 是隐藏所有这些的层。一次性添加索引器，然后每个 qBitlarr 搜索都并行命中所有索引器。 **添加索引器：** 1. 打开 `http://localhost:9696` 并进入 **索引器 → + 添加索引器**。 2. 在过滤器中输入索引器名称。 3. **公共索引器**：通常只需点击 **保存** - 无需登录。 4. **私人跟踪器**：粘贴来自您在该跟踪器上的帐户的 cookie / API 密钥 / passkey。每个跟踪器都有稍微不同的字段，Prowlarr 的表单会告诉您需要什么。 5. 点击 **测试** 以确认 Prowlarr 可以访问它，然后 **保存**。 6. 索引器现在有一个数字 ID，可以通过 `curl http://localhost:8000/prowlarr/indexers` 发现。 对于任何位于 Cloudflare 后的索引器，还要使用 `flaresolverr` 代理 - 参见下文 [为什么 FlareSolverr 被捆绑](#为什么 FlareSolverr 被捆绑)。 **公共与私人跟踪器：** - **公共索引器** 通常快速添加，但通常具有较低的信号噪声比：更多的死种子、垃圾邮件和伪造版本。 - **私人跟踪器** 需要一个帐户，并且通常具有更严格的访问规则。它们的设置字段各不相同；请遵循您允许使用的跟踪器的要求。 **推荐：** - **从 2-4 个索引器开始，而不是 20 个。** 每个索引器都会为每个搜索添加延迟 - 一个缓慢的站点可以成为整个过程的瓶颈，而堆叠公共索引器大多会堆叠噪音，而不是信号。 - **混合覆盖范围和质量。** 一个或两个广泛的公共索引器作为安全网，加上您有权访问的任何私人跟踪器，是一个坚实的基础。 - **跳过 `同步配置文件` 除非您也运行 Sonarr 或 Radarr - qBitlarr 不需要它们。** 一旦索引器就位，可选地在 [索引器选择](#索引器选择) 中设置主要和备用 ID，以便 qBitlarr 首先搜索您的快速可靠索引器，仅在需要时才使用较慢或噪声较大的索引器。 ## 为什么 FlareSolverr 被捆绑 一些流行的索引器位于 **Cloudflare 的反机器人挑战** 后。普通的 HTTP 请求 - Prowlarr 默认执行 - 将获得一个 HTML 挑战页面而不是搜索结果，并且索引器有效地返回无。 **FlareSolverr** 是一个小型无头 Chrome 代理，解决这些挑战为 Prowlarr。当配置 Prowlarr 将某些索引器路由通过它时，FlareSolverr 在一个真正的浏览器中打开页面，等待 Cloudflare 通过，并将 cookie 返回给 Prowlarr，以便实际的搜索 API 调用成功。 qBitlarr 将其捆绑在一起，因为当用户将 Cloudflare 保护的索引器添加到 Prowlarr 时，他们会遇到这个障碍 - 官方解决方法是“单独安装 FlareSolverr”。将它包含在 docker-compose 文件中可以消除这个障碍。 **如何在 Prowlarr 中连接 **（一次性，首次启动后）： 1. 在 `http://localhost:9696` 打开 Prowlarr。 2. 进入 **设置 → 索引器 → 索引器代理**。 3. 点击 **+** 并选择 **FlareSolverr**。 4. 将 **主机** 设置为 `http://flaresolverr:8191`（内部 docker-compose 主机名），并赋予它一个 **标签**，例如 `flaresolverr`。 5. 保存。然后在任何 Cloudflare 保护的索引器上，打开它，添加相同的 `flaresolverr` 标签，并保存。 没有标签的索引器完全跳过 FlareSolverr - 对于非保护站点没有性能损失。如果您不使用任何 CF 保护的索引器，可以停止容器（`docker compose stop flaresolverr`）并且 qBitlarr 继续工作。 ## 质量偏好 默认情况下，qBitlarr 针对 **1080p WEB-DL H.264**，至少有 5 个种子。可以通过 env 更改默认值： ```sh QBITLARR_PREFER_RESOLUTION=1080p # 480p | 720p | 1080p | 2160p QBITLARR_PREFER_SOURCE=WEB-DL # WEB-DL | WEBRip | BluRay | HDTV QBITLARR_PREFER_CODEC=H.264 # H.264 | H.265 QBITLARR_MIN_SEEDERS=5 ``` 最终用户可以通过自然语言直接覆盖每个请求： - `"The Hitch-Hiker 4K"` → 强制 2160p - `"The Hitch-Hiker Remux"` → 强制 Remux 版本 - `"The Hitch-Hiker 720p HEVC"` → 720p H.265 ## 请求如何解析 每个 `/handle` 请求都遵循相同的路径，因此关键词和 IMDb 链接最终会到达同一个地方： 1. **识别标题。** IMDb ID/URL 或支持的豆瓣/AlloCiné 链接直接解析。普通关键词与维基数据匹配（无需 API 密钥，无需额外帐户）。如果多个标题匹配，qBitlarr 返回 `choose_title` 列表（标题 + 年份）并等待用户选择一个；如果没有任何匹配，qBitlarr 返回 `needs_imdb` 并请求 IMDb 链接。 2. **为该标题排名版本**，使用您的质量偏好。 3. **默认返回前 4 个版本选择** 以供选择 - 或在 `auto` 模式下直接排队最好的一个。 维基数据关键词匹配故意保持轻量级，因此不常见的标题可能无法解析；当 qBitlarr 请求 IMDb 链接而不是猜测时。 ### 输出模式 `POST /handle` 接受一个可选的 `mode` 字段： - `manual` *(默认)* - 返回排名的版本选择，永远不会排队任何内容。 - `auto` - 直接排队最好的版本。适用于“设置并忘记”的朋友/家人使用；响应包括 2-3 个备选的“或者你想…”列表。 - `confirm` - 返回最佳选择加上备选，但 **不** 排队。 用 `QBITLARR_DEFAULT_MODE=manual|auto|confirm` 覆盖服务器范围的默认设置。 选择器显示对于标题消歧 (`choose_title`) 和版本选择 (`show_results`) 都是传输中立的。响应包括紧凑的 `label` 值，用于通用澄清/选择工具，以及 `choices_table`、`choice_display`、`choice_rich_message`、`choice_buttons` 和 `ui_hints`，用于更丰富的聊天适配器。`choice_rich_message` 是 Telegram Bot API 10.1 友好型富文本 HTML；适配器可以将它的 `html` 值作为 `sendRichMessage.rich_message.html` 发送，并在下面渲染 `choice_buttons`。零配置默认值是 Hermes 友好的股票：`QBITLARR_MANUAL_RESULT_LIMIT=4` 和 `QBITLARR_CHOICE_STYLE=hermes-default`，匹配 Hermes 样式的澄清界面，显示四个选择并添加自己的“其他”选项。如果您的本地 Telegram/Hermes 适配器可以渲染富文本表格和五个按钮的封闭行，请设置： ```sh QBITLARR_MANUAL_RESULT_LIMIT=5 QBITLARR_CHOICE_STYLE=telegram-rich ``` 这只更改 qBitlarr 的结构化响应；实际的水平按钮布局仍属于您的本地聊天适配器或 Hermes 配置文件。 ## 已完成任务清理 qBitlarr 可以可选地删除它管理的已完成 qBittorrent 任务，同时在磁盘上保留实际下载的文件。新 qBitlarr 下载获得 `qbitlarr.managed` 标签；较旧的具有 `requester.*` 标签的任务也可以包含在内以兼容。 默认情况下，对开源用户禁用。启用并使用 env 变量调整： ```sh QBITLARR_CLEANUP_ENABLED=false QBITLARR_CLEANUP_COMPLETED_AFTER_SECONDS=259200 QBITLARR_CLEANUP_INTERVAL_SECONDS=21600 QBITLARR_CLEANUP_INCLUDE_LEGACY_REQUESTER_TAGS=true ``` 注意： - `QBITLARR_CLEANUP_COMPLETED_AFTER_SECONDS=259200` 表示清理已完成至少 3 天的任务。 - `QBITLARR_CLEANUP_INTERVAL_SECONDS=21600` 每 6 小时检查一次。 - 清理调用 qBittorrent 时使用 `delete_files=false`，因此它只删除 qBittorrent 任务，而不删除媒体文件。 - 具有 `qbitlarr.managed` 或旧版 `requester.*` 标签的未管理种子被忽略。 ## 连接到代理 qBitlarr 作为一个 **MCP 服务器**，因此任何支持模型上下文协议（Model Context Protocol）的代理都可以与其连接，例如 Claude Desktop、Cursor、Cline、Hermes、OpenClaw、通过 MCP 桥接的 ChatGPT，或者您自己的自定义代理。 MCP 工具与语言无关。用户可以用英语、中文、法语或任何代理的 LLM 支持的语言提问；代理可以用用户使用的相同语言回答。这种多语言行为取决于代理背后的 LLM，而不是 qBitlarr 本身。 提供两种传输方式： - **stdio MCP**：大多数桌面代理应用程序希望使用这种方式。它们会启动 `bin/qbitlarr-mcp` 作为子进程。 - **HTTP MCP**：在 `http://localhost:8000/mcp` 处提供，供喜欢使用 HTTP 的主机使用。 两种方式都暴露了以下工具：`qbitlarr_handle`、`qbitlarr_search`、`qbitlarr_download`、`qbitlarr_list_downloads`、`qbitlarr_get_download_status`、`qbitlarr_render_downloads_status`、`qbitlarr_render_download_status`、`qbitlarr_pause_download`、`qbitlarr_resume_download`、`qbitlarr_delete_download`、`qbitlarr_watch_download`、`qbitlarr_get_query_snapshot`、`qbitlarr_list_prowlarr_indexers`、`qbitlarr_health`。 stdio MCP 包装器还会向 Hermes 风格的目标发送**一次性完成通知**： - 在排队 torrent 时传递 `notification_target`（例如 `telegram:123456789`）。qBitlarr 会监视哈希，发送一条进度消息，刷新它，并在监视间隔时消息目标在 100% 时消息目标。如果 `user_id` / `requester_id` 已经是 Hermes 目标，则自动重用 - 多用户机器人很少需要单独的 `notification_target`。 - 相同的每个用户 `user_id` / `requester_id` 将状态检查范围限定为该用户标记的 torrent。 - 对于手动流程，使用已知哈希调用 `qbitlarr_watch_download`；传递 `completion_followup_message` 以追加一行“接下来启动什么”（例如字幕处理）。 - Telegram 进度编辑读取 `QBITLARR_TELEGRAM_BOT_TOKEN`，然后 `QBITLARR_HERMES_ENV_PATH`、`HERMES_HOME/.env`、`~/.hermes/.env` - 将 `QBITLARR_HERMES_ENV_PATH` 指向配置文件 `.env` 以运行多个机器人。 - `QBITLARR_COMPLETION_HOOK_COMMAND` 在监视到的下载完成或删除后运行本地命令；qBitlarr 发送用户消息，然后将 `download_complete` / `download_removed` JSON 事件写入命令的 stdin。钩子失败不会隐藏用户通知。 如果设置了 `QBITLARR_API_KEY`，则两种传输都需要一个 `X-API-Key` 头部。stdio MCP 从同一个 env var 中获取它。 ### Claude Desktop 编辑 `~/Library/Application Support/Claude/claude_desktop_config.json`（macOS）或 `%APPDATA%\Claude\claude_desktop_config.json`（Windows）： ```json { "mcpServers": { "qbitlarr": { "command": "/absolute/path/to/qbitlarr/bin/qbitlarr-mcp", "env": { "QBITLARR_API_URL": "http://localhost:8000", "QBITLARR_API_KEY": "" } } } } ``` 重启 Claude Desktop。qbitlarr 工具出现在工具列表中，当您询问电影或电视时，Claude 会使用它们。 ### Cursor 设置 → **MCP** → **添加新的 MCP 服务器**： ```json { "mcpServers": { "qbitlarr": { "command": "/absolute/path/to/qbitlarr/bin/qbitlarr-mcp" } } } ``` ### 其他 MCP 主机（Hermes、OpenClaw、Cline、自定义代理） 模式相同 - 它们都支持一个或两个传输： - **stdio 路径**：配置主机以启动 `bin/qbitlarr-mcp` 作为子进程（带有 API URL 和可选 API 密钥的环境变量）。 - **HTTP 路径**：指向主机 `http://localhost:8000/mcp` 并带有 `X-API-Key` 头部（如果设置了）。 对于 `choose_title` 和 `show_results`，支持 Bot API `sendRichMessage` 的 Telegram 适配器应首先渲染 `choice_rich_message`，并将 `choice_buttons` 放在其下方。其他富文本主机可以渲染 `choice_display`；普通主机可以渲染 `choices_table`，在等宽块内。通用澄清/选择器主机应将每个候选或结果 `label` 作为选择列表传递。 ### 告诉您的代理何时使用 qBitlarr 如果您的代理支持系统提示或“工具说明”字段，请添加一个简短的指针，以便在正确的时间到达 qBitlarr： > *当用户要求下载他们允许访问的电影、电视节目或动漫时，请使用 qbitlarr MCP 工具。默认为 `qbitlarr_handle` - 它接受 IMDb ID、IMDb 网址、支持的 Douban 电影链接或 ID、支持的 AlloCine 电影链接或 ID 以及纯文本标题。默认情况下，它会返回排名的发布选择（或当关键词与多个标题匹配时，首先使用短标题选择器）；如果它返回 `needs_imdb`，请向用户询问 IMDb 链接。只有在手动强用户控制时，才使用 `qbitlarr_search` + `qbitlarr_download` 作为备用。* 这促使原本不知道您的下载器现在是一个选项的代理。 ### 快速健全检查 连接完成后，询问代理：*“使用 qbitlarr_health 检查服务是否正常。”* 如果它返回 `{“status”: “ok”}`，则表示您已连接。添加 `--deep`（或传递 `deep: true`）以验证 Prowlarr 和 qBittorrent 是否也可访问。 ## 命令行界面 命令行界面是与 MCP 使用的同一个 REST API 的薄客户端。它从环境中读取 `QBITLARR_API_URL`、`QBITLARR_API_KEY` 和 `QBITLARR_API_TIMEOUT_SECONDS`，并提供可覆盖的标志。 `handle` 默认打印友好的人类响应。添加 `--json` 以获取原始结构化响应。其他子命令默认打印 JSON 以便与 `jq` 一起使用。 ```sh bin/qbitlarr handle "tt0045877" bin/qbitlarr handle "douban:1292052" bin/qbitlarr handle "https://www.allocine.fr/film/fichefilm_gen_cfilm=25801.html" bin/qbitlarr handle "The Hitch-Hiker" --mode manual bin/qbitlarr handle "The Hitch-Hiker" --user-id telegram:123456789 bin/qbitlarr handle "The Hitch-Hiker" --mode manual --json bin/qbitlarr search --query "The Hitch-Hiker 1953 1080p" | jq '.[0]' bin/qbitlarr download 'magnet:?xt=urn:btih:...' --user-id telegram:123456789 bin/qbitlarr downloads --watch --user-id telegram:123456789 bin/qbitlarr downloads --render --user-id telegram:123456789 bin/qbitlarr download-status abcdef1234567890 --user-id telegram:123456789 bin/qbitlarr download-status abcdef1234567890 --render --user-id telegram:123456789 bin/qbitlarr health --deep bin/qbitlarr indexers ``` 在 shell 中引用磁铁链接，因为它们通常包含 `&`。 在 Docker 容器内，使用 `docker compose exec qbitlarr python -m app.cli health --deep` 运行相同的 CLI 模块。`bin/qbitlarr` 启动器用于主机检查。 ## 身份验证 对于 localhost 以外的部署，请设置 `QBITLARR_API_KEY`。之后，每个 REST 和 MCP 请求都需要 `X-API-Key` 头部： ```sh curl -H 'X-API-Key: change-this' http://localhost:8000/health ``` 留空以进行未经身份验证的本地使用。 ## Prowlarr URL `PROWLARR_URL` 是 qBitlarr 用于 Prowlarr API 调用的 URL。在 Docker Compose 中，它默认为 `http://prowlarr:9696`，即内部服务主机名 - 大多数用户不需要更改此设置。 `PROWLARR_DOWNLOAD_URL` 是可选的。仅当 Prowlarr 返回 qBitlarr 必须在获取 `.torrent` 文件之前重写的代理下载 URL 时设置，例如当 qBitlarr 必须通过 LAN 地址而不是内部 Docker 主机名访问 Prowlarr 时。 ## 索引器选择 `PROWLARR_PRIMARY_INDEXER_IDS` 和 `PROWLARR_FALLBACK_INDEXER_IDS` 是可选的逗号分隔的索引器 ID。 - 留空以让 Prowlarr 搜索每个适用的索引器。 - 设置主要 ID 以优先使用受信任的子集。 - 设置备用 ID 以使用较广或较慢的索引器，仅在主要结果缺失或不合适时尝试。 在配置 Prowlarr 后发现 ID： ```sh curl http://localhost:8000/prowlarr/indexers ``` ## 保存路径 `/handle` 根据媒体类型和分辨率将每个排队的下载路由到保存路径： - `QBITLARR_SAVE_PATH_MOVIE=/downloads/movies` - `QBITLARR_SAVE_PATH_MOVIE_4K=/downloads/movies-4k` - `QBITLARR_SAVE_PATH_TV=/downloads/tv` 电视下载在电视基本路径下创建显示文件夹，例如 `/downloads/tv/Example Show`。 `/handle` 和 `/download` 还接受一个可选的 `save_path` 字段，用于一次性覆盖。覆盖必须位于上述某个已配置的根目录内，或位于以逗号分隔的 `QBITLARR_EXTRA_SAVE_PATHS` 条目中，例如 `/media/Kids`。 当省略 `save_path` 时，`/handle` 和 `/download` 使用 qBitlarr 的默认配置。`/download` 从 torrent 元数据或磁铁显示名称推断目标，因此手动从搜索结果中选择的项目仍会进入电影、4K 电影或电视路径，而不是 qBittorrent 的全局默认下载文件夹。 ## REST API | 方法 | 路径 | 目的 | | --- | --- | --- | | GET | `/health` | 服务活跃性 | | GET | `/health?deep=true` | 活跃性 + Prowlarr/qBittorrent 可达性 | | POST | `/handle` | 主要入口点：搜索和（可选）排队 | | POST | `/search` | 原始 Prowlarr 搜索 | | POST | `/download` | 排队一个已知的下载链接 | | GET | `/downloads` | 列出 qBittorrent 中的 torrent | | GET | `/downloads/status-message` | 将所有匹配的下载项渲染为聊天进度消息 | | GET | `/downloads/{info_hash}` | 通过 info hash 读取一个 torrent | | GET | `/downloads/{info_hash}/status-message` | 将一个 torrent 渲染为聊天进度消息 | | POST | `/downloads/{info_hash}/pause` | 暂停一个请求者拥有的 torrent | | POST | `/downloads/{info_hash}/resume` | 恢复一个请求者拥有的 torrent | | POST | `/downloads/{info_hash}/delete` | 删除一个请求者拥有的 qBittorrent 任务，而不删除文件 | | GET | `/queries/{query_id}` | 重新读取一个已保存的搜索快照 | | GET | `/prowlarr/indexers` | 列出 Prowlarr 索引器及其 ID | 示例：排队一个已知链接到特定文件夹。 ```sh curl -X POST http://localhost:8000/download \ -H 'Content-Type: application/json' \ -d '{"download_link":"magnet:?xt=urn:btih:...","save_path":"/media/Kids"}' ``` ## 项目结构 ``` qbitlarr/ ├── app/ FastAPI 服务 — REST API、CLI 和规范逻辑 │ ├── api/ REST 端点处理程序（handle、search、download、...） │ ├── domain/ 纯逻辑：排名、保存路径、选择表、进度卡 │ └── services/ 外部客户端：prowlarr、qbittorrent、wikidata ├── mcp_server/ stdio MCP 服务器（app/client.py 的薄包装器） ├── bin/ `qbitlarr` 和 `qbitlarr-mcp` 启动器 ├── tests/ pytest 套件 ├── docs/ 架构图 + README 截图 └── docker-compose.yml、Dockerfile、.env.example、README*.md ``` REST API 是规范接口；CLI 和 stdio MCP 是 `app/client.py` 的薄客户端。大多数逻辑位于 `app/api/handle.py`（编排：识别 → 排名 → 排队）和 `app/domain/quality.py`（纯排名，无网络）。 ## 与 Babelarr 搭配使用字幕 qBitlarr 处理获取；将其与 [Babelarr](https://github.com/davezfr/babelarr) 配对，在下载完成准备字幕。 当两个 MCP 服务器可用于一个代理时，“下载 The Hitch-Hiker 并添加中英字幕” 变成：qBitlarr 排队电影，一旦有本地路径，Babelarr 查找或下载源字幕，翻译它，并写入 SRT/ASS 边车。 对于持久队列，还要公开 Babelarr 的 Runtime MCP 服务器 - 它记住下载并在路径准备好时调度 Babelarr。 <p> <img src="docs/screenshots/telegram-qbitlarr-babelarr-one-shot.jpg" alt="Telegram 示例：一个请求下载 His Girl Friday 使用 qBitlarr，然后使用 Babelarr 准备中英字幕。"> </p> * 仅供参考的组合工作流截图。 演示使用公共领域标题；权利可能因司法管辖区和特定修复、配乐、字幕或版本而异。* ## 第三方项目 qBitlarr 与以下第三方项目集成： - **[Prowlarr](https://github.com/Prowlarr/Prowlarr)** — GPL-3.0。 qBitlarr 可以将 Prowlarr 作为单独的 Docker Compose 服务运行，并通过其 HTTP API 与其通信。 - **[qBittorrent](https://github.com/qbittorrent/qBittorrent)** — GPL-2.0。 qBitlarr 要求您单独提供 qBittorrent，并通过其 Web UI API 与其通信。 - **[FlareSolverr](https://github.com/FlareSolverr/FlareSolverr)** — MIT。 qBitlarr 的 Docker Compose 设置包括它作为 Prowlarr 索引器需要它的可选挑战代理。 qBitlarr 不隶属于、不支持或赞助 Prowlarr、qBittorrent、FlareSolverr 或其维护者。 ## 许可证 MIT。