2546 字
13 分钟
Jellyfin:私人影音库与硬件转码
2026-11-15

先说主线:硬盘里躺着的影片,值得一个像样的家#

自建玩家走到影音这一步,手里多半已经攒了一堆资源:硬盘里按文件夹堆着的电影、剧集、演唱会和家庭录像。直接开文件夹找文件播,能播,但体验约等于没有:没有海报墙、没有简介、没有续播进度,电视上更是没法优雅地看。

Jellyfin 就是把这堆文件变成「私人版流媒体平台」的工具:开源免费(它是 Emby 分叉出来的自由软件,没有任何会员和授权费用),自动刮削海报与元数据,按剧集整理季和集,多用户各自进度,几乎所有平台都有客户端。服务器负责整理与串流,电视、手机、平板打开 App 就能接着看。

先把定位说清楚:Jellyfin 管的是你自己硬盘里已有的媒体文件,把它变成一个带海报墙的私人流媒体平台。本文主线:

  1. Docker 部署 Jellyfin
  2. 媒体目录命名规范——这是刮削成功率的决定因素
  3. 硬件转码:让核显或显卡干活,别让 CPU 硬扛
  4. 用户、远程访问与备份

部署前:媒体文件从哪来、放哪#

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 里,给只读权限可以彻底避免误删原片。启动:

Terminal window
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。还要两步:

  1. 确认宿主机能看到核显:ls /dev/dri 应有 renderD128
  2. 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 占用是唯一可靠的证据。

WARNING

4K HDR 转 SDR 的色调映射(Tone Mapping)非常吃性能,且需要额外的运行时库支持。低配机器建议:4K 片源单独建库、只在支持直放的设备上看,不要指望实时转码兜底,否则全家人一起卡。

用户、权限与远程访问#

  • 多用户:家里每人一个账号,各自的观看进度、收藏互不干扰;给孩子建单独账号,配合媒体库的访问控制和分级(年龄分级)限制可见内容
  • 媒体库可见性:用户设置里可按库授权,比如儿童账号只放动画库
  • 远程访问:Jellyfin 自带的「远程访问」设置允许外网连接,但不要把 8096 端口直接暴露到公网,走 NPM 的 HTTPS 反代是底线;只给家人用的话,再加一层访问控制更稳,做法见 自建服务安全加固
  • 带宽限制:后台可给远程播放设码率上限,避免一个人看片把家宽上行打满,影响全家网络

客户端生态#

平台客户端说明
Android / iOSJellyfin 官方 App免费,支持下载离线
Android TV / Apple TV官方 TV 客户端遥控器体验完整
Windows / macOSJellyfin 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 备份决定数据安全。这三件做好,它就是全家人打开电视就能用的私人影音库,零会员费、零广告、进度全打通。

Jellyfin:私人影音库与硬件转码
https://www.anexns.cloudns.org/posts/selfhost-jellyfin/
作者
Anexns
发布于
2026-11-15
许可协议
CC BY-NC-SA 4.0