GPU 环境准备（CUDA 版）
这个功能解决什么问题
CUDA 版安装脚本不会替你安装 NVIDIA 驱动——驱动是内核级组件，涉及内核模块加载和系统重启，属于服务器管理员的基础环境职责，需要在运行 VortLab 安装之前自行完成。驱动装好之后，容器要用 GPU 还需要一层 nvidia-container-toolkit 把 GPU 接入 Docker。
本页把这些准备工作整理成一份可对照执行的清单。仅 CUDA 版需要；CPU 版部署无需阅读本页。
安装预检会检查什么
CUDA 版在线安装开始时会先跑 GPU 相关预检，任何一项不过都会立即停止安装并给出提示：
| 字段 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
PF-10 GPU 硬件 | 预检项 | 必填 | — | 服务器必须装有 NVIDIA 显卡（通过 PCI 设备探测）。没有 GPU 的机器请向支持人员索取 CPU 安装令牌。 |
PF-11 驱动已加载 | 预检项 | 必填 | — | `nvidia-smi` 必须能正常执行。驱动未安装、或安装后模块未成功加载都会在这里被拦下。 |
PF-12 驱动版本下限 | 预检项 | 必填 | — | 驱动主版本 ≥ 525（对应 CUDA 12.1 支持矩阵；平台镜像基于 CUDA 12.1）。多卡机器取所有卡的最小版本。 |
PF-13 容器 GPU 接线 | 预检项 | 必填 | — | nvidia-container-toolkit 已安装且已接入 Docker（`docker info` 能看到 nvidia runtime）。 |
本页下面几节就是把每道关卡展开成完整操作步骤。
安装前自检清单
逐条执行以下命令，全部通过再开始安装：
确认 GPU 硬件存在
lspci -n | grep -i '10de'有输出即检测到 NVIDIA 显卡（
10de是 NVIDIA 的 PCI 厂商 ID）。无输出说明机器没有 NVIDIA GPU。确认驱动已加载
nvidia-smi正常时会打印 GPU 型号、驱动版本和显存占用的表格。如果报
NVIDIA-SMI has failed、Driver not loaded或couldn't communicate with the NVIDIA driver，说明驱动未安装或未正确加载，见下节。确认驱动版本达标
nvidia-smi --query-gpu=driver_version --format=csv,noheader输出的主版本号需要 ≥ 525。低于 525 请先升级驱动再安装。
确认 Docker 已接入 GPU
docker info | grep -i nvidia有
Runtimes: ... nvidia之类的输出即通过。无输出或命令报错，说明 nvidia-container-toolkit 未安装或未接线，见「安装 nvidia-container-toolkit」一节。
安装 NVIDIA 驱动
安装或升级 NVIDIA 驱动后必须重启服务器才能加载新内核模块。生产环境请提前规划停机窗口；重启不影响已安装的 VortLab 数据，服务会随系统自动拉起。
Ubuntu / Debian（推荐路径）
sudo apt update
sudo ubuntu-drivers install
sudo reboot
ubuntu-drivers install 会自动选择并安装与本机 GPU 和内核匹配的推荐驱动版本。重启后用 nvidia-smi 验证。这也是安装预检失败提示中给出的标准修复命令。
CentOS / RHEL / Rocky / Alma
这些发行版没有等价的 ubuntu-drivers，请通过以下任一途径安装（选择与你的系统版本匹配的包）：
- ELRepo 仓库：启用 elrepo 后安装
kmod-nvidia系列包。 - NVIDIA 官方安装包：在 NVIDIA 驱动下载页 按显卡型号和系统查询，下载
.run安装包按官方说明执行。
安装后重启，用 nvidia-smi 验证。
Secure Boot（安全启动）注意事项
如果服务器启用了 Secure Boot，第三方内核模块（含 NVIDIA 驱动）必须经过 MOK（Machine Owner Key）登记才能加载，否则会出现「驱动显示安装成功、nvidia-smi 却始终失败」的现象。
- Ubuntu 下
ubuntu-drivers install会提示设置一个 MOK 密码。 - 重启时进入蓝色的 MOK Management 菜单，选 Enroll MOK → Continue → 输入刚才设置的密码完成登记。
- 错过了蓝色菜单也没关系：再执行一次驱动安装重新设置密码并重启，或用
mokutil重新发起登记。 - 虚拟化环境（云主机）若不确定，可在固件设置中直接关闭 Secure Boot。
验证方法：mokutil --sb-state（输出 SecureBoot enabled 即需要走 MOK 流程）。
安装 nvidia-container-toolkit
驱动只让宿主机认识 GPU；容器里的训练进程要用 GPU，还需要 nvidia-container-toolkit 把 nvidia runtime 接入 Docker。平台安装脚本不会自动安装它，请提前完成。
Ubuntu / Debian
curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey \
| sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg
curl -fsSL https://nvidia.github.io/libnvidia-container/stable/deb/nvidia-container-toolkit.list \
| sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list
sudo apt-get update
sudo apt-get install -y nvidia-container-toolkit
sudo nvidia-ctk runtime configure --runtime=docker
sudo systemctl restart docker
完成后 docker info | grep -i nvidia 应能看到 nvidia runtime。
CentOS / RHEL / Rocky
使用 NVIDIA 官方 yum 仓库安装同名包（仓库地址见 NVIDIA Container Toolkit 官方文档），随后同样执行 nvidia-ctk runtime configure --runtime=docker 并重启 Docker。
可选：容器 GPU 冒烟测试
docker run --rm --gpus all nvidia/cuda:12.1.1-base-ubuntu22.04 nvidia-smi
容器内能打印出 GPU 表格，说明「驱动 → toolkit → Docker」全链路通畅（会拉取约 100MB 测试镜像）。跳过此步也可以，安装预检的 PF-13 会做等价检查。
常见问题
驱动未安装、或安装后内核模块没有成功加载。两种最常见的情况：
- 从没装过驱动：按上文「安装 NVIDIA 驱动」操作。
- 之前是好的，系统更新后坏了：
apt upgrade升级内核后 DKMS 没有为新内核编译 NVIDIA 模块。重新执行一遍驱动安装（如sudo ubuntu-drivers install）并重启即可。
先重启一次再验证——部分安装流程本来就需要重启才能加载模块。
升级路径与全新安装相同（Ubuntu 用 sudo ubuntu-drivers install，会自动装较新的推荐版本；其他发行版用对应包管理器）。升级后重启，再用 nvidia-smi --query-gpu=driver_version --format=csv,noheader 复核主版本 ≥ 525。
服务器场景通常没有桌面环境，nvidia-smi 就是验证手段——它能打印出 GPU 表格即代表驱动工作正常，与显示输出无关。
在线安装的预检（PF-10 ~ PF-13）与本页清单一一对应，即使跳过本页直接安装，问题也会在拉取镜像之前被拦下并给出提示——只是提前照本页准备可以一次通过。