Docker 容器 GPU 调用通用配置指南

1. 核心链路

在 Docker 中使用 GPU，必须打通：驱动 (Driver) -> 工具包 (Toolkit) -> 运行时 (Runtime) -> 配置文件 (Compose)。

2. 宿主机环境准备

确保宿主机已安装 NVIDIA 驱动，并配置好 NVIDIA Container Toolkit。

# 1. 自动向 /etc/docker/daemon.json 写入 nvidia 运行时配置
sudo nvidia-ctk runtime configure --runtime=docker

# 2. 重启 Docker 服务使配置生效
sudo systemctl restart docker

生产小贴士：建议在 daemon.json 中加入 "live-restore": true。这样在重启 Docker 守护进程时，不会导致正在运行的容器停止，保证业务连续性。

3. 通用 docker-compose.yml 模板 (v3.8)

这是目前最稳妥的通用配置。注意：由于配置了 runtime: nvidia，通常不需要再显式写 NVIDIA_VISIBLE_DEVICES 等环境变量。

version: '3.8'  # 建议使用 3.8 版本以获得更好的 GPU 资源调度支持

services:
  gpu_app:
    image: your_image_name:tag
    container_name: your_container_name
    runtime: nvidia  # 关键：强制调用 NVIDIA 容器运行时
    restart: always
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all  # 或指定数量，如 1
              capabilities: [gpu, utility, compute]
    # 根据需要挂载卷和网络配置
    # network_mode: "host" 
    # volumes:
    #   - ./config:/app/config

4. 验证与排查

验证步骤

容器启动后，直接在宿主机执行以下命令：

docker exec -it <容器名> nvidia-smi

如果能看到显卡型号、显存占用等表格信息，说明链路已完全打通。

常见问题排查表

5. 经验总结

1. Runtime 是灵魂：在 Compose 里指定 runtime: nvidia 是解决“容器看不见显卡”最直接有效的办法。
2. 版本兼容性：使用 version: '3.8' 能确保 deploy.resources 字段被正确解析。
3. 配置生效：任何对 daemon.json 的修改，必须执行 systemctl restart docker 才会生效。