以下是在 Ubuntu 系统上安装 NVIDIA Container Toolkit 的详细步骤，适用于支持 GPU 加速的 Docker 容器环境。以下是针对不同 Ubuntu 版本（如 Ubuntu 20.04 和 24.04）的通用流程：
- 环境准备
1.1 验证 NVIDIA 驱动状态
确保系统已正确安装 NVIDIA 显卡驱动：
bash
深色版本
nvidia-smi
如果驱动已正确安装，命令会显示 GPU 信息和驱动版本。如果没有输出或报错，请先安装 NVIDIA 驱动。
1.2 安装 Docker
确保已安装 Docker：
bash
深色版本
sudo apt update && sudo apt install docker.io -y
验证 Docker 是否正常运行：
bash
深色版本
sudo docker run hello-world
2. 安装 NVIDIA Container Toolkit
2.1 添加 NVIDIA 官方仓库
更新系统依赖：
bash
深色版本
sudo apt-get update && sudo apt-get install -y
ca-certificates
curl
gnupg
lsb-release
添加 NVIDIA GPG 密钥和 APT 仓库：
bash
深色版本
curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey | sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg
distribution=$(. /etc/os-release;echo $ID$VERSION_ID)
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.2 安装 NVIDIA Container Toolkit
更新 APT 缓存并安装：
bash
深色版本
sudo apt-get update && sudo apt-get install -y nvidia-container-toolkit
3. 配置 Docker 使用 NVIDIA 运行时
3.1 修改 Docker 配置
使用 nvidia-ctk 工具自动配置 Docker：
bash
深色版本
sudo nvidia-ctk runtime configure --runtime=docker
该命令会自动修改 /etc/docker/daemon.json 文件，添加 NVIDIA 运行时支持。
3.2 重启 Docker 服务
使配置生效：
bash
深色版本
sudo systemctl restart docker
4. 验证安装
4.1 运行测试容器
拉取一个支持 CUDA 的测试镜像并运行：
bash
深色版本
sudo docker run --rm --gpus all nvidia/cuda:12.6.0-base nvidia-smi
如果配置成功，会看到与宿主机相同的 GPU 信息输出。
4.2 检查 Docker 配置文件
确保 /etc/docker/daemon.json 包含以下内容（由 nvidia-ctk 自动生成）：
json
深色版本
{
"default-runtime": "nvidia",
"runtimes": {
"nvidia": {
"path": "/usr/bin/nvidia-container-runtime",
"runtimeArgs": []
}
}
}
5. 常见问题与解决方案
5.1 报错：nvidia-ctk 未找到
如果安装后找不到 nvidia-ctk 命令，请检查是否正确安装了 nvidia-container-toolkit：
bash
深色版本
sudo apt-get install -y nvidia-container-toolkit
5.2 配置文件冲突
如果 /etc/docker/daemon.json 中存在其他配置（如 storage-driver），可能导致冲突。确保 storage-driver 与 NVIDIA 兼容（默认 overlay2 通常可用）。如果冲突严重，可手动编辑配置文件。
5.3 离线安装（可选）
如果无法联网，可参考以下步骤：
在联网机器上下载以下 .deb 包（版本需匹配目标系统）：
libnvidia-container1
libnvidia-container-tools
nvidia-container-toolkit-base
nvidia-container-toolkit
将 .deb 文件传输到离线机器，依次安装：
bash
深色版本
sudo dpkg -i libnvidia-container1_.deb
sudo dpkg -i libnvidia-container-tools_.deb
sudo dpkg -i nvidia-container-toolkit-base_.deb
sudo dpkg -i nvidia-container-toolkit_.deb
手动配置 Docker 运行时并重启服务。
6. 示例：运行 GPU 加速容器
安装完成后，可以运行需要 GPU 的容器，例如：
bash
深色版本
docker run --gpus all -p 8880:8880 ghcr.io/remsky/kokoro-fastapi-gpu:latest