Jellyfin：家庭影音库

完成后，NAS 里的片库可以用浏览器、电视和手机上的 Jellyfin 客户端播放。片库以只读方式挂进容器，容器删不掉你的片子；有 Intel 核显的话，还可以硬件转码。

适合谁

• 想自建影音库，不想为 Plex 的收费功能付费。Jellyfin 开源免费。
• 只想让电视直接看 NAS 里的视频，不要海报墙和元数据：用 MiniDLNA 更轻。
• 片库已经按 Jellyfin 能识别的方式命名和分目录。命名规则见 Jellyfin 文档：Movies 和 Shows。

应用信息

项	内容
示例清单	有 jellyfin，截至 2026-10-23，示例文件日期为 2025-06-01
镜像	示例用 LinuxServer 的 lscr.io/linuxserver/jellyfin:latest，官方镜像是 jellyfin/jellyfin，支持 amd64 和 arm64
示例里的端口	8096（网页和客户端）、8920（HTTPS，可选）、7359/udp（客户端自动发现，可选）、1900/udp（DLNA 发现，可选）
数据	/config：数据库、元数据、插件。LinuxServer 的说明提醒，大型媒体库它可能增长到 50 GB 以上
官方文档	Jellyfin 文档

两种镜像怎么选

	LinuxServer 镜像（示例用的）	官方镜像 jellyfin/jellyfin
运行用户	PUID、PGID 环境变量	compose 的 user: 字段
目录	/config、媒体目录	/config、/cache、媒体目录
硬件转码权限	说明称自动处理 /dev/dri 的权限	要用 group_add 传入宿主机 render 组的编号

Jellyfin 文档特别说明：两种镜像的配置和数据路径不同，不能简单互换。选定一种就别中途换。本文以插件示例，也就是 LinuxServer 镜像为准。

部署

先准备好：

• 一个放片库的共享文件夹，下文叫 media；appdata 已建好。
• 专用用户 appuser，它对 media 至少有读权限，做法见容器权限：PUID、PGID 与共享文件夹。

步骤和部署第一个应用一样：服务 → Compose → 文件（Services → Compose → Files）→ 添加 → 从模板添加，选 jellyfin，添加后点 编辑。示例原样是这样：

services:
  jellyfin:
    image: lscr.io/linuxserver/jellyfin:latest
    container_name: jellyfin
    environment:
      - PUID=1000
      - PGID=100
      - TZ=Etc/UTC
      - JELLYFIN_PublishedServerUrl=192.168.0.5 #optional
    volumes:
      - CHANGE_TO_COMPOSE_DATA_PATH/jellyfin/library:/config
      - CHANGE_TO_COMPOSE_DATA_PATH/jellyfin/tvseries:/data/tvshows
      - CHANGE_TO_COMPOSE_DATA_PATH/jellyfin/movies:/data/movies
    ports:
      - 8096:8096
      - 8920:8920 #optional
      - 7359:7359/udp #optional
      - 1900:1900/udp #optional
    restart: unless-stopped

改成这样：

services:
  jellyfin:
    image: lscr.io/linuxserver/jellyfin:latest
    container_name: jellyfin
    environment:
      - PUID=${{ uid:"appuser" }}
      - PGID=${{ gid:"users" }}
      - TZ=${{ tz }}
    volumes:
      - ${{ sf:"appdata" }}/jellyfin/config:/config
      - ${{ sf:"media" }}:/media:ro
    devices:
      - /dev/dri:/dev/dri
    ports:
      - "8096:8096"
    restart: unless-stopped

改动的原因：

• 用户和时区：不再写死 1000、100 和 Etc/UTC，用占位符读 OMV 里的真实值。
• 配置目录：放进 appdata 的子目录 jellyfin/config，不要直接挂 appdata/jellyfin。配置放 SSD 上，翻封面和海报墙会快很多。
• 媒体目录：示例把片子放在 data 共享文件夹里的 jellyfin/movies，不方便你用已有的片库。改成直接挂你的 media，加 :ro 只读。Jellyfin 在容器里看到 /media，片库里的子目录它自己能浏览。:ro 的卷还有个好处：插件的计划备份永远不会去复制它。
• devices 那两行：只有用 Intel 核显转码才需要，见下一节。没有 /dev/dri 这个设备时必须删掉，否则容器起不来。先在 OMV 的 shell 里（root）运行 ls -l /dev/dri 看一下。
• 端口：只留 8096。8920 要你自己准备证书。7359 和 1900 的 UDP 是客户端自动发现和 DLNA 用的，在 Docker 默认网络下是否好用不一定，不依赖它们就不映射，客户端里手动填 http://<NAS 的 IP>:8096 最稳妥，细节以 Jellyfin 的网络文档为准。
• JELLYFIN_PublishedServerUrl：只影响自动发现的应答地址，可选。LinuxServer 现在的说明要求带上 http:// 前缀，示例里的值没有带。

点 保存，检查，上线。

首次设置

浏览器打开 http://<NAS 的 IP>:8096，按向导走：语言、创建管理员账号、添加媒体库、元数据语言。

• 添加媒体库时，路径填容器里的路径，也就是 /media/ 加你片库里的子目录，比如 /media/电影。
• 不要为了从外网访问，直接把 8096 映射到公网，也不要在向导里开自动端口映射。外网访问用 VPN 或反向代理，见反向代理与 HTTPS。

硬件转码：Intel 核显

1. 在 OMV 的 shell 里（root）确认 ls -l /dev/dri 里有 renderD128。没有，多半是内核或 BIOS 没启用核显。
2. compose 文件里保留上面的 devices 两行。
3. 权限：LinuxServer 的说明称镜像会自动让容器内的用户获得这个设备的权限；omv-extras wiki 的做法是把运行容器的用户加进 render 和 video 组。两种说法不冲突，转码不工作时两边都检查。
4. 在 Jellyfin 的管理控制台里打开转码设置，把硬件加速选成 QSV 或 VA-API，并取消勾选你的硬件不支持的编解码器，具体选项以你的 Jellyfin 版本界面为准。
5. 验证：随便播放一个视频，把画质调低，强制触发转码。想看显卡有没有在干活，可以在 OMV 上装 intel-gpu-tools，运行 intel_gpu_top，看 Video 引擎有占用。这是 Jellyfin 官方文档给的方法。

NVIDIA 显卡要装 NVIDIA 容器工具包，步骤更复杂，按 Jellyfin 和 LinuxServer 的文档来。注意：这时 Compose 设置页里的 Docker 存储 要留空，见Compose 插件设置详解。

元数据刮削：网络访问不稳定怎么办

Jellyfin 要从 TheMovieDb、TheTVDB 等外部网站获取海报和简介。在部分网络环境下，这些站点访问不稳定，现象是「搜索不到元数据」「封面是空的」，日志里出现超时。

先查 DNS 和网络。 容器能不能解析、访问这些域名。Jellyfin 的 issue 里有用户反馈，把 Docker 使用的 DNS 换掉就恢复了（#16229）。

再考虑代理。 Jellyfin 没有单独的出站代理设置，但它用的 .NET 会读取标准的代理环境变量，所以可以在容器里设置。注意这会让 Jellyfin 所有对外请求都走代理，没法只代理元数据，这个需求在 #14373 里已被关闭为不计划实现。

environment:
  - HTTPS_PROXY=http://<代理地址>:<端口>
  - NO_PROXY=localhost,127.0.0.1,<NAS 的 IP>

NO_PROXY 里多个地址用逗号隔开，不要有空格。这一做法来自微软 .NET 文档和社区资料，没有在真机上验证。

最后手动补。 自动识别错了，用 Jellyfin 的「识别」功能手动选对，或者在本地放 NFO 文件。

检查结果

1. 服务 → Compose → 文件 里状态灯是绿色，http://<NAS 的 IP>:8096 能打开。
2. 媒体库里有内容，海报和简介出来了。
3. 在手机或电视的 Jellyfin 客户端里，能连上服务并播放。
4. 确认片库是只读的：在 OMV 的 shell 里（root）运行 docker exec jellyfin touch /media/test，应该报 Read-only file system。
5. 用了核显转码的话，intel_gpu_top 在转码时 Video 引擎有占用。

备份与维护

数据	位置	怎么备份
配置、数据库、元数据	appdata/jellyfin/config	见下
片库	media 共享文件夹	用 rsync 任务等文件备份，插件的计划备份不会备份 :ro 的卷

• 配置目录默认不会被插件备份。 它通常超过 最大尺寸（默认 1 GB），会被悄悄跳过。在卷行尾写 # BACKUP，或者把最大尺寸调大。插件备份会先停容器，期间不能播放，放在夜里。
• Jellyfin 自带备份：10.11 起，管理控制台的 备份（Backups）页可以在运行中创建备份，数据库必选，元数据、字幕、Trickplay 可选。LinuxServer 镜像里它放在 <配置卷>/config/data/data/backups，所以别忘了把这个目录也带上。
• 更新要谨慎。 Jellyfin 官方说明它没有降级机制：新版本一启动就会迁移数据，退回旧版本的唯一办法是恢复备份。更新前先备份，并看发布说明，见更新与备份容器。
• 官方镜像提供 10、10.11 这样的大版本和小版本标签，LinuxServer 镜像用 latest。别让 latest 无人值守地自动更新。

常见问题

媒体库里扫不到文件。 路径要填容器里的 /media/...，不是 NAS 上的 /srv/...。再检查 appuser 对那个目录有没有读权限，ls -ln 看属主和权限。

容器起不来，日志里有 /dev/dri 相关的错误。 宿主机没有这个设备，删掉 compose 里的 devices 两行。

转码不工作，CPU 占用很高。 检查设备权限、Jellyfin 里选的加速方式，以及视频的编码本身是否被你的显卡支持。H.264 10-bit 这类格式，Intel、NVIDIA 和 AMD 的显卡都不支持硬解，会退回软件解码。

电视上的 DLNA 或自动发现找不到服务器。 见上面「端口」一条，手动填地址。

8096 端口被占用。 改映射左边的数字，排查见端口冲突。

参考资料

• Jellyfin 文档：容器安装
• Jellyfin 文档：硬件加速（Intel）
• Jellyfin 文档：备份与恢复
• LinuxServer.io：Jellyfin 镜像说明
• omv-extras wiki：Docker in OMV 8（用 Jellyfin 逐步演示）
• Jellyfin issue #14373：只对元数据使用代理（已按不计划处理关闭）
• 微软文档：HttpClient.DefaultProxy（.NET 读取的代理环境变量）