Jellyswarrm 是什么?把多台 Jellyfin 服务器合并为一站的完整指南
Jellyswarrm 是什么?把多台 Jellyfin 服务器合并为一站的完整指南
Jellyswarrm 是一款免费的开源反向代理工具,能把多台分散在不同位置的 Jellyfin 服务器合并为一个统一入口:你只需要接入一个地址,就能在同一个界面里浏览、播放所有服务器上的电影、剧集和音乐,实现"多服务器、单体验"的媒体中心效果。
为什么需要 Jellyswarrm?多台 Jellyfin 服务器的典型痛点
如果你家里一台 NAS 存电影、另一台服务器存剧集,或者你和朋友各自维护着 Jellyfin 实例,平时会碰到这些问题:
- 📺 客户端里要来回切换服务器地址,收藏、续播体验割裂
- 🔁 用 SMB/NFS 挂载远程媒体库,配置复杂、跨网络性能差
- 🧩 缺少统一的"下一集"(Next Up)、"最近添加"跨服务器合并视图
Jellyswarrm 的思路是:不做媒体搬运,而是做智能代理。它对外伪装成一台标准的 Jellyfin 服务器,所有 Jellyfin 客户端(网页端、TV 端、移动端 App)都能直接把它当作普通服务器接入;而视频流则直接从原始服务器播放,转码等重活留在媒体实际所在的机器上完成,避免中转瓶颈。这也是它相比挂载远程目录方案的优势:内容流式直出,性能更好。
项目说明中给出了选择它的核心理由,可参考 README.md 中的 FAQ 部分。
快速上手:Docker 一键部署 Jellyswarrm
最简单的方式是直接使用官方构建的 Docker 镜像。创建一个 docker-compose.yml,最小可用配置如下:
services:
jellyswarrm:
image: ghcr.io/llukas22/jellyswarrm:latest
container_name: jellyswarrm
restart: unless-stopped
ports:
- 3000:3000
volumes:
- ./data:/app/data
environment:
- JELLYSWARRM_USERNAME=admin
- JELLYSWARRM_PASSWORD=jellyswarrm # ⚠️ 生产环境请修改
然后执行 docker compose up -d 启动。仓库中也提供了开箱即用的 docker-compose.yml 可以直接参考。
启动后你会得到两个入口:
| 入口 | 地址 | 用途 |
|---|---|---|
| 管理界面 Web UI | http://主机:3000/ui |
添加服务器、管理用户、修改设置 |
| 内置 Jellyfin 网页端 | http://主机:3000 |
给普通用户的播放入口 |
配置与数据都保存在 ./data 目录(jellyswarrm.toml 配置 + jellyswarrm.db 数据库),挂载卷即可跨重启持久化,详细选项见 docs/config.md。
添加 Jellyfin 服务器:合并多台实例的第一步
用管理员账号登录 Web UI(默认端口 3000 下的 /ui 路径),进入 Servers 页面,填写服务器名称、Jellyfin URL、优先级(Priority)即可添加。Jellyswarrm 会实时显示每台服务器的在线状态与版本:
几个关键字段说明:
- Server Name:显示名称,例如 Movies、Tv Shows
- Jellyfin URL:目标服务器的完整地址
- Priority:数字越大优先级越高,决定主题、样式等由哪台服务器主导
- Streaming 流媒体模式:
Redirect(客户端能直连目标服务器时)或Proxy(流必须经过 Jellyswarrm 中转时),可逐服务器设置
用户联邦:一次登录,打通所有服务器
光合并服务器还不够,还要让一个用户在所有服务器上"有身份"。Jellyswarrm 提供了 Federation(联邦) 机制:
- 在 Servers 页面为服务器配置管理员凭据(点击服务器条目旁的管理员图标),Jellyswarrm 就获得了在该服务器自动创建用户的权限:
- 在 Users 页面新建用户时勾选 Enable Federation,系统会:
- 自动在所有已配置管理员凭据的服务器上创建同名同密码账号
- 自动生成服务器映射(Server Mappings),无需手动配置
如果不想开联邦,也可以在用户条目下手动添加映射:选择目标服务器,填入该服务器上对应用户的账号密码即可:
普通用户自己也可以管理绑定:登录后在个人页面的 Connected Servers 中,对可用服务器点击 Connect,支持密码登录或 Quick Connect(在已登录的 Jellyfin 客户端上批准验证码)。映射凭据与后端令牌会使用基于 session_key 派生的密钥加密存储,session_key 存放在 jellyswarrm.toml 中,建议备份。更多细节见 docs/ui.md。
合并后的体验:一个入口浏览全部媒体
配置完成后,打开内置的 Jellyfin 网页端,你的媒体库就"合并"到了一个界面里。启用默认的库合并功能(merge_libraries)后,同名库会被合并为虚拟库;同时开启媒体去重(deduplicate_media)后,多台服务器上的同一部电影/剧集还会折叠成一个条目:
用户个人页面则提供连接状态一览和自助管理:
全局设置与健康检查
Settings 页面可以在线修改运行时配置,并直接写回 TOML 文件:
常用选项:
- Public Address:对外报告的地址,Jellyfin 客户端据此建立连接
- Server Name:客户端里显示的服务器名称
- Add Server Name to Title:开启后媒体标题会追加
[服务器名]后缀,方便区分来源 - auto_create_users_on_login:已存在于某台服务器的用户首次登录时自动建立本地账号与映射
运维方面,Jellyswarrm 提供 /health 与 /ready 两个健康检查端点,Docker 镜像自带 30 秒周期的健康检查,可放心用于 Compose 编排,说明详见 docs/health-monitoring.md。
常见疑问(FAQ)
Q:能不能直接在 Jellyfin 客户端里添加多台服务器? 部分客户端支持,但来回切换体验割裂。Jellyswarrm 把一切合到一处,还能跨服务器合并"下一集"和"最近添加",一眼看到新内容。
Q:现有的 Jellyfin 客户端都能用吗? 大概率可以。Jellyswarrm 对外就是一台标准 Jellyfin 服务器,大多数客户端开箱即用,但并非所有客户端都经过测试。
Q:哪些功能还在完善中? 项目仍处于早期开发阶段,QuickConnect、SyncPlay 所需的 Websocket 支持、音频流、自动码率调整等仍在开发中,详见 README.md 的 Features 一节。
总结
Jellyswarrm 用最轻量的一台容器,解决了"多台 Jellyfin 各管一摊"的顽疾:
- 部署简单:Docker 一键启动,
/ui管理界面图形化配置 - 接入无感:伪装成标准 Jellyfin 服务器,现有客户端直接可用
- 体验统一:库合并、媒体去重、Next Up 跨服务器聚合
- 性能友好:视频流从源服务器直出,转码留在媒体所在机器
如果你的媒体分散在多台 Jellyfin 服务器上,Jellyswarrm 值得一试。想深入了解请求转发与响应合并的工作原理,可以阅读 docs/request-response-processing.md。






