Docker自托管Swiparr完整教程:5步连接Jellyfin媒体服务器

原创2026-10-27 22:39:441,663 阅读

Docker自托管Swiparr完整教程:5步连接Jellyfin媒体服务器

Swiparr 是一款把「今晚看什么」变成滑动卡牌游戏的开源观影发现工具——可以把它理解为"电影版 Tinder",既支持单人浏览,也支持多人组队,并且能直接连接你已有的 Jellyfin 媒体服务器。本教程面向新手,带你用 Docker 在 5 个步骤内完成 Swiparr 自托管部署,并成功接入 Jellyfin。

Swiparr 是什么:观影发现的"滑动卡牌游戏"

🍿 它解决的是一个每个家庭都有的问题——"今晚看什么?"。核心玩法与卖点:

  • 滑动卡牌发现:一张张浏览电影,右滑喜欢、左滑拒绝,告别纠结
  • 多人会话:几秒内创建/加入 Session,支持"任意两人一致"或"全员一致"等匹配规则
  • 媒体服务器集成:原生支持 Jellyfin,同时兼容 Emby、Plex,也可用 TMDB 独立运行
  • 收藏同步:把大家喜欢的作品一键写回媒体服务器的收藏/片单
  • 移动端优先:手机体验最佳,支持安装为 PWA

开始之前:3 个准备工作

  1. 一台已安装 Docker 和 Docker Compose 的主机
  2. 一台可正常访问的 Jellyfin 媒体服务器
  3. 清楚 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 步:首次登录并初始化管理员

  1. 浏览器打开 http://<你的服务器地址>:4321
  2. 使用你的 Jellyfin 账号登录(会跳转到 Jellyfin 完成认证)
  3. 第一个登录的 Jellyfin 用户自动成为该提供商的管理员
  4. 在管理设置中勾选要纳入滑动池的媒体库,完成初始化

如果想预先指定管理员,可设置环境变量 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 步流程:

  1. 写 compose:镜像 + 端口 + 数据目录
  2. 配变量:核心就是 JELLYFIN_URL(内网地址)
  3. 启动验证:docker compose up -d 后访问 /api/health
  4. 首次登录:Jellyfin 账号登录,第一人自动成为管理员
  5. 创建 Session:拉上家人朋友一起滑动选片

整个部署只有一个容器、一个数据目录、零外部依赖,对新手非常友好。更完整的环境变量矩阵、安全说明(AUTH_SECRET 生成、CORS、安全头)和反向代理配置示例,请参考 README.md。

登录后查看全文
messer-swipe