这是本文档旧的修订版！

qflow gpu 容器版 ubuntu 24.04 安装指南

适用系统：Ubuntu 24.04 LTS
包含：NVIDIA 显卡驱动、Docker、nvidia-container-toolkit

1. 安装 NVIDIA 显卡驱动

1.1 确认系统能识别到 NVIDIA 显卡

lspci | grep -i nvidia

1.2 检查驱动是否已经安装

nvidia-smi

如果能看到显卡型号、驱动版本、CUDA 版本等信息，说明驱动已经安装, 跳过这一步。

1.3 禁用系统自带的 nouveau 驱动

# 1. 先禁用 nouveau
sudo bash -c "echo blacklist nouveau > /etc/modprobe.d/blacklist-nvidia-nouveau.conf"
sudo bash -c "echo options nouveau modeset=0 >> /etc/modprobe.d/blacklist-nvidia-nouveau.conf"
sudo update-initramfs -u
 
# 2. 重启系统(让 nouveau 禁用生效)
sudo reboot

1.4 更新软件源

sudo apt update

1.5 安装必要工具

sudo apt install -y ubuntu-drivers-common

1.6 安装指定版本驱动

# 安装 535 版本驱动（支持 CUDA 12.1 及以上）
sudo ubuntu-drivers install nvidia:535

如需查看系统推荐驱动版本，可先执行 sudo ubuntu-drivers list 参考输出结果。

1.7 重启系统

sudo reboot

1.8 验证驱动安装

nvidia-smi

如果能看到显卡型号、驱动版本、CUDA 版本等信息，说明驱动已成功安装。

2. 安装 Docker

2.1 安装必要的依赖

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

2.2 添加 Docker 的官方 GPG 密钥和软件源（使用国内镜像站）

# 1. 创建存放密钥的目录
sudo install -m 0755 -d /etc/apt/keyrings
 
# 2. 从阿里云镜像站下载并保存 Docker 的 GPG 密钥[citation:5]
sudo curl -fsSL http://mirrors.aliyun.com/docker-ce/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc
 
# 3. 添加 Docker 软件源（同样使用阿里云镜像地址）[citation:5]
echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] http://mirrors.aliyun.com/docker-ce/linux/ubuntu \
  $(. /etc/os-release && echo "${UBUNTU_CODENAME:-$VERSION_CODENAME}") stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

2.3 安装 Docker

# 再次更新软件包索引
sudo apt update
 
# 安装 Docker 及其组件
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

2.2 启动并设置开机自启

sudo systemctl start docker
sudo systemctl enable docker

2.3 验证安装

sudo docker run --rm swr.cn-north-4.myhuaweicloud.com/ddn-k8s/docker.io/hello-world:latest

2.4 （可选）配置非 root 用户权限

sudo usermod -aG docker $USER

注意：需要重新登录或重启会话才能生效。

3. 安装 nvidia-container-toolkit

Ubuntu 24.04 推荐使用 NVIDIA 官方 apt 仓库安装，不再使用已废弃的 apt-key add 方式。

3.1 下载离线包并上传到服务器

链接：http://223.70.160.60:9999/nvidia-container-toolkit_1.19.1_deb_amd64.tgz
用户名：pwmat
密码: SimplyTheBest

3.2 安装 nvidia-container-toolkit

tar -zxvf nvidia-container-toolkit_1.19.1_deb_amd64.tgz
cd nvidia-container-toolkit_1.19.1_deb_amd64
dpkg -i *.deb
<code>
 
==== 3.3 配置 Docker 运行时 ====
 
<code bash>
sudo nvidia-ctk runtime configure --runtime=docker

3.4 重启 Docker 服务

sudo systemctl restart docker

3.5 验证安装

sudo docker run --rm --gpus all swr.cn-north-4.myhuaweicloud.com/ddn-k8s/docker.io/nvidia/cuda:12.4.0-base-ubuntu22.04 nvidia-smi

如果容器内能正常输出 nvidia-smi 信息，说明 nvidia-container-toolkit 安装成功。