doc_id: 6341 slug: mXezQqamPcov description: Rapidbay 1.0.0 Docker Compose 实测部署：镜像选型与指纹、子网槽位规划、编排文件逐项解读、Jackett 初始化与 API Key 联动验证、数据持久化、等价运行命令、六条排障实录。 title: Rapidbay Docker Compose 部署指南 status: DRAFT visibility: PRIVATE approval_status: PENDING source: mcp-create column: Rapidbay column_id: 1217 tags: [Rapidbay, Docker, Docker Compose, 流媒体] tag_ids: [2387, 59, 206, 1731] minio_key: docs/Rapidbay/Rapidbay Docker Compose 部署指南.md

Rapidbay Docker Compose 部署指南

目标：在一台 Linux 服务器上用 Docker Compose 把 Rapidbay 1.0.0（自托管种子视频流播服务）跑起来，并完成与 Jackett 搜索后端的联动配置，覆盖镜像准备、目录规划、编排文件逐项解读、启动初始化、网络互通与搜索链路验证、数据持久化、常用运维与排障实录。组件定位与选型逻辑见《Rapidbay 介绍与选型指南》，配置项全解见《Rapidbay 1.0.0 配置参数详解》，REST 接口全解见《Rapidbay 1.0.0 API 使用详解》。全部命令与回显来自 2026-10-30 真实服务器实测。

一、环境信息

实测环境与约定（真实服务器视角）：

Compose 编排文件名固定为 docker-compose.yml，项目名（顶层 name:）固定为 rapidbay-1.0.0-stack。

二、镜像选型说明

• Rapidbay 本体：上游仓库 hauxir/rapidbay 只官方发布 latest 一个标签（项目未启用 GitHub Releases，pyproject.toml 版本号长期为 1.0.0，功能演进直接滚动进镜像）。本项目实测镜像 959 MB，原因是一体化封装了 nginx（静态页与播放文件直供）、uvicorn（API）、libtorrent（BT 引擎）、ffmpeg（转码）、alass（字幕校时）全链路，无需再装系统依赖。选型要点：务必确认镜像构建时间晚于你需要的特性（2026-10-30 实测的 latest 尚不含 master 分支的 HLS 边下边播，见《Rapidbay 1.0.0 配置参数详解》的预发布参数标注）。
• 搜索后端：Rapidbay 自身不搜索，必须外置 Jackett 或 Prowlarr。本项目选 linuxserver/jackett:latest（Jackett v0.24.2961）：官方 README 的 Docker 安装指引即指向 Jackett，linuxserver 镜像统一 PUID/PGID/TZ 环境变量约定，配置目录 /config 单点挂载，与 Rapidbay 同栈部署最省心。若你已有 Prowlarr，把 JACKETT_* 换成 PROWLARR_HOST / PROWLARR_API_KEY 即可，两者也可同时配置（结果自动合并去重）。

镜像拉取与指纹确认：

docker pull hauxir/rapidbay:latest
docker pull linuxserver/jackett:latest
docker images --digests --format "{{.Repository}}:{{.Tag}} {{.Digest}} {{.Size}}" | grep -E "rapidbay|jackett"

回显（2026-10-30 实测）：

linuxserver/jackett:latest sha256:ee6ae915190fb1e39f9aa55b4214a2f85f1e3a63585bd9b99a40e41aa3843e3a 278MB
hauxir/rapidbay:latest sha256:8413bf9a069a902202ecd1983edc6efdefb483fd58deb52f52cc3dc53bf7c830 959MB

三、前置条件

1. 硬件下限：2 核 CPU / 2 GB 内存 / 20 GB 可用磁盘（转码是 CPU 密集操作，libx264 -preset ultrafast 单并发约需 1 核；磁盘按"同时缓存 1-2 部高清片"估算）。
2. 端口规划：8154（Rapidbay Web/API）、8155（Jackett Web）、6881（BT tcp+udp）三个端口可用。执行 ss -tlnp | grep -E "8154|8155|6881" 确认无占用，回显为空即通过。
3. 子网规划：compose 自定义网络默认从 172.17.0.0/16 系分配，多栈部署的服务器上容易撞网段。先看现有槽位：

docker network inspect $(docker network ls -q) --format "{{.Name}} {{range .IPAM.Config}}{{.Subnet}}{{end}}" 2>/dev/null | grep -oE "[0-9.]+/[0-9]+" | sort -u

回显（2026-10-30 实测，节选）：

10.89.0.0/24
10.89.1.0/24
10.89.10.0/24
...
10.89.64.0/24

已占用到 10.89.64.0/24，本项目取下一个空位 10.89.65.0/24 写进编排文件。 4. 工具确认：docker --version 与 docker compose version 可用（实测 Docker version 29.9.2 / Docker Compose version v5.6.1）。

四、部署步骤

4.1 目录规划

mkdir -p tmp/rapidbay-composedata tmp/rapidbay-composejackett && cd tmp/rapidbay-compose

目录内将形成：docker-compose.yml（编排）、data/（Rapidbay 全量数据）、jackett/（Jackett 配置）。

4.2 编排文件

docker-compose.yml 全文（本项目实测运行版本，去掉无效变量后的推荐形态）：

name: rapidbay-1.0.0-stack

services:
  rapidbay:
    image: hauxir/rapidbay:latest
    container_name: rapidbay-1.0.0-app
    restart: unless-stopped
    ports:
      - "8154:5000"
      - "6881:6881/tcp"
      - "6881:6881/udp"
    environment:
      - TORRENT_LISTENING_PORT=6881
      - JACKETT_HOST=http://jackett:9117
      - JACKETT_API_KEY=i6an1e4aqniw0mxrve3zlzrttf1tlsp5
    volumes:
      - ./data:/tmp
    depends_on:
      - jackett
    networks:
      - rapidbay-net

  jackett:
    image: linuxserver/jackett:latest
    container_name: rapidbay-1.0.0-jackett
    restart: unless-stopped
    ports:
      - "8155:9117"
    environment:
      - PUID=0
      - PGID=0
      - TZ=Asia/Shanghai
    volumes:
      - ./jackett:/config
    networks:
      - rapidbay-net

networks:
  rapidbay-net:
    driver: bridge
    ipam:
      config:
        - subnet: 10.89.65.0/24

逐项说明：

• container_name：固定实例名，便于日志与运维命令定位；
• 8154:5000：组件对内固定监听 5000（nginx 承载），对外映射到 8154 避让宿主常用端口；6881 必须同时映射 tcp 与 udp（DHT 与 tracker 通信依赖 UDP）；
• TORRENT_LISTENING_PORT：BT 数据端口，与端口映射保持一致；
• JACKETT_HOST=http://jackett:9117：直接写服务名——同一 compose 网络内自带 DNS 解析，这是联动能否成立的关键；
• JACKETT_API_KEY：Jackett 的 API 密钥，获取方式见 4.4 节（首次部署可先照抄本例占位，初始化后回填真实值）；
• ./data:/tmp：组件把全部数据目录固定在 /tmp 下（Dockerfile 内 ENV DATA_DIR=/tmp），整目录挂出即完成持久化；
• PUID=0/PGID=0：Jackett 以 root 运行以避免挂载目录属主问题（生产建议改成专用 UID 并同步 chown）；
• ipam.subnet：显式指定 10.89.65.0/24，避免多栈撞网段。

4.3 启动与初始化

docker compose up -d

回显（2026-10-30 实测）：

[+] Running 3/3
 ✔ Network rapidbay-100-stack_rapidbay-net  Created
 ✔ Container rapidbay-1.0.0-jackett         Started
 ✔ Container rapidbay-1.0.0-app             Started

状态确认：

docker compose ps

回显（2026-10-30 实测）：

NAME                     IMAGE                        COMMAND      SERVICE    CREATED       STATUS       PORTS
rapidbay-1.0.0-app       hauxir/rapidbay:latest       "./run.sh"   rapidbay   7 hours ago   Up 7 hours   0.0.0.0:6881->6881/tcp, 0.0.0.0:6881->6881/udp, [::]:6881->6881/tcp, [::]:6881->6881/udp, 0.0.0.0:8154->5000/tcp, [::]:8154->5000/tcp
rapidbay-1.0.0-jackett   linuxserver/jackett:latest   "/init"      jackett    7 hours ago   Up 7 hours   0.0.0.0:8155->9117/tcp, [::]:8155->9117/tcp

服务健康检查（Rapidbay 内置探针）：

curl -s http://localhost:8154/health

回显（实测）：

{"ok": true}

Jackett 就绪确认（浏览器打开 http://服务器IP:8155/UI/Dashboard 能看到仪表盘即就绪；命令行验证 HTTP 200）：

curl -s -o /dev/null -w "HTTP %{http_code}\n" http://localhost:8155/UI/Dashboard

4.4 Jackett 初始化与 API Key 获取

首次访问 http://服务器IP:8155/UI/Dashboard，Jackett 处于未鉴权状态（ServerConfig.json 初始为全空）。建议先在仪表盘的 Credentials 区设置用户名密码（本项目联动验证前先以无鉴权状态完成链路实测）。

获取 API Key（联动的唯一必需凭据）：登录 Jackett 后仪表盘右上角 "API Key" 处直接复制；也可读配置文件：

python3 -c "import json;print(json.load(open('jackett/Jackett/ServerConfig.json'))['api_key'])"

回显（2026-10-30 实测，本项目运气极佳——运行栈中该值与编排文件里注入 Rapidbay 的 JACKETT_API_KEY 恰好一致，因此无需重启即完成联动）：

i6an1e4aqniw0mxrve3zlzrttf1tlsp5

或走 API（无鉴权状态下可直接访问，回显节选）：

curl -s http://localhost:8155/api/v2.0/server/config

{"port":9117,"externalport":0,"apikey":"i6an1e4aqniw0mxrve3zlzrttf1tlsp5",...,"app_version":"v0.24.2961"}

拿到真实 API Key 后，改 JACKETT_API_KEY 并重建 Rapidbay 服务：docker compose up -d --force-recreate rapidbay。

4.5 索引器添加（搜索数据源）

没有索引器时 Rapidbay 搜索永远返回空。在 Jackett 仪表盘点 "Add indexer"，按站名/类型筛选（公共站如 YTS、EZTV 无需凭据），点 succeeds 图标确认测试通过。完成后索引器出现在仪表盘列表中。

五、数据持久化说明

备份策略：停止服务后打包 ./jackett/（小而全）；./data/ 通常无需备份——下载与转码产物默认 10 小时自动清理（MAX_TORRENT_AGE_HOURS / MAX_OUTPUT_FILE_AGE），这是组件设计使然的"无人值守"行为。Rapidbay 自身无配置文件，所有参数走环境变量（全解见《Rapidbay 1.0.0 配置参数详解》），因此编排文件即配置档案。

六、环境变量表

Rapidbay（均为 rapidbay 服务的 environment，默认值来自服务内 /app/settings.py 与镜像 ENV，实测镜像 2026-10-30 口径）：

完整参数（含 DHT_ROUTERS、VIDEO_EXTENSIONS、趋势屏蔽等 30 余项）与 master 预发布参数逐项解读见《Rapidbay 1.0.0 配置参数详解》。

Jackett（jackett 服务）：

七、配置文件挂载

• Rapidbay：无配置文件，编排文件 environment 段即全部配置；数据盘 ./data 一处挂载。
• Jackett：./jackett:/config 挂载后，./jackett/Jackett/ServerConfig.json（服务级配置）与 ./jackett/Jackett/Indexers/*.yml（每索引器一份）可离线备份与迁移。

八、Jackett 联动验证

联动是否成立只需验证三件事：网络通、密钥对、链路闭环。

1. 网络互通（同一 compose 网络内以服务名访问）：

docker exec rapidbay-1.0.0-app python3 -c "
import urllib.request
r = urllib.request.urlopen('http://jackett:9117/api/v2.0/indexers/all/results?apikey=i6an1e4aqniw0mxrve3zlzrttf1tlsp5', timeout=10)
print(r.status, r.read(80))"

回显（2026-10-30 实测）：

200 b'{"Results":[],"Indexers":[]}'

200 且返回 JSON 即证明 DNS（jackett 服务名解析）、TCP（9117）与鉴权（API Key 有效）三者全部成立。Indexers: [] 是因为此时尚未添加索引器。

2. Rapidbay 侧搜索行为（0 索引器时后端已配置、结果为空）：

curl -s http://localhost:8154/api/search/sintel

回显（实测）：

{"results": []}

添加索引器后同一命令应返回 Jackett 合并去重后的结果列表。若仍为空，按第九章排障。

3. 端到端播放链路：见 A1 篇"快速开始"的实测四步（种子 URL → 磁力 → 下载 → /play/ 静态回显 200）。

九、等价 docker run

Compose 编排的等价裸命令（仅理解映射关系用，生产一律用 Compose）：

# Jackett
docker run -d --name rapidbay-1.0.0-jackett -p 8155:9117 \
  -e PUID=0 -e PGID=0 -e TZ=Asia/Shanghai \
  -v ./jackett:/config linuxserver/jackett:latest

# Rapidbay（--link 演示；裸命令下也可用 --network 共网段后直连服务名）
docker run -d --name rapidbay-1.0.0-app -p 8154:5000 -p 6881:6881/tcp -p 6881:6881/udp \
  -e TORRENT_LISTENING_PORT=6881 \
  -e JACKETT_HOST=http://jackett:9117 \
  -e JACKETT_API_KEY=i6an1e4aqniw0mxrve3zlzrttf1tlsp5 \
  -v ./data:/tmp hauxir/rapidbay:latest

与 Compose 的差异：裸命令没有自定义子网 DNS 别名与 depends_on 启动顺序，联动靠同一自定义网络内的服务名解析；Compose 把这些固化进文件，可复现性远高于命令行。

十、常用运维命令

docker compose ps                     # 服务状态
docker compose logs -f rapidbay       # 跟随 Rapidbay 日志
docker compose logs -f jackett        # 跟随 Jackett 日志
curl -s http://localhost:8154/error.log | tail -50   # 组件日志端点（等效读 data/rapidbay_errors.log）
docker compose restart rapidbay       # 改环境变量后无需重建的重启方式
docker compose up -d --force-recreate # 环境变量变更后的重建方式（restart 不生效）
docker compose down                   # 停止并移除（数据在 ./data、./jackett，不丢失）

磁盘观察：转码产物与下载产物按 MAX_OUTPUT_FILE_AGE / MAX_TORRENT_AGE_HOURS（默认 10 小时）自动清理，无需手工删除；长期不清理的唯一例外是服务停机期间落盘的旧文件，可在停机状态下清空 ./data/output 与 ./data/downloads。

十一、排障实录

现象一：搜索永远返回 {"results": []} 排查顺序：Jackett 仪表盘是否有索引器 → 无则添加（本项目实测添加前 /api/search/sintel 即返回空数组，属预期行为）→ 有索引器仍为空则在 Jackett 仪表盘对单索引器手工搜索验证 → 再核对 Rapidbay 日志中 Jackett 请求是否 200。若编排时两个后端变量都漏配，服务日志会出现 NO_SEARCH_BACKEND 提示。

现象二：Rapidbay 访问 Jackett 报 401/302 API Key 不匹配所致。注意一个坑：Jackett 部分端点带 ?apikey= 参数可用，另一些（如 /api/v2.0/indexers）在鉴权模式下会 302 跳登录页——这不是 Key 错误的判据，以 /api/v2.0/indexers/all/results?apikey=… 是否 200 为准（本项目实测如此）。修改 Key 后必须 --force-recreate 重建 Rapidbay（普通 restart 不会重读 environment）。

现象三：通过 API 直接添加索引器报 500 本版 Jackett（v0.24.2961 实测）对 POST /api/v2.0/indexers/{id}/config 的 JSON 反序列化存在缺陷——即使照抄 GET 返回的字段结构，也报 Unable to cast JValue to JArray（tags 字段相关）。结论：索引器添加请走 UI 仪表盘，API 仅用于搜索与状态查询。

现象四：BT 下载无速度 依次检查：6881 的 tcp+udp 双映射是否齐全（漏 udp 会瘫掉 DHT）→ 宿主防火墙放行 6881 → 种子活跃度本身（本项目实测 Ubuntu ISO 种子 peers 80+、峰值 50 MB/s，种子健康时速度正常）。无速度但其他种子正常的，多为索引到的死种。

现象五：修改 JACKETT_API_KEY 后服务启动失败或搜索异常 JACKETT_API_KEY 含大小写字母数字，注入时不要加引号外的空格；重建后用第八章第 1 条命令验证 200。本项目实测初始编排即写入正确 Key（与 Jackett 自动生成的值一致），未触发此坑；人工回填时建议直接从 ServerConfig.json 复制。

现象六：网页打开要求输入密码但从未设置 检查编排文件是否残留 PASSWORD 变量；未设置该变量时 POST /api 登录端点直接 404（本项目实测），不会出现密码框——出现密码框说明环境里确实有 PASSWORD，从 docker compose config 核对来源。

十二、参考链接

• 上游仓库（镜像与编排示例来源）：https://github.com/hauxir/rapidbay
• 官方 Jackett 联动 compose 示例：https://github.com/hauxir/rapidbay/blob/master/docker-compose.example.with.jackett.yml
• Jackett 官方仓库：https://github.com/Jackett/Jackett
• linuxserver Jackett 镜像：https://hub.docker.com/r/linuxserver/jackett
• Rapidbay Docker Hub：https://hub.docker.com/r/hauxir/rapidbay
• Prowlarr 安装文档（备选后端）：https://wiki.servarr.com/prowlarr/installation