Jellyfin — 自托管媒体服务器

是什么

Jellyfin 是一个开源的自托管媒体服务器：你把电影、剧集、音乐和照片放在自己机器上，它负责整理海报、字幕、用户、播放进度，并把内容串流到手机、电视和浏览器。

日常类比：它像给家里硬盘装了一个“私人视频网站”。硬盘还是你的，片源还是你的，只是 Jellyfin 帮你做目录、搜索、封面、播放记录和远程观看。

最小使用方式通常是先起一个服务：

docker pull jellyfin/jellyfin
docker run -d --name jellyfin -p 8096:8096 \
  --volume /srv/jellyfin/config:/config \
  --volume /srv/jellyfin/cache:/cache \
  --mount type=bind,source=/media,target=/media \
  jellyfin/jellyfin

打开 http://localhost:8096 后，网页向导会让你创建管理员、添加媒体库、选择元数据语言。之后客户端访问的不是某个文件夹，而是 Jellyfin 整理好的“媒体馆”。

为什么重要

不理解 Jellyfin，下面这些事会很难解释：

• 为什么很多人不想把私人媒体库交给闭源云服务：账号、功能、隐私和订阅规则都不在自己手里。
• 为什么媒体服务器不只是“开一个文件共享”：它还要处理元数据、字幕、用户权限、客户端兼容和播放进度。
• 为什么同一个视频在电视上能直接播放，在浏览器上却要转码：客户端支持的编码、容器和字幕能力不同。
• 为什么家庭 NAS、迷你主机和旧电脑都能变成媒体中心：核心是把存储、索引和串流服务连起来。

核心要点

Jellyfin 可以先抓住 三件事：

1. 服务器做中枢：Jellyfin Server 扫描媒体目录，建立数据库，向网页、手机、电视 App 提供 API 和视频流。类比：图书馆管理员先把书编目，读者不用直接翻仓库。

2. 能直播放就直播放，不能就转码：如果客户端能吃原始文件，Jellyfin 直接传；如果不能，就用 jellyfin-ffmpeg 临时改成客户端能播的格式。类比：客人能听中文就直接讲，听不懂才现场翻译。

3. 文件命名会影响识别质量：电影、剧集、音乐各有推荐目录结构，文件名越接近元数据网站的标题，自动匹配越准。类比：快递地址写得规范，分拣机器才不容易送错。

这三个点合起来，解释了 Jellyfin 的定位：它不是单次转码工具，而是围绕“长期管理个人媒体库”的完整系统。

实践案例

案例 1：在 Linux 主机上用 Docker 跑家庭媒体库

官方容器文档给出的基本思路是：配置、缓存、媒体目录都挂到容器外面，服务端口默认是 8096。

services:
  jellyfin:
    image: jellyfin/jellyfin
    container_name: jellyfin
    ports:
      - 8096:8096/tcp
      - 7359:7359/udp
    volumes:
      - /srv/jellyfin/config:/config
      - /srv/jellyfin/cache:/cache
      - type: bind
        source: /media
        target: /media
    restart: unless-stopped

逐部分解释：

• /config 保存账号、媒体库、插件和服务器配置；容器删了也不能丢。
• /cache 放转码临时片段和缓存；空间太小会影响播放。
• /media 是真实片库，通常建议只让 Jellyfin 读，减少误删风险。
• 7359/udp 用于局域网发现；只在家里访问时很方便。

官方也提醒：在 Windows 或 macOS 上跑 Docker 版不属于推荐路径，硬件转码和文件扫描可能踩坑。

案例 2：把电影和剧集按 Jellyfin 认识的方式摆好

官方媒体文档强调：电影最好一部一个文件夹，剧集最好“剧名 / Season 01 / S01E01”。

Media
├── Movies
│   └── Movie Name (2021) [imdbid-tt12801262]
│       ├── Movie Name (2021) [imdbid-tt12801262] - 2160p.mp4
│       └── Movie Name (2021) [imdbid-tt12801262] - 1080p.mp4
└── Shows
    └── Series Name (2024)
        └── Season 01
            ├── Series Name S01E01.mkv
            └── Series Name S01E02.mkv

逐部分解释：

• Movie Name (2021) 帮元数据匹配区分同名电影。
• [imdbid-...] 是更强的定位信息，能减少识别错片。
• - 2160p 和 - 1080p 是同一电影的多版本标签，前缀必须和父文件夹一致。
• Season 01 不要简写成 S01 文件夹；Jellyfin 文档明确推荐完整季目录。

这个案例说明：Jellyfin 的“自动整理”不是魔法，它依赖文件系统里的线索。片库越乱，后期手动修元数据越多。

案例 3：用 Nginx 给外网访问加 HTTPS 入口

官方反向代理文档给了 Nginx 示例：公网域名先到 Nginx，Nginx 再把请求转给本机 Jellyfin 的 8096。

server {
  listen 443 ssl;
  http2 on;
  server_name jellyfin.example.org;

  location / {
    proxy_pass http://127.0.0.1:8096;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_buffering off;
  }

  location /socket {
    proxy_pass http://127.0.0.1:8096;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
  }
}

逐部分解释：

• proxy_pass 把外部 HTTPS 请求转到内网 Jellyfin。
• X-Forwarded-Proto 让后端知道用户原本走的是 HTTPS。
• /socket 单独处理 WebSocket，少了它会影响实时状态更新。
• proxy_buffering off 避免代理层把流媒体播放缓存得太重。

外网访问还要配证书、防火墙、强密码，不能只把端口暴露出去就结束。

踩过的坑

1. 把 Jellyfin 当网盘：它不是通用文件管理器，目录结构、命名和元数据规则会直接影响体验。
2. 以为所有播放都会转码：能直接播放时 Jellyfin 会尽量直传；转码是兼容兜底，不是默认目标。
3. 容器里看不到媒体目录：宿主机路径没有 bind mount 到容器，网页里自然找不到片库。
4. 远程访问只开端口不做安全：公网暴露媒体服务器要考虑 HTTPS、密码、反代日志和更新节奏。

适用 vs 不适用场景

适用：

• 想把个人电影、剧集、音乐、照片集中放在自己机器上管理。
• 家里有 NAS、迷你主机、旧电脑，愿意长期维护一个媒体服务。
• 需要多用户、多客户端、播放进度同步和自动元数据。
• 不想依赖专有媒体平台的订阅、账号和功能限制。

不适用：

• 只是临时把一个视频发给别人，用文件分享或对象存储更简单。
• 只想批量压缩视频，直接用 handbrake 或 ffmpeg 更贴切。
• 要做直播、互动连麦或低延迟分发，应该看 ant-media-server、gstreamer 这类方向。
• 完全不想维护主机、硬盘、备份、证书和更新；自托管一定会带来运维责任。

历史小故事（可跳过）

• 2018 年 12 月：Jellyfin 团队从 Emby 3.5.2 分叉出来，背景是 Emby 后续版本转向闭源，社区想保留自由软件路线。
• 早期阶段：项目先完成改名、清理授权边界、迁移到 .NET Core，让服务端跨平台运行更稳定。
• 随后几年：服务器、Web 客户端、移动端、电视端和插件生态逐步分开维护，Jellyfin 变成一个组织而不是单仓库。
• 今天：主仓库大约 36k stars，定位是和 Emby、Plex 同类的开源替代品，核心承诺是没有高级功能付费墙。

学到什么

1. 自托管的价值不是“免费”，而是控制权：数据、功能、升级节奏和访问方式都回到自己手里。
2. 媒体服务器的难点在边界：文件系统、元数据、客户端格式、转码性能、网络安全都要一起考虑。
3. 直传优先、转码兜底是一种很务实的系统设计，既省资源，也保证兼容性。
4. 文件命名不是小事，它是自动化识别的输入质量；输入越规范，系统越省心。

延伸阅读

• 官方仓库：jellyfin/jellyfin
• 官方文档入口：Jellyfin Documentation
• 快速开始：Quick Start
• 容器部署：Container Installation
• ffmpeg —— 理解 Jellyfin 转码为什么依赖媒体工具链。

关联

• ffmpeg —— Jellyfin 转码依赖 jellyfin-ffmpeg，播放兼容问题最终常落到编码和封装。
• handbrake —— 适合提前离线转码，减少 Jellyfin 播放时的实时压力。
• docker —— 官方容器镜像是常见部署方式，配置和媒体目录都靠挂载保存。
• docker-compose —— 家庭服务器常用 compose 把 Jellyfin、反代和备份任务放在一起管理。
• nginx —— 远程访问时常作为反向代理和 HTTPS 入口。
• gstreamer —— 同属媒体基础设施，适合对照“媒体管线”和“媒体服务器”的差别。

反向链接

（暂无反向链接）