Jellyswarrm 配置完全指南:jellyswarrm.toml 全参数与环境变量速查清单

原创2026-10-23 15:34:021,982 阅读

Jellyswarrm 配置完全指南:jellyswarrm.toml 全参数与环境变量速查清单

Jellyswarrm 是一个将多台 Jellyfin 服务器合并为统一入口的反向代理,其全部配置由 jellyswarrm.toml 一个文件管理。本文给出 jellyswarrm.toml 全参数速查表、JELLYSWARRM_* 环境变量对照清单,以及通过 Web UI 修改配置的完整步骤,帮你快速完成 Jellyswarrm 部署与调优。

Jellyswarrm 把多台 Jellyfin 服务器合并为一个统一媒体库界面

一、jellyswarrm.toml 放在哪里?

Jellyswarrm 启动后会在数据目录中自动查找/生成配置文件:

文件 路径(容器内) 说明
配置文件 ./data/jellyswarrm.toml 所有参数都在这里
数据库 ./data/jellyswarrm.db SQLite 存储服务器与用户映射

几个关键机制(实现见 config.rs 的 load_config 函数):

  • 首次启动自动生成:文件不存在时,Jellyswarrm 会用默认值加自动生成的 server_id、session_key 写出配置,因此你不需要手写这个文件;
  • 数据目录可迁移:通过环境变量 JELLYSWARRM_DATA_DIR 指定数据目录(默认 ./data),Docker 部署时挂载 ./data 卷即可持久化;
  • 覆盖方式二选一:挂载自己的 jellyswarrm.toml,或用 JELLYSWARRM_* 环境变量逐项覆盖(详见第三部分);
  • 调试构建:debug 模式编译的版本会额外读取 jellyswarrm.dev.toml,仓库里提供了示例 data/jellyswarrm.dev.toml 可直接参考。

二、全参数速查表 📋

以下为 jellyswarrm.toml 支持的全部参数(依据 docs/config.md 与 config.rs 的 AppConfig 结构整理)。参数名即 TOML 键名,环境变量 = JELLYSWARRM_ + 参数名大写 + _ 分隔。

网络与基础参数

参数 默认值 环境变量 说明
server_id 自动生成的 UUID JELLYSWARRM_SERVER_ID 代理实例唯一标识
public_address localhost:3000 JELLYSWARRM_PUBLIC_ADDRESS 客户端能访问到的代理地址(媒体流地址会基于它生成)
server_name Jellyswarrm Proxy JELLYSWARRM_SERVER_NAME 代理的显示名称
host 0.0.0.0 JELLYSWARRM_HOST 监听地址
port 3000 JELLYSWARRM_PORT 监听端口
timeout 20 JELLYSWARRM_TIMEOUT 请求超时(秒)

安全参数

参数 默认值 环境变量 说明
username admin JELLYSWARRM_USERNAME 默认管理员用户名
password jellyswarrm JELLYSWARRM_PASSWORD 默认管理员密码,⚠️ 生产环境务必修改
session_key 自动生成 64 字节密钥 JELLYSWARRM_SESSION_KEY Base64 编码的会话加密密钥,至少 64 字节

上游服务器与流媒体参数

参数 默认值 环境变量 说明
preconfigured_servers [] JELLYSWARRM_PRECONFIGURED_SERVERS 预配置 Jellyfin 服务器列表(见第四部分)
media_streaming_mode Proxy JELLYSWARRM_MEDIA_STREAMING_MODE 全局流媒体模式:Redirect 或 Proxy
server_background_check_interval_secs 30 JELLYSWARRM_SERVER_BACKGROUND_CHECK_INTERVAL_SECS 后台服务器健康检查间隔(秒)

用户、库与媒体参数

参数 默认值 环境变量 说明
auto_create_users_on_login true JELLYSWARRM_AUTO_CREATE_USERS_ON_LOGIN 上游登录成功时自动创建本地用户
merge_libraries true JELLYSWARRM_MERGE_LIBRARIES 合并各服务器上同名媒体库为虚拟库
deduplicate_media false JELLYSWARRM_DEDUPLICATE_MEDIA 将多台服务器上的同一部电影/剧集折叠为一个条目(旧参数名 deduplicate_movies 仍可用)
include_server_name_in_media true JELLYSWARRM_INCLUDE_SERVER_NAME_IN_MEDIA 媒体标题后附加来源服务器名称

Web UI 与调试参数

参数 默认值 环境变量 说明
ui_route ui JELLYSWARRM_UI_ROUTE Web UI 路径段,如 /ui
url_prefix 无 JELLYSWARRM_URL_PREFIX 所有路由的 URL 前缀,适合反向代理子路径部署
debug_user 无 无 仅 debug 构建生效,格式 [debug_user] username = "..."

💡 除了 JELLYSWARRM_DATA_DIR 和 RUST_LOG(日志级别,Docker 镜像默认 info),数据目录中的一切配置项都有对应的 JELLYSWARRM_* 环境变量。

三、环境变量:覆盖 jellyswarrm.toml 的最快方式

配置加载优先级为:环境变量 > TOML 文件 > 内置默认值(源码中环境变量源后于文件源加入,见 config.rs)。

命名规则非常规律:JELLYSWARRM_ + 参数名转大写、以下划线分隔。例如 TOML 中的 include_server_name_in_media 对应 JELLYSWARRM_INCLUDE_SERVER_NAME_IN_MEDIA。

最常用的一组——在 docker-compose.yml 中设置管理员账号(仓库自带示例见 docker-compose.yml):

environment:
  - JELLYSWARRM_USERNAME=admin
  - JELLYSWARRM_PASSWORD=your-strong-password   # ⚠️ 生产环境务必修改

典型场景:

  • 换端口:JELLYSWARRM_PORT=8080
  • 改名:JELLYSWARRM_SERVER_NAME=My Media Hub
  • 子路径部署(Nginx/Traefik 反向代理):JELLYSWARRM_URL_PREFIX=jellyswarrm
  • 数据目录迁移:JELLYSWARRM_DATA_DIR=/opt/jellyswarrm/data

四、预配置上游服务器:preconfigured_servers 字段

不想每次都在 Web UI 里点加服务器?可以在 TOML 中直接写好,priority 数字越大优先级越高:

[[preconfigured_servers]]
url = "http://192.168.0.10:8096"
name = "Movies"
priority = 101
media_streaming_mode = "Proxy"

[[preconfigured_servers]]
url = "http://192.168.0.11:8096"
name = "Shows"
priority = 100
  • media_streaming_mode 可选 Redirect(客户端直连源服务器播放)或 Proxy(经代理转发媒体流,客户端只看到一个服务器);
  • 服务器添加后,可在 Web UI 的 Server Management 页面统一调整优先级并查看在线状态:

Jellyswarrm Web UI 服务器管理页面:设置 preconfigured_servers 的名称、URL 与优先级

五、用 Web UI 改配置,无需编辑文件

登录 http://<地址>:<端口>/ui 后进入 Settings 页,可直接修改 server_name、public_address、include_server_name_in_media 等常用项,点击 Save 即自动持久化回 jellyswarrm.toml(保存逻辑见 settings.rs),还有 Reset / Reload From Disk 按钮应对误操作:

Jellyswarrm 设置页面:修改 public_address、server_name 等配置并保存回 jellyswarrm.toml

六、用户与联邦:auto_create_users_on_login 相关

  • auto_create_users_on_login = true(默认)时,用户用上游 Jellyfin 账号首次登录,Jellyswarrm 自动为其创建本地账号并建立映射,无需管理员预先建号;
  • 也可在 Users 页手动创建用户并勾选 Enable Federation,把同一账号同步到各上游服务器:

Jellyswarrm 用户管理页面:创建用户并启用联邦用户映射

映射成功后,对应服务器会显示 Federated 徽标:

Jellyswarrm 服务器列表中 Federated 徽标表示已建立联邦用户映射

七、部署要点与常见坑 ✅

  1. ⚠️ 改默认密码:默认 admin / jellyswarrm 仅适合本地试用,公网部署请先设置 JELLYSWARRM_PASSWORD;
  2. public_address 要写对:它决定返回给客户端的媒体流地址,跨网访问时应填客户端可达的域名/IP,填 localhost 会导致外部设备无法播放;
  3. session_key 不要运行中更换:密钥在首次启动自动生成并写回 TOML,运行期间更换会使现有会话数据失效(见 config.rs 的热重载保护逻辑);
  4. 持久化数据卷:务必把 ./data 挂到宿主机,否则重启后服务器映射与用户全部丢失;
  5. 合并与去重按需开启:多台服务器媒体高度重叠时,开启 deduplicate_media 可把重复条目折叠成一个;库分散时保持 merge_libraries = true 即可得到统一虚拟库。

📌 一句话总结:日常只需要 jellyswarrm.toml + 几个 JELLYSWARRM_* 环境变量;参数全表见 docs/config.md,解析逻辑见 crates/jellyswarrm-proxy/src/config.rs。

登录后查看全文
Jellyswarrm