本页面由 PageTurner AI 翻译（测试版）。未经项目官方认可。 发现错误？ 报告问题 →
NVIDIA GPU硬件加速教程
本教程指导您如何通过NVENC在NVIDIA GPU上设置完整的视频硬件加速功能。
加速方法
自Maxwell架构起，NVIDIA GPU开始支持硬件加速转码。
在Windows和Linux系统中，NVENC是唯一可用的加速方法。
NVENC/NVDEC是NVIDIA GPU的专有视频编解码API，配合CUDA使用可实现完整的硬件加速。
已知问题和限制请参阅此章节。
NVENC在Windows和Linux上均支持无显示器运行(headless server)，这意味着无需连接物理显示器。
色调映射方法
支持HEVC 10-bit解码的所有NVIDIA GPU均可实现HDR/DV到SDR的硬件加速色调映射。
在Windows和Linux系统中，CUDA是唯一可用的色调映射方法。该方法同时支持杜比视界P5格式和零拷贝技术。
Enable enhanced NVDEC decoder功能可在新版NVDEC和旧版CUVID解码流程之间切换。启用杜比视界支持需勾选此选项以激活NVDEC。
选择GPU硬件
初学者请参考硬件选择指南获取选购建议，高级用户请继续阅读本节内容。
大多数NVIDIA GPU都支持NVENC/NVDEC，但部分低端和移动型号（如GT1030和MX450）属于例外情况。
购买适用于硬件加速的GPU前，可通过NVIDIA GPU编解码支持矩阵查询视频编解码支持情况。
转码H.264
AVC/H.264 8-bit因其出色的兼容性仍被广泛使用。所有支持NVENC/NVDEC的NVIDIA GPU均可对其进行解码/编码。
- H.264 8-bit解码与编码 - 任何支持NVENC/NVDEC的NVIDIA GPU
转码HEVC
HEVC/H.265 仍然是存储4K 10-bit、HDR和杜比视界视频的首选格式。得益于x265成熟的软件编码支持，以及2016年后发布的大多数GPU广泛实现的硬件编码支持。
Maxwell及以上架构GPU提供HEVC支持：
-
HEVC 8-bit解码与编码 - Maxwell第二代(GM206)及更新架构
-
HEVC 10-bit解码 - Maxwell第二代(GM206)及更新架构
-
HEVC 10-bit编码 - Pascal及更新架构
请注意，在Maxwell第二代系列中，仅GM206型号支持HEVC 10-bit解码。其继任者Pascal架构则完全支持HEVC 10-bit，并提升了速度与画质。
AV1转码支持
AV1是免版税的未来视频编解码器。其更小的文件尺寸能显著节省存储空间和网络带宽，但缺点是编解码对CPU要求极高。硬件加速使得实时转码AV1流成为可能。AV1编码功能在Jellyfin 10.9及以上版本提供支持。
NVIDIA已在其最新GPU中添加AV1加速支持：
-
解码 AV1 8/10-bit - Ampere 及更新架构
-
编码 AV1 8/10-bit - Ada Lovelace 及更新架构
其他编解码器支持
请参考以下资源：
速度与画质表现
编码质量：
-
H.264 & HEVC - Blackwell/Ada/Ampere/Turing > Turing TU117/Volta/Pascal > Maxwell
-
AV1 - 仅限 Ada Lovelace 和 Blackwell
同代架构的解码与编码速度：
-
多 NVENC/NVDEC 单元型号 > 单 NVENC/NVDEC 单元型号
-
高 GPU 时钟频率型号 > 低 GPU 时钟频率型号
-
高显存带宽型号 > 低显存带宽型号
NVENC/NVDEC 性能参考表：
Windows环境配置
推荐使用Windows 10 64位或更高版本。Jellyfin 10.10要求最低NVIDIA驱动版本为522.25。
Windows主机配置步骤
-
若从 Maxwell 前代 NVIDIA GPU 升级且未执行全新安装，请使用 DDU 彻底清除旧驱动。
-
从 NVIDIA 驱动下载页面 安装最新版驱动。
-
在 Jellyfin 中启用 NVENC 并取消勾选不支持的编解码器。
Windows 虚拟化配置
NVIDIA Windows 驱动支持在 WSL2 和 Docker 环境中访问 NVENC/NVDEC 及 CUDA。
请参考 Linux 物理机配置 和 Linux 虚拟化配置。
Windows 环境验证
-
在 Jellyfin Web 客户端播放视频，通过降低分辨率或码率触发视频转码。
-
打开"任务管理器"并切换到 GPU 页面。
-
按以下方式检查各引擎占用情况：
-
3D - 2D/3D引擎或CUDA/GPGPU工作负载
-
Copy - 位块传输/复制引擎工作负载
-
Video Decode - 视频解码器工作负载
-
Video Encode - 视频编码器工作负载
-
Cuda - CUDA/GPGPU工作负载
-
Linux 环境配置
需要 64 位 Linux 发行版。Jellyfin 10.10 最低要求 NVIDIA 驱动版本为 520.56.06。
Linux 主机配置指南
Debian/Ubuntu 系统
Jellyfin 所需的 jellyfin-ffmpeg* deb 包不包含任何 NVIDIA 专有驱动。
您需要从发行版安装 NVIDIA 驱动程序并配置 jellyfin 用户的权限。
需要 root 权限。
-
假设您已添加 Jellyfin 仓库至 apt 源列表，并安装了
jellyfin-server和jellyfin-web。 -
安装
jellyfin-ffmpeg7软件包。若存在冲突依赖可移除废弃的jellyfin元包：sudo apt update && sudo apt install -y jellyfin-ffmpeg7 -
通过以下链接安装NVIDIA专有驱动，然后安装两个额外软件包以支持NVENC和NVDEC：
-
Debian系统：https://wiki.debian.org/NvidiaGraphicsDrivers
sudo apt update && sudo apt install -y libnvcuvid1 libnvidia-encode1 -
Ubuntu系统：https://ubuntu.com/server/docs/nvidia-drivers-installation
备注可能需要将驱动版本作为软件包名称的后缀。
sudo apt update && sudo apt install -y libnvidia-decode libnvidia-encode
-
-
使用
nvidia-smi检查 NVIDIA GPU 状态：$ nvidia-smi
+-----------------------------------------------------------------------------+
| NVIDIA-SMI 520.56.06 Driver Version: 520.56.06 CUDA Version: 11.8 |
|-------------------------------+----------------------+----------------------+
| GPU Name Persistence-M| Bus-Id Disp.A | Volatile Uncorr. ECC |
| Fan Temp Perf Pwr:Usage/Cap| Memory-Usage | GPU-Util Compute M. |
| | | MIG M. |
|===============================+======================+======================|
| 0 NVIDIA GeForce ... Off | 00000000:1C:00.0 Off | N/A |
| 0% 44C P0 N/A / 75W | 0MiB / 1998MiB | 0% Default |
| | | N/A |
+-------------------------------+----------------------+----------------------+
... -
在 Jellyfin 中启用 NVENC 并取消勾选不支持的编解码器。
Linux Mint
Linux Mint 基于 Ubuntu 的软件包体系构建
您可以遵循 Debian 和 Ubuntu Linux 的配置步骤，但需从 Jellyfin 服务器发布页面手动安装所有软件包：jellyfin-server, jellyfin-web 和 jellyfin-ffmpeg7。同时请根据 官方版本映射表 选择正确的代号。
Arch Linux
需要 root 权限。
-
安装 Archlinux/extra 仓库的
jellyfin-ffmpeg包：sudo pacman -Syu jellyfin-ffmpeg -
通过以下链接安装NVIDIA专有驱动，然后安装额外软件包以支持NVENC和NVDEC：
sudo pacman -Syu nvidia-utils -
使用
nvidia-smi检查 NVIDIA GPU 状态：nvidia-smi -
在 Jellyfin 中启用 NVENC 并取消勾选不支持的编解码器。
其他发行版
对于缺乏常规维护的发行版，我们提供便携式 jellyfin-ffmpeg 二进制文件。
可通过以下链接下载：
glibc 和 Linux 内核最低要求：
- x86_64 / amd64 架构 - glibc >= 2.28, Linux 内核 >= 4.18 (2018 年及之后发布的主流发行版)
解压后安装到正确路径，并在 Jellyfin 控制台修改 FFmpeg 路径使其匹配：
需要 root 权限。
cd ~/
mkdir -p jellyfin-ffmpeg
wget https://repo.jellyfin.org/releases/ffmpeg/<VERSION>/jellyfin-ffmpeg_<VERSION>_portable_linux64-gpl.tar.xz
tar -xvf jellyfin-ffmpeg_<VERSION>_portable_linux64-gpl.tar.xz -C jellyfin-ffmpeg
sudo mv jellyfin-ffmpeg /usr/lib
sudo ldd -v /usr/lib/jellyfin-ffmpeg/ffmpeg
安装包含以下关键字的 NVIDIA 专有驱动包及其依赖项：
-
NVIDIA NVDEC CUVID - 解码
-
NVIDIA NVENC - 编码
Linux 虚拟化环境配置
官方 Docker 镜像
官方 Docker 镜像未包含任何 NVIDIA 专有驱动。
需在宿主机系统安装 NVIDIA 驱动和 NVIDIA Container Toolkit，使 Docker 能访问 GPU。
需要 root 权限。
-
在宿主机安装 NVIDIA 专有驱动（参考前文说明）
-
通过以下链接在宿主机上安装NVIDIA Container Toolkit：
-
使用Docker命令行或docker-compose：
-
命令行示例：
docker run -d \
--name=jellyfin \
--volume /path/to/config:/config \
--volume /path/to/cache:/cache \
--volume /path/to/media:/media \
--user 1000:1000 \
--net=host \
--restart=unless-stopped \
--runtime=nvidia \
--gpus all \
jellyfin/jellyfin -
docker-compose配置文件示例（YAML格式）：
services:
jellyfin:
image: jellyfin/jellyfin
user: 1000:1000
network_mode: 'host'
volumes:
- /path/to/config:/config
- /path/to/cache:/cache
- /path/to/media:/media
runtime: nvidia
deploy:
resources:
reservations:
devices:
- driver: nvidia
count: all
capabilities: [gpu]
备注若遇到上游问题
CUDA_ERROR_NO_DEVICE: no CUDA-capable device is detected，请将这些设备映射到Docker容器：/dev/nvidia-caps:/dev/nvidia-caps
/dev/nvidia0:/dev/nvidia0
/dev/nvidiactl:/dev/nvidiactl
/dev/nvidia-modeset:/dev/nvidia-modeset
/dev/nvidia-uvm:/dev/nvidia-uvm
/dev/nvidia-uvm-tools:/dev/nvidia-uvm-tools -
-
将用户名加入 video 用户组：
sudo usermod -aG video $USER -
更新动态链接并重启 Docker 服务：
docker exec -it jellyfin ldconfig
sudo systemctl restart docker -
使用
nvidia-smi检查 NVIDIA GPU 状态：docker exec -it jellyfin nvidia-smi -
如需尝试不稳定版本，请自行承担风险将
jellyfin/jellyfin替换为jellyfin/jellyfin:unstable。 -
在 Jellyfin 中启用 NVENC 并取消勾选不支持的编解码器。
请注意，官方 Jellyfin Docker 镜像已为 NVIDIA GPU 设置所需环境变量。若需自行构建镜像，请勿忘记在 Docker 配置中添加以下两个环境变量：
-
NVIDIA_DRIVER_CAPABILITIES=all -
NVIDIA_VISIBLE_DEVICES=all
Linuxserver.io Docker 方案
LSIO Docker 镜像由 linuxserver.io 维护，请参考其 GitHub 文档：linuxserver/docker-jellyfin。
官方 Docker 镜像与 LSIO Docker 镜像中 Jellyfin 配置文件和数据的存储路径不同，因此无法直接互换使用。
Podman
-
将CUDA软件仓库添加到包管理器。
浏览以下目录获取适用于您发行版的仓库文件：CUDA软件仓库
将对应的仓库文件安装至包管理器。具体操作方式取决于您的包管理器及操作系统版本。请将下方示例中的仓库URL替换为适配您发行版的正确地址。
a. Fedora/RHEL/CentOS系统：
sudo dnf config-manager addrepo --from-repofile=https://developer.download.nvidia.com/compute/cuda/repos/fedora42/$(uname -m)/cuda-fedora42.repob. Debian/Ubuntu系统：
echo "deb https://developer.download.nvidia.com/compute/cuda/repos/ubuntu2404/x86_64/cuda-ubuntu2404.pin stable main" | sudo tee /etc/apt/sources.list.d/cuda-ubuntu2404.listsudo apt-get update -
安装软件包
cuda-toolkit和nvidia-container-toolkit-basea. Fedora, RHEL, CentOS:
sudo dnf install cuda-toolkit nvidia-container-toolkit-baseb. Debian, Ubuntu:
sudo apt-get install -y cuda-toolkit nvidia-container-toolkit-base -
生成 CDI 规范文件
sudo nvidia-ctk cdi generate --output=/etc/cdi/nvidia.yaml -
调整您的podman命令行或systemd容器文件以使用设备：
nvidia.com/gpu=0例如，您的podman命令行应调整为如下格式：
podman run \
--detach \
--label "io.containers.autoupdate=registry" \
--name myjellyfin \
--publish 8096:8096/tcp \
--device nvidia.com/gpu=0 \
# --security-opt label=disable # Only needed for older versions of container-selinux < 2.226
--rm \
--user $(id -u):$(id -g) \
--userns keep-id \
--environment=JELLYFIN_DATA_DIR=/var/lib/jellyfin
--environment=JELLYFIN_CONFIG_DIR=/etc/jellyfin
--environment=JELLYFIN_LOG_DIR=/var/log/jellyfin
--environment=JELLYFIN_CACHE_DIR=/var/cache/jellyfin
--volume=/your/path/to/data:/var/lib/jellyfin # Replace paths with actual paths on your host's filesystem
--volume=/your/path/to/config:/etc/jellyfin
--volume=/your/path/to/logs:/var/log/jellyfin
--volume=/your/path/to/cache:/var/cache/jellyfin
--mount type=bind,source=/path/to/media,destination=/media,ro=true,relabel=private \
docker.io/jellyfin/jellyfin:latestSystemd配置文件示例：
[Unit]
Description=jellyfin
[Container]
Image=docker.io/jellyfin/jellyfin:latest
AutoUpdate=registry
PublishPort=8096:8096/tcp
UserNS=keep-id
#SecurityLabelDisable=true # Only needed for older versions of container-selinux < 2.226
AddDevice=nvidia.com/gpu=0
Environment=JELLYFIN_DATA_DIR=/var/lib/jellyfin
Environment=JELLYFIN_CONFIG_DIR=/etc/jellyfin
Environment=JELLYFIN_LOG_DIR=/var/log/jellyfin
Environment=JELLYFIN_CACHE_DIR=/var/cache/jellyfin
Volume=/your/path/to/data:/var/lib/jellyfin # Replace paths with actual paths on your host's filesystem
Volume=/your/path/to/config:/etc/jellyfin
Volume=/your/path/to/logs:/var/log/jellyfin
Volume=/your/path/to/cache:/var/cache/jellyfin
[Service]
# Inform systemd of additional exit status
SuccessExitStatus=0 143
[Install]
# Start by default on boot
WantedBy=default.target -
创建以下 udev 规则，确保在容器启动前初始化 GPU 设备
将以下内容保存为
/etc/udev/rules.d/nvidia.rules：ACTION=="add|bind", ATTR{vendor}=="0x10de", ATTR{class}=="0x03[0-9]*", \
DRIVER=="nvidia", TEST!="/dev/nvidia-uvm", \
RUN+="/usr/bin/nvidia-modprobe", \
RUN+="/usr/bin/nvidia-modprobe -c0 -u", \
RUN+="/usr/bin/nvidia-modprobe -m"
其他虚拟化方案
其他虚拟化方案未经验证，可能无法在 NVIDIA GPU 上运行
更多信息请参考 Intel GPU 硬件加速教程 - Linux 虚拟化配置。
Linux 系统验证方法
-
在 Jellyfin Web 客户端播放视频，通过降低分辨率或码率触发视频转码。
-
使用
nvidia-smi命令检查 NVIDIA GPU 的占用情况以及每个 jellyfin-ffmpeg 进程的显存使用情况：$ nvidia-smi
+-----------------------------------------------------------------------------+
| NVIDIA-SMI 520.56.06 Driver Version: 520.56.06 CUDA Version: 11.8 |
|-------------------------------+----------------------+----------------------+
| GPU Name Persistence-M| Bus-Id Disp.A | Volatile Uncorr. ECC |
| Fan Temp Perf Pwr:Usage/Cap| Memory-Usage | GPU-Util Compute M. |
| | | MIG M. |
|===============================+======================+======================|
| 0 NVIDIA GeForce ... Off | 00000000:1C:00.0 Off | N/A |
| 43% 44C P2 36W / 75W | 274MiB / 1998MiB | 68% Default |
| | | N/A |
+-------------------------------+----------------------+----------------------+
+-----------------------------------------------------------------------------+
| Processes: |
| GPU GI CI PID Type Process name GPU Memory |
| ID ID Usage |
|=============================================================================|
| 0 N/A N/A 4024 G /usr/lib/xorg/Xorg 63MiB |
| 0 N/A N/A 5837 C /usr/lib/jellyfin-ffmpeg/ffmpeg 195MiB |
+-----------------------------------------------------------------------------+