Nvidia 显卡 Docker 配置指引
太太太难了，到处都是墙......这篇指引把上上一篇文章里关于如何在 Docker 中调用 Nvidia 显卡的部分特地摘出来讲一下，以及讲解如果遇到网络问题该如何解决。
在开始之前
本文旨在指引你如何在网络封锁的情况下在 Ubuntu Server 中安装和配置 Nvidia 显卡工具链以及怎样让 Docker 容器能够调用显卡进行计算或渲染。
在开始之前，你必须能够满足如下要求：
有稳定的跨国流量中转服务，什么工具均可但是要能够在本地/局域网支持代理连接（如 http://127.0.0.1:7890）。
基本 Linux 操作常识，至少常用命令、vi 的使用都要会。
基本 Docker 操作常识，知道怎样通过命令行连接容器、操作容器、查看容器日志、操作容器编排等等。
如果上述条件不满足或者看不懂，那么代表你目前掌握的技术还不足以支撑你继续在折腾 AI 的道路上走下去，请先历练一下再继续吧。
本文将会使用图形工作站进行演示，采用多显卡配置，所以部分步骤与你的实际显示不会完全一致。但一般只要电脑和显卡不是太旧就不会出现意外问题。
前置相关教程：
安装显卡驱动
安装驱动
对于 Ubuntu Server 来说，正常情况下只需 2 行命令即可完成显卡驱动安装：
ubuntu-drivers devices
sudo ubuntu-drivers autoinstall # 如果对驱动程序版本有要求则使用 sudo apt install nvidia-driver-<version> 安装特定版本驱动。其中 ubuntu-drivers devices 会检测并提示你当前系统中检测到的所有 GPU 设备。注意，如果你有多张同型号显卡时此命令只会显示一条记录。运行后你会看到类似如下输出：
== /sys/devices/pci0000:00/0000:00:01.0/0000:01:00.0 ==
modalias : pci:v000010DEd83fnenz12ibvk1u2csmuh2qt9tphx303sc00i00
vendor : NVIDIA Corporation
model : AD106 [GeForce RTX 4060 Ti]
driver : nvidia-driver-535 - distro non-free
driver : nvidia-driver-570-server - distro non-free
driver : nvidia-driver-535-server - distro non-free
driver : nvidia-driver-550 - distro non-free recommended
driver : nvidia-driver-550-open - distro non-free
driver : nvidia-driver-535-server-open - distro non-free
driver : nvidia-driver-535-open - distro non-free
driver : nvidia-driver-570-server-open - distro non-free
driver : xserver-xorg-video-nouveau - distro free builtin
== /sys/devices/pci0000:00/0000:00:1d.0/0000:08:00.0 ==
modalias : pci:v000010DEd8akk498zyyu2fzuwj9rucjem35u5p603sc02i00
vendor : NVIDIA Corporation
model : GM200GL [Tesla M40]
manual_install: True
driver : nvidia-driver-470-server - distro non-free
driver : nvidia-driver-470 - distro non-free
driver : xserver-xorg-video-nouveau - distro free builtin此处前面可能会有一些 udevadm hwdb is deprecated. Use systemd-hwdb instead. 的报错，是正常现象，忽略即可。
此处的输出为推荐驱动列表，末尾有 recommended 的是自动安装功能所使用的驱动。你有两种方式可以安装驱动：
没有驱动版本要求或者不知道自己在做什么的，输入
sudo ubuntu-drivers autoinstall来让系统自动安装驱动。对驱动版本有要求，输入
sudo apt install nvidia-driver-<version>来安装特定版本驱动。
等待显卡驱动安装完成后，使用 sudo reboot 重新启动系统，使用 nvidia-smi 命令来查看驱动是否安装成功：
+-----------------------------------------------------------------------------------------+
| NVIDIA-SMI 550.120 Driver Version: 550.120 CUDA Version: 12.4 |
|-----------------------------------------+------------------------+----------------------+
| GPU Name Persistence-M | Bus-Id Disp.A | Volatile Uncorr. ECC |
| Fan Temp Perf Pwr:Usage/Cap | Memory-Usage | GPU-Util Compute M. |
| | | MIG M. |
|=========================================+========================+======================|
| 0 NVIDIA GeForce RTX 4060 Ti Off | 00000000:01:00.0 Off | N/A |
| 0% 43C P8 10W / 160W | 2MiB / 8188MiB | 0% Default |
| | | N/A |
+-----------------------------------------+------------------------+----------------------+
| 1 Tesla M40 24GB Off | 00000000:05:00.0 Off | Off |
| N/A 31C P8 15W / 250W | 0MiB / 24576MiB | 0% Default |
| | | N/A |
+-----------------------------------------+------------------------+----------------------+
| 2 Tesla M40 24GB Off | 00000000:08:00.0 Off | Off |
| N/A 33C P8 15W / 250W | 0MiB / 24576MiB | 0% Default |
| | | N/A |
+-----------------------------------------+------------------------+----------------------+
+-----------------------------------------------------------------------------------------+
| Processes: |
| GPU GI CI PID Type Process name GPU Memory |
| ID ID Usage |
|=========================================================================================|
| No running processes found |
+-----------------------------------------------------------------------------------------+卸载驱动
如果你安装过程中出现失败，或者安装了错误版本的驱动程序，按照如下步骤完全卸载 Nvidia 显卡驱动及相关工具：
sudo apt-get --purge remove nvidia*
sudo apt autoremove
sudo reboot排错指引
Q: nvidia-smi 命令报错 NVIDIA-SMI has failed because it couldn't communicate with the NVIDIA driver. Make sure that the latest NVIDIA driver is installed and running.
重新启动系统，安装完驱动不重启直接运行此命令必然报这个错误。
检查自己的驱动，使用
ls /usr/src | grep nvidia可以查看当前安装的驱动名称，如果是后缀带有 open 或者 server-open 字样的驱动也可能会出现此错误，卸载显卡驱动后使用sudo apt install nvidia-driver-<version>命令来指定安装无后缀版本驱动。
Q: nvidia-smi 命令报错找不到可用的计算设备
完全卸载显卡驱动，使用
sudo apt install nvidia-driver-<version>来逐步降级你的显卡驱动，直到错误排除为止。如果你降级到 400 以下版本仍未排除错误，则极大概率为硬件兼容性问题。
安装显卡容器工具链
要在 Docker 上使用 GPU，首先需要安装 Nvidia Container Toolkit。SSH 连接服务器，运行下列命令添加仓库配置：
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-get update仓库配置添加完成后运行 sudo apt-get install nvidia-container-toolkit 即可安装 Nvidia Container Toolkit。之后运行 sudo nvidia-ctk runtime configure --runtime=docker 来自动给 Docker Engine 添加相关配置，让其能够调用 GPU 资源。
上述命令运行完成之后，运行 sudo systemctl restart docker 来重启 Docker Engine 应用配置。
排错指引
Q: 添加仓库配置时报错 Recv failure: Connection reset by peer.
网络问题，按照如下步骤通过代理进行仓库安装（注意替换自己的代理地址）：
curl -fsSL --proxy 127.0.0.1:7890 https://nvidia.github.io/libnvidia-container/gpgkey \
| sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg
curl -s -L --proxy 127.0.0.1:7890 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-get updateQ: 执行 sudo apt-get update / sudo apt-get install nvidia-container-toolkit 报错 Failed to fetch https://nvidia.github.io/libnvidia-container/stable/deb/amd64/InRelease Could not handshake: Error in the pull function.
网络问题，按照如下步骤给 apt 添加代理链接（注意替换自己的代理地址）：
sudo vi /etc/apt/apt.conf.d/05proxy
# 在其中写入如下内容：
Acquire::http::Proxy "http://127.0.0.1:7890";Docker 容器调用 GPU
要检查 GPU 是否能正确的被 Docker 容器调用，可以使用 docker run --gpus all --rm nvidia/cuda:12.4.0-base-ubuntu20.04 nvidia-smi 命令，你应该能看到如下输出：
Thu Mar 13 06:22:46 2025
+-----------------------------------------------------------------------------------------+
| NVIDIA-SMI 550.120 Driver Version: 550.120 CUDA Version: 12.4 |
|-----------------------------------------+------------------------+----------------------+
| GPU Name Persistence-M | Bus-Id Disp.A | Volatile Uncorr. ECC |
| Fan Temp Perf Pwr:Usage/Cap | Memory-Usage | GPU-Util Compute M. |
| | | MIG M. |
|=========================================+========================+======================|
| 0 NVIDIA GeForce RTX 4060 Ti Off | 00000000:01:00.0 Off | N/A |
| 0% 44C P8 10W / 160W | 2MiB / 8188MiB | 0% Default |
| | | N/A |
+-----------------------------------------+------------------------+----------------------+
| 1 Tesla M40 24GB Off | 00000000:05:00.0 Off | Off |
| N/A 32C P8 15W / 250W | 0MiB / 24576MiB | 0% Default |
| | | N/A |
+-----------------------------------------+------------------------+----------------------+
| 2 Tesla M40 24GB Off | 00000000:08:00.0 Off | Off |
| N/A 34C P8 15W / 250W | 0MiB / 24576MiB | 0% Default |
| | | N/A |
+-----------------------------------------+------------------------+----------------------+
+-----------------------------------------------------------------------------------------+
| Processes: |
| GPU GI CI PID Type Process name GPU Memory |
| ID ID Usage |
|=========================================================================================|
| No running processes found |
+-----------------------------------------------------------------------------------------+在容器编排中调用 GPU 则可以参照，只需在你的编排中加入如下内容：
services:
example_srv:
deploy:
resources:
reservations:
devices:
- capabilities:
- gpu
count: all
driver: nvidia
......排错指引
Q: docker run 报错 docker: permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock: Head "http://%2Fvar%2Frun%2Fdocker.sock/_ping": dial unix /var/run/docker.sock: connect: permission denied
给自己添加 Docker 使用权限：
sudo groupadd docker
sudo usermod -aG docker $USERQ: docker run 报错 docker: Error response from daemon: Get "https://registry-1.docker.io/v2/": read: connection reset by peer
网络问题，按照如下步骤给 docker engine 添加代理链接（注意替换自己的代理地址）：
sudo vi /etc/docker/daemon.json
# 此时文件内应该已存在一部分内容比如：
{
"runtimes": {
"nvidia": {
"args": [],
"path": "nvidia-container-runtime"
}
}
}
# 将以下内容与之前内容进行合并：
{
"proxies": {
"http-proxy": "127.0.0.1:7890",
"https-proxy": "127.0.0.1:7890",
"no-proxy": "localhost,127.0.0.0/8,192.168.0.0/16"
}
}
# 最终的样子应该是：
{
"proxies": {
"http-proxy": "127.0.0.1:7890",
"https-proxy": "127.0.0.1:7890",
"no-proxy": "localhost,127.0.0.0/8,192.168.0.0/16"
},
"runtimes": {
"nvidia": {
"args": [],
"path": "nvidia-container-runtime"
}
}
}
# 完成修改后保存并退出
# 重启 Docker Engine
sudo systemctl restart dockerQ: docker run 报错 nvidia-container-cli: requirement error: unsatisfied condition: cuda>=12.4, please update your driver to a newer version, or use an earlier cuda container: unknown
首先在安装驱动时我们运行过 nvidia-smi 指令，这条指令的输出中有写当前驱动所支持的 CUDA 版本。此处 docker run 所使用的测试容器的版本号实际就是容器所调用的 CUDA 版本，这个版本号不能大于你驱动所能支持的版本。
举个例子，我先前 nvidia-smi 命令告诉我的 CUDA 版本是 12.4.0，所以这里我的容器运行命令是
docker run --gpus all --rm nvidia/cuda:12.4.0-base-ubuntu20.04 nvidia-smi，但是如果我使用docker run --gpus all --rm nvidia/cuda:12.8.0-base-ubuntu20.04 nvidia-smi就会报错，因为 12.8.0 大于我驱动所能支持的 12.4.0。你可以在这里找到所有可用的测试容器 Tag：nvidia/cuda Tags