📚 课程目录第4章 NVIDIA容器工具包

4、NVIDIA容器工具包：安装nvidia-docker2或NVIDIA Container Toolkit

4.1 核心原理：从“GPU直通”到“用户态转发”

在Docker早期版本中，要让容器访问GPU，通常需要以--privileged模式运行容器，并将宿主机上的/dev/nvidia*设备节点和libcuda.so等驱动库手动挂载进容器。这种方式不仅繁琐，而且存在严重的兼容性问题——容器内的CUDA运行时版本必须与宿主机驱动严格匹配，一旦驱动升级或更换镜像，容器就可能报出CUDA driver version is insufficient的错误。

NVIDIA Container Toolkit（旧称nvidia-docker2）改变了这一局面。它的核心思路是：在Docker运行时（runc）与OCI运行时之间插入一层“预启动钩子”。当用户通过--gpus参数请求GPU时，Docker会调用NVIDIA Container Runtime，该运行时在容器启动前自动完成以下三件事：

设备注入：将宿主机上必要的GPU设备节点（/dev/nvidia0、/dev/nvidiactl、/dev/nvidia-uvm等）动态挂载到容器内。
驱动库映射：将宿主机驱动目录（如/usr/lib/x86_64-linux-gnu/libcuda.so.1）映射进容器，并自动设置LD_LIBRARY_PATH。
能力校验：检查容器镜像中是否包含与宿主机驱动匹配的CUDA用户态库，避免运行时不兼容。

这一机制的本质是“用户态转发”：容器内并不需要安装完整的NVIDIA驱动，只需包含CUDA运行时库（libcudart、libcublas等），而内核态驱动与用户态驱动（libcuda）始终由宿主机提供。这样既保证了隔离性，又大幅提升了镜像的可移植性。

架构示意：下图展示了Docker、NVIDIA Container Runtime与宿主机驱动之间的协作关系。

4.2 安装方法流程：两条路径殊途同归

根据操作系统与Docker版本的不同，安装方式分为传统nvidia-docker2与新版NVIDIA Container Toolkit两条路径。前者适用于Docker 19.03之前的版本，后者是当前官方推荐的方式。以下以Ubuntu 20.04/22.04 + Docker CE为例说明。

路径一：安装nvidia-docker2（兼容旧版Docker）

# 1. 添加NVIDIA官方仓库
distribution=$(. /etc/os-release;echo $ID$VERSION_ID)
curl -s -L https://nvidia.github.io/nvidia-docker/gpgkey | sudo apt-key add -
curl -s -L https://nvidia.github.io/nvidia-docker/$distribution/nvidia-docker.list | \
  sudo tee /etc/apt/sources.list.d/nvidia-docker.list

# 2. 安装并重启Docker
sudo apt-get update
sudo apt-get install -y nvidia-docker2
sudo systemctl restart docker

# 3. 验证安装
sudo docker run --rm --gpus all nvidia/cuda:11.8-base nvidia-smi

路径二：安装NVIDIA Container Toolkit（新版推荐）

# 1. 配置GPG密钥与仓库
curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey | \
  sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg
curl -s -L https://nvidia.github.io/libnvidia-container/stable/deb/nvidia-container-toolkit.list | \
  sed 's#deb https://#deb [signed-by=/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://#g' | \
  sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list

# 2. 安装工具包
sudo apt-get update
sudo apt-get install -y nvidia-container-toolkit

# 3. 配置Docker运行时（关键步骤）
sudo nvidia-ctk runtime configure --runtime=docker
sudo systemctl restart docker

# 4. 验证
sudo docker run --rm --gpus all ubuntu:22.04 nvidia-smi

关键区别：新版工具包安装后必须执行nvidia-ctk runtime configure，该命令会自动修改/etc/docker/daemon.json，将nvidia-container-runtime注册为Docker的运行时之一。如果跳过此步骤，--gpus参数将无法生效。

4.3 验证与故障排查：从“能用”到“好用”

安装完成后，建议按以下清单逐项验证，确保GPU环境真正可用：

验证项	命令	预期结果
运行时注册	`docker info \| grep -i runtime`	输出包含 `nvidia` 运行时
GPU可见性	`docker run --rm --gpus all ubuntu nvidia-smi`	显示GPU型号、驱动版本、显存信息
CUDA版本匹配	`docker run --rm --gpus all nvidia/cuda:12.2.0-base nvcc --version`	CUDA版本与镜像标签一致
多卡分配	`docker run --rm --gpus '"device=0,1"' ubuntu nvidia-smi -L`	仅显示指定的GPU 0和1

如果验证失败，最常见的错误及对策如下：

错误：could not select device driver "" with capabilities: [[gpu]] —— 说明Docker守护进程没有加载NVIDIA运行时。检查/etc/docker/daemon.json是否包含"default-runtime": "nvidia"或--gpus参数是否拼写正确。
错误：nvidia-smi: command not found —— 镜像内没有安装NVIDIA工具。请使用nvidia/cuda官方基础镜像，或自行安装nvidia-driver。
错误：Failed to initialize NVML: Driver/library version mismatch —— 宿主机驱动与容器内CUDA库版本不兼容。升级宿主机驱动或更换匹配的CUDA镜像。

4.4 实战案例：为PyTorch容器启用GPU加速

假设你需要在容器中运行PyTorch训练脚本，宿主机已安装NVIDIA驱动535.104.05，CUDA版本为12.2。推荐使用官方PyTorch镜像：

# 拉取PyTorch 2.1.0 + CUDA 12.1镜像
docker pull pytorch/pytorch:2.1.0-cuda12.1-cudnn8-runtime

# 运行容器并挂载代码目录
docker run -it --rm \
  --gpus all \
  --shm-size=16g \
  -v /home/user/project:/workspace \
  pytorch/pytorch:2.1.0-cuda12.1-cudnn8-runtime \
  bash

# 在容器内验证GPU可用性
python -c "import torch; print(torch.cuda.is_available()); print(torch.cuda.device_count())"

输出应显示True和GPU数量。若返回False，请检查容器内nvidia-smi是否正常，以及PyTorch版本是否与CUDA版本匹配。

4.5 误区与复盘：避开这些“坑”

误区一：在容器内安装NVIDIA驱动。容器共享宿主机内核，无法独立安装内核模块。正确做法是仅安装CUDA用户态库，驱动始终由宿主机提供。

误区二：忽略--gpus参数直接运行。即使安装了Toolkit，如果不加--gpus all，容器默认无法访问GPU。这是初学者最容易犯的错误。

误区三：宿主机驱动版本过旧。NVIDIA Container Toolkit要求宿主机驱动版本不低于470.x，且需支持CUDA 11.0以上。建议使用最新稳定版驱动。

复盘总结：安装NVIDIA Container Toolkit的本质是打通“Docker运行时 → NVIDIA运行时 → 宿主机驱动”这条链路。只要理解“容器内不需要驱动，只需要库”这一核心思想，大部分问题都能迎刃而解。建议在安装前先执行nvidia-smi确认宿主机驱动正常，再按步骤安装Toolkit，最后用官方镜像验证。整个流程从“安装”到“验证”通常不超过10分钟，但能彻底解决容器化GPU环境的后顾之忧。