Linux服务器部署GPU容器运行环境前,驱动与容器依赖如何核对?

发布人:A5数据发布时间:2026-10-30 09:40阅读量:143

首次在 Linux 服务器上部署 GPU 容器运行环境,先要确认的不是容器命令,而是“GPU 能否被宿主机识别、驱动是否正常、容器运行时能否注入 GPU、目标镜像是否与驱动兼容”。以 NVIDIA GPU、Docker Engine 和 NVIDIA Container Toolkit 为例,宿主机需要安装驱动,容器内通常使用镜像自带的 CUDA 用户态库,不要求宿主机额外安装完整 CUDA Toolkit。

本文以 Ubuntu 22.04/24.04、x86_64、Docker Engine 为主线说明首次部署流程。其他发行版或使用 containerd、Kubernetes 的环境,应保留相同的核对逻辑,但安装包名、仓库地址和运行时配置位置需要按照实际系统调整。示例命令用于说明操作方式和预期结果,不代表已经在某台服务器上执行。

A5idc数据提供香港、美国等地区的GPU物理服务器,涵盖A100 80GB、RTX 4090等显卡资源,并配套服务器CPU、内存与NVMe存储,可为AI推理、模型测试、图像处理及GPU容器运行提供硬件基础。结合不同地区的线路与带宽方案,A5idc数据也能为跨区域部署、业务镜像拉取和容器化计算任务提供相应的网络资源选择。

一、先确定部署边界和验收目标

开始操作前,先把以下条件写入实施记录:

  • GPU 型号、数量、显存容量以及是否通过 PCIe 直通或云平台挂载。
  • Linux 发行版、版本、内核版本和 CPU 架构。
  • 使用 Docker Engine、containerd,还是 Kubernetes。
  • 目标容器镜像的完整名称、标签或摘要。
  • 运行容器的用户、需要使用的 GPU 数量、数据目录和网络要求。
  • 是否允许重启服务器、重启 Docker,以及是否存在正在运行的业务容器。

首次部署可以把验收目标设为以下几项:

  1. 宿主机 nvidia-smi 能正确列出 GPU。
  2. 宿主机存在 NVIDIA 设备节点,驱动模块已加载。
  3. Docker 或 containerd 已安装并能正常启动。
  4. NVIDIA Container Toolkit 已安装,并且配置到了实际使用的容器运行时。
  5. 使用目标镜像执行 GPU 测试容器时,容器能够看到指定 GPU。
  6. 业务镜像启动后,应用日志没有 CUDA、设备权限或动态库加载错误。

如果使用 AMD GPU,应改用对应的 ROCm 驱动、容器运行时组件和镜像,不能直接套用 NVIDIA Container Toolkit 命令。

二、准备条件:记录现有环境

1. 记录系统、GPU和内核信息

先不要安装或升级任何软件,保存当前环境信息。以下命令不会修改系统:

cat /etc/os-release
uname -r
uname -m
lspci -nn | grep -Ei 'vga|3d|display|nvidia'
free -h
df -hT

重点关注:

  • uname -m 应与目标镜像支持的架构一致,常见服务器为 x86_64。
  • lspci 能看到 NVIDIA 控制器,说明 PCIe 层面至少发现了设备;如果这里没有 GPU,继续安装容器组件通常不能解决问题。
  • /、/var 或 Docker 数据目录应有足够空间。拉取基础镜像、业务镜像和构建缓存时,实际占用会高于镜像压缩包大小。
  • 如果服务器是云主机,还要确认实例规格确实附带 GPU,并核对 GPU 是否已完成直通。

检查内核头文件、Secure Boot 和 DKMS 状态:

test -e "/lib/modules/$(uname -r)/build" \
  && echo "kernel headers: present" \
  || echo "kernel headers: missing"

if command -v mokutil >/dev/null 2>&1; then
  mokutil --sb-state
else
  echo "mokutil: not installed"
fi

if command -v dkms >/dev/null 2>&1; then
  dkms status
else
  echo "dkms: not installed"
fi

如果需要首次安装或编译 NVIDIA 驱动,当前内核对应的 headers、编译工具和 DKMS 状态会直接影响驱动模块能否生成。Secure Boot 开启时,还要确认驱动模块签名或平台允许加载相应模块。

2. 检查驱动是否已经可用

执行:

nvidia-smi

正常情况下会看到 GPU 名称、驱动版本、显存使用情况和进程列表,例如:

+-----------------------------------------------------------------------------+
| NVIDIA-SMI 550.xx       Driver Version: 550.xx       CUDA Version: 12.x   |
|-------------------------------+----------------------+----------------------|
| GPU  Name                     | Bus-Id        Disp.A | Volatile Uncorr. ECC |
|  0  NVIDIA ...               | 00000000:01:00.0 Off |                  0 |
+-------------------------------+----------------------+----------------------+

这里的 CUDA Version 表示当前驱动能够支持的 CUDA Driver API 上限参考值,不等于宿主机已经安装了完整 CUDA Toolkit,也不表示容器镜像内部一定使用相同版本。

进一步检查设备节点和内核模块:

ls -l /dev/nvidia*
lsmod | grep -E '^nvidia|nvidia_drm|nvidia_modeset'

常见设备节点包括:

/dev/nvidia0
/dev/nvidiactl
/dev/nvidia-uvm

如果 nvidia-smi 正常,但没有 nvidia-uvm,部分 CUDA 应用仍可能无法运行。可以先记录现状,不要直接执行卸载或重装命令,避免影响已有业务。

3. 检查 Docker 和实际运行模式

command -v docker
docker version
sudo systemctl is-enabled docker
sudo systemctl is-active docker
sudo docker info | egrep -i 'Server Version|Storage Driver|Cgroup Version|Rootless'

预期结果包括:

  • 能同时看到 Docker Client 和 Server 版本。
  • systemctl is-active docker 返回 active。
  • Docker 服务端可访问。
  • 能看出使用的是 rootful 还是 rootless 模式。

如果普通用户执行 docker ps 返回 permission denied while trying to connect to the Docker daemon socket,这属于 Docker Socket 权限问题,不等于 GPU 依赖缺失。实施阶段可以先使用 sudo docker 验证,避免为了方便直接扩大用户权限。将用户加入 docker 组相当于授予较高的宿主机控制能力,应经过权限审批,并在重新登录后再验证。

4. 核对依赖关系

核对对象宿主机检查方式通过条件
GPU硬件lspci -nn能看到目标GPU控制器
NVIDIA驱动nvidia-smi、lsmod能列出GPU,驱动模块已加载
设备节点ls -l /dev/nvidia*至少存在目标GPU及控制节点
Docker服务docker version、systemctl is-active docker客户端可连接服务端,服务为active
容器工具包nvidia-ctk --version、软件包查询命令存在,版本来自受控软件源
运行时配置/etc/docker/daemon.json或containerd配置配置指向实际使用的运行时
镜像兼容性目标镜像元数据和GPU试运行镜像要求不高于驱动能力,实际容器可见GPU
网络和存储getent hosts、df -hT、实际拉取镜像软件源、镜像仓库可访问,空间足够

三、逐步安装和配置

1. 先处理宿主机驱动

如果 nvidia-smi 已经正常,首次部署容器环境时不要为了“版本统一”重新安装驱动。先记录驱动版本、GPU型号和当前运行中的 GPU 进程。

如果 nvidia-smi 失败,应先解决宿主机驱动问题,再继续容器配置。在 Ubuntu 环境中,以下是发行版驱动管理路径示例:

sudo apt-get update
ubuntu-drivers devices

确认推荐驱动和当前内核后,再在维护窗口执行:

sudo ubuntu-drivers install
sudo reboot

驱动安装和重启会影响整台服务器上的 GPU 任务,应提前确认业务已停止或迁移,并保存当前软件包和内核信息。重启后重新执行:

nvidia-smi
ls -l /dev/nvidia*
lsmod | grep -E '^nvidia|nvidia_drm|nvidia_modeset'

Ubuntu 以外的发行版、云厂商定制镜像或使用厂商驱动仓库的系统,不要直接执行上述 Ubuntu 命令。应先用以下命令确认发行版和可用包:

cat /etc/os-release
apt-cache policy nvidia-driver 2>/dev/null || true
dnf list --available '*nvidia*' 2>/dev/null || true

如果服务器启用了 Secure Boot、驱动通过 DKMS 编译失败,或 GPU来自虚拟化直通环境,先处理这些系统层问题,不能用容器参数绕过。

2. 安装 NVIDIA Container Toolkit

在 Ubuntu/Debian 系统中,先确认仓库和网络条件。以下示例使用 NVIDIA 软件源,生产环境也可以替换为经过审核的内部镜像源:

distribution=$(. /etc/os-release; echo "${ID}${VERSION_ID}")

sudo apt-get update
sudo apt-get install -y ca-certificates curl gnupg

sudo install -d -m 0755 /usr/share/keyrings

curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey \
  | sudo gpg --dearmor --yes -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg

curl -fsSL "https://nvidia.github.io/libnvidia-container/${distribution}/libnvidia-container.list" \
  | sed 's#deb https://#deb [signed-by=/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://#' \
  | sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list >/dev/null

sudo apt-get update
sudo apt-get install -y nvidia-container-toolkit

安装后先检查工具是否存在:

nvidia-ctk --version
dpkg -l | grep -E 'nvidia-container|libnvidia-container'

如果软件源返回 404、GPG 校验失败或没有可用版本,不要临时改用不明来源的安装脚本。先核对 distribution 变量、系统版本、DNS、代理和内部软件源配置。

3. 配置 Docker 运行时

配置前先备份 Docker 配置。nvidia-ctk runtime configure 会修改 Docker 的运行时配置,重启 Docker 可能影响正在运行的容器:

sudo install -d -m 0755 /etc/docker

if [ -f /etc/docker/daemon.json ]; then
  sudo cp -a /etc/docker/daemon.json \
    "/etc/docker/daemon.json.bak.$(date +%Y%m%d-%H%M%S)"
fi

sudo nvidia-ctk runtime configure --runtime=docker

sudo python3 -m json.tool /etc/docker/daemon.json >/dev/null
sudo systemctl restart docker
sudo systemctl is-active docker

如果 Docker 原来已经有日志、镜像仓库、代理或 cgroup 相关配置,应检查工具包写入后的 JSON 是否保留原有字段。不要用一个新文件直接覆盖原有 daemon.json。

验证 Docker 是否能看到 NVIDIA 运行时配置:

sudo docker info
sudo cat /etc/docker/daemon.json

配置成功后,文件中通常会出现 NVIDIA runtime 相关内容。具体字段可能随工具包版本变化,优先以 nvidia-ctk 生成结果和 Docker 服务状态为准,而不是手工照抄其他服务器的配置。

4. 使用 containerd 或 Kubernetes 时单独配置

如果实际环境使用的是 containerd,不要只配置 Docker。可以先确认服务:

systemctl is-active containerd
containerd --version

在维护窗口备份 containerd 配置后执行对应配置:

if [ -f /etc/containerd/config.toml ]; then
  sudo cp -a /etc/containerd/config.toml \
    "/etc/containerd/config.toml.bak.$(date +%Y%m%d-%H%M%S)"
fi

sudo nvidia-ctk runtime configure --runtime=containerd
sudo systemctl restart containerd
sudo systemctl is-active containerd

Kubernetes 环境还需要确认节点上的 NVIDIA device plugin、RuntimeClass 或平台既有 GPU 调度方式。不要因为 Docker 测试成功,就直接认定 Kubernetes Pod 一定能获得 GPU;Pod 的资源声明、设备插件和节点标签仍需单独验证。

四、用目标镜像进行逐步验证

1. 先验证镜像能否拉取

不要只使用一个与业务无关的临时镜像作为最终依据。可以先使用固定版本的 CUDA 基础镜像做基础测试,再用业务实际镜像复测:

IMAGE=nvidia/cuda:12.4.1-base-ubuntu22.04

sudo docker pull "${IMAGE}"
sudo docker image inspect "${IMAGE}" \
  --format 'image={{.RepoTags}} architecture={{.Architecture}} os={{.Os}}'

如果生产环境使用私有仓库,应将 IMAGE 替换为经过审批的完整镜像地址,并先完成仓库认证。镜像标签可能被重新指向其他内容,正式验收时建议记录镜像摘要:

sudo docker image inspect "${IMAGE}" \
  --format '{{index .RepoDigests 0}}'

2. 核对镜像要求与驱动能力

容器镜像里的 CUDA Runtime 不应高于宿主机驱动能够支持的范围。可以查看镜像环境变量中是否声明了 CUDA 要求:

sudo docker run --rm \
  --entrypoint /bin/sh \
  "${IMAGE}" \
  -c 'env | grep -E "^NVIDIA_REQUIRE_CUDA|^CUDA_VERSION" || true'

有些镜像还可以查看 CUDA 版本文件:

sudo docker run --rm \
  --entrypoint /bin/sh \
  "${IMAGE}" \
  -c 'cat /usr/local/cuda/version.json 2>/dev/null || true'

需要注意以下关系:

四、用目标镜像进行逐步验证|2. 核对镜像要求与驱动能力配图

  • 宿主机必须有可用的 NVIDIA 驱动。
  • NVIDIA Container Toolkit 负责把宿主机驱动相关库和设备注入容器。
  • CUDA 用户态库通常来自容器镜像。
  • 宿主机不一定需要安装 nvcc,也不一定需要安装完整 CUDA Toolkit。
  • nvidia-smi 显示的驱动支持版本只能作为初步判断,最终仍应使用目标镜像实际运行验证。

如果镜像声明的 CUDA 要求明显高于驱动能力,应优先升级驱动或选择匹配的镜像版本,不要通过修改环境变量伪装兼容性。

3. 运行最小 GPU 容器测试

执行:

sudo docker run --rm \
  --gpus all \
  "${IMAGE}" \
  nvidia-smi

通过时,容器内应能看到 GPU 名称、驱动版本和显存信息。宿主机与容器中显示的驱动版本通常应保持一致,因为容器使用的是宿主机驱动接口。

再测试 GPU 数量和设备编号:

sudo docker run --rm \
  --gpus all \
  "${IMAGE}" \
  nvidia-smi -L

如果业务只允许使用一张卡,可以进行定向验证:

sudo docker run --rm \
  --gpus '"device=0"' \
  "${IMAGE}" \
  nvidia-smi -L

预期是容器只列出编号为 0 的 GPU。不同 Docker 版本对 --gpus 参数的引号解析可能略有差异,执行失败时先检查 Docker 版本和命令行是否被 Shell 改写。

如果业务镜像本身没有 nvidia-smi,不能据此判断 GPU 不可用。此时应使用业务程序的诊断参数,或用 CUDA 基础镜像完成运行时验证后,再按业务镜像的启动命令验证:

sudo docker run --rm \
  --gpus all \
  --entrypoint /bin/sh \
  "${IMAGE}" \
  -c 'ls -l /dev/nvidia* 2>/dev/null; env | grep NVIDIA || true'

不要使用 --privileged 作为 GPU 故障的通用修复手段。它会扩大容器权限范围,改变安全边界,也会掩盖真正的运行时配置问题。

五、常见异常及处理顺序

nvidia-smi 在宿主机就失败

先看 lspci 是否能发现 GPU,再检查内核模块、驱动包、DKMS 和 Secure Boot。若 lspci 没有设备,应检查云主机规格、PCIe 直通和虚拟机配置;若有设备但驱动模块未加载,再处理驱动安装和内核兼容性。

此时不要继续排查 Docker,因为容器层无法修复宿主机没有识别的 GPU。

Docker 报 GPU runtime 不存在

典型表现为:

could not select device driver "" with capabilities: [[gpu]]

优先检查:

nvidia-ctk --version
sudo docker info
sudo cat /etc/docker/daemon.json
sudo systemctl status docker --no-pager

常见原因包括:

  • NVIDIA Container Toolkit 没安装完整。
  • 配置写入了 rootless Docker,但实际执行的是 rootful Docker,或反过来。
  • 修改配置后没有重启 Docker。
  • 实际使用的是 containerd,却只配置了 Docker。
  • daemon.json 存在 JSON 语法错误或字段冲突。

容器能启动但看不到 GPU

检查:

sudo docker run --rm \
  --gpus all \
  "${IMAGE}" \
  nvidia-smi

sudo journalctl -u docker -n 100 --no-pager

如果宿主机设备节点存在,而容器内不存在,重点检查 NVIDIA runtime 配置、Docker 版本和 cgroup 模式。如果容器内能看到设备但应用报 CUDA 错误,则继续检查镜像 CUDA 版本、应用依赖和 GPU 架构支持。

驱动版本与镜像不匹配

如果错误信息包含 CUDA 初始化失败、驱动版本过低或不支持的 CUDA capability,先记录:

nvidia-smi
sudo docker image inspect "${IMAGE}" \
  --format '{{json .Config.Env}}'

然后在“升级宿主机驱动”和“选择较低 CUDA 版本镜像”之间做取舍。生产环境通常优先选择与既有驱动兼容的镜像,避免为了单个容器直接升级整台服务器驱动。

软件源或镜像仓库无法访问

分别验证 DNS、HTTPS 和 Docker 服务端代理:

getent hosts nvidia.github.io
getent hosts registry-1.docker.io
sudo systemctl show docker --property=Environment

当前 Shell 能访问互联网,不代表 Docker daemon 一定继承了相同的代理环境。若使用企业代理或私有仓库,应按服务器网络规范配置 CA、代理和认证,不要把凭据直接写入公开脚本。

六、结果检查和验收记录

基础测试完成后,按以下项目留存结果:

  • nvidia-smi 输出中的 GPU 型号、驱动版本和 GPU 数量。
  • /dev/nvidia* 设备节点清单。
  • Linux 发行版、内核版本、CPU 架构。
  • Docker 或 containerd 的版本和服务状态。
  • NVIDIA Container Toolkit 版本。
  • /etc/docker/daemon.json 或 containerd 配置的备份文件路径。
  • 目标镜像完整名称、标签和镜像摘要。
  • docker run --gpus ... nvidia-smi 的验证结果。
  • 业务镜像实际启动命令和关键日志。
  • 使用普通业务用户运行时的权限结果。
  • 服务器重启后重复测试的结果。

如果只验证了 nvidia/cuda 基础镜像,而没有验证业务镜像,验收结论应写成“GPU 容器运行时通过”,不能扩大为“业务应用已通过”。业务镜像可能额外依赖特定 CUDA 库、显卡架构、共享内存、驱动能力或数据目录权限。

七、回滚检查项

回滚应按变更层次执行,不要一开始就卸载驱动。

Docker 配置回滚

如果配置后 Docker 无法启动,先查看错误:

sudo systemctl status docker --no-pager
sudo journalctl -u docker -n 100 --no-pager

确认是本次配置导致后,在已停止或已迁移业务容器的前提下恢复备份的 daemon.json,再启动 Docker。恢复时应使用实施记录中的具体备份文件,不要随意删除当前配置:

sudo systemctl stop docker

# 将下面的备份文件名替换为实施记录中的实际文件
sudo cp -a /etc/docker/daemon.json.bak.YYYYMMDD-HHMMSS \
  /etc/docker/daemon.json

sudo systemctl start docker
sudo systemctl is-active docker

容器工具包回滚

如果只是本次新增 NVIDIA Container Toolkit,且没有其他 GPU 容器依赖它,可以在维护窗口内根据软件包记录回退。执行卸载前,应确认不会影响其他项目:

dpkg -l | grep -E 'nvidia-container|libnvidia-container'
apt-cache policy nvidia-container-toolkit

不要直接删除所有名称中带 nvidia 的软件包,否则可能连宿主机驱动一并移除。

驱动回滚

驱动回滚会影响所有 GPU 任务,通常需要停机或重启。优先采用以下方式:

  • 云服务器镜像或系统快照恢复。
  • 启动已验证过的旧内核和对应驱动。
  • 使用软件仓库中明确存在的上一版本驱动包。
  • 在非生产服务器先完成降级验证,再安排业务窗口。

回滚后必须重新执行 nvidia-smi、设备节点检查和目标镜像 GPU 测试。只恢复 Docker 配置而不验证宿主机驱动,不能确认环境已经回到可运行状态。

镜像回滚

如果问题来自业务镜像升级,保留上一个已验证的镜像摘要,不要只依赖可变标签。回滚后重新执行:

sudo docker run --rm \
  --gpus all \
  '上一个已验证的镜像摘要' \
  nvidia-smi

最终验收应同时满足“宿主机驱动正常、容器运行时配置正确、目标镜像能够获得指定 GPU、业务容器日志无初始化错误”四项条件;任一项不满足,都应保留当前现场和日志,先回到上一个已验证的配置,再安排下一轮变更。

本文由A5数据原创发布,转载请注明出处:https://www.a5idc.com/helpcontent/6517.html

相关推荐