nexus/wiki/concepts/设备直通.md

title, type, tags, date

title	type	tags	date
设备直通	concept	docker hardware device passthrough jellyfin	2026-04-14

设备直通

在容器化环境中将宿主机物理设备（GPU、声卡、硬件编码器等）映射到容器内，使容器内应用可直接访问和使用该硬件。

Core Mechanism

Docker 容器默认运行在隔离的命名空间中，容器内无法直接访问宿主机的硬件设备。设备直通通过 --device 参数或 devices 配置项，将宿主机设备节点映射到容器内，使容器内进程可以像宿主机一样访问硬件。

Docker 配置方式

services:
  jellyfin:
    devices:
      - /dev/dri:/dev/dri              # Intel GPU / VA-API
      - /dev/nvidia0:/dev/nvidia0     # NVIDIA GPU (需 nvidia-container-toolkit)
      - /dev/snd:/dev/snd:rw          # 声卡设备

常见使用场景

场景	宿主机设备	容器用途
Intel QuickSync 转码	/dev/dri/renderD*	Jellyfin / FFmpeg 硬件视频转码
NVIDIA 加速	/dev/nvidia*	CUDA 计算、视频编码
声卡直通	/dev/snd/*	音频播放/录制
串口设备	/dev/ttyUSB0	嵌入式设备调试
GPU 直通（VM）	PCI 设备	游戏 / AI 推理

Jellyfin 中的设备直通

devices:
  - /dev/dri:/dev/dri

• /dev/dri 是 Linux DRM（Direct Rendering Manager）设备目录
• 包含 renderD128/129 等节点，代表 GPU 渲染引擎
• Intel CPU 集成 GPU 通过此接口提供 QuickSync 视频编码
• VA-API 和 VDPAU 也依赖此接口

权限问题

• 默认情况下，容器以非 root 用户运行时可能无法访问 /dev/dri
• 解决方案：
  1. 将设备映射为可读（:ro）
  2. 在 docker run 时加上 --group-add video
  3. 群晖 NAS 使用 user: "1026:100" 映射到有权限的用户

Related Concepts

• 硬件转码 — 设备直通是硬件转码在 Docker 环境下的实现前提
• Docker 用户权限映射 — 解决容器用户访问宿主机设备权限问题
• nvidia-container-toolkit — NVIDIA GPU 在 Docker 中的特殊设备直通方案

Connections

• Jellyfin ← 受益应用 ← 设备直通 — QuickSync 硬件转码
• 群晖 NAS ← 宿主机 ← 设备直通 — NAS Intel CPU GPU 访问
• Intel QuickSync ← 依赖 ← 设备直通 — GPU 硬件加速通道

Sources

• 用docker安装jellyfin — /dev/dri 设备直通的 Docker Compose 配置示例