先说主线:硬盘里躺着的影片,值得一个像样的家
自建玩家走到影音这一步,手里多半已经攒了一堆资源:硬盘里按文件夹堆着的电影、剧集、演唱会和家庭录像。直接开文件夹找文件播,能播,但体验约等于没有:没有海报墙、没有简介、没有续播进度,电视上更是没法优雅地看。
Jellyfin 就是把这堆文件变成「私人版流媒体平台」的工具:开源免费(它是 Emby 分叉出来的自由软件,没有任何会员和授权费用),自动刮削海报与元数据,按剧集整理季和集,多用户各自进度,几乎所有平台都有客户端。服务器负责整理与串流,电视、手机、平板打开 App 就能接着看。
先把定位说清楚:Jellyfin 管的是你自己硬盘里已有的媒体文件,把它变成一个带海报墙的私人流媒体平台。本文主线:
- Docker 部署 Jellyfin
- 媒体目录命名规范——这是刮削成功率的决定因素
- 硬件转码:让核显或显卡干活,别让 CPU 硬扛
- 用户、远程访问与备份
部署前:媒体文件从哪来、放哪
Jellyfin 本身不存媒体,它只是读取你指定的目录。所以先规划目录:
/media├── movies/ # 电影├── tv/ # 剧集├── music/ # 音乐└── homevideo/ # 家庭录像(不刮削,单独建库)媒体目录可以是本机硬盘,也可以是 NAS 挂载、甚至是 Cloudreve 网盘目录的本地落点。VPS 磁盘小的玩家更常见的组合是:媒体放家里 NAS 或大硬盘机器上,Jellyfin 也装在那台机器上,VPS 只做入口——影音这种大流量、吃硬件的活儿,本来就更适合放在家里。本文按「Jellyfin 与媒体在同一台机器」写,容器需要对媒体目录的读权限。
Docker Compose 部署
官方镜像 jellyfin/jellyfin:
services: jellyfin: image: jellyfin/jellyfin:latest container_name: jellyfin restart: unless-stopped environment: - TZ=Asia/Shanghai - PUID=1000 - PGID=1000 ports: - "127.0.0.1:8096:8096" volumes: - ./config:/config - ./cache:/cache - /media:/media:ro # 硬件转码(二选一,见下文): # Intel 核显: devices: - /dev/dri:/dev/dri # NVIDIA 显卡改用 runtime 方式,见下文媒体目录用 :ro 只读挂载是好习惯:Jellyfin 只需要读文件,刮削产生的海报和元数据都存在它自己的 /config 里,给只读权限可以彻底避免误删原片。启动:
docker compose up -d浏览器打开 http://服务器IP:8096 走初始化向导:建管理员账号 → 添加媒体库(电影选 /media/movies、剧集选 /media/tv,类型别选错)→ 元数据语言设中文 → 完成。之后入口走 Nginx Proxy Manager 反代到 8096 并套 HTTPS,远程观看必须走加密连接。
命名规范:刮削成功率全看它
Jellyfin 靠文件名和目录名去匹配在线数据库(TheMovieDB 等)的条目,命名乱就刮错、刮不到。规范很简单,照着改一遍文件名,后面全是省心:
电影:/media/movies/流浪地球 (2019)/流浪地球 (2019).mkv/media/movies/Inception (2010)/Inception (2010).mkv
剧集:/media/tv/权力的游戏 (2011)/Season 01/权力的游戏 S01E01.mkv/media/tv/Breaking Bad (2008)/Season 02/Breaking Bad S02E03.mkv要点:
- 文件夹名用「片名 (年份)」,集数用
S01E02这种国际通用标记,识别率最高 - 一部电影一个文件夹,外挂字幕同名放旁边(
片名.zh.srt这样带语言标记更稳) - 刮不到时进条目页用「识别」功能手动搜,或在文件夹名里加 TMDB ID,如
片名 (2019) [tmdbid=xxxxxx]强制指定
命名规范花一下午整理一次,胜过之后每次刮错了手动改一百次。整理文件名可以用 FileBot 这类工具批量处理,但改之前先备份目录清单,别批量改错了没法回滚。
硬件转码:这一篇的技术核心
为什么需要转码
客户端能不能播某个文件,取决于它的解码能力。电视不支持片源的编码、手机在外网带宽不够、字幕是图片格式需要烧录——这些情况服务器都要把视频实时转成客户端能吃的格式,这就是转码。纯 CPU 软件转码压一部 4K 片源能把 CPU 跑满还卡顿;硬件转码把活交给核显/显卡的专用单元,功耗低、速度快,是影音服务器能不能用的分水岭。
当然,最好的情况是直接播放(Direct Play):客户端能力够、带宽够,服务器只传文件不做任何处理,零负担。折腾转码是为了兜底那些播不动的场景。
Intel 核显(QSV / VAAPI)
Compose 里已经挂了 /dev/dri。还要两步:
- 确认宿主机能看到核显:
ls /dev/dri应有renderD128 - Jellyfin 后台 → 控制台 → 播放 → 转码 → 硬件加速选
Intel QuickSync (QSV)(或 VAAPI),勾选要硬解的编码格式,保存
权限报错是最常见的坑:容器里的用户要有权访问 /dev/dri/renderD128。宿主机上查它的属组(一般是 render 或 video 组),把该组 ID 通过 Compose 的 group_add 或环境变量给到容器:
group_add: - "105" # 换成宿主机上 render 组的实际 GID,用 getent group render 查NVIDIA 显卡
NVIDIA 走容器运行时,Compose 写法不同:
runtime: nvidia environment: - NVIDIA_VISIBLE_DEVICES=all - NVIDIA_DRIVER_CAPABILITIES=compute,video,utility宿主机需先装好驱动和 NVIDIA Container Toolkit。后台硬件加速选 NVIDIA NVENC。老显卡对新编码(如 AV1)的支持有限,能硬解哪些格式以显卡世代为准,勾选时只勾硬件真正支持的,不支持的会自动回落软解。
验证转码真的在工作
随便播一个需要转码的文件(比如把客户端画质手动调低到 720p 强制触发),然后:
- Jellyfin 后台 → 控制台 → 活动,播放条目会标注转码原因
- 播放详情(ffprobe/信息)里能看到转码方式
- Intel 核显:宿主机执行
intel_gpu_top能看到 Video 引擎有占用;NVIDIA:nvidia-smi能看到 jellyfin 的 ffmpeg 进程
不要没验证就默认硬转在工作——很多人装好后其实一直在软转,CPU 长期满载都不知道原因。活动页的转码信息和 GPU 占用是唯一可靠的证据。
WARNING4K HDR 转 SDR 的色调映射(Tone Mapping)非常吃性能,且需要额外的运行时库支持。低配机器建议:4K 片源单独建库、只在支持直放的设备上看,不要指望实时转码兜底,否则全家人一起卡。
用户、权限与远程访问
- 多用户:家里每人一个账号,各自的观看进度、收藏互不干扰;给孩子建单独账号,配合媒体库的访问控制和分级(年龄分级)限制可见内容
- 媒体库可见性:用户设置里可按库授权,比如儿童账号只放动画库
- 远程访问:Jellyfin 自带的「远程访问」设置允许外网连接,但不要把 8096 端口直接暴露到公网,走 NPM 的 HTTPS 反代是底线;只给家人用的话,再加一层访问控制更稳,做法见 自建服务安全加固
- 带宽限制:后台可给远程播放设码率上限,避免一个人看片把家宽上行打满,影响全家网络
客户端生态
| 平台 | 客户端 | 说明 |
|---|---|---|
| Android / iOS | Jellyfin 官方 App | 免费,支持下载离线 |
| Android TV / Apple TV | 官方 TV 客户端 | 遥控器体验完整 |
| Windows / macOS | Jellyfin Media Player | 解码能力强,最容易实现直放 |
| 网页 | 任意浏览器 | 免安装,但浏览器解码能力最弱、最容易触发转码 |
一个经验:同一部片在网页端卡、在桌面客户端流畅,通常不是服务器不行,而是浏览器不支持片源编码触发了转码。选客户端优先选解码能力强的,直放比例越高,服务器越轻松。
备份
Jellyfin 要备份的是 ./config:里面有全部用户、媒体库配置、元数据和观看记录。媒体文件本体不在备份范围(它们该有自己的存储冗余)。把 config 纳入 自建服务备份与迁移实战 的常规节奏即可;注意备份时最好停一下容器或用其内置的数据库一致性方式,避免拷到写一半的数据库文件。
常见问题与排障
媒体库扫描不到新文件
先确认容器内能看到文件(docker exec jellyfin ls /media/movies);看不到是挂载问题,能看到则查命名规范和文件权限;手动在媒体库设置里点「扫描所有媒体库」。
刮削出来全是错的或英文信息 元数据语言和国家/地区在媒体库设置里改成中文;个别条目用「识别」手动指定;顽固的用文件夹名加 TMDB ID 锁定。
播放卡顿、CPU 100% 先看活动页是否在软转码。是软转的,按上文验证硬转配置;是直放还卡,查网络(远程走公网时上行带宽是瓶颈)和客户端解码。
字幕不显示或乱码 外挂字幕文件名要与视频同名并带语言后缀;编码以 UTF-8 为准,老的 GBK 字幕转码后再放进去。图片字幕(PGS)需要烧录,会强制触发转码,这是正常现象。
容器里没有 /dev/dri
宿主机层面核显被禁用或驱动没装好,先在宿主机 ls /dev/dri 确认设备存在,容器才谈得上映射;云 VPS 大多没有核显,这类机器不适合做转码服务器,老老实实只直放,或者把 Jellyfin 装回家里有核显的机器。
小结
Jellyfin 的三板斧:目录命名规范决定刮削、硬件转码决定播放流畅度、只读挂载加 config 备份决定数据安全。这三件做好,它就是全家人打开电视就能用的私人影音库,零会员费、零广告、进度全打通。