doc_id: 6338 slug: L9HrjL2UECHn description: Rapidbay 1.0.0 介绍与选型指南：定位与版本口径、单体服务加外置索引器架构、功能特性与磁盘自动清理、最小可用 API 链路实测、适用场景限制与版权合规边界、五类种子流播方案对比与兼容矩阵。 title: Rapidbay 介绍与选型指南 status: DRAFT visibility: PRIVATE approval_status: PENDING source: mcp-create column: Rapidbay column_id: 1217 tags: [Rapidbay, Docker, 流媒体] tag_ids: [2387, 59, 1731] minio_key: docs/Rapidbay/Rapidbay 介绍与选型指南.md

Rapidbay 介绍与选型指南

目标：面向"把种子（BitTorrent）内容在浏览器/电视上即点即播"的自托管场景，讲清 Rapidbay 1.0.0 的定位、架构、功能边界与同类方案对比，给出最小可用示例与合规使用边界。本文为纯联网溯源的认知篇，本地实测只用于验证关键行为；部署细节见《Rapidbay Docker Compose 部署指南》，配置项全解见《Rapidbay 1.0.0 配置参数详解》，REST 接口全解见《Rapidbay 1.0.0 API 使用详解》。

一、环境信息

本文以联网溯源为主、本地实测为辅，信息来源与查询口径如下：

• 查询日期：2026-10-30（下文所有版本号、星数、特性描述均以该日期实查结果为准）；
• 项目主仓库：GitHub hauxir/rapidbay（README 与源码）；
• 星数与活跃度来源：GitHub API api.github.com/repos/hauxir/rapidbay（2026-10-30 实查：stars 902 / forks 56 / open_issues 7）；
• 版本口径：仓库 master 分支 pyproject.toml 的 version = "1.0.0"（GitHub Contents API blob 5e2af689 实查）与本项目运行环境 /openapi.json 返回的 info.version: 1.0.0 双源核对一致；
• 本地实测环境：Ubuntu 24.04.5 LTS x86_64 服务器，Rapidbay 1.0.0（官方镜像 hauxir/rapidbay:latest，服务端口 8154），搜索后端 Jackett v0.24.2961（linuxserver/jackett:latest）；
• 实测内容全部为自由授权/合法公测素材：Blender 开放电影 Sintel（CC-BY 授权，官方发布种子）与 Ubuntu 24.04.5 官方 ISO 种子（releases.ubuntu.com 自带 .torrent），未使用任何受版权保护的第三方内容。

二、软件概述

Rapidbay 是一个自托管的"种子视频流播服务"，官方 README 对它的一句话定位是："Self-hosted torrent video streaming service compatible with Chromecast, AppleTV & Kodi deployable in the cloud"（兼容 Chromecast、AppleTV 与 Kodi 的自托管种子视频流播服务，可部署在云端）（来源：GitHub hauxir/rapidbay 仓库简介，2026-10-30 实查）。它把"从磁力链接到能播"的过程压缩成四步：打开网页 → 搜索或粘贴磁力链接 → 选一个视频文件 → 等待下载与转码完成即可播放。

项目档案一览（来源均为官方仓库与运行环境实查，2026-10-30）：

版本节奏说明：Rapidbay 没有语义化的版本发布轨道，1.0.0 就是 pyproject.toml 里的长期版本号，功能演进直接落在 master 分支并滚动构建进 latest 镜像。因此选型时不能只看"版本号新旧"，要看镜像构建日期与 master 推送记录。一个典型例子：master 分支已合入 HLS 边下边播与 SSE 进度事件流（HLS_* 系列变量、/api/magnet/{h}/{f}/stream 启动端点与 Search-Events SSE 路由，2026-10-30 对 master 源码 app/settings.py、app/app.py 实查），而本文实测的 latest 镜像尚不含这些路由与变量——两侧差异在《Rapidbay 1.0.0 配置参数详解》中有逐项标注。

三、核心架构

Rapidbay 是一个"单体服务 + 外置搜索后端"的架构：主服务进程内同时跑着 Web/API、BT 引擎与转码调度，搜索则委托给外部的 Jackett 或 Prowlarr。

1. Web/API 层：FastAPI（uvicorn 承载）对外暴露搜索、文件列表、下载状态与播放接口；生产部署形态下前端是 nginx 直接服务的静态页面（app/frontend/），API 走 nginx 反代到 uvicorn（来源：master 分支 run.sh、nginx.conf 与 Dockerfile，2026-10-30 实查）。
2. BT 引擎：libtorrent 2.0.11 以守护线程形式内嵌在服务进程中，负责磁力解析、DHT/Tracker 爬取、分片下载；下载完成后做顺序化整理，保证文件能被播放器按字节区间拖动（来源：pyproject.toml 依赖与 app/rapidbaydaemon.py）。
3. 转码层：下载完成后调用 ffmpeg 做"浏览器兼容化"转码——视频统一转 H.264（默认 libx264 -preset ultrafast），不支持的音频轨转 AAC（默认 256 kbps 双声道），字幕统一转 WebVTT；这是"所有浏览器/Chromecast/AppleTV 都能播"的关键（来源：官方 README Features 与运行环境 /app/settings.py 实查）。
4. 字幕层：下载完成时按 SUBTITLE_LANGUAGES 从 OpenSubtitles 拉取字幕（官方要求该服务的 VIP 账号），可选 alass 做字幕与版本校时（来源：官方 README Subtitles 章节）。
5. 搜索后端（外置）：Jackett 和/或 Prowlarr 负责"去各 BT 站搜内容"，Rapidbay 只消费它们的 Torznab 结果；两者可以同时配置，结果会合并去重（来源：官方 README Setting up a search backend 章节）。

一次播放请求的完整数据流：

浏览器 → Web 前端 → /api/search/{term} → Jackett/Prowlarr（Torznab）→ 结果合并去重 → 前端文件列表
用户选中文件 → /api/magnet_download/ → libtorrent 引擎启动下载（分片优先级 + 顺序整理）
下载完成 → ffmpeg 转码到 output/（mp4 + vtt）→ /play/{hash}/{filename} 由 nginx 直供静态文件

工作目录职责（Docker 形态下统一在 DATA_DIR 下，本项目实测为 ./data，各目录均已在运行环境取证）：

💡 技术拓展：「种子流播」如何做到不整部下完就能看？主流做法有两类。一类是 Stremio 式的"内部引擎 + 边下边播"：引擎把分片流式喂给播放器，未下载段的拖动会触发引擎补拉。另一类是 Rapidbay 1.0.0 的"先下后播"折中：利用 libtorrent 的分片优先级把视频文件提前排到队首并做顺序化，同时磁盘清理策略（MAX_TORRENT_AGE_HOURS，默认 10 小时）让用户无需管理磁盘；代价是点播后有数分钟级等待。master 分支正在向第一类演进（HLS 切片 + /stream 端点在下载中途即可启动转码分片，HLS_STREAMING=True 打开），2026-10-30 的 latest 镜像尚未包含，属于选型时需要预判的路线图差异。

四、功能特性

以下特性均来自官方 README（2026-10-30 实查），并逐项与运行环境行为核对：

• 搜索聚合：Jackett / Prowlarr 二选一或同时使用，结果自动合并去重；前端也可直接粘贴磁力链接或 .torrent 链接（实测：/api/torrent_url_to_magnet/ 可把 Ubuntu 官方种子 URL 转成磁力）。
• 按文件下载：磁力解析出文件清单后，单个文件即可触发下载与转码，不必下载整个种子。
• 自动字幕：下载完成自动从 OpenSubtitles 拉取指定语言字幕并转 WebVTT（实测：Sintel 拉到 9 条 vtt，SUBTITLE_LANGUAGES 默认 ['en']）。需 OpenSubtitles VIP 账号。
• 自动转码：视频统一 H.264、不兼容音频转 AAC，产出"所有浏览器/Chromecast/AppleTV 可播"的文件（实测：VIDEO_CONVERSION_PARAMS 默认 libx264 -preset ultrafast，AAC_BITRATE=256k）。
• 自动磁盘清理：默认 10 小时后清理下载与转码产物（MAX_TORRENT_AGE_HOURS / MAX_OUTPUT_FILE_AGE），长期无人值守也不撑爆磁盘。
• 磁力链接处理器：访问 /registerHandler 可把自建服务注册为浏览器磁力链接的默认处理器。
• Kodi 支持：/kodi.repo 提供 Kodi 仓库入口与官方插件（官方 wiki 有图文教程）。
• 投屏：Web 界面面向手机/平板/智能 TV 设计，支持 Chromecast 与 AppleTV（README 定位声明）。
• 访问口令：PASSWORD 环境变量可给整个站点加一道口令（实测：未设置时 POST /api 直接 404，行为详见《Rapidbay 1.0.0 API 使用详解》）。
• master 预发布特性（截至 2026-10-30 尚未进入 latest 镜像）：HLS 边下边播、SSE 下载进度事件流、Real-Debrid / TorBox debrid 缓存加速（RD_TOKEN / TB_TOKEN）。选型时若依赖这些能力，需确认所用镜像的构建时间。

五、快速开始（最小可用示例）

完整部署（含 Jackett 联动、目录规划、子网选择）见《Rapidbay Docker Compose 部署指南》，这里只给最小体验路径。单服务体验形态：官方镜像 hauxir/rapidbay 暴露 5000 端口，启动时注入两个环境变量——JACKETT_HOST（指向你的 Jackett 实例地址）与 JACKETT_API_KEY（Jackett 的 API 密钥）；只配 Prowlarr 时换成 PROWLARR_HOST / PROWLARR_API_KEY。生产建议直接用 Compose 编排（见 B2 篇）。

用 REST 接口走一遍"种子 URL → 文件列表 → 下载 → 播放"的最小链路（本项目 2026-10-30 实测，以 Ubuntu 官方 ISO 种子为例）：

# 1. 种子 URL 转磁力
curl -s -X POST -F "url=https://releases.ubuntu.com/24.04/ubuntu-24.04.5-live-server-amd64.iso.torrent" \
  http://localhost:8154/api/torrent_url_to_magnet/

回显（实测）：

{"magnet_link":"magnet:?xt=urn:btih:a3b4136a174e30b121a6bb6ab75b577ea7eda5f3&dn=ubuntu-24.04.5-live-server-amd64.iso.tr&xl=4080486400&tr=udp%3A%2F%2Ftracker.openbittorrent.com%3A6969%2Fannounce"}

# 2. 提交磁力，拿到 hash 并触发下载
curl -s -X POST --data-urlencode "magnet_link=magnet:?xt=urn:btih:a3b4136a..." http://localhost:8154/api/magnet_download/
# 3. 轮询文件状态（下载中 → ready）
curl -s "http://localhost:8154/api/magnet/a3b4136a.../ubuntu-24.04.5-live-server-amd64.iso"
# 4. 播放地址直出静态文件
curl -I "http://localhost:8154/play/a3b4136a.../ubuntu-24.04.5-live-server-amd64.iso"

第 3 步下载中的回显（实测，节选；progress 为 0-1 进度）：

{"status":"downloading","percent":30.7,"progress":0.307,"num_peers":80,"download_rate":50.3,"size":4080486400,"downloaded":1254000000}

第 4 步回显（实测，节选；支持 Range 拖动）：

HTTP/1.1 200 OK
Content-Length: 4080486400
Accept-Ranges: bytes

每个接口的参数、错误码与边界行为（含 waiting_for_torrent、坏 hash、非视频文件 supported:false 等）在《Rapidbay 1.0.0 API 使用详解》中有全量实测。

六、适用场景与限制

适用场景：

• 家庭影音：树莓派级别的小主机即可跑，手机/平板/电视浏览器或 Chromecast/AppleTV 直接点播；
• 云端自用站：VPS 部署（官方 wiki 提供配合 VPN 隧道的完整方案），出差路上也能看自己关注的自由授权内容；
• 快速验片：拿到磁力链接先验证文件内容质量再决定是否长期归档（自动清理省去手工管理）。

限制（选型前必须接受的边界）：

• 单用户定位：没有账号体系与多用户权限，最多一道站点口令，不适合做多人共享站；
• 无媒体库管理：不刮削海报、不建索引，只做"即点即播"，长期收藏请配合 Jellyfin/Emby 之类的库管理器；
• 搜索依赖外部：自己不聚合 BT 站，Jackett/Prowlarr 的索引器生态决定搜索覆盖面；一个索引器都没配时 /api/search 返回空结果（实测如此）；
• 字幕依赖 OpenSubtitles VIP：免费账号拉不到字幕；
• 版本发布粗放：1.0.0 是长期版本号，功能差异只能靠镜像构建时间与 master 提交记录判断。

⚠️ 合规使用边界（务必阅读）：

• Rapidbay 本身是内容无关的通用 BitTorrent 工具，许可为 MIT；但下载与分发的具体内容受所在地版权法约束。请仅用于：自有版权内容、公有领域作品、CC/自由授权作品（如 Blender 开放电影 Sintel/Big Buck Bunny）以及发行方主动提供官方种子的内容（如 Ubuntu 各版本 ISO）；
• BitTorrent 协议在下载的同时默认向他人回传数据（分发行为），多数司法辖区对"分发"的约束严于"下载"，请确认所分发内容的授权范围；
• 在云服务器（VPS）上运行时，还需遵守服务商的服务条款——部分机房对 BT 流量或 DMCA 投诉有明确处理策略，官方 wiki 的 VPS 方案即建议以 VPN 隧道承载 BT 流量；
• 本文与同专栏所有实测均只使用上述自由授权素材，不提供任何受版权保护内容的获取指引。

七、同类选型对比

与 Rapidbay 同属"种子到播放"赛道的方案主要有四类（对比为 2026-10-30 快照；Rapidbay 星数为 GitHub API 实查 902/56，其余竞品未逐一实查星数，仅做定性比较）：

兼容矩阵（Rapidbay 官方 README 声明 + 运行环境实测口径）：

版本节奏对比：Rapidbay 滚动发布（master + latest 镜像，最近推送 2026-10-29）；Jellyfin/Emby 走常规语义化版本；Stremio 以客户端商店分发节奏为准。若你重视"版本可预期"，Rapidbay 需要接受"看提交记录选镜像"的维护方式。

选型结论：要"给自建服务器加一个即点即播入口、配置面小、能自动转码与清理"，Rapidbay 是当前最省心的自托管选择；要完整媒体库体验，走 Jellyfin 组合栈；只在自己电脑上看一次，CLI 工具更轻。

八、参考链接

• 上游仓库（A1 溯源主仓库）：https://github.com/hauxir/rapidbay
• 官方 README（本文特性与命令来源）：https://github.com/hauxir/rapidbay#readme
• VPS + VPN 隧道部署 wiki：https://github.com/hauxir/rapidbay/wiki/Setting-RapidBay-up-on-a-VPS-and-tunnel-torrent-traffic-through-NordVPN
• Kodi 前端 wiki：https://github.com/hauxir/rapidbay/wiki/Setting-up-Rapidbay-with-Kodi
• Docker Hub 镜像页：https://hub.docker.com/r/hauxir/rapidbay
• 搜索后端 Jackett：https://github.com/Jackett/Jackett
• 搜索后端 Prowlarr：https://wiki.servarr.com/prowlarr/installation
• 字幕校时 alass：https://github.com/kaegi/alass
• OpenSubtitles：https://www.opensubtitles.org/
• 合法种子素材来源一（CC 授权开放电影）：https://mango.blender.org/
• 合法种子素材来源二（Ubuntu 官方 ISO 种子）：https://releases.ubuntu.com/24.04/