关键三步：宿主机驱动就绪→容器运行时授权→compose精准声明；缺一不可，否则仅见虚拟设备或报错。
要在 Docker Compose 中让容器真正用上物理硬件加速（比如 GPU、Intel/AMD 视频编解码器、USB 设备等），关键不是“加个参数就行”，而是分三步走：宿主机驱动就绪 → 容器运行时授权 → Compose 文件精准声明。跳过任一环节，容器都只能看到虚拟设备或直接报错。
确认宿主机硬件与驱动已就绪
容器无法凭空调用硬件，必须先确保宿主机能识别并正常使用该设备：
-
GPU（NVIDIA）：运行
nvidia-smi能显示显卡型号和驱动版本（≥525.x），且已安装nvidia-container-toolkit并完成 Docker 集成（docker run --rm --gpus all nvidia/cuda:12.4.0-base-ubuntu22.04 nvidia-smi应成功） -
Intel/AMD 视频加速（VAAPI/QSV）：执行
sudo ls /dev/dri/render*有输出，且用户在video组中（sudo usermod -aG video $USER） -
USB 设备（如加密狗、摄像头）：运行
lsusb可见目标设备，注意其 Bus/Device ID（如001:003）
GPU 加速：用标准 Compose v3.8+ 语法声明设备
不再依赖老旧的 runtime: nvidia（已弃用），改用规范的 deploy.resources.reservations.devices：
- 指定驱动类型为
nvidia，能力必须含[gpu] -
count: 1表示预留任意 1 块 GPU；device_ids: ["0", "1"]表示只用编号为 0 和 1 的卡（二者互斥） - 镜像需内置 CUDA 或 cuDNN（如
nvidia/cuda:12.4.0-base-ubuntu22.04或tensorflow/tensorflow:2.16.0-gpu）
示例配置：
services:
train:
image: pytorch/pytorch:2.3.0-cuda12.1-cudnn8-runtime
command: python -c "import torch; print(torch.cuda.device_count())"
deploy:
resources:
reservations:
devices:
- driver: nvidia
count: 1
capabilities: [gpu]
视频硬解/硬编：挂载 DRM 设备节点
适用于 Jellyfin、FFmpeg、GStreamer 等需要 VAAPI/QSV 的场景，不涉及 NVIDIA 驱动，只需设备透传：
- 在
volumes中挂载/dev/dri:/dev/dri（宿主机路径在前） - 确保容器内用户有权限读写
/dev/dri/renderD128（通常通过user:或组映射解决） - 镜像需预装
intel-media-va-driver（Intel）或mesa-va-drivers（AMD）
Jellyfin 典型片段：
services:
jellyfin:
image: jellyfin/jellyfin:10.9.10
volumes:
- /path/to/config:/config
- /dev/dri:/dev/dri
devices:
- /dev/dri:/dev/dri
environment:
- JELLYFIN_PREFERRED_HW_ACCEL=vaapi
USB 设备直通：按路径或厂商 ID 绑定
避免用 privileged: true（过度开放），推荐精确绑定：
- 用
devices:直接挂载设备文件（如- "/dev/video0:/dev/video0"） - 或通过 udev 规则固定设备路径（如
/dev/usb-dongle），再在 Compose 中引用 - 若需热插拔，配合
restart: on-failure+ 容器内轮询检测
例如接入 RealSense 摄像头：
services:
realsense:
image: intelrealsense/librealsense:latest
devices:
- /dev/video0:/dev/video0
- /dev/bus/usb:/dev/bus/usb
privileged: false
不复杂但容易忽略：所有硬件访问都依赖宿主机环境是否干净——驱动版本匹配、用户组权限正确、SELinux/AppArmor 未拦截。配完别急着跑服务，先用 docker-compose run --rm [service] ls /dev 确认设备节点是否存在，再验证功能。
