Docker Compose GPU 部署：从设备可见到深度学习框架可用

类型：官方文档中文解读，不是全文转载。主文依据 Docker 的 Run Docker Compose services with GPU access；环境配置依据 NVIDIA 的 Installing the NVIDIA Container Toolkit。本文保留原文的配置约束，额外的 Python 检查明确标为补充示例。未在本站服务器进行 GPU 实测。

先划清适用环境

本文讨论 Linux Docker 主机上的 NVIDIA GPU 容器。开始之前，应具备可用的宿主机 NVIDIA 驱动、Docker Engine、Compose 插件和 NVIDIA Container Toolkit。Docker 文档的前提是宿主机存在相应设备，且 Docker daemon 已正确配置。[1][5]

容器镜像不能代替宿主机安装内核驱动。也不要把通用服务器教程直接套到 Jetson：Jetson 应另外核对 JetPack/L4T、设备架构和镜像匹配关系。本文不提供 Jetson 的版本兼容承诺。

部署应该分三层验证：宿主机识别 GPU，容器访问 GPU，目标深度学习框架完成 GPU 运算。前一层成功，并不自动证明后一层成功。

GPU 申请配置中哪些字段不能写错

Docker 官方使用 deploy.resources.reservations.devices 声明设备需求。[1]

• driver: nvidia 指定设备驱动。
• capabilities: [gpu] 是必填字段；省略会导致部署错误。
• count 可以是数量或 all。
• device_ids 指定宿主机上的设备 ID。
• count 和 device_ids 互斥，不能同时声明。

下面保留官方最小示例的镜像和字段，仅把服务名改为更易识别的 gpu-check。该镜像用于检查 GPU 可见性，不是安装了 PyTorch 的训练镜像。镜像中的 CUDA 版本还需要匹配宿主机驱动能力。

services:
  gpu-check:
    image: nvidia/cuda:12.9.0-base-ubuntu22.04
    command: nvidia-smi
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: 1
              capabilities: [gpu]

如果需要固定设备，用下面的设备声明替换上面对应部分，而不是把两份配置叠加。设备 ID 必须按真实宿主机填写。[1]

devices:
  - driver: nvidia
    device_ids: ["0"]
    capabilities: [gpu]

count: 1 表示申请一块设备，不表示只使用一定比例的显存，也不是 GPU 算力配额。不要把设备选择和资源限额混为一谈。

Container Toolkit 配置属于宿主机变更

NVIDIA 官方配置流程使用 nvidia-ctk runtime configure --runtime=docker，它修改宿主机 /etc/docker/daemon.json，随后要求重启 Docker daemon。[5]

以下 Python 片段等价调用官方命令，必须在已经安装 Toolkit 的机器上执行。它不是只读诊断；重启 Docker 可能影响现有容器，应先备份配置、确认重启策略和维护窗口。不要在业务主机上为了测试随手执行。

import subprocess

# 会修改 Docker daemon 配置，需要管理员权限。
subprocess.run(
    ["sudo", "nvidia-ctk", "runtime", "configure", "--runtime=docker"],
    check=True,
)

# 仅在确认业务影响后执行。
subprocess.run(["sudo", "systemctl", "restart", "docker"], check=True)

Rootless Docker 的配置文件和重启方式不同，不能直接使用上述系统级路径。NVIDIA 文档给出了单独流程；应按自己的 daemon 模式选择。[5]

用 Python 驱动一次性检查

将前面的 YAML 保存为独立学习目录内的 compose.yaml。以下为本文补充的执行脚本，先核对配置，再启动检查容器；使用独立项目名，避免碰到其他 Compose 项目。

from pathlib import Path
import subprocess

project = Path.home() / "gpu-compose-lab"
compose_file = project / "compose.yaml"
if not compose_file.is_file():
    raise FileNotFoundError(compose_file)

prefix = [
    "docker", "compose", "--project-name", "gpu-compose-lab",
    "--file", str(compose_file),
]

subprocess.run(["nvidia-smi"], check=True)
subprocess.run(prefix + ["config", "--quiet"], check=True)
try:
    subprocess.run(prefix + ["run", "--rm", "gpu-check"], check=True)
finally:
    # 仅清理这个学习项目；不附加删除卷选项。
    subprocess.run(prefix + ["down"], check=True)

这里没有提供一张虚构的 nvidia-smi 成功截图。你应该检查真实设备名称、容器退出码和错误信息。官方页面示例输出与镜像标签可能来自不同编辑时间，不能把演示输出当成自己机器的兼容性证明。

深度学习还需要框架级检查

以下是补充的 PyTorch 自检代码，应在已安装兼容 PyTorch 的目标容器里执行，而不是在上面的 CUDA base 镜像中直接运行。

import torch

print("PyTorch:", torch.__version__)
print("PyTorch 构建使用的 CUDA:", torch.version.cuda)
print("CUDA 可用:", torch.cuda.is_available())

if not torch.cuda.is_available():
    raise RuntimeError("当前 PyTorch 环境不能使用 CUDA")

print("设备:", torch.cuda.get_device_name(0))
x = torch.randn((128, 128), device="cuda")
y = x @ x.T
torch.cuda.synchronize()
assert y.is_cuda
assert bool(torch.isfinite(y).all().item())
print("GPU 矩阵运算检查通过")

这段代码证明当前环境完成了一次有限规模的 GPU 运算，不证明训练速度、混合精度稳定性、数据加载或多卡通信已经正确。实际训练还应检查模型、输入尺寸、显存峰值和结果合理性。

按层定位故障

宿主机 nvidia-smi 失败时，先排查宿主机驱动和设备，不要反复重建 Python 镜像。宿主机正常而容器检查失败时，再检查 Toolkit、daemon 配置、设备声明和实际使用的 Docker context。

容器能看到设备而 torch.cuda.is_available() 为假时，应转向框架安装、CPU/CUDA 构建类型以及驱动兼容关系。nvidia-smi 成功不能排除框架安装错误。

如果环境曾经正常，在管理操作后突然失去 GPU，NVIDIA 安装文档还提示了 systemd cgroup 场景下执行 daemon reload 导致容器失去 GPU 访问的已知问题。应沿官方故障排查入口核对，不宜直接增加 privileged: true 掩盖问题。[5]

部署验收记录

建议保存宿主机驱动版本、设备型号、Docker/Compose 版本、Toolkit 版本、镜像标签或 digest，以及真实检查日志。更换训练镜像后，重新做框架级验证，而不是沿用旧镜像的结论。

本篇只完成文档与示例静态核对，没有执行驱动安装、Docker 重启或 GPU 训练。

来源

1. Docker：Run Docker Compose services with GPU access
2. NVIDIA：Installing the NVIDIA Container Toolkit

本文为中文技术解读，代码示例已按原文语义整理；补充示例和未实测声明见正文。