Rapidbay 1.0.0 API 使用详解
Rapidbay 1.0.0 全量 REST 接口实测：19 端点清单与契约、认证约定、磁力解析到下载轮询闭环、播放域 Range 验证、magnet_status JSON 陷阱、状态机与错误行为速查表。
doc_id: 6344 slug: OU9Zw1QM44hV description: Rapidbay 1.0.0 全量 REST 接口实测：19 端点清单与契约、认证约定、磁力解析到下载轮询闭环、播放域 Range 验证、magnet_status JSON 陷阱、状态机与错误行为速查表。 title: Rapidbay 1.0.0 API 使用详解 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 1.0.0 API 使用详解.md
Rapidbay 1.0.0 API 使用详解
目标：把 Rapidbay 1.0.0 对外的全部 REST 接口一次讲清——端点清单、请求格式、认证约定、响应结构与错误行为，全部以运行环境实测回显为准（含边界用例）。组件定位见《Rapidbay 介绍与选型指南》，部署见《Rapidbay Docker Compose 部署指南》，参数见《Rapidbay 1.0.0 配置参数详解》。实测环境为 2026-10-30 的 Ubuntu 24.04.5 服务器，服务地址
http://localhost:8154，素材使用 Ubuntu 官方 ISO 种子与 Blender 开放电影 Sintel（均为合法授权内容）。
一、环境信息
| 项目 | 取值 |
|---|---|
| 实测日期 | 2026-10-30 |
| 服务器 | Ubuntu 24.04.5 LTS x86_64 |
| Rapidbay | 1.0.0（官方镜像 hauxir/rapidbay:latest） |
| 服务地址 | http://localhost:8154（对外端口 8154 → 服务内 5000） |
| 接口契约 | OpenAPI 3（FastAPI 内建），/openapi.json 与 /docs 可在线查看 |
| 认证状态 | 实测环境未设 PASSWORD（匿名可用），认证差异见第四章 |
| 实测素材 | Sintel（hash 08ada5a7…，CC-BY）、Ubuntu 24.04.5 ISO（hash a3b4136a…，官方种子） |
二、前置条件
- 服务已按 B2 篇部署并
{"ok": true}； - 客户端任意 HTTP 工具即可，本文统一用
curl； - 两条通用约定先记住：列表/详情类接口一次性返回全量数据（无分页参数）；写操作端点多数收表单编码（
application/x-www-form-urlencoded或 multipart），唯一例外POST /api/magnet_status/收 JSON body（实测混用会 422，见第七章）。
三、API 总览
服务自述契约（/openapi.json 实查）：{"title": "RapidBay", "version": "1.0.0"}。全部对外端点（19 个，2026-10-30 实查）：
| 方法 | 路径 | 作用 |
|---|---|---|
| GET | /health | 健康探针 |
| GET | /robots.txt | 爬虫声明 |
| GET | /api/status | 全站状态（配置 + 磁力会话目录树） |
| GET | /api/search/ | 搜索占位（空关键词） |
| GET | /api/search/{searchterm} | 关键词搜索（走 Jackett/Prowlarr） |
| POST | /api/torrent_url_to_magnet/ | .torrent URL 转磁力链接 |
| POST | /api/magnet_files/ | 解析磁力，返回 hash 与文件清单 |
| POST | /api/magnet_download/ | 触发单个文件下载 |
| POST | /api/magnet_status/ | 批量查询磁力状态（JSON body） |
| GET | /api/magnet/{magnet_hash}/ | 单磁力文件清单 |
| GET | /api/magnet/{magnet_hash}/{filename} | 单文件下载状态 |
| GET | /api/next_file/{magnet_hash}/{filename} | 连播下一文件定位 |
| POST | /api | 登录（设 PASSWORD 后启用） |
| GET | /play/{magnet_hash}/{filename} | 播放静态文件（转码产物直供） |
| GET | /kodi.repo、/kodi.repo/、/kodi.repo/{path} | Kodi 插件仓库 |
| GET | /error.log | 运行日志 |
| GET | /（及前端路由） | Web 前端页面 |
另有两个 FastAPI 内建契约端点：/openapi.json 与 /docs。
四、认证与访问控制
- 未设置
PASSWORD（本项目实测状态）：所有读接口匿名可用；登录端点POST /api无密码可交，直接 404：
curl -s -X POST http://localhost:8154/api -w "\nHTTP %{http_code}\n"
回显（实测）：
{"detail":"Not Found"}
HTTP 404
- 设置
PASSWORD后：打开网页先入口令，服务端签发 Cookie 会话；自写客户端需先POST /api（表单字段password）携带凭据换取 Cookie，后续请求带上同一 Cookie。未携带会话的请求会被重定向到登录页。 - 站点无账号体系与 Token 机制，口令是唯一防线，公网部署务必强口令并优先置于反代之后。
五、健康与元信息域
GET /health——探针：
curl -s http://localhost:8154/health
回显（实测）：
{"ok": true}
GET /robots.txt——声明不收录：
User-agent: *
Disallow: /
GET /error.log——运行日志（即 DATA_DIR/rapidbay_errors.log 的直读端点）：
curl -s http://localhost:8154/error.log
回显（实测，服务刚启动无异常时为空响应、HTTP 200；排障时先看这里）。
GET /api/status——全站状态，返回配置摘要与全部磁力会话的目录树（torrents/filelists/output/downloads 各桶），适合巡检与对账；响应较大，摘录结构（实测）：
{"torrents": ["a3b4136a.../ubuntu-24.04.5...iso.torrent", "08ada5a7.../Sintel.mp4.torrent"],
"filelists": ["a3b4136a.../...", "08ada5a7.../..."],
"output": ["08ada5a7.../Sintel.mp4", "08ada5a7.../Sintel.en.vtt"],
"downloads": ["08ada5a7.../Sintel.mp4"]}
六、搜索域
GET /api/search/{searchterm}——透传给 Jackett/Prowlarr，结果合并去重后返回（响应字段含站名、标题、大小、种子数、磁力链接等）。两种实测状态：
后端已配置但零索引器（本项目联动验证时的真实状态）：
curl -s http://localhost:8154/api/search/sintel
回显（实测）：
{"results": []}
索引器就绪后，同一请求返回非空 results 数组（每项含 title、size、seeders、magnet_link 等字段）。两个搜索后端（Jackett/Prowlarr）同时配置时结果自动合并去重，无需客户端处理。
GET /api/search/——空关键词占位，返回与上同构的空结果（前端首页建议位用）。
说明：搜索结果有磁盘缓存（
cache/目录），短时间内重复搜索命中缓存；索引器故障不会使接口报错，而是体现在空结果里——排障先查 Jackett 侧（B2 篇排障实录现象一）。
七、磁力与下载域
这是 Rapidbay 的核心链路，四个 POST 端点 + 三个 GET 端点构成"解析 → 触发 → 轮询"闭环。实测以 Ubuntu 官方 ISO 种子走全流程。
POST /api/torrent_url_to_magnet/（表单字段 url）——.torrent 链接转磁力（服务端下载种子文件并提取 infohash）：
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"}
POST /api/magnet_files/（表单字段 magnet_link）——解析磁力，登记会话并返回 hash 与文件清单：
curl -s -X POST --data-urlencode "magnet_link=magnet:?xt=urn:btih:a3b4136a..." http://localhost:8154/api/magnet_files/
回显（实测，节选）：
{"magnet_hash":"a3b4136a174e30b121a6bb6ab75b577ea7eda5f3","files":[{"path":"ubuntu-24.04.5-live-server-amd64.iso","size":4080486400}],"file_statuses":null}
POST /api/magnet_download/（表单字段 magnet_link + filename）——触发指定文件下载：
回显（实测）：
{"status":"started","magnet_hash":"a3b4136a...","filename":"ubuntu-24.04.5-live-server-amd64.iso"}
GET /api/magnet/{magnet_hash}/{filename}——单文件状态轮询（前端下载页就是轮它）。状态机实测：downloading → ready（下载完成待转码/转码中，非视频文件直接到 ready）→ 展示播放可用。下载中回显（实测，节选）：
{"status":"downloading","percent":30.7,"progress":0.307,"num_peers":80,"download_rate":50.3,"size":4080486400,"downloaded":1254000000}
完成回显（实测；ISO 非视频文件，supported:false 且无字幕数组）：
{"status":"ready","filename":"ubuntu-24.04.5-live-server-amd64.iso","subtitles":[],"supported":false}
对照：Sintel.mp4（视频文件）完成后 supported:true 且 subtitles 含 9 条 .vtt 字幕路径——supported 字段即"转码后能否在浏览器播放"的判定结果，由服务端扩展名白名单（SUPPORTED_EXTENSIONS）决定。
POST /api/magnet_status/（JSON body，字段 magnet_hash）——批量状态查询：
curl -s -X POST -H "Content-Type: application/json" -d '{"magnet_hash":"08ada5a7..."}' http://localhost:8154/api/magnet_status/
回显（实测；会话存在时返回各文件状态字典，本例为已清理会话的空对象形态）：
{"statuses":{}}
表单/JSON 格式坑（实测）：该端点若按其他端点的习惯发表单编码，返回 422 校验错误（实测回显）：
{"detail":[{"type":"model_attributes_type","loc":["body"],"msg":"Input should be a valid dictionary or object to extract fields from","input":"magnet_hash=08ada5a7..."}]}
GET /api/magnet/{magnet_hash}/——单磁力文件清单（同 magnet_files 的响应结构，但按 hash 查询已登记会话）：
回显（实测，Sintel 会话）：
{"files":[{"path":"Sintel.mp4","size":129202869}],"file_statuses":{"Sintel.mp4":"downloaded"}}
GET /api/next_file/{magnet_hash}/{filename}——连播定位（配合 AUTO_PLAY_NEXT_FILE）：
回显（实测；单文件磁力无下一文件）：
{"next_filename": null, "next_magnet": null}
多文件磁力则返回同磁力内按清单排序的下一个视频文件名。
八、播放域
GET /play/{magnet_hash}/{filename}——转码产物静态直供（服务内 nginx 指向 output/ 目录），支持 Range 分段请求（拖动进度条的协议基础）：
curl -s -I "http://localhost:8154/play/08ada5a7.../Sintel.mp4"
回显（实测，节选）：
HTTP/1.1 200 OK
Content-Length: 129202869
Accept-Ranges: bytes
任意字节区间验证（实测 206 返回且 Content-Range 起点与请求一致），浏览器 <video> 标签可直接播放。
GET /kodi.repo——Kodi 插件仓库入口。实测返回 HTML 页（内含 rapidbay.zip 下载链接）：
curl -s http://localhost:8154/kodi.repo
回显（实测，节选）：
<a href="rapidbay.zip">rapidbay.zip</a>
实测踩坑：跟随链接 GET /kodi.repo/rapidbay.zip 返回 404——原因是打包插件需要 zip 命令，而当前镜像内未预装（服务内 which zip 实测无果）。这是 1.0.0 官方镜像的已知瑕疵；Kodi 接入可改走官方 wiki 的手动插件安装路径，或期待后续镜像修复。/kodi.repo/{path} 其余路径为插件源码目录直读。
九、状态与错误行为约定
实测汇总（排障速查）：
| 行为 | 实测结果 | 说明 |
|---|---|---|
| 未开始下载就查文件状态 | HTTP 200，{"status":"waiting_for_torrent"} | 组件语义：会话已登记但下载未触发（实测对未触发文件稳定返回） |
| 查询不存在的文件 | HTTP 200，{"status":"waiting_for_torrent"} | 同上，文件粒度不区分 404 |
| 查询坏 hash 的文件清单 | HTTP 200，{"files":null,"file_statuses":null} | hash 格式合法但无会话 |
| POST 专用端点用 GET 访问 | HTTP 405 | 如对 /api/torrent_url_to_magnet/ 发 GET |
magnet_status 用表单编码 | HTTP 422 | 仅收 JSON body（见第七章实测回显） |
| 未设密码时 POST /api | HTTP 404 {"detail":"Not Found"} | 登录端点整体不启用 |
| 前端路由 | HTTP 200（SPA catch-all） | 任意未匹配路径返回前端页面，勿以此判断 API 路径存在性 |
| 搜索零索引器 | HTTP 200，{"results": []} | 不报错，空结果（见第六章） |
通用错误结构遵循 FastAPI 惯例：校验类错误为 422 + detail 数组，资源类缺失多为 404 + detail 字符串。
十、常见问题
Q1：状态轮询一直 waiting_for_torrent？
说明只走了"解析"没走"触发"。检查是否调用了 POST /api/magnet_download/（带 filename），或前端是否停留在文件选择页未点播。
Q2：文件完成后 /play/ 404？
播放只服务转码产物（output/ 目录）。CONVERT_VIDEO=False 或转码进行中（状态 ready 但产物未落盘）时 404；非视频文件（supported:false）无转码产物，/play/ 直供原始文件（实测 ISO 直接 200 返回 4 GB 原件）。
Q3：HEAD 请求 /play/ 返回 405？
静态文件端点对 HEAD 的支持取决于服务内代理层版本；实测 HEAD 返回 200。若自建反代包在外层，确认反代透传 Range/HEAD。
Q4：搜索接口报错吗？
永远 200。索引器挂了、密钥错了、没配索引器都表现为空 results；排障顺序：Jackett 仪表盘手工搜索 → Rapidbay 侧 /error.log → B2 篇联动验证三步。
Q5：接口有没有限流？
无内建限流（master 分支近期提交刚移除了 /play/ 的频率上限）；公网暴露时建议反代层自行加防护。
十一、参考链接
- 接口契约自文档：
http://<服务地址>/openapi.json与/docs（FastAPI 内建） - 上游仓库：https://github.com/hauxir/rapidbay
- 官方 Kodi 接入 wiki：https://github.com/hauxir/rapidbay/wiki/Setting-up-Rapidbay-with-Kodi
- 同专栏实操篇：《Rapidbay Docker Compose 部署指南》《Rapidbay 1.0.0 配置参数详解》