TencentOS Server 4.0 GCE 自定义镜像构建手册

本手册记录了如何在 Google Compute Engine (GCE) 上构建并物理验证 TencentOS Server 4.0 ARM64 (Linux 6.6 核心) 的自适应系统镜像,专门针对 NVIDIA Blackwell GB200/GB300 高性能加速实例进行深入优化,集成了 NVIDIA Open R580 驱动与 IMEX 高速集群组件。GCP A4X 采用 Shared NVSwitch 虚拟化架构,NVSwitch 由 hypervisor Service VM 管理,Guest VM 无需运行 Fabric Manager。

为何编写本指南?
在 Enterprise Linux 9 / TencentOS 4.0 系统架构中,GCE 官方预编译包有已知的共享库版本不兼容问题:Google 客体环境包依赖 libboost_regex.so.1.75.0,而 TencentOS 4.0 官方发行版仅集成 libboost_regex.so.1.82.0。同时,OS Login 核心缓存服务(google_oslogin_nss_cache)具有对 Rocky 9 标准 libicu 67 系列硬编码链接依赖,而系统只带有最新的 libicu 71/72,这会导致该服务因动态链接错误而挂起或以 127 状态崩溃,阻断 SSH via IAP 授权登录。本指南包含了完整的宿主机包提取和 chroot 注入解决方案。

全局环境变量设置

在构建宿主机环境(GCE ARM64 虚拟机)中,在开始操作前首先声明以下环境变量。本构建过程所需的环境变量已被放于最上方,读者在设置这些变量后,后续命令行拷贝均可无缝粘贴直接执行。

构建环境变量声明

export PROJECT_ID="gpu-launchpad-playground"
export ZONE="us-central1-f"
export BUILDER_VM="tlinux-builder-v5"
export DISK_DEVICE="/dev/nvme0n2"
export MOUNT_DIR="/mnt/target"
export IMAGE_NAME="tlinux-server-4-gb200-v5"
export SNAPSHOT_NAME="tlinux-v4-snap-v5"
export NVIDIA_VERSION="580.159.04"
export NVIDIA_CUDA_REPO="https://developer.download.nvidia.com/compute/cuda/repos/rhel9/sbsa"

0. 准备工作:Builder VM 创建与客户 qcow2 导入

当客户提供 qcow2 格式的预制镜像(包含定制内核、预装软件等),需要先创建 ARM64 Builder VM 作为构建宿主机,然后将 qcow2 内容导入 GCE 目标磁盘。此步骤替代了传统的 dnf installroot 从零安装流程。

0a. 创建 ARM64 Builder VM

# 1. 创建 ARM64 构建宿主机(Rocky Linux 9,至少 200GB boot 盘以容纳 qcow2 转换空间)
gcloud compute instances create "$BUILDER_VM" \
    --project="$PROJECT_ID" --zone="$ZONE" \
    --machine-type=t2a-standard-8 \
    --image-family=rocky-linux-9-optimized-gcp-arm64 \
    --image-project=rocky-linux-cloud \
    --boot-disk-size=200GB --boot-disk-type=pd-ssd \
    --scopes=cloud-platform

# 2. 创建 50GB 目标数据磁盘(最终封装为 GCE 镜像)
gcloud compute disks create "tlinux-root-disk-v5" \
    --project="$PROJECT_ID" --zone="$ZONE" \
    --size=50GB --type=pd-ssd

# 3. 挂载目标磁盘到 Builder VM
gcloud compute instances attach-disk "$BUILDER_VM" \
    --disk="tlinux-root-disk-v5" \
    --zone="$ZONE" --project="$PROJECT_ID"

0b. qcow2 转换与文件系统挂载

为何不直接 gcloud compute images create --source-uri?
GCE images create 的 --source-uri 要求 tar.gz 内含名为 disk.raw 的完整磁盘映像(含 GPT 分区表)。客户 qcow2 通常使用单分区布局、无 ESP、且可能缺少 GCE 所需的 UEFI GRUB 配置。因此我们使用"分区 + rsync"方式,可完全控制分区布局和引导链。
# SSH 到 Builder VM 后执行以下操作

# 1. 安装必要工具
sudo dnf install -y qemu-img rsync parted gdisk xfsprogs wget curl

# 2. 上传 qcow2 文件到 Builder VM(从本地或 GCS)
# 方式 A:通过 gcloud scp 从本地上传
gcloud compute scp TencentOS-Server-*.qcow2 "$BUILDER_VM":/tmp/ \
    --zone="$ZONE" --project="$PROJECT_ID" --tunnel-through-iap

# 方式 B:从 GCS 下载
# gsutil cp gs://your-bucket/TencentOS-Server-*.qcow2 /tmp/

# 3. 将 qcow2 转换为 raw 格式以便 loop 挂载
sudo qemu-img convert -f qcow2 -O raw /tmp/TencentOS-Server-*.qcow2 /tmp/tlinux.raw

# 4. 挂载 raw 磁盘映像(需先检测分区偏移)
LOOP_DEV=$(sudo losetup --show -fP /tmp/tlinux.raw)
echo "Loop device: $LOOP_DEV"
lsblk "$LOOP_DEV"

# 5. 挂载 qcow2 的根分区(通常是 p1 或 p2,视分区表而定)
sudo mkdir -p /mnt/qcow2
sudo mount "${LOOP_DEV}p1" /mnt/qcow2  # 单分区 qcow2 通常只有 p1
qcow2 分区检查要点
客户 qcow2 可能使用 MBR(单分区)或 GPT(含 ESP)分区。使用 lsblk $LOOP_DEV 和 fdisk -l $LOOP_DEV 检查。如 qcow2 已含 ESP 分区和完整引导链,可考虑直接转换为 GCE 镜像;否则按本指南 Step 1 重新分区后 rsync 内容。

1. 磁盘分区与文件系统准备

在附加的 50GB 数据盘上建立 GPT 分区表,并规划独立的 UEFI 引导系统分区 (ESP, 格式化为 FAT32) 与主系统挂载根分区 (格式化为 XFS)。

# 1. 宿主机安装格式化与文件系统工具
sudo dnf install -y parted gdisk xfsprogs wget curl

# 2. 将目标副盘进行 GPT 分区,规划 EFI 引导分区 (512MB) 和系统根分区 (其余全部空间)
sudo parted -s "$DISK_DEVICE" mklabel gpt
sudo parted -s "$DISK_DEVICE" mkpart primary fat32 1MiB 513MiB
sudo parted -s "$DISK_DEVICE" set 1 esp on
sudo parted -s "$DISK_DEVICE" mkpart primary xfs 513MiB 100%

# 3. 强制内核刷新分区表缓存
sudo partprobe "$DISK_DEVICE"
sleep 3

# 4. 格式化 EFI 分区 (FAT32) 与系统根分区 (XFS)
sudo mkfs.vfat -F32 "${DISK_DEVICE}p1"
sudo mkfs.xfs -f "${DISK_DEVICE}p2"

# 5. 挂载至宿主临时工作目录
sudo mkdir -p "$MOUNT_DIR"
sudo mount "${DISK_DEVICE}p2" "$MOUNT_DIR"
sudo mkdir -p "$MOUNT_DIR/boot/efi"
sudo mount "${DISK_DEVICE}p1" "$MOUNT_DIR/boot/efi"

2. 基础系统安装

根据镜像来源选择安装方式:如从零构建选择 2a (dnf installroot),如有客户 qcow2 选择 2b (rsync 复制)。

2a. dnf installroot 方式(从零构建)

通过配置 TencentOS 官方高性能软件源,利用 dnf installroot 命令跨盘部署 TencentOS Server 4.0 基础系统和必要的编译依赖包。

# 1. 在宿主机上创建腾讯云临时镜像配置源
cat <<EOF | sudo tee /tmp/tlinux4.repo
[tlinux4-baseos]
name=TencentOS Server 4.0 BaseOS
baseurl=https://mirrors.tencent.com/tlinux/4.0/BaseOS/aarch64/os/
enabled=1
gpgcheck=0
retries=20

[tlinux4-appstream]
name=TencentOS Server 4.0 AppStream
baseurl=https://mirrors.tencent.com/tlinux/4.0/AppStream/aarch64/os/
enabled=1
gpgcheck=0
retries=20
EOF

# 2. 调用 dnf installroot 在目标盘中构建核心操作系统
sudo dnf -y --installroot="$MOUNT_DIR" --config=/tmp/tlinux4.repo --releasever=4.0 \
    --disablerepo="*" --enablerepo="tlinux4-*" \
    --setopt=max_parallel_downloads=1 \
    install \
    systemd kernel kernel-core kernel-modules kernel-devel kernel-headers \
    grub2-efi-aa64 shim-aa64 efibootmgr dnf iproute passwd \
    openssh-server openssh-clients NetworkManager tar gzip git make gcc \
    elfutils-libelf-devel binutils kmod pciutils lshw wget curl lsof rsync tmux \
    rdma-core rdma-core-devel librdmacm librdmacm-utils libibverbs ucx-ib mstflint

2b. 从客户 qcow2 复制系统(推荐用于客户定制内核)

当客户提供包含定制内核的 qcow2 时,使用 rsync 将内容直接复制到目标磁盘。此方式保留了客户内核和预装软件。

# 前置条件:Step 0 已完成 qcow2 挂载(/mnt/qcow2),Step 1 已完成磁盘分区($MOUNT_DIR)

# 1. 将 qcow2 根文件系统完整 rsync 到目标磁盘
sudo rsync -aHAXx --info=progress2 /mnt/qcow2/ "$MOUNT_DIR/"

# 2. 卸载 qcow2 环回挂载
sudo umount /mnt/qcow2
sudo losetup -d "$LOOP_DEV"

# 3. 可选:清理 raw 文件节省空间
rm -f /tmp/tlinux.raw
rsync 后必须检查的关键项目

3. Chroot 环境初始化与系统修复

将宿主机的底层虚拟 API 设备(/dev, /proc, /sys 等)绑定映射进入客体环境磁盘,确保 UEFI 内核启动及配置重建所需的特权上下文。

# 1. 绑定挂载虚拟设备接口
sudo mount --bind /dev "$MOUNT_DIR/dev"
sudo mount --bind /dev/pts "$MOUNT_DIR/dev/pts"
sudo mount --bind /proc "$MOUNT_DIR/proc"
sudo mount --bind /sys "$MOUNT_DIR/sys"
sudo mount --bind /sys/firmware/efi/efivars "$MOUNT_DIR/sys/firmware/efi/efivars" || true

# 2. 同步 DNS 文件与软件源
sudo cp /etc/resolv.conf "$MOUNT_DIR/etc/resolv.conf"
sudo mkdir -p "$MOUNT_DIR/etc/yum.repos.d"
sudo cp /tmp/tlinux4.repo "$MOUNT_DIR/etc/yum.repos.d/tlinux4.repo"

FSTAB & GRUB / BLS 配置重构

进入 Chroot Jail 内部,根据设备的分区 UUID 构建正确的启动挂载体系,并消除从宿主机上残留拷贝下的 BLS / Grub 宿主 Root UUID 泄漏 Bug。

sudo chroot "$MOUNT_DIR" /bin/bash <<'EOF'
set -ex

# 1. 读取各分区真实的 UUID 并写入 fstab
ROOT_UUID=$(blkid -o value -s UUID /dev/nvme0n2p2)
EFI_UUID=$(blkid -o value -s UUID /dev/nvme0n2p1)

cat <<FSTAB_CFG > /etc/fstab
UUID=$ROOT_UUID / xfs defaults 0 0
UUID=$EFI_UUID /boot/efi vfat defaults,uid=0,gid=0,umask=0077,shortname=winnt 0 2
FSTAB_CFG

# 2. 重置 Grub 全局配置,声明 GCE Aarch64 PL011 虚拟串口终端并屏蔽 nouveau 开源显卡驱动
cat <<'GRUB_CFG' > /etc/default/grub
GRUB_TIMEOUT=5
GRUB_DISTRIBUTOR="TencentOS"
GRUB_DEFAULT=saved
GRUB_DISABLE_SUBMENU=true
GRUB_TERMINAL_OUTPUT="console"
GRUB_CMDLINE_LINUX="console=ttyAMA0,115200 earlycon=pl011,mmio32,0x09000000 rd.driver.blacklist=nouveau modprobe.blacklist=nouveau nvme_core.io_timeout=255"
GRUB_DISABLE_RECOVERY="true"
GRUB_ENABLE_BLSCFG=false
GRUB_CFG

EOF
BLS 引导必须禁用
必须设置 GRUB_ENABLE_BLSCFG=false。dnf --installroot 安装的内核不会自动创建 BLS 入口文件(/boot/loader/entries/*.conf),且不会将 vmlinuz 复制到 /boot/。禁用 BLS 后,grub2-mkconfig 直接扫描 /boot/vmlinuz-* 生成 menuentry。

内核引导文件生成

dnf --installroot 将 vmlinuz 放置在 /lib/modules/<ver>/vmlinuz 而非 /boot/,也不会生成 initramfs。需手动复制并生成引导文件后,再构建 GRUB 配置。

# 从 host 侧检测内核版本(chroot 内 rpm -q kernel 不可靠)
KERNEL_VER=$(ls "$MOUNT_DIR/lib/modules/" | head -1)
echo "Detected kernel: $KERNEL_VER"

# 复制 vmlinuz 并生成 initramfs,然后构建 GRUB 配置
sudo chroot "$MOUNT_DIR" /bin/bash <<CHROOT_BOOT
set -ex
cp /lib/modules/${KERNEL_VER}/vmlinuz /boot/vmlinuz-${KERNEL_VER}
dracut --force /boot/initramfs-${KERNEL_VER}.img ${KERNEL_VER}
grub2-mkconfig -o /boot/grub2/grub.cfg
CHROOT_BOOT
Heredoc 变量展开规则
此处使用不带引号的 heredoc(<<CHROOT_BOOT),使 ${KERNEL_VER} 在 host 侧展开后传入 chroot。如使用带引号 heredoc(<<'CHROOT_BOOT'),变量不会展开,导致 chroot 内引用空值。后续 Step 5 驱动编译同理。

3c. Cloud-init 处理与网络配置修复(qcow2 源必须)

客户 qcow2 通常配置了 cloud-init 连接腾讯云元数据服务 (169.254.0.23),而 GCE 使用 169.254.169.254。cloud-init 会干扰 NetworkManager、阻塞 sshd 密钥生成。此步骤彻底禁用 cloud-init 并配置 GCE 兼容的网络。

sudo chroot "$MOUNT_DIR" /bin/bash <<'EOF'
set -ex

# ===== 1. 彻底禁用 cloud-init =====
# 创建禁用标记文件
touch /etc/cloud/cloud-init.disabled

# 禁用 cloud-init 管理网络
mkdir -p /etc/cloud/cloud.cfg.d
cat > /etc/cloud/cloud.cfg.d/99-disable-network-config.cfg <<'CLOUDINIT'
network: {config: disabled}
CLOUDINIT

# Mask 所有 cloud-init 服务
for svc in cloud-init.service cloud-init-local.service cloud-config.service cloud-final.service cloud-init.target; do
    systemctl mask "$svc" 2>/dev/null || true
done

# ===== 2. SSH 端口与密钥生成修复 =====
# 确保 sshd 监听标准端口 22(客户 qcow2 可能配置了 36000/56000)
sed -i 's/^Port .*/Port 22/' /etc/ssh/sshd_config
# 如果没有 Port 行则添加
grep -q "^Port " /etc/ssh/sshd_config || echo "Port 22" >> /etc/ssh/sshd_config

# Mask 客户自定义的非标端口 sshd 服务
systemctl mask sshd-56000.service 2>/dev/null || true

# 修复 sshd-keygen 的 cloud-init 条件阻塞
# cloud-init.target 被 mask 后,sshd-keygen 的 ConditionPathExists 检查会误判
for algo in rsa ecdsa ed25519; do
    mkdir -p "/etc/systemd/system/sshd-keygen@${algo}.service.d"
    cat > "/etc/systemd/system/sshd-keygen@${algo}.service.d/override.conf" <<'OVERRIDE'
[Unit]
ConditionPathExists=
OVERRIDE
done

# ===== 3. NetworkManager GVNIC 网络配置 =====
# GCE A4X 的第一块 GVNIC 接口名为 enp0s3(不是 eth0)
cat > /etc/NetworkManager/system-connections/enp0s3-gvnic.nmconnection <<'NMCONN'
[connection]
id=enp0s3-gvnic
type=ethernet
interface-name=enp0s3
autoconnect=true
autoconnect-priority=100

[ipv4]
method=auto

[ipv6]
method=auto
NMCONN
chmod 600 /etc/NetworkManager/system-connections/enp0s3-gvnic.nmconnection

# 全局自动连接配置
cat > /etc/NetworkManager/conf.d/99-dhcp-all.conf <<'NMDHCP'
[main]
no-auto-default=
autoconnect-retries-default=2

[device]
match-device=type:ethernet
managed=1
NMDHCP

EOF
关键:cloud-init 与 sshd 的依赖链
在 TencentOS 4.0 的 systemd 中,sshd-keygen@.service 包含条件 ConditionPathExists=!/run/systemd/generator.early/multi-user.target.wants/cloud-init.target。当 cloud-init.target 被 mask(链接到 /dev/null)后,systemd generator 不会在该路径创建文件,但条件检查行为取决于具体版本。上述 override 通过清空条件确保密钥总是会被生成。

4. GCE 客体环境 Agent 依赖注入与修复

为确保云端虚拟机元数据交互、自动化 SSH 公钥同步(SSH via IAP)能够顺畅运作,在此模块中进行最关键的 boost-regex 及 libicu 67 基础组件的离线解包与注入。

关于 OS Login ICU 67 链接库缺失的修复(核心点)
由 Google 预编译构建的 Enterprise Linux 9 OS Login NSS 缓存器 (google_oslogin_nss_cache) 强制硬编码链接了 Rocky 9 底层的 libicu*.so.67。而 TencentOS Server 4.0 底层使用的是更高版本的 ICU 共享库(v71/72)。由于大版本更新间 ABI 函数入口签名已经发生了彻底改变,直接使用软链接欺骗(ln -s libicu.so.71 libicu.so.67)会引起符号解析运行时彻底崩溃!

为此,我们必须在 Rocky Linux 9.7 宿主机上,下载标准的 libicu 软件包,提取原生编译的库,然后直接复制同步到目标 chroot 系统的 /usr/lib64 下解决此动态装载器缺陷。
# 1. 宿主机下载 Rocky 9 的 boost-regex 包并注入目标盘
# 注:直接 wget URL 可能因版本更新返回 404,改用 dnf download 从宿主机 repo 获取
dnf download boost-regex --destdir=/tmp
BOOST_RPM=$(ls /tmp/boost-regex-*.aarch64.rpm | head -1)
sudo cp "$BOOST_RPM" "$MOUNT_DIR/tmp/"
sudo chroot "$MOUNT_DIR" rpm -ivh --nodeps /tmp/$(basename "$BOOST_RPM")
sudo rm -f "$MOUNT_DIR/tmp/$(basename "$BOOST_RPM")"

# 2. 宿主机动态下载 Rocky 9.7 的 libicu 67,解包并把 so 文件注入 chroot
dnf download libicu --destdir=/tmp || yumdownloader libicu --destdir=/tmp
mkdir -p /tmp/icu67-extract
rpm2cpio /tmp/libicu-67.1-*.el9_*.aarch64.rpm | cpio -idmv -D /tmp/icu67-extract/
sudo cp -d /tmp/icu67-extract/usr/lib64/libicu*.so.67* "$MOUNT_DIR/usr/lib64/"
rm -rf /tmp/icu67-extract /tmp/libicu-67.1-*.el9_*.aarch64.rpm

# 3. 进入 chroot 内部署 Google Compute Environment
sudo chroot "$MOUNT_DIR" /bin/bash <<'EOF'
set -ex

# 4. 验证 OS Login NSS 缓存依赖动态库是否已彻底补全
ldd /usr/bin/google_oslogin_nss_cache

# 5. 配置 GCE Agent Yum 软件源
cat <<'GCREPO' > /etc/yum.repos.d/google-cloud.repo
[google-compute-engine]
name=Google Compute Engine
baseurl=https://packages.cloud.google.com/yum/repos/google-compute-engine-el9-aarch64-stable
enabled=1
gpgcheck=0

[google-cloud-sdk]
name=Google Cloud SDK
baseurl=https://packages.cloud.google.com/yum/repos/cloud-sdk-el9-aarch64
enabled=1
gpgcheck=0
GCREPO

# 6. 安装 GCE 核心进程组件
dnf install -y google-compute-engine google-guest-agent google-osconfig-agent

# 7. 配置开机自启动依赖进程
systemctl enable NetworkManager
systemctl enable sshd
systemctl enable google-guest-agent google-startup-scripts google-shutdown-scripts google-osconfig-agent

EOF

5. NVIDIA GPU 开放内核驱动模块编译

在 Chroot 内部编译并注册适用于 TencentOS Server 4.0 6.6 内核环境的 OpenGPU 驱动核心模块。

编译类型说明
对于 Blackwell GB200/GB300 高级多节点卡,其高速互联架构和定制的 TCPXo 多网卡 DMA-BUF 处理体系要求驱动必须带有 --kernel-module-type=open 开放类型参数,传统的闭源驱动在底层协议支持上可能会遭遇阻塞或吞吐异常。
# 1. 在 host 侧下载驱动(约 314MB)
wget -O "$MOUNT_DIR/tmp/nvidia.run" \
    "https://us.download.nvidia.com/tesla/${NVIDIA_VERSION}/NVIDIA-Linux-aarch64-${NVIDIA_VERSION}.run"

# 2. 内核版本已在 Step 3 通过 ls /lib/modules/ 获取($KERNEL_VER)
# 使用不带引号 heredoc 让 $KERNEL_VER 在 host 侧展开
sudo chroot "$MOUNT_DIR" /bin/bash <<CHROOT_NVIDIA
set -ex

# 3. 向系统写入 Nouveau 开源显卡屏蔽参数
cat > /etc/modprobe.d/blacklist-nouveau.conf <<'NOUVEAU'
blacklist nouveau
options nouveau modeset=0
NOUVEAU

echo "Building NVIDIA open driver against kernel: ${KERNEL_VER}"

# 4. 执行无人值守的开放内核编译
sh /tmp/nvidia.run \
    --silent \
    --no-questions \
    --accept-license \
    --kernel-module-type=open \
    --kernel-name="${KERNEL_VER}" \
    --kernel-source-path="/lib/modules/${KERNEL_VER}/build" \
    --utility-prefix=/usr \
    --opengl-prefix=/usr

rm -f /tmp/nvidia.run

# 5. 验证驱动模块为 Open 类型
for mod in nvidia nvidia-modeset nvidia-uvm nvidia-drm nvidia-peermem; do
    modfile=\$(find /lib/modules/${KERNEL_VER} -name "\${mod}.ko*" 2>/dev/null | head -1)
    if [ -n "\$modfile" ]; then
        license=\$(modinfo -F license "\$modfile" 2>/dev/null || echo "unknown")
        echo "  \${mod}: \${license}"
    fi
done
CHROOT_NVIDIA

5b. GVE GVNIC 驱动编译(自定义内核必须)

GCE A4X 使用 Google Virtual Ethernet (GVE/GVNIC) 作为网络接口。客户定制内核自带的 GVE 驱动版本可能过旧(如 v1.0.0),无法与 GCP GVNIC 硬件正常通信(串口日志表现为 AQ commands timed out, need to reset AQ 和 Could not verify driver compatibility)。必须从 Google 官方仓库编译最新版本。

为何不能直接编译?
Google GVE 最新源码使用了 Linux 6.8+ 新增的内核 API(netdev_queue_mgmt_ops、netdev_stat_ops、netmem_tx、netdev_lock 等)。仓库提供了 Coccinelle 语义补丁来实现向后兼容,但 Rocky Linux 9 aarch64 无法直接安装 coccinelle 包。解决方案:使用 podman + Fedora 容器运行 coccinelle。
# 在 Builder VM(host 侧,非 chroot)执行

# 1. 安装 podman 和 git
sudo dnf install -y podman git

# 2. 克隆 Google GVE 驱动源码
cd /tmp
git clone https://github.com/GoogleCloudPlatform/compute-virtual-ethernet-linux.git

# 3. 在 Fedora 容器中运行 coccinelle 补丁 + 生成兼容源码
podman run --rm -v /tmp/compute-virtual-ethernet-linux:/src:Z fedora:41 bash -c '
  dnf install -y coccinelle make
  cd /src
  bash build_src.sh --target=oot --version=1.4.10
'

# 4. 将打好补丁的源码复制到 chroot 内
sudo cp -r /tmp/compute-virtual-ethernet-linux/build "$MOUNT_DIR/tmp/gve-build"

# 5. 在 chroot 内编译 GVE 模块
KERNEL_VER=$(ls "$MOUNT_DIR/lib/modules/" | head -1)
sudo chroot "$MOUNT_DIR" bash -c "
  cd /tmp/gve-build
  make BUILD_KERNEL=$KERNEL_VER
"

# 6. 安装新 GVE 模块(替换旧版本)
GVE_DIR="$MOUNT_DIR/lib/modules/$KERNEL_VER/kernel/drivers/net/ethernet/google/gve"
sudo mkdir -p "$GVE_DIR"
# 备份旧模块
sudo mv "$GVE_DIR/gve.ko.xz" "$GVE_DIR/gve.ko.xz.bak" 2>/dev/null || true
sudo mv "$GVE_DIR/gve.ko" "$GVE_DIR/gve.ko.bak" 2>/dev/null || true
# 安装新模块
sudo cp "$MOUNT_DIR/tmp/gve-build/gve.ko" "$GVE_DIR/gve.ko"

# 7. 更新模块依赖并重建 initramfs
sudo chroot "$MOUNT_DIR" bash -c "
  depmod -a $KERNEL_VER
  dracut --force --kver $KERNEL_VER
"

# 8. 清理编译残留
sudo rm -rf "$MOUNT_DIR/tmp/gve-build"
验证方式
启动 VM 后在串口日志中应看到 GVE version 1.4.10-oot 和 Driver is running with DQO RDA queue format。modinfo gve 应显示 version: 1.4.10-oot。

6. NVIDIA IMEX 部署(无 Fabric Manager)

Blackwell GPU 节点的跨物理卡高速 NVLink 通信需要 IMEX 通道进程。GCP A4X 采用 Shared NVSwitch 虚拟化架构,NVSwitch 由 hypervisor Service VM 管理,Guest VM 无需也不应运行 Fabric Manager(GCP 官方 Rocky Linux 10 GPU 镜像亦不包含 FM)。

# 1. 从 NVIDIA CUDA 仓库下载 nvidia-modprobe(IMEX 的 RPM 依赖)
wget -O "$MOUNT_DIR/tmp/nvidia-modprobe.rpm" \
    "${NVIDIA_CUDA_REPO}/nvidia-modprobe-${NVIDIA_VERSION}-1.el9.aarch64.rpm"
sudo chroot "$MOUNT_DIR" rpm -ivh --nodeps /tmp/nvidia-modprobe.rpm

# 2. 下载并安装 IMEX
wget -O "$MOUNT_DIR/tmp/nvidia-imex.rpm" \
    "${NVIDIA_CUDA_REPO}/nvidia-imex-${NVIDIA_VERSION}-1.el9.aarch64.rpm"

sudo chroot "$MOUNT_DIR" /bin/bash <<'EOF'
set -ex
dnf localinstall -y /tmp/nvidia-imex.rpm

# 3. 针对 Blackwell 写入 IMEX 通道标志参数
echo "options nvidia NVreg_CreateImexChannel0=1" > /etc/modprobe.d/nvidia-imex.conf

# 4. 激活 IMEX 服务开机预加载
systemctl enable nvidia-imex

rm -f /tmp/nvidia-imex.rpm /tmp/nvidia-modprobe.rpm
EOF

7. 临时文件清理与系统安全卸载

为保证最终制作的 GCP 虚拟机镜像干净无泄漏,请务必删除 chroot 时产生的所有临时 DNS 文件与宿主机软件仓库残余缓存,并按树状依赖干净地进行递归 umount 强制断开,从而避免镜像中根文件系统损坏或残留设备锁。

# 1. 彻底清除 Chroot 产生的临时交互配置文件
sudo rm -f "$MOUNT_DIR/etc/resolv.conf"
sudo rm -f "$MOUNT_DIR/etc/yum.repos.d/tlinux4.repo"

# 2. 依次强制递归卸载底层 API 设备树和 EFI / 主系统根分区
sudo umount /mnt/tlinux/sys/firmware/efi/efivars || true
sudo umount /mnt/tlinux/sys || true
sudo umount /mnt/tlinux/proc || true
sudo umount /mnt/tlinux/dev/pts || true
sudo umount /mnt/tlinux/dev || true
sudo umount /mnt/tlinux/boot/efi || true
sudo umount /mnt/tlinux || true

# 3. 验证是否仍有残留的任何活动挂载锁
mount | grep /mnt/tlinux || echo "Success: 磁盘已完全安全卸载,状态为干净的可卸载态"

8. GCP 虚拟机镜像封装与配置

卸载完成后,便可在本地 GCP 控制端命令行中,将宿主上的 50GB 数据副盘进行快照抓取,并通过声明高吞吐低延迟等网络特征(GVNIC, IDPF)完成自定义系统镜像的最后生成。

# 1. 抓取格式化完成的副盘,创建持久性快照
gcloud compute snapshots create "$SNAPSHOT_NAME" \
    --project="$PROJECT_ID" \
    --source-disk="tlinux-root-disk" \
    --source-disk-zone="$ZONE" \
    --storage-location="us"

# 2. 通过快照生成支持 UEFI 固件与下一代千兆 GVNIC / IDPF 网卡特性的自定义 ARM64 系统镜像
gcloud compute images create "$IMAGE_NAME" \
    --project="$PROJECT_ID" \
    --source-snapshot="$SNAPSHOT_NAME" \
    --guest-os-features="UEFI_COMPATIBLE,GVNIC,IDPF" \
    --architecture="ARM64" \
    --storage-location="us"

9. A4X GPU 虚拟机部署与完整验证

完整验证需要在 A4X GPU 实例上进行。以下包含 A4X VM 创建命令和全面的硬件自检清单。

创建 A4X GPU 测试虚拟机

A4X VM 创建注意事项
# 环境变量(根据实际集群调整)
export A4X_ZONE="us-east1-d"
export RESERVATION="nvidia-gb200-z4pzosg110ik8"
export PLACEMENT_POLICY="a4x-nvl72-policy"
export GVNIC_NET="gke-hzchen-a4x-poc-gvnic-net"
export GVNIC_SUB="gke-hzchen-a4x-poc-gvnic-sub"
export GVNIC_NET_1="gke-hzchen-a4x-poc-gvnic-net-1"
export GVNIC_SUB_1="gke-hzchen-a4x-poc-gvnic-sub-1"
export RDMA_NET="forrest-rdma-net-us-east1-d"

gcloud compute instances create tlinux-v5-test \
    --project="$PROJECT_ID" --zone="$A4X_ZONE" \
    --machine-type=a4x-highgpu-4g \
    --image="$IMAGE_NAME" --image-project="$PROJECT_ID" \
    --boot-disk-size=200GB --boot-disk-type=hyperdisk-balanced \
    --scopes=cloud-platform \
    --reservation-affinity=specific --reservation="$RESERVATION" \
    --provisioning-model=RESERVATION_BOUND \
    --instance-termination-action=STOP \
    --maintenance-policy=TERMINATE \
    --restart-on-failure \
    --resource-policies="$PLACEMENT_POLICY" \
    --network-interface=nic-type=GVNIC,network=$GVNIC_NET,subnet=$GVNIC_SUB \
    --network-interface=nic-type=GVNIC,network=$GVNIC_NET_1,subnet=$GVNIC_SUB_1,no-address \
    --network-interface=nic-type=MRDMA,network=$RDMA_NET,subnet=forrest-rdma-sub-${A4X_ZONE}-0,no-address \
    --network-interface=nic-type=MRDMA,network=$RDMA_NET,subnet=forrest-rdma-sub-${A4X_ZONE}-1,no-address \
    --network-interface=nic-type=MRDMA,network=$RDMA_NET,subnet=forrest-rdma-sub-${A4X_ZONE}-2,no-address \
    --network-interface=nic-type=MRDMA,network=$RDMA_NET,subnet=forrest-rdma-sub-${A4X_ZONE}-3,no-address

完整硬件自检清单

A4X 启动需要约 2-3 分钟(PCI 枚举 GPU/NVSwitch 设备较多)。通过串口日志确认 GVE 加载后再 SSH。

  1. 串行控制台检查 GVE 和网络

    # 检查串口日志确认 GVE 驱动加载和网络就绪
    gcloud compute instances get-serial-port-output tlinux-v5-test \
        --project="$PROJECT_ID" --zone="$A4X_ZONE" 2>&1 | \
        grep -i 'gve\|enp0s3\|google_guest_agent'
    # 期望: "GVE version 1.4.10-oot" + "DQO RDA queue format"
  2. SSH 登录并执行完整自检

    # 确保 IAP 防火墙规则存在
    gcloud compute firewall-rules create allow-ssh-iap-gvnic \
        --project="$PROJECT_ID" \
        --network="$GVNIC_NET" \
        --allow=tcp:22 \
        --source-ranges=35.235.240.0/20 2>/dev/null || true
    
    # SSH via IAP
    gcloud compute ssh tlinux-v5-test \
        --project="$PROJECT_ID" --zone="$A4X_ZONE" \
        --tunnel-through-iap
  3. GPU 与驱动验证

    # A. 内核版本
    uname -r
    # 期望: 6.6.119-49.101.nvidia.tl4.aarch64
    
    # B. GPU 可见性 — 4x NVIDIA GB200,每张 189GB HBM3e
    nvidia-smi -L
    nvidia-smi --query-gpu=driver_version,gpu_name,memory.total --format=csv,noheader
    # 期望: 580.159.04, NVIDIA GB200, 189471 MiB (×4)
    
    # C. NVIDIA 内核模块(Open 类型)
    lsmod | grep nvidia
    # 期望: nvidia, nvidia_uvm, nvidia_drm, nvidia_modeset
    # 注意: nvidia_peermem 在 A4X 上不可用(正常,使用 GIB 插件)
    
    # D. GVE 驱动版本
    modinfo gve | grep version
    # 期望: version: 1.4.10-oot
  4. 网络与 RDMA 验证

    # E. 网络接口 — 2x GVNIC (ip link 可见) + 4x MRDMA (仅 rdma link 可见)
    ip -brief addr show
    # 期望: enp0s3 (GVNIC), enp192s2 (GVNIC-1)
    # 注意: MRDMA VF 为纯 RDMA 设备,不创建 Linux 网络接口,ip link 中不会显示
    
    # F. RDMA 链路 — 4x mlx5 ACTIVE (验证 RDMA 设备)
    rdma link show
    # 期望: mlx5_0..3/1 state ACTIVE physical_state LINK_UP
  5. 系统服务验证

    # G. GCE Guest Agent
    systemctl is-active google-guest-agent
    # 期望: active
    
    # H. IMEX
    systemctl is-enabled nvidia-imex
    ls /dev/nvidia-caps-imex-channels/
    # 期望: enabled, channel0 存在
    
    # I. SELinux 和防火墙(客户要求禁用)
    getenforce              # 期望: Disabled
    systemctl is-active firewalld  # 期望: inactive
v5 镜像验证结果(2026-07-03)
检查项结果
Kernel6.6.119-49.101.nvidia.tl4.aarch64
NVIDIA Driver580.159.04 (Open, Dual MIT/GPL)
GPU4x NVIDIA GB200, 189471 MiB HBM3e
GVEv1.4.10-oot, DQO RDA
RDMA4x mlx5 ACTIVE
IMEXenabled, channel0
google-guest-agentactive
SSH via IAP正常
测试完毕后释放 GPU
A4X GPU 资源有限,验证通过后务必立即停止 VM:
gcloud compute instances stop tlinux-v5-test --zone=$A4X_ZONE --project=$PROJECT_ID --discard-local-ssd=true

官方文档与参考链接

以下外部文档已被严格审核并确认在线有效,供您在开发和运营云端客体机环境时参考: