Changelog:

  • 2025-11-04: 更新 mknod 方案。精简行文。

0x01 参考资料

  1. Enabling GPU passthrough post launch? --discuss.linuxcontainers.org
  2. NVIDIA CUDA Installation Guide for Linux --docs.nvidia.com
  3. Installing the NVIDIA Container Toolkit --docs.nvidia.com

0x02 驱动安装

示例环境：

  • Debian GNU/Linux 12 (6.1.0-26-amd64)
  • Incus 6.0.2 (APT Suite: bookworm-backports)
  • GPU: Tesla P4

我们需要在宿主机安装显卡驱动与 CUDA 工具包。参考资料 2, 3 自行安装即可。

下载页面的驱动安装有两个选项，分别是新的开源内核模块 nvidia-open 和旧的闭源模块 cuda-drivers，按显卡支持情况安装其中之一。由于 Tesla P4 属于较老的 Pascal 架构，新模块并不支持，因此这里选择后者。

最终我们会安装以下软件包：

  • cuda-toolkit
  • cuda-drivers
  • nvidia-container-toolkit

安装程序会帮助我们禁用默认的 nouveau 驱动。安装完成后，可能需要重启才能够驱动显卡。之后，通过 nvidia-smi 查看显卡驱动状态。

最后可以参考资料 2 中的推荐操作部分，尝试编译运行一些调用 CUDA 的实例，确保 CUDA 能够正常运行。

0x03 容器部署

首先，我们需要获取显卡的 PCI 插槽。以 P4 为例:

1
incus info --resources | grep -in -C5 -- 'p4'

查询得到的插槽标识是 0000:04:00.0，这个写法是 Incus 要求的标准格式，不接受其他写法。

接着，创建一个容器。

1
2
incus create images:debian/12 jelly -c nvidia.runtime=true -c nvidia.driver.capabilities=all
incus config device add jelly tesla-p4 gpu pci="0000:04:00.0"

关于 nvidia.driver.capabilities 配置项：

  • 对应 NVIDIA_DRIVER_CAPABILITIES 变量 (详见 Driver Capabilities)，Incus 会将这个值透传给 nvidia-container-toolkit，用来配置容器
  • Incus 的默认配置是 utility,compute，这也是 nvidia-container-toolkit 的默认配置
  • 如果需要进行视频处理，需要加上 video。直接配置为 all 也是可以的

启动该容器，应当可以在容器内执行 nvidia-smi 并获取显卡驱动状态。

1
2
# loop per second
nvidia-smi -lms 1000

以 FFmpeg 为例，验证显卡可用性。

1
2
3
ffmpeg -init_hw_device cuda=cu:0 -filter_hw_device cu \
    -hwaccel cuda -hwaccel_output_format cuda \
    -i "sample.mp4" -c:v hevc_nvenc -f mp4 "out.mp4"

0x04 其他

偶尔地，FFmpeg 会失败：

1
Error parsing global options: Generic error in an external library

同时可以观察到容器内缺失 /dev/nvidia-uvm。

参考此文章进行 mknod，然后重启实例即可。