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普通bmbare-metal 直启guest 内核镜像必选vmlinux-pvmPVM 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与常用 appletawk/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 的默认路径均支持通过环境变量覆盖下表汇总了三个核心变量及其语义环境变量默认值含义ONE_CLICK_CUBE_KERNEL_VMLINUXdeploy/one-click/assets/kernel-artifacts/vmlinux普通 guest 内核镜像bm的路径ONE_CLICK_CUBE_KERNEL_PVM_VMLINUXdeploy/one-click/assets/kernel-artifacts/vmlinux-pvm可选 PVM guest 内核镜像路径ONE_CLICK_GUEST_IMAGE_TAR空未设置时本地构建预构建的cube-guest-image-*.tar.gz归档路径典型用法不修改仓库文件直接把内核制品放在仓库外的自定义位置再通过环境变量注入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 manifestkernel 的version优先取自version.json的 variant digestvmlinux_digest_sha256为必填项缺失会触发ValueError。最终产物统一落在发布包的assets/kernel-artifacts/cube-kernel-scf.zip与cube-kernel-scf/目录中。五、常见问题与排查5.1 内核镜像缺失若构建时找不到vmlinuxensure_kernel_vmlinux会在 stderr 输出明确的错误提示并给出两种修复方式Option A将内核文件放到默认位置cp /path/to/your/vmlinux deploy/one-click/assets/kernel-artifacts/vmlinuxOption Bexport 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或versioninstall_prebuilt_guest_image_tar中的ensure_file校验会直接终止构建。因此务必使用与 Release / docker 资产同布局的归档。六、相关文件速查kernel-artifacts README本文主题的原始约定文档build-vm-assets.sh内核制品打包、版本计算与 runtime layout 组装build-guest-image.shguest image 本地构建与预构建归档复用build-release-bundle.sh内核 zip 打包与 release manifest 元数据写入lib/common.shensure_kernel_vmlinux校验逻辑第 2645 行起build.env.example全部构建环境变量说明含本文三个核心变量guest-image/Dockerfileguest 根文件系统的最小化定义【免费下载链接】CubeSandboxInstant, Concurrent, Secure Lightweight Sandbox for AI Agents.项目地址: https://gitcode.com/GitHub_Trending/cu/CubeSandbox创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 CubeSandbox 内核制品与 Guest Image 资产准备指南：kernel-artifacts 目录约定与构建覆盖机制
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普通bmbare-metal 直启guest 内核镜像必选vmlinux-pvmPVM 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与常用 appletawk/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 的默认路径均支持通过环境变量覆盖下表汇总了三个核心变量及其语义环境变量默认值含义ONE_CLICK_CUBE_KERNEL_VMLINUXdeploy/one-click/assets/kernel-artifacts/vmlinux普通 guest 内核镜像bm的路径ONE_CLICK_CUBE_KERNEL_PVM_VMLINUXdeploy/one-click/assets/kernel-artifacts/vmlinux-pvm可选 PVM guest 内核镜像路径ONE_CLICK_GUEST_IMAGE_TAR空未设置时本地构建预构建的cube-guest-image-*.tar.gz归档路径典型用法不修改仓库文件直接把内核制品放在仓库外的自定义位置再通过环境变量注入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 manifestkernel 的version优先取自version.json的 variant digestvmlinux_digest_sha256为必填项缺失会触发ValueError。最终产物统一落在发布包的assets/kernel-artifacts/cube-kernel-scf.zip与cube-kernel-scf/目录中。五、常见问题与排查5.1 内核镜像缺失若构建时找不到vmlinuxensure_kernel_vmlinux会在 stderr 输出明确的错误提示并给出两种修复方式Option A将内核文件放到默认位置cp /path/to/your/vmlinux deploy/one-click/assets/kernel-artifacts/vmlinuxOption Bexport 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或versioninstall_prebuilt_guest_image_tar中的ensure_file校验会直接终止构建。因此务必使用与 Release / docker 资产同布局的归档。六、相关文件速查kernel-artifacts README本文主题的原始约定文档build-vm-assets.sh内核制品打包、版本计算与 runtime layout 组装build-guest-image.shguest image 本地构建与预构建归档复用build-release-bundle.sh内核 zip 打包与 release manifest 元数据写入lib/common.shensure_kernel_vmlinux校验逻辑第 2645 行起build.env.example全部构建环境变量说明含本文三个核心变量guest-image/Dockerfileguest 根文件系统的最小化定义【免费下载链接】CubeSandboxInstant, Concurrent, Secure Lightweight Sandbox for AI Agents.项目地址: https://gitcode.com/GitHub_Trending/cu/CubeSandbox创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考