Auto-sync: 2026-04-22 08:02

wiki/concepts/设备直通.md

@@ -0,0 +1,62 @@
+---
+title: "设备直通"
+type: concept
+tags: [docker, hardware, device, passthrough, jellyfin]
+date: 2026-04-14
+---
+
+# 设备直通
+
+在容器化环境中将宿主机物理设备（GPU、声卡、硬件编码器等）映射到容器内，使容器内应用可直接访问和使用该硬件。
+
+## Core Mechanism
+Docker 容器默认运行在隔离的命名空间中，容器内无法直接访问宿主机的硬件设备。设备直通通过 `--device` 参数或 `devices` 配置项，将宿主机设备节点映射到容器内，使容器内进程可以像宿主机一样访问硬件。
+
+## Docker 配置方式
+```yaml
+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 中的设备直通
+```yaml
+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 配置示例