====== qflow gpu 容器版 ubuntu 24.04 安装指南 ======

适用系统：Ubuntu 24.04 LTS\\
包含：qflow gpu 容器版与现有主流容器版 GPU 应用相同，都在运行时依赖 NVIDIA 显卡驱动、Docker、nvidia-container-toolkit，安装qflow gpu 容器版前请先确定您的机器已经安装这些依赖项。本手册中提供了这些依赖项的安装步骤，您可以参考安装。

----

===== 1. 安装 NVIDIA 显卡驱动 =====

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

<code bash>
lspci | grep -i nvidia
</code>

==== 1.2 检查驱动是否已经安装 ====

<code bash>
nvidia-smi
</code>

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

==== 1.3 禁用系统自带的 nouveau 驱动 ====

<code bash>
# 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
</code>

==== 1.4 更新软件源 ====

<code bash>
sudo apt update
</code>

==== 1.5 安装必要工具 ====

<code bash>
sudo apt install -y ubuntu-drivers-common
</code>

==== 1.6 安装指定版本驱动 ====

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

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

==== 1.7 重启系统 ====

<code bash>
sudo reboot
</code>

==== 1.8 验证驱动安装 ====

<code bash>
nvidia-smi
</code>

如果能看到显卡型号、驱动版本、CUDA 版本等信息，说明驱动已成功安装（如下图例所示）：

NVIDIA-SMI 535.309.01 为命令行工具本身的版本号，是用来查询GPU状态的可执行程序；

Driver Version: 535.309.01 是 NVIDIA 显卡内核驱动 的版本号。它是真正掌管GPU硬件、与操作系统内核交互的核心底层程序；

CUDA Version: 12.2 是当前驱动所能支持的最高 CUDA 运行时（Runtime）版本。只要CUDA应用程序（如PyTorch、TensorFlow）依赖的CUDA版本 不超过 12.2，就可以正常调用GPU。

{{:qflow:nvidia-smi.png?400|}}
----

===== 2. 安装 Docker =====

安装前请先确认您的机器是否未安装docker:

<code bash>
docker --version
# 如果输出类似 Docker version 29.6.1, build 8900f1d 信息，则表示已安装docker

systemctl status docker
# 检查检查 Docker 服务是否运行，显示 active (running) ，则不仅安装了，服务也在运行
</code>
==== 2.1 安装必要的依赖 ====

<code bash>
sudo apt update
sudo apt install -y ca-certificates curl
</code>

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

<code bash>
# 1. 创建存放密钥的目录
sudo install -m 0755 -d /etc/apt/keyrings

# 2. 从阿里云镜像站下载并保存 Docker 的 GPG 密钥
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 软件源（同样使用阿里云镜像地址）
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
</code>


==== 2.3 安装 Docker ====

<code bash>
# 再次更新软件包索引
sudo apt update

# 安装 Docker 及其组件
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
</code>

==== 2.4 启动并设置开机自启 ====

<code bash>
sudo systemctl start docker
sudo systemctl enable docker
</code>

==== 2.5 验证安装 ====

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

# 展示类似如下信息则表示安装成功
# Hello from Docker!
# This message shows that your installation appears to be working correctly.

# To generate this message, Docker took the following steps:
#  1. The Docker client contacted the Docker daemon.
#  2. The Docker daemon pulled the "hello-world" image from the Docker Hub. (amd64)
#  3. The Docker daemon created a new container from that image which runs the executable that produces the output you are currently reading.
#  4. The Docker daemon streamed that output to the Docker client, which sent it to your terminal.

#  To try something more ambitious, you can run an Ubuntu container with:
#   $ docker run -it ubuntu bash

</code>

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

<code bash>
sudo usermod -aG docker $USER
</code>

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

----

===== 3. 安装 nvidia-container-toolkit =====

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

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

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

可在服务器直接下载：
<code bash>
wget --user=pwmat --password=SimplyTheBest "http://223.70.160.60:9999/qflow/nvidia-container-toolkit_1.19.1_amd64.deb.tgz"
</code>
==== 3.2 安装 nvidia-container-toolkit ====

<code bash>
tar -zxvf nvidia-container-toolkit_1.19.1_deb_amd64.tgz
cd nvidia-container-toolkit_1.19.1_deb_amd64
sudo dpkg -i *.deb
</code>

==== 3.3 配置 Docker 运行时 ====

<code bash>
sudo nvidia-ctk runtime configure --runtime=docker
</code>

==== 3.4 重启 Docker 服务 ====

<code bash>
sudo systemctl restart docker
</code>

==== 3.5 验证安装 ====

<code bash>
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
</code>

如果容器内能正常输出 ''nvidia-smi'' 信息（如下图所示），说明 nvidia-container-toolkit 安装成功。
{{:qflow:docker-install-check.png?400|}}
===== 4. 开始 qflow gpu 容器版安装 =====

点击链接, 从 ''宿主机安装 server.py 服务'' 开始: [[qflow:quickstart_gpu#宿主机安装 server.py 服务|跳转到宿主机安装 server.py 服务章节]] 跟着文档安装到结尾

~~DISCUSSION:off~~