Docker Compose 部署

理论聊完，进入动手环节。Jellyfin 的部署方式主要有两种：官方提供的 jellyfin/jellyfin Docker 镜像，以及从官网下载二进制压缩包直接运行。对家用玩家来说，Docker 几乎是闭眼选——升级、迁移、重建都省事。本篇以 Docker 为例，把第一台 Jellyfin 从零跑起来。

一、为什么推荐 Docker

Docker 的本质是“应用连同依赖打包进一个盒子”。对 Jellyfin 而言，这个盒子的优势体现在三件事上：装的时候不用管系统里那一堆依赖库；升级时拉新镜像即可，老配置原样保留；换机器时把整个配置目录拷走，新容器里就是熟悉的样子。

再来一个角度：Docker 让家庭服务的复利变得可见。Jellyfin 是你装在 NAS 或小主机上的第一个容器，但绝不会是最后一个。相册、下载、笔记、家庭网盘，每一个服务都用同一套套路：拉镜像、挂目录、开端口。第一个服务的部署成本最高，其后每一个的边际成本都在降低。这也是为什么本书的部署篇值得你细读一遍——它不只是 Jellyfin 的说明书，而是家庭服务器时代的通用操作姿势。

成品 NAS 用户可以用系统自带的图形化容器管理套件来完成同样的操作，勾选的参数与本篇下面讲的一一对应，概念完全相同。群晖用户可先翻一翻 《群晖 DSM 指南》 的容器与共享目录章节，再回来对号入座。

对还没决定要不要上 Docker 的读者再说一句：Docker 的学习成本只在第一次。条命令、一个目录、一个端口的组合一旦跑通，它就是整个家庭服务的标准姿势——Jellyfin 之后想加相册、下载、网盘，都是同一个套路，边际学习成本接近于零。这也是社区教程几乎全部默认 Docker 的原因：作者们吃过写成系统服务的苦。

二、部署前的准备

先在宿主机上规划三个目录：配置目录（容器里的 /config，存放所有设置、用户与刮削数据）、缓存目录（容器里的 /cache，转码与元数据缓存）、媒体目录（容器里的 /media，指向第一章规划好的媒体根目录）。前两者建议放在系统盘或一块可靠的 SSD 上，媒体目录则指向存储盘。目录归属用户与容器运行用户保持一致，能避开后面八成的权限问题。

目录大小留多少合适？配置目录随媒体规模缓慢增长，几百部影片的库通常占用不足 1GB（海报与元数据都很小），但给到 5GB 以上比较安心；缓存目录在多人同时转码时膨胀得快，10GB 是一个够用的起点，它会在空闲时自行回收。宿主机是 NAS 时，这两个目录放 SSD 上能明显加快海报墙加载，媒体目录则放在大盘上不必追求速度。

网络方面，默认端口 8096 用于 HTTP 访问，再留一个 8920 给可选的 HTTPS。这两个端口如果在宿主机上被其他服务占用，映射时换成本机空闲端口即可，容器内部端口号不变。

三、用一条命令跑起来

确认 Docker 与设备就绪后，用下面这条命令启动服务（镜像名 jellyfin/jellyfin，标签建议锁定稳定版本而非 latest：latest 看似省事，实际每次拉取都可能落到不同版本，家庭的固定客户端偶尔会因服务端悄悄升级而界面错位。锁定 stable 这类显式标签，升级时机就完全掌握在你手里。）：

docker run -d --name jellyfin \
  -p 8096:8096 \
  -v /srv/jellyfin/config:/config \
  -v /srv/jellyfin/cache:/cache \
  -v /srv/media:/media:ro \
  --restart unless-stopped \
  jellyfin/jellyfin:stable

这条命令的要点拆开看：-d 表示后台运行；三个 -v 分别把宿主机目录挂进容器；媒体目录加了 :ro 表示只读挂载，防止 Jellyfin 回写媒体目录（对只读库很安全，若要在 Jellyfin 里删除文件则去掉该参数）；--restart unless-stopped 保证容器异常退出或宿主机重启后自动拉起。启动后用浏览器访问 宿主机 IP 加端口 8096，就会看到初始化向导。

顺带解释一下冒号两边路径的含义：冒号左边是宿主机上的真实路径，右边是容器内部看到的路径。容器内部路径是固定的，左边随你的实际情况改。只要弄清“哪边改哪边不改”，容器挂载永远不会写错。

向导第一步会让你创建管理员账户。这里有两个小建议：密码当时就设好，别留空后补；账户名不要用 admin 这类默认值，改成一个你喜欢的名字。第二步问元数据语言：显示语言选中文，刮削优先语言选中文或原文，配错也不要紧，之后在控制台随时能改。第三步添加媒体库，先只加一个电影库做试验，等扫描和播放都验证通过，再批量把剧集库与音乐库加上。

四、开机自启与升级策略

unless-stopped 重启策略配合 Docker 服务自启，已经覆盖绝大多数场景：断电恢复后容器会自己回来。升级操作同样简单，流程是拉取新镜像、删除旧容器、用完全相同的参数重建。由于配置都在挂载目录里，重建后所有设置、用户与海报墙原样保留：

docker pull jellyfin/jellyfin:stable
docker stop jellyfin
docker rm jellyfin

然后用第三步的命令重新启动即可。建议升级前给配置目录做一次快照或压缩备份，万一新版本与刮削数据不兼容，可以快速回滚到旧版本继续用。社区建议生产环境不要追逐每个新版本，半年左右跟进一次稳定版即可。

升级节奏还有个实际考量：Jellyfin 的客户端与服务端通常分开迭代，服务端大版本更新后旧客户端偶尔会出现界面错位。家里若有老人用的固定客户端，升级服务端后顺手检查一下电视端的显示，出问题就回滚，比逐台调客户端省事。

远程访问先不放在本篇解决。内网里跑通全部功能是第一里程碑；远程观看涉及的反向代理与内网穿透属于网络层工程，放在第四章专门展开。这里只提醒一句：任何涉及外部访问的改造，都等本地家人用顺手了再做，否则排障时分不清是服务端的事还是网络的事。

五、部署阶段的小坑汇总

这些坑的共性是：全部与容器参数有关，而不是 Jellyfin 本身有关。排查时先怀疑挂载与权限，再怀疑应用层设置，能最快定位问题。把这张表对着自己的启动命令逐项核对一遍，等于完成一次免费的部署体检。

时区问题值得多说一句：容器默认使用 UTC，海报墙的“最近添加”时间会差八小时，顺手在启动命令里加上时区设置再重启一次即可。修好后时间轴立刻恢复正常，这个小细节常被误当成系统 bug。

六、给部署留一张速查卡

整套部署完成后，你手上其实只剩三样东西值得备份：写好的容器启动命令、宿主机上的三个目录、以及第一次扫描成功的媒体库。把启动命令存成一个脚本文件放在配置目录里，任何时候换机器重装都只需要两条命令。更稳妥的做法是给媒体目录之外的那个配置目录做定期快照，这是本书第四章备份一篇的核心内容。

速查卡这里再补几个部署之后的自检动作，按顺序做一遍即可：

• 用浏览器访问页面，完成初始化向导并加一个媒体库；
• 播放一个文件，确认画面声音正常、续播记录生效；
• 重启宿主机一次，确认容器自启且配置仍在；
• 记下宿主机的 IP 与端口， television 端 App 用这个地址登录。

这四步全过，部署这一篇就算毕业了。之后想加 HTTPS、反向代理或远程穿透，都是在同一个容器之上叠建设施，底子打得正，上层怎么加都稳。部署阶段的最后一个提醒：把成功跑通的那份启动命令复制到记事本里，连同宿主机 IP、端口、管理员账号一起，当成家庭服务器的基础信息文档——将来一定会回头找它。

延伸阅读

• 核显直通与转码参数见本篇的下一章硬件解码；
• 媒体目录怎么组织、文件怎么命名见本篇目录规划一篇；
• 部署完成后的排障思路见第四章故障排查一篇；
• 对宿主机选型还有疑问可回顾 《NAS 自建指南》。