企业官网建设流程全解析

CubeSandbox 内核制品与 Guest Image 资产准备指南：kernel-artifacts 目录约定与构建覆盖机制

【免费下载链接】CubeSandboxInstant, Concurrent, Secure & Lightweight Sandbox for AI Agents.项目地址: https://gitcode.com/GitHub_Trending/cu/CubeSandbox

导读

本文围绕 CubeSandbox one-click 发布包构建体系中的固定内核制品（kernel artifacts）目录展开，系统讲解deploy/one-click/assets/kernel-artifacts/的目录约定（vmlinux与可选vmlinux-pvm默认文件名）、guest image 的两种来源（基于deploy/guest-image/Dockerfile的本地重建与通过ONE_CLICK_GUEST_IMAGE_TAR复用预构建包），以及三个核心环境变量（ONE_CLICK_CUBE_KERNEL_VMLINUX、ONE_CLICK_CUBE_KERNEL_PVM_VMLINUX、ONE_CLICK_GUEST_IMAGE_TAR）的覆盖机制。读完本文，你将能正确放置内核制品、定制或复用 guest image，并理解它们在 one-click 构建流程中如何被校验、打包与记录版本。

一、kernel-artifacts 目录：固定内核制品的唯一默认来源

CubeSandbox 的 one-click 发布包构建脚本通过一组“固定制品”（fixed artifacts）目录来收集构建所需的基础资产，其中内核制品位于仓库下的deploy/one-click/assets/kernel-artifacts/目录。该目录下的README.md明确规定了默认文件名约定：

• vmlinux：普通（bm，bare-metal 直启）guest 内核镜像，必选；
• vmlinux-pvm：PVM guest kernel，可选。当该文件存在时，才会被打包为 PVM 变体。

在deploy/one-click/build-vm-assets.sh中，该目录被绑定为内核制品的默认查找位置：

RAW_ARTIFACTS_DIR="${SCRIPT_DIR}/assets/kernel-artifacts" CUBE_KERNEL_VMLINUX="${ONE_CLICK_CUBE_KERNEL_VMLINUX:-${RAW_ARTIFACTS_DIR}/vmlinux}" CUBE_KERNEL_PVM_VMLINUX="${ONE_CLICK_CUBE_KERNEL_PVM_VMLINUX:-${RAW_ARTIFACTS_DIR}/vmlinux-pvm}"

即：只要将内核镜像以vmlinux命名放入该目录，构建脚本即会自动发现并使用，无需任何额外配置。

注意：当前仓库的kernel-artifacts目录中仅有这份README.md，实际的vmlinux内核镜像需要构建者自行准备（可从内核编译产物或 Release / docker 资产中获取）。构建脚本对此有强制校验，详见本文第五节。

二、Guest Image 的两种来源：本地重建与预构建复用

Guest image 是沙箱 guest 侧的根文件系统镜像（包含作为/sbin/init的 cube-init）。deploy/one-click/assets/kernel-artifacts/README.md明确说明其有两种来源。

2.1 默认方式：基于 Dockerfile 本地生成

默认情况下，one-click 构建流程基于deploy/guest-image/Dockerfile在本地生成 guest image。该 Dockerfile 以tencentos/tencentos4-minimal:latest为基础镜像，仅保留运行期最小依赖：

• util-linux：提供mount/umount/blkid等工具（被 agent 间接引用）；
• busybox：提供/bin/sh与常用 applet（awk/sed/grep等），并显式清理 yum 缓存与文档，控制镜像体积。

在实际构建中，deploy/one-click/build-guest-image.sh会完成如下流程：构建 cube-init → 组装 rootfs → 生成cube-guest-image-cpu.img与配套version文件，期间依赖docker、truncate、mkfs.ext4、e2fsck、resize2fs等工具。

2.2 复用方式：通过ONE_CLICK_GUEST_IMAGE_TAR指向预构建包

如果需要跳过本地 docker/mkfs 重建（例如 CI 复用已发布的 guest image），可以设置环境变量：

export ONE_CLICK_GUEST_IMAGE_TAR=/path/to/cube-guest-image-amd64.tar.gz

该 tar 需与 Release / docker 资产保持相同布局，内部至少包含cube-guest-image-cpu.img与version两个文件。build-guest-image.sh的install_prebuilt_guest_image_tar()函数会先解压归档到输出目录，再逐一校验必需文件存在后直接退出，跳过本地重建。

三、三个核心环境变量的覆盖机制

内核制品与 guest image 的默认路径均支持通过环境变量覆盖，下表汇总了三个核心变量及其语义：

典型用法：不修改仓库文件，直接把内核制品放在仓库外的自定义位置，再通过环境变量注入：

export ONE_CLICK_CUBE_KERNEL_VMLINUX=/opt/kernels/vmlinux-6.6 export ONE_CLICK_CUBE_KERNEL_PVM_VMLINUX=/opt/kernels/vmlinux-pvm-6.6 export ONE_CLICK_GUEST_IMAGE_TAR=/data/release/cube-guest-image-amd64.tar.gz ./deploy/one-click/build-release-bundle.sh

在deploy/one-click/build.env.example中，这三个变量与 guest image 相关的其余选项（如ONE_CLICK_GUEST_IMAGE_DOCKERFILE、ONE_CLICK_GUEST_IMAGE_CONTEXT_DIR、ONE_CLICK_GUEST_IMAGE_REF、ONE_CLICK_GUEST_IMAGE_VERSION）一并列为可覆盖项，构建前可cp build.env.example build.env后按需编辑。

四、源码级流程：内核制品如何被打包并记录版本

从源码可以完整还原内核制品在 one-click 构建中的流转路径：

第 1 步：内核校验。deploy/one-click/build-vm-assets.sh调用lib/common.sh中的ensure_kernel_vmlinux，确认默认路径或环境变量指定的vmlinux真实存在。

第 2 步：写入 runtime layout。普通内核被复制为cube-kernel-scf/vmlinux-bm，并软链接为vmlinux；若存在 PVM 内核（vmlinux-pvm），则一并复制。值得注意的分支行为：若ONE_CLICK_CUBE_KERNEL_PVM_VMLINUX被显式设置但文件不存在，构建将直接失败（die）；若未设置且默认文件不存在，则仅打包普通内核并记录日志，不会报错。

第 3 步：生成版本元数据。脚本对vmlinux-bm（以及可选的vmlinux-pvm）计算 sha256 摘要，取前 12 位形成sha256-xxxxxxxxxxxx形式的短版本号，写入cube-kernel-scf/version.json（含schema_version与variants，键为bm/pvm，记录version与digest_sha256）以及纯文本version文件。

第 4 步：打包与发布。deploy/one-click/build-release-bundle.sh将内核资产打包为cube-kernel-scf.zip（归档内同时包含vmlinux与vmlinux-bm两份），并写入 release manifest：kernel 的version优先取自version.json的 variant digest，vmlinux_digest_sha256为必填项（缺失会触发ValueError）。最终产物统一落在发布包的assets/kernel-artifacts/cube-kernel-scf.zip与cube-kernel-scf/目录中。

五、常见问题与排查

5.1 内核镜像缺失

若构建时找不到vmlinux，ensure_kernel_vmlinux会在 stderr 输出明确的错误提示，并给出两种修复方式：

• Option A：将内核文件放到默认位置cp /path/to/your/vmlinux deploy/one-click/assets/kernel-artifacts/vmlinux；
• Option B：export ONE_CLICK_CUBE_KERNEL_VMLINUX=/path/to/vmlinux后重新运行构建脚本。

5.2 PVM 内核行为差异

• 未提供vmlinux-pvm且未设置环境变量：构建正常继续，仅打包普通内核，日志提示 “PVM kernel vmlinux not found; packaging ordinary kernel only”；
• 显式设置了ONE_CLICK_CUBE_KERNEL_PVM_VMLINUX但路径无效：构建立即失败，避免生成不完整的发布包。

5.3 guest image 归档缺文件

复用ONE_CLICK_GUEST_IMAGE_TAR时，若归档内缺少cube-guest-image-cpu.img或version，install_prebuilt_guest_image_tar中的ensure_file校验会直接终止构建。因此务必使用与 Release / docker 资产同布局的归档。

六、相关文件速查

• kernel-artifacts README：本文主题的原始约定文档
• build-vm-assets.sh：内核制品打包、版本计算与 runtime layout 组装
• build-guest-image.sh：guest image 本地构建与预构建归档复用
• build-release-bundle.sh：内核 zip 打包与 release manifest 元数据写入
• lib/common.sh：ensure_kernel_vmlinux校验逻辑（第 2645 行起）
• build.env.example：全部构建环境变量说明（含本文三个核心变量）
• guest-image/Dockerfile：guest 根文件系统的最小化定义

【免费下载链接】CubeSandboxInstant, Concurrent, Secure & Lightweight Sandbox for AI Agents.项目地址: https://gitcode.com/GitHub_Trending/cu/CubeSandbox