Ubuntu 下 Docker + NVIDIA Container Toolkit 安装流程与 daemon.json 配置速记

环境:Ubuntu 22.04。目标:让 vLLM 容器能直接用 --gpus all 跑起来。安装步骤官方文档已经写得很全,这里不重复贴命令,只记录流程顺序、国内环境的坑,以及最终的 /etc/docker/daemon.json 配置。

一、Docker 安装

国内直接走阿里云镜像站的教程,一步到位,不需要科学上网:

https://developer.aliyun.com/mirror/docker-ce

要点:

卸载系统自带的旧版 docker / docker.io / containerd,避免版本冲突;
按教程添加阿里云的 GPG key 和 apt 源(教程里的源地址已经是 mirrors.aliyun.com,替换了官方的 download.docker.com);
apt install docker-ce docker-ce-cli containerd.io 装完后,docker run hello-world 验证。

注意:hello-world 镜像本身要从 Docker Hub 拉取,国内大概率超时。这一步失败不代表安装有问题,先配好下面的 registry-mirrors 再验证。

二、NVIDIA Container Toolkit 安装

前置条件:宿主机 NVIDIA 驱动已装好(nvidia-smi 能正常输出),不需要在宿主机装 CUDA Toolkit,容器内自带。

官方安装文档:

https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html

流程就三步:

添加 NVIDIA 的 apt 仓库并安装 nvidia-container-toolkit(官方源 nvidia.github.io 国内访问尚可,如果超时可挂代理或换国内镜像源);
执行 sudo nvidia-ctk runtime configure --runtime=docker ------ 这一步会自动往 /etc/docker/daemon.json 写入 nvidia runtime 配置,不用手改;
重启 docker 后,用 CUDA 基础镜像跑一次 nvidia-smi 验证 GPU 直通。

三、/etc/docker/daemon.json 配置

这是我最终使用的完整配置,几个字段的作用写在后面:

json 复制代码

{
  "registry-mirrors": [
    "https://<你的ID>.mirror.aliyuncs.com"
  ],
  "runtimes": {
    "nvidia": {
      "path": "nvidia-container-runtime",
      "runtimeArgs": []
    }
  },
  "default-runtime": "nvidia",
  "data-root": "/workspace/docker",
  "log-driver": "json-file",
  "log-opts": {
    "max-size": "100m",
    "max-file": "3"
  }
}

逐项说明:

registry-mirrors :镜像加速地址。公共免费加速器这两年陆续失效,建议直接用阿里云容器镜像服务(ACR)控制台里分配给自己账号的专属加速地址,格式为 https://<ID>.mirror.aliyuncs.com,登录 ACR 控制台 → 镜像工具 → 镜像加速器即可查看。
runtimes.nvidia :由 nvidia-ctk runtime configure 自动写入。如果你手动编辑过 daemon.json,注意别把这段覆盖掉。
default-runtime: "nvidia" :把 nvidia 设为默认 runtime,这样 docker-compose 里不写 runtime: nvidia 也能拿到 GPU。单机 GPU 服务器建议加,多租户环境慎用。
data-root :把镜像和容器数据从默认的 /var/lib/docker 挪到大分区。vLLM 一个镜像动辄 20GB+,系统盘很快就满,建议一开始就规划好。
log-opts:限制单容器日志体积。vLLM 长期运行,不限制的话 json 日志能吃掉几十 GB 磁盘。

改完配置后:

bash 复制代码

sudo systemctl daemon-reload
sudo systemctl restart docker
docker info | grep -A3 Runtimes   # 确认 nvidia runtime 已注册

四、踩坑备忘

改 daemon.json 前先停掉正在跑的容器,restart docker 会把所有容器杀掉;
JSON 格式错误会导致 docker 起不来 ,改完先用 python3 -m json.tool /etc/docker/daemon.json 校验一遍;
换了 data-root 后旧镜像不会自动迁移 ,要么重新拉取,要么把 /var/lib/docker 整体 rsync 过去再改配置;
registry-mirrors 只对 Docker Hub 生效,从 ACR 私有仓库拉镜像(registry.cn-xxx.aliyuncs.com/...)走的是直连,不受影响。

流程本身不复杂,难点全在网络环境。