Rapidbay 1.0.0 配置参数详解
Rapidbay 1.0.0 全量配置参数：运行镜像 settings.py 实查基准、eval 注入语义、服务基础与搜索后端与 BT 引擎与字幕与转码与路径参数逐项解读、master 预发布 HLS 参数标注、生产模板与修改生效方式。
doc_id: 6343 slug: AH10kQnuPp0b description: Rapidbay 1.0.0 全量配置参数：运行镜像 settings.py 实查基准、eval 注入语义、服务基础与搜索后端与 BT 引擎与字幕与转码与路径参数逐项解读、master 预发布 HLS 参数标注、生产模板与修改生效方式。 title: Rapidbay 1.0.0 配置参数详解 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 配置参数详解.md
Rapidbay 1.0.0 配置参数详解
目标：把 Rapidbay 1.0.0 的全部配置参数一次讲清——参数从哪看、怎么改、每个参数的类型/默认值/生效行为，并单独标注 master 分支已合入但当前
latest镜像尚未识别的预发布参数。组件定位见《Rapidbay 介绍与选型指南》，部署与联动实操见《Rapidbay Docker Compose 部署指南》，接口行为见《Rapidbay 1.0.0 API 使用详解》。参数默认值全部取自实测运行镜像内的/app/settings.py（2026-10-30 导出），master 预发布参数取自同日 master 分支源码实查。
一、环境信息
| 项目 | 取值 |
|---|---|
| 实测日期 | 2026-10-30 |
| 服务器 | Ubuntu 24.04.5 LTS x86_64 |
| Rapidbay | 1.0.0（官方镜像 hauxir/rapidbay:latest，959 MB） |
| 参数基准 | 运行中服务内 /app/settings.py（95 行，与 master 分支 diff 仅为 8 个 HLS_* 预发布参数） |
| 配置形态 | 无配置文件，全部参数经环境变量注入（Docker Compose environment 段） |
| 部署形态 | Docker Compose 双服务（Rapidbay + Jackett v0.24.2961），编排文件即配置档案 |
二、前置条件
- 已按 B2 篇完成部署，能访问服务并看到
{"ok": true}； - 知道自己所用镜像的构建时间——本文反复强调"参数以镜像内
/app/settings.py为准"的原因：项目未启用版本发布，latest镜像与 master 分支之间存在特性窗口期，参数清单会随镜像滚动变化； - 查看当前生效值的三种途径：
- 服务内参数文件：
docker exec rapidbay-1.0.0-app cat /app/settings.py（2026-10-30 实测，路径/app/settings.py）； - 服务进程环境：
docker exec rapidbay-1.0.0-app env | grep -E "JACKETT|TORRENT|PASSWORD"； - 行为验证：多数参数可通过 API 行为反查（示例见第四章各参数的"验证"列）。
- 服务内参数文件：
三、参数查看与修改方式
Rapidbay 的参数加载逻辑非常直接（/app/settings.py 实测源码摘录）：
- 文件内为每个参数声明类型与默认值；
- 启动时遍历这些参数名，从环境变量读入；列表/字典/数字/布尔值按 Python 字面量
eval解析——这意味着注入"['en','de']"会被解析为列表，注入"True"才是布尔真（大写首字母）； - 路径类参数（
DATA_DIR等 9 个）单独处理，空值时按DATA_DIR拼接默认子目录。
修改方式的唯一正解：改 Compose 编排文件的 environment 段后重建：
docker compose up -d --force-recreate rapidbay
回显（2026-10-30 实测）：
[+] Running 2/2
✔ Container rapidbay-1.0.0-jackett Running
✔ Container rapidbay-1.0.0-app Recreated
注意：普通 docker compose restart 不会重读环境变量，参数变更必须 --force-recreate（B2 篇排障实录现象五同源）。
四、参数总览
以下为实测镜像 1.0.0 的全量参数（默认值即 /app/settings.py 内声明值；镜像另以 ENV DATA_DIR=/tmp 固定数据根目录，实测进程环境可见）。
4.1 服务基础
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
PASSWORD | str/None | None | 站点口令。未设置时登录端点直接 404（实测）；设置后打开网页需先输入口令，API 侧凭 Cookie 会话访问 |
AUTO_PLAY_NEXT_FILE | bool | True | 前端播完当前文件自动连播下一文件 |
OPENAPI_HOST | str/None | None | OpenAPI 文档中显示的服务地址（反代后文档调试用，不影响监听） |
4.2 搜索后端
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
JACKETT_HOST | str/None | None | Jackett 地址（如 http://jackett:9117）；与 Prowlarr 可同时配置，结果自动合并去重 |
JACKETT_API_KEY | str | "" | Jackett API 密钥（仪表盘右上角或 ServerConfig.json 的 api_key） |
PROWLARR_HOST | str/None | None | Prowlarr 地址，同上 |
PROWLARR_API_KEY | str | "" | Prowlarr API 密钥 |
两组都未配置时服务日志出现 NO_SEARCH_BACKEND 提示，/api/search 返回空结果（实测行为见 D5 篇）。
4.3 BT 引擎
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
TORRENT_LISTENING_PORT | int/None | None（镜像内 ENV 注入 6881） | BT 数据端口；Compose 形态下必须与端口映射一致（tcp+udp 双映射） |
DHT_ROUTERS | list[tuple] | 5 个公共 DHT 节点（router.utorrent.com:6881 等） | DHT 引导节点表，一般无需改动 |
MAX_TORRENT_AGE_HOURS | int | 10 | 下载内容保留时长（小时），到期自动清理——无人值守防磁盘打满的核心参数 |
VIDEO_EXTENSIONS | list[str] | ['mp4','mkv','avi','mpg','mpeg'] | 视频扩展名白名单（前端文件列表筛选） |
SUPPORTED_EXTENSIONS | list[str] | 视频五种 + mp3/flac | 可触发下载的扩展名全集（实测：ISO 虽可下载，转码判定 supported:false） |
TORRENT_DOWNLOAD_LIMIT | int | -1 | 全局下载限速（B/s），-1 不限 |
TORRENT_UPLOAD_LIMIT | int | -1 | 全局上传限速（B/s），-1 不限 |
EXCLUDE_TRACKERS_FROM_TRENDING | list[str] | [] | 趋势列表排除的 tracker 域名 |
EXCLUDE_CATEGORIES_FROM_TRENDING | list[int] | [] | 趋势列表排除的 Jackett 分类 ID |
TRENDING_TITLE_BLOCKLIST | list[str] | [] | 趋势结果标题关键词黑名单 |
TRENDING_BLOCK_NON_LATIN_TITLES | bool | False | 屏蔽非拉丁字符标题（过滤水印组噪音常用） |
MOVE_RESULTS_TO_BOTTOM_CONTAINING_STRINGS | list[str] | ['XviD'] | 命中关键词的搜索结果沉底（老编码格式兼容性差） |
4.4 字幕
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
SUBTITLE_LANGUAGES | list[str] | ['en'] | 下载完成自动拉取的字幕语言，多语言写法 ['en','de','es']（官方 README 同款示例） |
OPENSUBTITLES_USERNAME | str/None | None | OpenSubtitles 账号（官方要求 VIP 才能拉字幕） |
OPENSUBTITLES_PASSWORD | str/None | None | OpenSubtitles 密码 |
实测佐证：Sintel 下载完成后自动获得 9 条 .vtt 字幕并出现在文件状态里（未配账号时的行为为空列表）。
4.5 转码
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
CONVERT_VIDEO | bool | True | 下载完成后自动转码；改 False 则只下载（仅当播放端本地解码能力完整时） |
VIDEO_CONVERSION_PARAMS | str | libx264 -preset ultrafast | ffmpeg 视频编码参数（编码器 + 预设），追求画质可换 -preset veryfast -crf 23，代价是 CPU 时长 |
AAC_BITRATE | str | 256k | 音频轨转 AAC 的码率 |
AAC_CHANNELS | int | 2 | 音频转码声道数 |
INCOMPLETE_POSTFIX | str | .incomplete | 未完成文件的后缀标识 |
LOG_POSTFIX | str | .log | 日志文件后缀 |
MAX_OUTPUT_FILE_AGE | int | 10 | 转码产物保留时长（小时），到期清理 |
MAX_PARALLEL_CONVERSIONS | int | 2 | 并发转码任务数；2C 服务器建议压到 1，防转码挤占下载带宽 |
4.6 路径与端口
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
DATA_DIR | str | ./data（镜像 ENV 固定为 /tmp） | 数据根目录，其余目录默认在其下派生 |
CACHE_DIR | str | <DATA_DIR>/cache | 搜索缓存（diskcache） |
LOGFILE | str | <DATA_DIR>/rapidbay_errors.log | 运行日志（/error.log 端点读取的就是它） |
DOWNLOAD_DIR | str | <DATA_DIR>/downloads/ | 原始下载目录 |
FILELIST_DIR | str | <DATA_DIR>/filelists/ | 文件清单目录 |
TORRENTS_DIR | str | <DATA_DIR>/torrents/ | 会话状态目录 |
OUTPUT_DIR | str | <DATA_DIR>/output/ | 转码产物目录（播放直供处，nginx 指向） |
FRONTEND_DIR | str | ./app/frontend | 前端静态文件目录 |
KODI_ADDON_DIR | str | ./app/kodi.addon | Kodi 插件源码目录（/kodi.repo 打包源） |
端口语义：HTTP 服务固定监听 5000（由启动脚本承载，nginx 同服务内反代），对外暴露端口号由 Compose 端口映射决定（本项目 8154）；BT 数据端口即 TORRENT_LISTENING_PORT（本项目 6881）。
五、master 预发布参数（当前 latest 镜像不识别）
以下 8 个参数仅存在于 master 分支源码（2026-10-30 对 app/settings.py 实查），对应"HLS 边下边播"特性；实测镜像（同日拉取的 latest，内部 1.0.0）不含这批参数——注入不报错但完全无效（本项目编排文件残留的 HLS_STREAMING=True、HLS_SEGMENT_DURATION=6 即属此类，运行环境 env 与 settings.py 均无此变量，已在 B2 篇编排文件中移除）：
| 参数 | master 默认值 | 说明 |
|---|---|---|
HLS_STREAMING | False | HLS 边下边播总开关（注意 master 上默认也是关，需显式开启） |
HLS_SEGMENT_DURATION | 6 | HLS 分片时长（秒） |
HLS_START_THRESHOLD | 52428800（50 MiB） | 启动 HLS 前需要的顺序数据量（字节） |
MAX_PARALLEL_HLS_STREAMS | 2 | 并发 HLS 转码上限（独立于 MAX_PARALLEL_CONVERSIONS） |
HLS_STALL_TIMEOUT | 180 | 无进度多少秒后回收 HLS 流 |
HLS_VIEWER_TIMEOUT | 300 | 无客户端轮询多少秒后停掉 HLS 流 |
HLS_PREFETCH_BYTES | 33554432（32 MiB） | 码率未知时的预取窗口（字节） |
HLS_READ_AHEAD_SECONDS | 60 | 码率已知后保持超前预读的播放秒数 |
master 源码注释给出的机制：用 libtorrent 分片 deadline 抢出"连续头部"，观看者停留在文件页时抢头部窗口，流式器按预取窗口滚动抢先；种子级顺序下载被刻意弃用（未观看的任务保持 rarest-first 选片）。选型含义：想要真·边下边播，要么等特性进入镜像，要么自建镜像（git clone 后按官方 Dockerfile 构建）。
六、生产配置模板
单机 2 核 / 4 GB / 50 GB VPS、以浏览器观影为主的最小化生产模板（Compose environment 段）：
environment:
- PASSWORD=替换为不少于12位的强口令
- TORRENT_LISTENING_PORT=6881
- JACKETT_HOST=http://jackett:9117
- JACKETT_API_KEY=从Jackett仪表盘复制
- OPENSUBTITLES_USERNAME=你的VIP账号
- OPENSUBTITLES_PASSWORD=对应密码
- SUBTITLE_LANGUAGES="['en', 'zh']"
- TORRENT_DOWNLOAD_LIMIT=8388608 # 限速 8 MB/s，保护上传带宽
- TORRENT_UPLOAD_LIMIT=1048576 # 限速 1 MB/s，VPS 带宽友好
- MAX_PARALLEL_CONVERSIONS=1 # 2 核压到 1，防转码卡顿
- MAX_TORRENT_AGE_HOURS=6 # 磁盘紧张时缩短保留期
- MAX_OUTPUT_FILE_AGE=6
- TRENDING_BLOCK_NON_LATIN_TITLES=True # 过滤非拉丁标题噪音
- MOVE_RESULTS_TO_BOTTOM_CONTAINING_STRINGS="['XviD', 'CAM']"
要点：PASSWORD 上线必配（服务无账号体系，口令是唯一门槛）；列表型变量保持 Python 字面量语法；限速值单位是 B/s（8388608 = 8 MB/s）；改完 --force-recreate 重建。
七、常见问题
Q1：改了环境变量但行为没变？
普通 restart 不重读环境。执行 docker compose up -d --force-recreate rapidbay，再用 docker exec rapidbay-1.0.0-app env | grep 你的参数名 确认注入成功。
Q2：列表型参数注入后服务启动异常或行为怪异？
注入值会被 Python eval 解析，务必写合法字面量：列表 ['en','de']（注意单引号在 Compose 里需整体再包双引号）、布尔 True/False（小写 true 会被当字符串）、数字直接写。最稳妥的验证：docker exec rapidbay-1.0.0-app python3 -c "from app import settings; print(settings.SUBTITLE_LANGUAGES)"。
Q3：DATA_DIR 为什么是 /tmp？会不会丢数据？
这是镜像 Dockerfile 的固化选择（组件作者把"临时中转"作为默认定位）。数据是否丢失取决于你是否像 B2 篇那样把宿主目录挂载到 /tmp——挂了就是持久化的，没挂则重建即清空。想换根目录：注入 DATA_DIR=/data 并同步挂载，注意 nginx 对播放目录 /tmp/output 的指向也需一并调整，因此一般不建议动，保持默认挂载即可。
Q4：转码太慢或 CPU 打满？
调 VIDEO_CONVERSION_PARAMS（ultrafast 已是最快档）与 MAX_PARALLEL_CONVERSIONS（压到 1）；仍不足可关转码（CONVERT_VIDEO=False）配合本地播放器直接播放原始文件。
Q5：磁盘仍被撑满？
确认两个保留时长参数（MAX_TORRENT_AGE_HOURS/MAX_OUTPUT_FILE_AGE）；清理只对运行中的服务生效——服务停机期间落下的旧文件需手工清空 downloads/ 与 output/（先 docker compose down）。
Q6：设置了 HLS_STREAMING=True 却没有边下边播？
当前 latest 镜像不含该特性（见第五章），参数无效属预期；关注官方仓库 master 提交与镜像构建时间。
八、参考链接
- 参数基准（运行镜像内文件）：服务内
/app/settings.py（docker exec rapidbay-1.0.0-app cat /app/settings.py可复核） - master 分支参数源码：https://github.com/hauxir/rapidbay/blob/master/app/settings.py
- 官方 README 的环境变量示例：https://github.com/hauxir/rapidbay#readme
- 上游仓库：https://github.com/hauxir/rapidbay
- 同专栏实操篇：《Rapidbay Docker Compose 部署指南》《Rapidbay 1.0.0 API 使用详解》