Ubuntu安装支持NVIDIA GPU的Docker（NVIDIA Container Toolkit）

本文适用于使用systemd的Ubuntu宿主机。已有的 NVIDIA Server 闭源驱动继续使用，下面按顺序配置软件仓库、安装容器工具、设置 GPU 运行时和镜像加速，最后统一重启 Docker，使配置生效。

整个正常安装流程只执行一次 apt update、一次 apt install，保留软件包安装过程中默认的服务自动启动行为，完成配置后只重启一次 Docker。文中的命令分组执行即可，无需保存为 Bash 脚本。遇到报错时，先解决该步骤的问题，再继续。

1. 环境与下载来源

项目	本文设置
NVIDIA 驱动	沿用宿主机已安装且正常工作的 Server 闭源驱动
Ubuntu 系统 APT 源	保持现有配置
Docker CE 软件仓库	南方科技大学 Docker CE 镜像
NVIDIA Container Toolkit 软件仓库	NVIDIA 官方专用仓库
Docker Hub 镜像加速	https://dockerproxy.net

这里的南科大 APT 源用于获取 Docker CE 软件包；NVIDIA Container Toolkit 使用其官方安装文档提供的独立仓库。本文不修改 /etc/apt/sources.list 或 ubuntu.sources，也不为 Docker CE 配置其他备用镜像站。

执行前应满足以下条件：

• NVIDIA 驱动已完成安装，上一轮 DKMS 构建已经结束。
• 已具备前面流程中准备好的 curl 和 ca-certificates，能够通过 HTTPS 下载签名密钥。
• 当前没有其他 APT、dpkg 或驱动安装进程正在运行。

检查宿主机 GPU，以及是否存在未完成配置的软件包：

nvidia-smi
sudo dpkg --audit

第一条命令应正常显示 GPU 信息；第二条通常没有输出。若存在未完成配置的软件包，应先完成此前的安装。本教程不重新选择或切换显卡驱动。

2. 备份配置并准备软件仓库

以下命令在同一个终端中按顺序执行。先创建目录，并将现有第三方软件源配置和 Docker 配置备份到 /root 下：

docker_backup="/root/docker-gpu-backup-$(date +%Y%m%d-%H%M%S)"
sudo install -d -m 0755 "$docker_backup" /etc/apt/keyrings /etc/docker
sudo cp -a /etc/apt/sources.list.d /etc/docker "$docker_backup/"

本文统一使用 .sources 格式。移除前面教程可能留下的同名旧式 .list 文件，避免同一仓库出现重复条目或 Signed-By 冲突；其内容已包含在刚才的备份中：

sudo rm -f /etc/apt/sources.list.d/docker.list \
  /etc/apt/sources.list.d/nvidia-container-toolkit.list

2.1 Docker CE：使用南科大镜像

下载 Docker 官方签名密钥：

sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg \
  -o /etc/apt/keyrings/docker.asc

写入 Docker CE 软件源。发行版代号和 CPU 架构自动读取，避免将 Ubuntu 26.04 的 resolute 软件包装到 Ubuntu 24.04：

sudo tee /etc/apt/sources.list.d/docker.sources > /dev/null <<EOF
Types: deb
URIs: https://mirrors.sustech.edu.cn/docker-ce/linux/ubuntu
Suites: $(. /etc/os-release && echo "${UBUNTU_CODENAME:-$VERSION_CODENAME}")
Components: stable
Architectures: $(dpkg --print-architecture)
Signed-By: /etc/apt/keyrings/docker.asc
EOF

南科大镜像说明提供的这个仓库用于 Docker CE 软件包下载，容器镜像加速在第 4 步单独配置。

2.2 NVIDIA Container Toolkit：使用官方仓库

下载 NVIDIA 仓库的签名密钥：

sudo curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey \
  -o /etc/apt/keyrings/nvidia-container-toolkit.asc

APT 支持 ASCII 格式的 .asc 签名密钥，因此这里不需要先使用 gpg --dearmor 转换密钥。参见 APT 签名验证说明。

统一设置两个密钥文件的读取权限：

sudo chmod a+r /etc/apt/keyrings/docker.asc \
  /etc/apt/keyrings/nvidia-container-toolkit.asc

将 NVIDIA 的 stable 仓库写成 .sources 格式：

sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.sources > /dev/null <<EOF
Types: deb
URIs: https://nvidia.github.io/libnvidia-container/stable/deb/$(dpkg --print-architecture)
Suites: /
Architectures: $(dpkg --print-architecture)
Signed-By: /etc/apt/keyrings/nvidia-container-toolkit.asc
EOF

这个仓库使用按架构划分的平铺目录，Suites: / 是仓库格式要求。仓库地址来自 NVIDIA 官方源列表，字段写法见 APT sources.list 手册。

3. 一次性更新索引并安装全部软件包

两个第三方仓库均已配置完成，现在执行本文唯一一次软件包索引更新：

sudo apt update

这里更新的是软件包索引，不会修改 Ubuntu 系统软件源地址，也不会执行系统升级。

如果之前安装过 Ubuntu 仓库中的 docker.io 等冲突包，在安装 Docker CE 前按 Docker 官方要求移除。下面只筛选已经安装的冲突包，没有匹配项时不会执行卸载：

dpkg-query -W -f='${db:Status-Abbrev} ${binary:Package}\n' \
  docker.io docker-compose docker-compose-v2 docker-doc docker-buildx \
  podman-docker containerd runc 2>/dev/null |
  awk 'substr($1, 2, 1) == "i" {print $2}' |
  xargs -r sudo apt remove

检查 APT 给出的移除列表后再确认。该步骤用于迁移冲突的软件包，没有删除 Docker 镜像或数据目录的命令。

一次性安装 Docker Engine、Buildx、Compose、NVIDIA Container Toolkit，以及后面编辑 JSON 配置使用的 jq：

sudo apt install -y \
  docker-ce \
  docker-ce-cli \
  containerd.io \
  docker-buildx-plugin \
  docker-compose-plugin \
  nvidia-container-toolkit \
  jq

Docker 官方安装文档说明，Ubuntu 上安装 Docker 软件包时通常会自动启动服务。这里保留默认行为，接着完成 GPU 和镜像配置，再统一重启。NVIDIA Container Toolkit 的安装和运行时配置方式参见 NVIDIA 官方文档。

4. 配置 GPU 运行时与 Docker Hub 镜像加速

先注册 NVIDIA 容器运行时：

sudo nvidia-ctk runtime configure --runtime=docker

该命令创建或更新 /etc/docker/daemon.json，将 NVIDIA 运行时加入 Docker 配置。它不需要 Docker 守护进程已经运行。

再将 Docker Hub 镜像加速器设置为 dockerproxy.net。用 jq 修改单个字段，保留 NVIDIA 运行时以及其他现有配置：

sudo jq '.["registry-mirrors"] = ["https://dockerproxy.net"]' \
  /etc/docker/daemon.json |
  sudo tee /etc/docker/daemon.json.new > /dev/null

先验证新配置，验证成功后再替换原文件：

sudo dockerd --validate --config-file=/etc/docker/daemon.json.new &&
sudo mv /etc/docker/daemon.json.new /etc/docker/daemon.json

--validate 只检查配置并退出，不会启动 Docker 守护进程。registry-mirrors 用于 Docker Hub 镜像加速，不是通用的 HTTP/SOCKS 代理设置。参见 dockerd 命令文档和 Docker Hub 镜像加速配置。

5. 设置开机启动，并统一重启一次

确认安装和配置验证均已成功，设置服务开机启动：

sudo systemctl enable containerd.service docker.service docker.socket

统一重启 Docker，让 GPU 运行时和镜像加速配置同时生效：

sudo systemctl restart docker.service

如果 Docker 此前尚未运行，restart 会启动它。Docker 的服务依赖会同时拉起所需的 containerd 和 socket。若已有容器正在运行，这次重启可能影响其运行，请在合适的时间执行。

6. 验证 Docker 和 GPU 容器

检查 Docker、Compose 和实际生效的镜像配置：

sudo docker version
sudo docker compose version
sudo docker info --format '{{json .RegistryConfig.Mirrors}}'

docker version 应显示客户端和服务端信息；镜像配置应包含 https://dockerproxy.net，其末尾可能自动带上 /。

通过显式的代理仓库地址运行测试容器；本地不存在该镜像时，Docker 会自动拉取：

sudo docker run --rm \
  --runtime=nvidia \
  --gpus all \
  dockerproxy.net/library/ubuntu:26.04 \
  nvidia-smi

参数	含义
--rm	命令结束后自动删除测试容器
--runtime=nvidia	使用 NVIDIA 容器运行时
--gpus all	向容器开放所有 GPU
dockerproxy.net/library/ubuntu:26.04	通过指定代理获取 Ubuntu 官方镜像
nvidia-smi	在容器内部查询 GPU 和驱动状态

容器内能够显示 GPU 信息，表示 Docker 已能访问宿主机显卡。这是 GPU 可见性验证；具体深度学习框架还需要在相应的 CUDA/PyTorch 容器中验证计算功能。NVIDIA 官方验证示例采用的也是容器内运行 nvidia-smi 的方式。