N100 独显级折腾：Jellyfin 在 SR-IOV 虚拟显卡下 H.265 10bit 转码 HDR 偏色的终极解决方案

在使用 Intel N100 处理器（Alder Lake-N）搭建 Home Lab 时，通过 SR-IOV 技术将核显虚拟化出多个 VF（Virtual Function）分给 Jellyfin、iStoreOS 或 PVE 虚拟机，是目前榨干这颗神卡性价比的标配玩法。

但很多人在配置完成后会遇到一个非常恶心的痛点：H.265 10bit 的 HDR 视频在触发转码（HDR to SDR）时，画面出现严重偏色（如发绿、发紫、色彩惨白或过暗），而关闭“色调映射（Tone Mapping）”后色彩虽然正常但画面灰蒙蒙的。

这个问题并非 N100 硬件性能不足，而是因为 SR-IOV 虚拟化环境下，OpenCL 运行库、宿主机 GuC/HuC 固件加载以及容器内驱动链条断裂 导致的。以下是彻底解决该问题的完整排查与实操指南。

为什么会偏色？深层原因分析

Jellyfin 的 HDR to SDR 色调映射有两条技术路径：

Intel VPP (Video Processing Pipeline)：基于 Intel Media SDK / oneVPL 硬件加速通道。
OpenCL 色调映射：通过编写好的着色器（Shader）在 GPU 算力单元上进行像素级色彩重映射。

在 SR-IOV 虚拟化环境下，偏色通常由以下三个致命原因导致：

原因一：宿主机未给虚拟显卡（VF）启用 GuC/HuC。 没有 GuC/HuC 固件的底层支持，Intel 的硬件色调映射（尤其是 VPP）和 OpenCL 加速会直接失效或产生渲染错误。
原因二：Jellyfin 容器内缺少 intel-compute-runtime（OpenCL 驱动）。 许多人在 Docker 中只挂载了 /dev/dri，但没有在容器内部署完整的 Intel OpenCL 运行时，导致 Jellyfin 无法调用 GPU 的执行单元来计算 HDR 色彩矩阵，退化为软解或错误的 VA-API 渲染。
原因三：驱动与运行时版本不匹配。 宿主机内核使用的 i915-sriov-dkms 与容器内 intel-media-driver / onevpl 存在 API 冲突。

核心解决步骤

第一步：确保宿主机（以 PVE 为例）正确加载 GuC/HuC

如果你的 N100 宿主机使用的是 strongtz/i915-sriov-dkms 驱动，必须确保在加载模块时，为虚拟出的 VF 开启了 GuC 和 HuC。

在宿主机中检查当前 i915 驱动的参数：
```
cat /sys/module/i915/parameters/enable_guc
```
必须输出 3 或 7。 如果输出 1 或 0，说明没有同时启用 GuC 和 HuC。
修改宿主机 /etc/modprobe.d/i915.conf（或者是 sriov.conf，取决于你的安装方式），确保包含以下参数：
```
options i915 enable_guc=3
options i915 max_vfs=7
```
注：enable_guc=3 表示同时启用 GuC 提交和 HuC 身份验证（有些内核版本可能需要设为 7，代表启用 GuC 提交、HuC 以及 SLPC）。
更新 initramfs 并重启宿主机：
```
update-initramfs -u -k all
reboot
```
重启后，在宿主机执行以下命令，确认 HuC/GuC 处于 RUNNING 状态：
```
journalctl -b | grep -i guc
journalctl -b | grep -i huc
```
如果看到 HuC initialized 和 GuC submission enabled，说明底层硬件通道已打通。

第二步：将正确的 VF 节点挂载给 Docker 容器

在 SR-IOV 启用后，宿主机的 /dev/dri/ 下会出现多个 renderD128、renderD129、renderD130 等节点。其中 renderD128 通常是主卡（PF），其余为虚拟卡（VF）。

在 Docker Compose 中，切忌直接挂载整个 /dev/dri 目录。你需要明确指定将哪一个 VF 给 Jellyfin，以防止驱动冲突。

version: "3"
services:
  jellyfin:
    image: jellyfin/jellyfin:latest  # 推荐使用官方镜像或 linuxserver 镜像
    container_name: jellyfin
    user: 1000:1000  # 确保此用户有访问宿主机 GPU 节点的权限（通常需要加入 render/video 组）
    devices:
      - /dev/dri/renderD129:/dev/dri/renderD129 # 将特定的 VF（如 D129）映射进去
      - /dev/dri/card1:/dev/dri/card1         # 对应的 card 节点也建议映射
    environment:
      - TZ=Asia/Shanghai
      - JELLYFIN_PublishedServerUrl=http://your-ip

如果你使用的是 LXC 容器，请在 LXC 的 .conf 配置文件中添加对应的 lxc.cgroup2.devices.allow 以及挂载 lxc.mount.entry。

第三步：为 Jellyfin 补齐 OpenCL 驱动（核心步骤）

很多用户使用的是官方的 jellyfin/jellyfin 镜像，虽然它自带了部分驱动，但在 SR-IOV 环境下，容器内的 Intel 运行时可能无法正确识别虚拟显卡。我们需要进入容器内部验证并修复。

进入 Jellyfin 容器：
```
docker exec -it jellyfin bash
```
运行 clinfo 查看 OpenCL 状态。如果提示命令不存在，先安装：
```
apt-get update && apt-get install -y clinfo
clinfo
```
- 非正常状态：Number of platforms 显式为 0，或者报错。
- 正常状态：能够输出 Intel(R) OpenCL Graphics，且能看到 Device Name 关联到 Intel(R) Graphics [0x46d0] (N100 的 Alder Lake 架构标识)。
如果 OpenCL 未正常工作，必须安装 Intel Compute Runtime。在容器内执行：
```
apt-get install -y intel-opencl-icd intel-media-va-driver-non-free
```
如果你使用的是 linuxserver/jellyfin 镜像，可以通过添加环境变量来自动安装 OpenCL 插件，无需手动进入容器：
- 环境变量中添加：DOCKER_MODS=linuxserver/mods:jellyfin-opencl-intel

第四步：Jellyfin 控制台正确配置（防踩坑配置）

进入 Jellyfin 后台，导航到 “控制台” -> “播放” -> “转码”，按照以下逻辑进行配置：

配置项	设置值	备注说明
硬件加速	Intel QuickSync (QSV)	千万不要选 VA-API。N100 只有在 QSV 模式下才能完美调用 oneVPL 进行 10bit 转码，且效率最高。
硬件解码选项	勾选 HEVC、HEVC 10bit、VP9、AV1	N100 物理支持这些格式的硬解。
启用硬件编码	勾选	必须启用。
启用 Intel 低延迟硬件编码	不勾选（建议）	在 SR-IOV 的虚拟通道中，开启此项有时会导致帧排队错误，产生绿屏。
启用 VPP 色调映射	不勾选（重点）	这是偏色的重灾区！很多 SR-IOV 驱动对 VPP 的色调映射指令支持有缺陷，勾选后极易导致画面发绿。
启用色调映射 (Tone Mapping)	勾选	这会强制 Jellyfin 调用 OpenCL 色调映射（刚才我们通过 `intel-opencl-icd` 激活的通道）。

*关键在于：启用“色调映射”，但关闭“VPP 色调映射”。这样系统会调用纯正的 OpenCL 着色器进行 HDR 映射，避开了物理驱动与虚拟驱动在 VPP 层面的兼容性漏洞，色彩还原度极高，且画面绝对不会偏色。*

验证与效果测试

配置完成后，找一部 4K HDR10 10bit (H.265/HEVC) 的电影进行播放，并在播放设置中强制限制码率以触发转码：

在容器宿主机运行 intel_gpu_top（如果宿主机是 PVE，需要安装 intel-gpu-tools）：
```
intel_gpu_top
```
观察你分配给 Jellyfin 的那个 renderDxx 节点的 Render/3D 和 Video/Enhancement（或 Video）利用率。
此时，Video 应该有 30%-60% 的负载，Render 应该有 15%-30% 的负载。
- 为什么 Render 会有负载？ 因为 OpenCL 色调映射正在利用 GPU 的执行单元（EU）进行色彩计算。
检查手机或浏览器的播放画面。此时，原本惨白、发绿或灰暗的 HDR 画面，应当被完美重映射为色彩饱满、过渡自然的 SDR 画面，偏色问题彻底解决。

总结：两句话避坑法则

宿主机端：SR-IOV 必须开启 enable_guc=3（或 7），否则容器内硬件 OpenCL 跑不起来。
Jellyfin 端：硬件加速选 QSV，开启 “色调映射”（走 OpenCL 通道），关闭 “VPP 色调映射”，偏色立解。