Jellyswarrm 配置完全指南:jellyswarrm.toml 全参数与环境变量速查清单
Jellyswarrm 配置完全指南:jellyswarrm.toml 全参数与环境变量速查清单
Jellyswarrm 是一个将多台 Jellyfin 服务器合并为统一入口的反向代理,其全部配置由 jellyswarrm.toml 一个文件管理。本文给出 jellyswarrm.toml 全参数速查表、JELLYSWARRM_* 环境变量对照清单,以及通过 Web UI 修改配置的完整步骤,帮你快速完成 Jellyswarrm 部署与调优。
一、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 页面统一调整优先级并查看在线状态:
五、用 Web UI 改配置,无需编辑文件
登录 http://<地址>:<端口>/ui 后进入 Settings 页,可直接修改 server_name、public_address、include_server_name_in_media 等常用项,点击 Save 即自动持久化回 jellyswarrm.toml(保存逻辑见 settings.rs),还有 Reset / Reload From Disk 按钮应对误操作:
六、用户与联邦:auto_create_users_on_login 相关
auto_create_users_on_login = true(默认)时,用户用上游 Jellyfin 账号首次登录,Jellyswarrm 自动为其创建本地账号并建立映射,无需管理员预先建号;- 也可在 Users 页手动创建用户并勾选 Enable Federation,把同一账号同步到各上游服务器:
映射成功后,对应服务器会显示 Federated 徽标:
七、部署要点与常见坑 ✅
- ⚠️ 改默认密码:默认
admin / jellyswarrm仅适合本地试用,公网部署请先设置JELLYSWARRM_PASSWORD; - public_address 要写对:它决定返回给客户端的媒体流地址,跨网访问时应填客户端可达的域名/IP,填
localhost会导致外部设备无法播放; - session_key 不要运行中更换:密钥在首次启动自动生成并写回 TOML,运行期间更换会使现有会话数据失效(见 config.rs 的热重载保护逻辑);
- 持久化数据卷:务必把
./data挂到宿主机,否则重启后服务器映射与用户全部丢失; - 合并与去重按需开启:多台服务器媒体高度重叠时,开启
deduplicate_media可把重复条目折叠成一个;库分散时保持merge_libraries = true即可得到统一虚拟库。
📌 一句话总结:日常只需要 jellyswarrm.toml + 几个 JELLYSWARRM_* 环境变量;参数全表见 docs/config.md,解析逻辑见 crates/jellyswarrm-proxy/src/config.rs。




