Docker 使用 GPU：NVIDIA 与 ROCm 容器

安装 Docker Engine

按照 Docker 官方文档中的说明，从 Docker 自己的仓库安装 Docker Engine：

sudo apt update
sudo apt install -y ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc

sudo tee /etc/apt/sources.list.d/docker.sources <<EOF
Types: deb
URIs: https://download.docker.com/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

sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
sudo docker run --rm hello-world

要在不使用 sudo 的情况下运行 docker，把您的用户加入 docker 组（sudo usermod -aG docker $USER，然后重新登录）。属于这个组等同于拥有服务器的 root 权限，所以只应该把它给已经拥有 sudo 权限的人。

使用 NVIDIA Container Toolkit

该工具包能让容器使用主机的 NVIDIA 驱动。请先在主机上安装驱动（参见 NVIDIA 驱动与 CUDA）；这样容器就不需要自带驱动了。

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
sudo apt update
sudo apt install -y nvidia-container-toolkit

sudo nvidia-ctk runtime configure --runtime=docker   # 把 nvidia 运行时加入 /etc/docker/daemon.json
sudo systemctl restart docker

sudo docker run --rm --runtime=nvidia --gpus all ubuntu nvidia-smi

为每个容器选择要使用的 GPU：

docker run --rm --gpus all ubuntu nvidia-smi -L
docker run --rm --gpus '"device=0,1"' ubuntu nvidia-smi -L   # 只使用 GPU 0 和 1

该工具包会把主机的驱动库挂载到容器里，所以镜像内的 CUDA 版本必须得到主机驱动的支持（即 nvidia-smi 显示的 CUDA Version）。安装细节参见 NVIDIA Container Toolkit 指南。

NVIDIA NGC 镜像

NVIDIA 的 NGC 目录发布了 PyTorch、Triton Inference Server、TensorRT-LLM 等镜像，按发布版本打标签（YY.MM）。公开镜像无需账号即可拉取。

docker pull nvcr.io/nvidia/pytorch:<yy.mm>-py3
docker run --rm -it --gpus all --ipc=host \
  --ulimit memlock=-1 --ulimit stack=67108864 \
  -v /data:/workspace/data \
  nvcr.io/nvidia/pytorch:<yy.mm>-py3

--ipc=host 以及两个 --ulimit 参数是 NVIDIA 为其框架容器推荐的设置：PyTorch 的数据加载器会用到共享内存，而 Docker 默认只给 64 MB。每个版本都基于特定的 CUDA 版本构建；选定标签前，请对照框架支持矩阵检查您的驱动是否支持。若要获取受限内容，用用户名 $oauthtoken 和 NGC API 密钥作为密码执行 docker login nvcr.io。

MI355X 上的 ROCm 容器

ROCm 容器不需要额外的运行时：把 AMD 的设备节点传进去即可。请先在主机上安装内核驱动（参见 MI355X 上的 ROCm）。

docker run -it --rm \
  --device=/dev/kfd --device=/dev/dri \
  --group-add video --ipc=host \
  --cap-add=SYS_PTRACE --security-opt seccomp=unconfined \
  -v /data:/data \
  rocm/pytorch:latest

如果要把容器限制在部分 GPU 上，可以传入具体的渲染节点（例如 --device=/dev/dri/renderD128），而不是整个 /dev/dri。AMD 的 Container Toolkit 可以帮您完成这种映射：从 AMD 的仓库安装 amd-container-toolkit 包，执行 sudo amd-ctk runtime configure，重启 Docker，然后就可以按索引选择 GPU 了：

docker run --rm --runtime=amd -e AMD_VISIBLE_DEVICES=0,1 rocm/dev-ubuntu-24.04 amd-smi list

在 MI355X 上，请使用基于 ROCm 7.0 或更新版本构建的镜像。

Docker Compose 中的 GPU

Compose 通过 deploy.resources 预留 NVIDIA GPU。下面这个文件会在所有 GPU 上运行 vLLM，模型缓存放在 NVMe 上，API 只发布在 localhost 上：

# compose.yaml
services:
  vllm:
    image: vllm/vllm-openai:latest
    command: ["--model", "Qwen/Qwen3-4B", "--max-model-len", "8192"]
    environment:
      - VLLM_API_KEY=${VLLM_API_KEY}
      - HF_TOKEN=${HF_TOKEN}
    volumes:
      - /data/hf:/root/.cache/huggingface
    ports:
      - "127.0.0.1:8000:8000"
    ipc: host
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all          # 或者用 device_ids: ["0", "1"]
              capabilities: [gpu]

export VLLM_API_KEY=$(openssl rand -hex 32)
docker compose up -d
docker compose logs -f vllm

count 和 device_ids 互斥，且必须指定 capabilities（参见 Compose GPU 支持）。在 MI355X 上，则改为映射设备：

services:
  rocm:
    image: rocm/pytorch:latest
    command: sleep infinity
    devices:
      - /dev/kfd
      - /dev/dri
    group_add:
      - video
    ipc: host
    cap_add:
      - SYS_PTRACE
    security_opt:
      - seccomp=unconfined
    volumes:
      - /data:/data

把数据和镜像保存在本地 NVMe 上

容器是可随时丢弃的；您的数据不应该存在容器里面。请从 NVMe 数据盘挂载目录（参见存储与数据），模型缓存也一样放在那里：

docker run --rm -it --gpus all \
  -v /data/datasets:/datasets:ro \
  -v /data/checkpoints:/checkpoints \
  -v /data/hf:/root/.cache/huggingface \
  nvcr.io/nvidia/pytorch:<yy.mm>-py3

镜像和具名数据卷保存在 Docker 的数据目录里，默认是 /var/lib/docker。如果系统盘空间较小，可以把它迁移到数据盘：

sudo systemctl stop docker docker.socket
sudo mkdir -p /data/docker
sudo rsync -aHAX /var/lib/docker/ /data/docker/
sudo nano /etc/docker/daemon.json     # 添加 "data-root"，并保留原有的 "runtimes" 项
sudo systemctl start docker
docker info --format '{{ .DockerRootDir }}'

{
  "data-root": "/data/docker",
  "runtimes": {
    "nvidia": {
      "args": [],
      "path": "nvidia-container-runtime"
    }
  }
}

用 docker system df 检查空间占用，用 docker image prune 清理。租期结束又不续费时，服务器上的所有内容（包括 Docker 数据卷）都会被清除：请把重要数据另外备份一份。

端口、用户和防火墙

• Docker 会通过自己的防火墙规则发布端口，这发生在 ufw 看到流量之前（参见 Docker 关于防火墙的说明）。用 -p 8000:8000 启动的容器即使 ufw 封锁了 8000 端口，依然能从公网访问。请改成发布在回环地址上，即 -p 127.0.0.1:8000:8000，再通过 SSH 隧道或反向代理来访问该服务（参见推理服务）。
• docker 组等同于 root：任何能启动容器的人都能挂载主机的文件系统。
• 把镜像标签固定到具体版本，而不是用 latest，这样重新构建时您的技术栈不会毫无征兆地发生变化。