Docker自托管Swiparr完整教程:5步连接Jellyfin媒体服务器
Docker自托管Swiparr完整教程:5步连接Jellyfin媒体服务器
Swiparr 是一款把「今晚看什么」变成滑动卡牌游戏的开源观影发现工具——可以把它理解为"电影版 Tinder",既支持单人浏览,也支持多人组队,并且能直接连接你已有的 Jellyfin 媒体服务器。本教程面向新手,带你用 Docker 在 5 个步骤内完成 Swiparr 自托管部署,并成功接入 Jellyfin。
Swiparr 是什么:观影发现的"滑动卡牌游戏"
🍿 它解决的是一个每个家庭都有的问题——"今晚看什么?"。核心玩法与卖点:
- 滑动卡牌发现:一张张浏览电影,右滑喜欢、左滑拒绝,告别纠结
- 多人会话:几秒内创建/加入 Session,支持"任意两人一致"或"全员一致"等匹配规则
- 媒体服务器集成:原生支持 Jellyfin,同时兼容 Emby、Plex,也可用 TMDB 独立运行
- 收藏同步:把大家喜欢的作品一键写回媒体服务器的收藏/片单
- 移动端优先:手机体验最佳,支持安装为 PWA
开始之前:3 个准备工作
- 一台已安装 Docker 和 Docker Compose 的主机
- 一台可正常访问的 Jellyfin 媒体服务器
- 清楚 Jellyfin 的内网地址(供 Swiparr 容器访问,如
http://192.168.1.10:8096或 Docker 服务名)
💡 默认端口为
4321,若被占用只需修改 compose 文件中的宿主端口映射。
第 1 步:创建 docker-compose.yml 配置文件
项目提供了官方标注好每一项用法的示例 docker-compose.example.yml,新手可参照它写一份最小配置:
services:
swiparr:
image: ghcr.io/m3sserstudi0s/swiparr:latest
container_name: swiparr
restart: unless-stopped
environment:
- PROVIDER=jellyfin
- JELLYFIN_URL=http://jellyfin:8096 # 换成你的 Jellyfin 内网地址
volumes:
- ./swiparr-data:/app/data
ports:
- 4321:4321
两个最关键的点:
JELLYFIN_URL必须填写容器能访问到的地址。如果 Jellyfin 挂在反向代理后面,这里用容器名/IP + 端口,而不是公网域名./swiparr-data目录用于持久化 SQLite 数据库(默认file:/app/data/swiparr.db),升级容器不会丢数据
第 2 步:配置关键环境变量
连接 Jellyfin 只需关注下面几个变量(完整版见 docker-compose.example.yml 注释,变量校验逻辑在 src/lib/config.ts):
| 变量 | 必填 | 说明 |
|---|---|---|
PROVIDER |
否 | 媒体提供商:jellyfin(默认)/ emby / plex / tmdb |
JELLYFIN_URL |
✅ | Jellyfin 内网地址(容器视角) |
JELLYFIN_PUBLIC_URL |
否 | Jellyfin 公网地址,供浏览器端登录跳转和加载海报图,默认同 JELLYFIN_URL |
JELLYFIN_USE_WATCHLIST |
否 | true 时写入 Watchlist 而非 Favorites(需 Jellyfin Enhanced 插件等支持) |
AUTH_SECRET |
否 | 会话加密密钥(≥32 位)。不填则首次启动自动生成并存入数据库 |
USE_SECURE_COOKIES |
否 | HTTPS 部署时设为 true |
DATABASE_URL |
否 | 默认容器内 SQLite,可指向外部数据库 |
⚠️ 新手最常见的坑:只填了公网域名导致容器连不上 Jellyfin。记住——JELLYFIN_URL 是"容器看的地址",JELLYFIN_PUBLIC_URL 才是"浏览器看的地址"。
第 3 步:启动容器并验证服务健康
docker compose up -d
docker logs -f swiparr
容器的启动流程由 docker-entrypoint.sh 控制,首次启动会依次执行:数据库迁移 → 确保 AUTH_SECRET 存在(scripts/ensure-auth-secret.cjs)→ 启动服务。
随后打开健康检查端点验证:
http://<你的服务器地址>:4321/api/health
看到 {"status":"healthy","database":"connected"} 即表示服务就绪(该端点实现在 src/app/api/health/route.ts)。
第 4 步:首次登录并初始化管理员
- 浏览器打开
http://<你的服务器地址>:4321 - 使用你的 Jellyfin 账号登录(会跳转到 Jellyfin 完成认证)
- 第一个登录的 Jellyfin 用户自动成为该提供商的管理员
- 在管理设置中勾选要纳入滑动池的媒体库,完成初始化
如果想预先指定管理员,可设置环境变量 JELLYFIN_ADMIN_USERNAME(全局则用 ADMIN_USERNAME)。权限判定逻辑见 src/lib/services/auth-service.ts。
第 5 步:创建 Session,开始一起滑动
- 房主创建 Session,把邀请码发出去;访客只需输入昵称就能加入,无需注册账号
- 选择匹配规则:大群体用"任意两人一致"出结果快,小群体用"全员一致"保证共识
- 可限制每人点赞/点踩次数和最大匹配数,防止无脑右滑
- 滑动结束后,匹配结果汇总在匹配列表,喜欢的作品可写回 Jellyfin 的收藏
- 手机上建议把 Swiparr 安装为 PWA,体验接近原生 App
进阶:你可能遇到的 3 个场景
子路径部署(URL_BASE_PATH)
想把 Swiparr 放到 /swipe/ 这类子路径下时,注意:URL_BASE_PATH 必须在构建镜像时通过 --build-arg 写入,官方预构建镜像不支持。需要自行构建:
git clone https://gitcode.com/gh_mirrors/sw/swiparr
cd swiparr
docker build --build-arg URL_BASE_PATH=/swipe -t swiparr-custom .
构建后在 compose 中将镜像改为 swiparr-custom,并让运行时环境变量 URL_BASE_PATH 与构建参数完全一致;反向代理转发时不要剥离该前缀。
备份与迁移
所有数据(数据库、缓存)都在挂载目录 ./swiparr-data 中,复制这一个目录即可完成整体迁移或备份。若挂载卷权限报错,可用官方镜像支持的 PUID/PGID 环境变量指定运行用户。
排错调试
设置 ENABLE_DEBUG=true 可获得详细日志和客户端-服务端错误映射,排查连接失败时非常有用。
总结
回顾一下 Swiparr 自托管的 5 步流程:
- 写 compose:镜像 + 端口 + 数据目录
- 配变量:核心就是
JELLYFIN_URL(内网地址) - 启动验证:
docker compose up -d后访问/api/health - 首次登录:Jellyfin 账号登录,第一人自动成为管理员
- 创建 Session:拉上家人朋友一起滑动选片
整个部署只有一个容器、一个数据目录、零外部依赖,对新手非常友好。更完整的环境变量矩阵、安全说明(AUTH_SECRET 生成、CORS、安全头)和反向代理配置示例,请参考 README.md。