SSD Nodes Learn Hosting plans →
指南 Matt Connor作者: Matt Connor

Docker Jellyfin 开启 NVIDIA 硬件转码配置指南

在 Docker 中为 Jellyfin 配置 NVIDIA GPU 硬件转码的完整步骤。包含安装 NVIDIA Container Toolkit、Docker Compose 挂载配置以及验证 NVENC 与 NVDEC 转码状态的方法,助您解决容器无法识别显卡的问题。

构建目标

在 NVIDIA GPU 上启用 Jellyfin 硬件转码需按固定顺序执行四个步骤,且仅最后一步在 Jellyfin 内部完成。如果宿主机驱动未加载,容器将无法识别 GPU;如果容器无法识别 GPU,Jellyfin 也无法使用它。请按此顺序操作,以便在出现故障时能快速定位问题。

  1. 在宿主机安装 NVIDIA 驱动,并使用 nvidia-smi 进行验证。
  2. 安装 NVIDIA Container Toolkit,以便 Docker 能将 GPU 分配给容器。
  3. 在 docker-compose.yml 中为 Jellyfin 服务预留 GPU,并确认容器已识别到该设备。
  4. 在 Jellyfin 的播放设置中开启 NVENC 和 NVDEC,并确认实际播放时已调用硬件加速。

NVENC(NVIDIA 编码器)和 NVDEC(NVIDIA 解码器)是显卡上的固定功能模块。它们与运行 CUDA(统一计算设备架构)任务的着色器核心在物理上是分离的。这种分离正是硬件转码的价值所在:原本需要消耗多个 CPU 核心的软件转码任务,现在只需占用极少量的 CPU 资源,并由 GPU 上的专用硬件模块完成。

直接播放优先于任何转码,因此应先检查这一点

在配置这些内容之前,先确认是否有可以直接消除的转码原因。Jellyfin 会在客户端无法直接播放文件时进行转码。原因通常只有几类:视频编码器、音频编码器、容器格式、基于图像的字幕、客户端请求的比特率限制,或客户端报告的分辨率及其他限制。

打开 Dashboard,然后进入 Playback,并在播放内容时监控活动会话。标记为 Direct playing 的会话会原样发送文件,几乎不占用 CPU。标记为 Transcoding 的会话会显示 Jellyfin 选择转码的原因。消除该原因后,GPU 完全不需要运行。

两项调整可以消除大多数转码。将客户端应用的质量设置为 Auto 或最大值,因为客户端请求 4 Mbps 时,无论文件使用哪种编码器,都会强制将 20 Mbps 的文件重新编码。然后使用原生客户端应用,不要使用浏览器标签页,因为浏览器是你拥有的限制最多的播放器,而同一台电视上的原生应用通常可以直接播放相同文件。

只有在客户端无法直接渲染基于图像的字幕时,才需要将其烧录到视频中。Blu-ray 转录中的 PGS 字幕和 DVD 转录中的 VOBSUB 都是图像,但兼容的客户端无需重新编码视频即可显示它们;Jellyfin 的 Android 集成播放器直接支持 PGS。客户端支持 SRT 时,文本字幕会单独发送。当字幕兼容性迫使系统烧录字幕时,将字幕轨道转换为文本会很有用。服务器端的其余内容见 在 VPS 上运行 Jellyfin 媒体服务器的指南。

大多数 VPS 套餐不提供 GPU

标准 VPS 套餐不包含 GPU。在进行任何规划前,请先在服务器上运行此命令。

lspci -nn | grep -Ei "3d|display|vga"

在典型的 KVM VPS 上,该命令只会显示来自宿主机的虚拟显示适配器,或者没有任何有效输出。该设备无法进行视频编码。只有当服务商将物理显卡透传给你的实例,或者为你分配了显卡切片时,才会出现真实的 GPU,而此类套餐的价格也相应更高。哪些工作负载值得购买 GPU VPS 一文详细说明了哪些用户需要或不需要 GPU。

如果没有 GPU,请优先选择直接播放,并将软件转码视为极少数情况。单路 1080p H.264 软件转码虽然负载较重,但在几个 CPU 核心上尚可运行。4K HDR 软件转码配合色调映射(tone mapping)无法在小型 VPS 上实时完成,这会导致 CPU 占用率达到 100%,进而引发视频流卡顿。

在主机上安装 NVIDIA 驱动

Jellyfin 10.11 在 Linux 上要求的 NVIDIA 驱动最低版本为 520.56.06。已安装的 jellyfin-ffmpeg 版本可能需要更新的驱动;当驱动的 NVENC API 版本过低时,转码日志会报告所需的最低版本。Ubuntu 提供了一个辅助工具,可以为您选择匹配的软件包。

sudo ubuntu-drivers list --gpgpu
sudo ubuntu-drivers install --gpgpu
sudo reboot

--gpgpu 会选择无头服务器版本的驱动。媒体服务器通常应使用此版本,因为服务器没有桌面环境。list 命令会显示可用的驱动分支,您可以按名称固定一个分支,例如 sudo ubuntu-drivers install --gpgpu nvidia:570-server。请使用 list 实际显示的分支,不要直接使用此处写出的分支。

服务器版本不一定会自动安装 nvidia-smi。请为所选分支安装匹配的 utils 软件包,例如 sudo apt install nvidia-utils-570-server。然后检查驱动。

nvidia-smi

正常结果会在表头显示驱动版本和 CUDA 版本,并按名称列出您的显卡。进程列表会报告使用 Compute、Graphics 或 Other GPU 资源的进程。健康的 GPU 上也可能显示进程;列表为空表示当前没有报告 GPU 进程。这里常见有两种故障。nvidia-smi: command not found 表示缺少 utils 软件包,而不是缺少驱动。NVIDIA-SMI has failed because it couldn't communicate with the NVIDIA driver 表示内核模块未加载。在刚安装完系统的情况下,这几乎总是因为尚未重启,或者 Secure Boot 拒绝加载未签名模块。使用 lsmod | grep nvidia 确认模块是否存在。如果该命令没有输出,并且 sudo modprobe nvidia 因 Key was rejected by service 失败,则表示 Secure Boot 阻止了模块加载。清除 Secure Boot 密钥拒绝状态介绍了如何检查固件状态,然后注册机器所有者密钥或关闭强制验证。

安装 NVIDIA Container Toolkit

驱动程序允许主机使用 GPU。但 Docker 仍不会将 GPU 传递到容器中,因为容器既没有设备节点,也没有驱动程序库。NVIDIA Container Toolkit 会在容器启动时注入这两者。以下命令遵循 NVIDIA 针对 Debian 和 Ubuntu 提供的安装步骤。NVIDIA 当前的指南还会通过版本变量,将 Toolkit 软件包固定到同一个版本;本示例未设置版本固定,因此会安装软件仓库中的最新版本。

curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey | sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg
curl -s -L https://nvidia.github.io/libnvidia-container/stable/deb/nvidia-container-toolkit.list | sed 's#deb https://#deb [signed-by=/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://#g' | sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list
sudo apt-get update
sudo apt-get install -y nvidia-container-toolkit

仅安装软件包还不够,因为还必须告知 Docker 存在该运行时。

sudo nvidia-ctk runtime configure --runtime=docker
sudo systemctl restart docker

nvidia-ctk runtime configure 会在 /etc/docker/daemon.json 中写入一个 nvidia 运行时条目。重启是最容易被跳过的步骤,而跳过它会导致整个配置过程中最常见的错误。在操作 Jellyfin 之前,先测试这套连接是否正常。

sudo docker run --rm --runtime=nvidia --gpus all ubuntu nvidia-smi

该命令应输出与主机上相同的表格。如果命令失败,并提示无法选择具有 gpu 功能的设备驱动程序,说明 Docker daemon 不知道 nvidia 运行时。请再次运行配置命令,然后重启 daemon。

在 Docker Compose 中为 Jellyfin 容器分配 GPU

这是现代 Compose 写法。它基于 Jellyfin 发布的示例,并明确写出两个 NVIDIA 环境变量。

services:
  jellyfin:
    image: jellyfin/jellyfin
    container_name: jellyfin
    user: 1000:1000
    network_mode: host
    restart: unless-stopped
    environment:
      - NVIDIA_VISIBLE_DEVICES=all
      - NVIDIA_DRIVER_CAPABILITIES=all
    volumes:
      - /srv/jellyfin/config:/config
      - /srv/jellyfin/cache:/cache
      - /srv/media:/media:ro
    runtime: nvidia
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all
              capabilities: [gpu]

启动容器,然后直接从容器内部检查。

docker compose up -d
docker compose exec jellyfin nvidia-smi

如果该命令在容器内输出驱动程序表,说明容器可以访问 GPU,管理库也能正常工作;但仍需检查视频库和实际转码功能。

该文件中的 4 行需要说明。capabilities: [gpu] 是 Compose 本身要求的配置项。省略它后,Compose 会拒绝该服务,而不是在不分配 GPU 的情况下启动服务。NVIDIA_DRIVER_CAPABILITIES=all 也很重要,因为只有请求 video capability 时,工具包才会将视频库挂载到容器中;如果未设置该变量,默认值只有 utility 和 compute。官方 Jellyfin 镜像已经设置了该变量,因此对该镜像而言,这一行可防止其他配置将其覆盖;Jellyfin 文档说明,如果自行构建镜像,则必须手动添加这一行。没有 video capability 时,CUDA 可以工作,但 NVDEC 无法工作,转码日志会报告 Cannot load libnvcuvid.so.1。network_mode: host 是 Jellyfin 自带 NVIDIA 示例使用的配置。Jellyfin 的容器指南将 host networking 列为可选项,但 DLNA 必须使用它。如果改用 bridge 网络,则需要自行发布 8096/tcp 和 7359/udp 自动发现端口。

user: 1000:1000 是最后一项,与 GPU 无关。它决定 Jellyfin 可以读取媒体挂载中的哪些文件。配置不匹配时,通常会显示为空媒体库,而不是权限错误。PUID 和 PGID 如何将容器用户映射到磁盘上的文件解释了编号方式;如果您在旁边通过 Docker Compose 运行 Sonarr 和 Radarr 堆栈,这里使用的编号与您已经设置的编号相同。

为什么大多数教程仍然写 runtime: nvidia

您会在几乎所有教程中看到较旧的写法。这种写法并没有错误,只是历史遗留形式。最初的 nvidia-docker2 软件包注册了名为 nvidia 的 OCI runtime,环境变量方式通过该 runtime 使用 NVIDIA_VISIBLE_DEVICES;您可以通过 --runtime=nvidia 选择它,也可以将其设为 Docker 的默认 runtime。Docker 19.03 增加了 --gpus 标志和规范的设备请求 API。Compose 的支持晚了更久;支持该 API 后,设备请求被放在 deploy.resources.reservations.devices 下。许多人此前一直忽略这个键,因为 deploy 过去表示 Docker Swarm。

因此,这两种写法目前都可用,而 Jellyfin 发布的示例同时保留了两种写法。保留 runtime: nvidia 不会增加任何成本,还能让配置文件兼容较旧的 Compose 版本。如果您只保留 runtime: nvidia 并删除 deploy 块,就必须保留 NVIDIA_VISIBLE_DEVICES=all,因为旧路径会读取环境变量,以决定要注入哪些设备;它没有设备请求可供读取。

在 Jellyfin 中启用 NVIDIA 硬件转码

到目前为止,还没有设置 Jellyfin 使用该显卡。依次进入 Dashboard、Playback 和 Transcoding。将 Hardware acceleration 设置为 Nvidia NVENC。勾选 Enable hardware encoding,否则 Jellyfin 会在 GPU 上解码,再由 CPU 编码,形成一种容易混淆的中间状态:GPU 显示有活动,但 CPU 仍持续高负载。

启用 enhanced NVDEC decoder 会在当前 NVDEC 路径和较旧的 CUVID 路径之间切换。保持启用。Dolby Vision 处理需要启用此选项,才能使用 NVDEC。

在 Enable hardware decoding for 下,仅勾选显卡实际支持解码的编码格式。很多人会错误配置此设置。在不支持 AV1 解码的显卡上勾选 AV1,可能会请求硬件解码并因 Hardware is lacking required capabilities 失败。不受支持的选择不保证会回退到软件解码。

整个页面还适用另一项限制:硬件加速只有在随附的 jellyfin-ffmpeg 构建中才获得完整支持。Jellyfin 文档警告,从其他来源获取的 FFmpeg 二进制文件会导致加速不完整。因此,如果您将 FFmpeg 路径指向了系统 FFmpeg,请将其改回。

您的 GPU 代际支持解码和编码的编解码器

以下是 Jellyfin 对 NVENC 和 NVDEC 所记录的能力边界。解码和编码是两项独立能力,显卡可能只支持其中一项。

  • H.264 8-bit:所有同时支持 NVENC 和 NVDEC 的 NVIDIA GPU 都支持解码和编码。
  • HEVC 8-bit:从第二代 Maxwell(GM206)及更新架构开始支持解码和编码。
  • HEVC 10-bit:从第二代 Maxwell 及更新架构开始支持解码,但该代只有 GM206 变体支持此功能;编码则仅从 Pascal 及更新架构开始支持。
  • AV1:从 Ampere 及更新架构开始支持解码,但 GA100 数据中心芯片除外(NVIDIA 的解码器表还列出 Hopper 不支持 AV1 解码);从 Ada Lovelace 及更新架构开始支持编码,Jellyfin 从 10.9 开始支持此功能。

HEVC 10-bit 的差异在实际使用中最容易造成问题。基于 GM206 的 Maxwell 显卡可以使用 GPU 解码 4K HDR 文件,但无法编码 10-bit 输出;不过,它支持 H.264 8-bit 和 HEVC 8-bit 编码。其他 Maxwell 芯片完全不支持硬件 HEVC 10-bit 解码。Jellyfin 根据客户端能力和编码设置选择输出编解码器;其 HEVC 转码路径会强制使用 8-bit Main 配置文件。仅在客户端支持 AV1 时选择 AV1 输出。

色调映射为何会悄然再次占满 GPU

HDR(高动态范围)到 SDR(标准动态范围)的色调映射会消耗原本分配给 GPU 的余量,原因在于其架构。解码由 NVDEC 执行。编码由 NVENC 执行。色调映射由二者之外的 CUDA filter 执行,运行在 shader core 上;shader core 是 GPU 中负责通用计算的部分。因此,需要色调映射的 4K HDR 流会同时使用解码器和编码器,还会额外占用 shader。

Jellyfin 文档说明,任何能够解码 HEVC 10-bit 的 NVIDIA GPU 都支持 CUDA 色调映射。这意味着在无法稳定处理 4K 色调映射的显卡上,该选项也会显示并正常工作。其表现是流开始播放后不断缓冲,始终无法稳定下来,而 nvidia-smi 显示编码器几乎没有负载。

因此,应单独监控 shader 负载。

nvidia-smi dmon -s u

该命令每秒输出一行,并分别显示 sm、enc 和 dec 列。enc 和 dec 较低、sm 数值较高,说明负载主要位于 shader,而不是固定功能模块,因此色调映射、缩放或字幕烧录可能是主要开销。请将此结果视为线索,而不是结论:NVIDIA 将 GPU 利用率定义为采样期间至少有一个 kernel 正在执行的时间占比,因此较高的数值只能说明 shader 繁忙,不能说明其已达到饱和。CUDA 路径还会以 zero copy 方式处理 Dolby Vision profile 5,这一点很重要,因为没有 zero copy 时,帧会在各个 filter 步骤之间传出到系统内存,再传回 GPU;每一帧都会产生这次往返,并消耗带宽。

消费者 NVENC 会话上限实际限制的内容

图表NVENC engines and concurrent encode session cap, NVIDIA published support matrix, October 2026
此图表背后的数据
[
  {
    "label": "GeForce RTX 5090",
    "nvenc_engines": 3,
    "max_encode_sessions": 12
  },
  {
    "label": "GeForce RTX 4090",
    "nvenc_engines": 2,
    "max_encode_sessions": 12
  },
  {
    "label": "GeForce RTX 4060",
    "nvenc_engines": 1,
    "max_encode_sessions": 12
  }
]

这些是 NVIDIA 截至 October 2026 发布的矩阵数据,不是本文环境中的实测结果。NVIDIA 的策略会将一台系统中所有 GeForce 显卡的并发编码会话合计限制为 12,与具体型号无关。该上限由驱动而非芯片实施,而且 NVIDIA 多年来已多次提高上限,因此应查看当前矩阵,不要依据旧论坛帖子。真正随显卡变化的是引擎数量:GeForce RTX 5090 配备 3 个 NVENC 引擎,而 GeForce RTX 4060 配备 1 个。引擎越多,并行编码吞吐量越高,但会话上限不会提高。

该上限计算所有编码会话,包括 Jellyfin 之外的视频编码。Direct play 和 remuxing 不会创建编码会话。L4 等数据中心显卡在同一矩阵中标记为不受限制,但 A100 和 H100 等型号没有 NVENC 编码器,因此在 GPU VPS 方案中应确认具体显卡型号。

达到上限时,转码会失败,FFmpeg 日志中会出现 OpenEncodeSessionEx failed: out of memory (10)。该消息提到内存,但会话数限制拒绝也会报告相同的代码,因此在排查 VRAM 泄漏前,应先检查并发流数量。实际上,大多数用户会先达到色调映射上限,或先受上传带宽限制,通常早于第 12 个会话。

证明 GPU 正在执行转码,不要仅凭配置判断

已保存的设置不能作为证据。播放一个确定会强制转码的文件,然后执行以下 3 项检查。

  1. 打开 Dashboard,然后打开 Playback。活动会话应显示 Transcoding,并说明转码原因。如果显示 Direct playing,表示没有执行转码,当前测试的文件不正确。
  2. 打开 Dashboard,然后打开 Logs,并打开最新的 FFmpeg.Transcode 日志。完整的硬件转码会在命令行中显示 -hwaccel cuda 和 -hwaccel_output_format cuda,并使用 h264_nvenc 或 hevc_nvenc 等 NVENC 编码器;在 Ada Lovelace 及更新架构上,也可能使用 AV1 NVENC 编码器。如果其中出现 libx264,表示编码正在软件中执行,无论设置页面显示什么。使用 NVENC 编码器但缺少 -hwaccel cuda,表示解码部分正在软件中执行。
  3. 在播放继续进行时,在主机上运行 nvidia-smi。此时应看到来自 /usr/lib/jellyfin-ffmpeg/ffmpeg 的进程,并且已分配 GPU 内存;nvidia-smi dmon -s u 的 enc 和 dec 列应显示非零值。

第 3 项检查必须在主机上执行,不能在容器内执行。容器内的 nvidia-smi 通常会显示空的进程列表,因为它无法查看自身命名空间之外的进程 ID,但利用率数值仍会正确显示。容器内的进程列表为空不表示存在故障。

软件回退时不会通知您

当硬件编码被禁用,或请求的硬件编码器不可用时,Jellyfin 会选择软件编码器。播放期间硬件路径发生故障时,流仍可能失败,因此应读取 FFmpeg 日志,不要假定所有故障都会回退到软件编码。

转码日志中的 Cannot load libnvcuvid.so.1 表示动态加载器未能加载解码器库。仅凭此消息无法确定该库是否已挂载。检查 NVIDIA_DRIVER_CAPABILITIES=all,以及容器中的驱动库和动态链接。如果修改了环境,请使用 docker compose up -d 重新创建容器;直接重启会保留旧设置。

No capable devices found from h264_nvenc 表示 FFmpeg 已到达编码器库,但未找到可用的显卡。再次检查 docker compose exec jellyfin nvidia-smi,然后读取前面的日志消息,查找设备和编码器能力检查失败的原因。

CPU 使用率高而 GPU 几乎空闲时,应检查哪些阶段使用了软件处理。取消选择您的设备无法解码的编码格式,然后重新播放同一文件,再次读取 FFmpeg 日志,确认是否出现 -hwaccel cuda。如果出现且 CPU 仍然繁忙,请查找 Jellyfin 无法交给 GPU 处理的阶段,例如图像字幕烧录。

转码在 4K HDR 播放时启动后停滞,而 1080p 正常时,通常是色调映射达到性能上限,而不是安装损坏。查看 nvidia-smi dmon -s u 中的 sm 列,然后关闭色调映射并重新播放同一文件:如果流恢复稳定,说明瓶颈在色调映射。此时可以降低客户端请求的分辨率,或仅在支持直接播放 4K HDR 文件的客户端上播放这些文件。

FAQ

启用 NVENC 后,Jellyfin 为什么仍然占用 CPU?

在 Dashboard 中打开 Logs,检查最新的 FFmpeg.Transcode 日志。如果其中显示 libx264,说明编码正在软件中运行。如果同时缺少 -hwaccel cuda,请检查命令中选择的解码器,并运行 docker compose exec jellyfin nvidia-smi 以确认 GPU 可见性。如果 -hwaccel cuda 与 libx264 一同出现,说明命令请求使用 GPU 解码,但使用软件编码;请检查是否启用了硬件编码,以及 Jellyfin 是否检测到所请求的硬件编码器。仅凭这些标志不能证明 GPU 解码已成功。如果显示 h264_nvenc 但没有 -hwaccel cuda,请检查该文件的编解码器是否在“启用硬件解码的编解码器”中勾选。勾选显卡无法解码的编解码器,可能会产生硬件解码器错误,而不是回退到软件解码。如果两者都存在但 CPU 仍然繁忙,负载可能来自必须由 CPU 处理的阶段,例如字幕烧录。

Docker Compose 中是否仍需要 runtime: nvidia 行?

如果已有 deploy.resources.reservations.devices 块并使用当前版本的 Docker Compose,则不需要。该块是现代的设备请求格式,作用相同。runtime: nvidia 是 nvidia-docker2 时代遗留的旧路径,目前仍然有效,而且 Jellyfin 自己发布的示例同时保留了两者。两者同时保留没有影响。仅保留 runtime: nvidia 时,还必须保留 NVIDIA_VISIBLE_DEVICES=all,因为该路径没有可读取的设备请求,会从环境中获取设备列表。

一块 NVIDIA GPU 可同时转码多少个流?

截至 October 2026,NVIDIA 发布的策略将 GeForce 显卡限制为每个系统合计十二个并发编码会话;L4 等数据中心显卡标记为不受限制,但部分数据中心型号没有 NVENC 编码器。这个上限很少是实际瓶颈。HDR 到 SDR 的色调映射运行在着色器核心上,而不是 NVENC 上,因此会增加一个独立的性能限制。使用 nvidia-smi dmon -s u 测量实际情况,并观察 sm 列,而不是会话数量。

没有 GPU 的 VPS 是否可以使用硬件转码?

不可以。编码需要物理 NVENC 模块,而标准 VPS 上的 lspci -nn | grep -Ei "3d|display|vga" 只会显示来自虚拟机监控程序的虚拟显示适配器。在没有 GPU 的套餐上,实际可行的方案是取消转码:将客户端的画质设置提高到 Auto,使用原生客户端应用而不是浏览器,并使用能够直接渲染基于图像的字幕的客户端;如果字幕兼容性要求烧录,则将字幕转换为文本。

1080p 可以正常转码时,4K HDR 为什么会卡顿?

这两种工作负载使用显卡的不同部分。1080p SDR 转码主要包括解码和编码;如果显卡支持相应编解码器,这两个步骤都会在固定功能硬件上运行,此外还包括流所需的缩放、去隔行或字幕烧录。4K HDR 流还会增加色调映射,这是运行在着色器核心上的 CUDA 滤镜,同时需要缩放更大的帧。如果 nvidia-smi dmon -s u 显示 enc 和 dec 较低,而 sm 较高,就说明问题可能出在这里,因为固定功能模块负载较轻,而着色器处于繁忙状态。关闭色调映射后重新播放该文件即可确认。

这篇文章对您有帮助吗?