CubeSandbox cubecow 端到端 Smoke 测试指南：用 cubecow_api_smoke 驱动全部 16 个 Engine 子命令

CubeSandbox cubecow 端到端 Smoke 测试指南用 cubecow_api_smoke 驱动全部 16 个 Engine 子命令【免费下载链接】CubeSandboxInstant, Concurrent, Secure Lightweight Sandbox for AI Agents.项目地址: https://gitcode.com/GitHub_Trending/cu/CubeSandbox导读cubecow_api_smoke是 cubecow 存储引擎Volume / Snapshot 快照后端的端到端 smoke 测试程序它通过 shell 方式调用cubecow-cli的 16 个子命令进而逐一覆盖公开cubecow::Enginetrait 的全部方法完整走一遍「创建卷 → 快照 → 克隆 → 激活/去激活 → 导出/导入 → 清理」的生命周期。读完本文你将掌握该 smoke 测试的构建、运行、参数调优、退出码语义以及它在源码层面的实现机制可直接用它为自己的 cubecow 部署做回归验证。一、cubecow_api_smoke 的定位CLI 侧的端到端验证cubecow_api_smoke位于 cubecow/examples/cubecow_api_smoke/其定位在 README.md 中写得很明确Anend-to-endsmoke test that drives every one of the 16 subcommands exposed bycubecow-cli, which in turn covers every method of the publiccubecow::Enginetrait.它并不直接链接 cubecow 库而是把cubecow-cli当作被测程序以子进程方式调用并解析其--json输出。它是与s3_rpc_smoke互补的另一个 smoke 测试两者对比如下Smoke 二进制驱动对象通信方式s3_rpc_smokes3lvol 守护进程的 11 个原始 JSON-RPC 方法直接走 Unix socket 发 JSON-RPCcubecow_api_smokecubecow-cli的 16 个子命令即Enginetrait子进程执行cubecow-cli ... --json并解析 stdout从代码看两个示例也刻意保持了风格一致cubecow_cli.rs与s3_rpc_smoke一样采用手写参数解析不使用 clap 依赖见 cubecow/src/bin/cubecow_cli.rs 头部注释。测试的生命周期流程镜像自设计文档 cubecow/docs/cubecow-api.md 中定义的 Volume/Snapshot 生命周期语义。二、16 个子命令与 Engine trait 的完整映射cubecow-cli的每个子命令与Enginetrait 方法一一对应。完整的 16 组映射记录在 cubecow/src/bin/cubecow_cli.rs 顶部注释中cubecow-cli子命令Enginetrait 方法create-volumecreate_volumedelete-volumedelete_volumeresize-volumeresize_volumeget-volume-infoget_volume_infoget-volume-block-infoget_volume_block_infolist-volumeslist_volumescreate-snapshotcreate_snapshot_from_volumedelete-snapshotdelete_snapshotcreate-volume-from-snapshotcreate_volume_from_snapshotlist-snapshotslist_snapshotsactivate-volumeactivate_volumedeactivate-volumedeactivate_volumeexport-snapshotexport_snapshotimport-lvolimport_lvolreset-node-storagereset_node_storagemetricsmetricsEnginetrait 本身定义在 cubecow/src/engine/mod.rs是一个Send Sync的后端无关接口。其中值得注意的两点是export_snapshot/import_lvol在 trait 中提供默认实现默认直接返回PreconditionFailednot implemented by this backend。也就是说跨节点导出/导入是可选能力由各后端自行决定是否实现reflink 后端不实现S3 后端实现。reset_node_storage是破坏性操作删除本节点所有 cubecow 管理的卷与快照因此 smoke 测试的 15 个编号步骤不包含它16 个子命令因此以 15 步编号的测试形式呈现。三、15 步生命周期测试从创建到清理cubecow_api_smoke的 15 个编号步骤完整镜像了卷与快照的生命周期。每一步除了验证功能正确还内嵌了幂等性探测idempotency probe#子命令说明与校验点1create-volume创建 1 GiB 卷随后幂等性探测同名第二次创建必须失败stderr 含already exists2get-volume-info校验返回的size_bytes与请求值一致3get-volume-block-info打印num_blocks/block_size4resize-volume扩容卷默认 1 GiB → 2 GiB校验new_size5list-volumes确认新卷出现在列表含total计数6create-snapshot基于卷创建已激活的快照7list-snapshots确认快照出现在其源卷origin_volume之下8create-volume-from-snapshot从快照克隆出可写卷9deactivate-volume去激活快照幂等性探测第二次去激活也必须成功10activate-volume重新激活快照验证重新挂载设备11metrics输出后端内部计数器12export-snapshot仅 S3 后端reflink 后端自动跳过13get-volume-info(status)轮询export_status DONE配合--upload-timeout-secs14import-lvol仅 S3 后端用export_uuid物化出可写卷15delete-snapshotdelete-volume清理 幂等性探测第二次删除必须报 not found这些校验点在 cubecow/examples/cubecow_api_smoke/main.rs 中逐段实现。测试在退出时无论成功或失败都会执行一次 best-effort 清理避免部分运行在后端遗留命名残留。3.1 幂等性探测的语义依据幂等性探测并非随意设计而是严格对应 cubecow/docs/cubecow-api.md 的幂等性总结表幂等 API幂等行为delete_volume/delete_snapshot对不存在的名字也返回成功activate_volume重复调用返回相同device_pathdeactivate_volume对未激活的名字也返回成功resize_volume等大new old为 no-op 直接返回export_snapshot对同一快照重复导出返回相同export_uuid对应到 smoke 测试实现中见main.rs的run_cleanup函数清理阶段会对每个快照/卷执行两次删除第一次必须成功第二次必须失败且 stderr 含not found或no such——否则视为幂等性违规并报告[FAIL]。四、依赖隔离设计为什么可以独立构建cubecow_api_smoke在自己的 Cargo.toml 中携带了独立的[workspace]标记与外部 cubecow workspace 隔离。这意味着它只依赖serde_json用于解析cubecow-cli --json输出的 JSON不依赖 cubecow 库本身在这里执行cargo build --release不会重新编译 cubecow lib产物可以独立分发包括交叉编译到x86_64-unknown-linux-musl实现「scp 即跑」的工作流与s3_rpc_smoke完全一致。Cargo.toml还配置了发布优化的 profileopt-level 3、lto thin、codegen-units 1、strip symbols进一步压缩静态产物体积。五、构建步骤1. 先在 workspace 根目录构建cubecow-clicd cube-sandbox/cubecow cargo build --release --bin cubecow-cli # 产物: target/release/cubecow-clicubecow-cli是围绕Enginetrait 的薄命令行封装手写参数解析、无 clap 依赖见 cubecow/src/bin/cubecow_cli.rs。它的退出码约定为0成功、1引擎层错误、2非法参数、3引擎初始化失败——smoke 测试的退出码设计与之呼应。2. 构建 smoke 二进制cd examples/cubecow_api_smoke cargo build --release # 产物: target/release/cubecow_api_smoke可选静态 musl 构建rustup target add x86_64-unknown-linux-musl # 一次性操作 cd examples/cubecow_api_smoke cargo build --release --target x86_64-unknown-linux-musl # 产物: target/x86_64-unknown-linux-musl/release/cubecow_api_smoke得到的 musl 产物是静态链接的没有任何共享库依赖——把它拷贝到任意一台已有可用cubecow-cli的 x86_64 Linux 主机即可直接运行ldd会报告 statically linked。六、运行方式与参数详解在已部署 cubecow TOML 配置默认路径/etc/cubecow/cubecow.toml的主机上典型调用方式为./target/release/cubecow_api_smoke \ --cubecow-cli ../../target/release/cubecow-cli \ --config /etc/cubecow/cubecow.toml更丰富的运行选项# 指向另一个 CLI 二进制 JSON 格式配置文件 cubecow_api_smoke \ --cubecow-cli /usr/local/bin/cubecow-cli \ --json-config /etc/cubecow/cubecow.json # 内联配置在自定义 root_dir 上使用最小化 reflink 后端 cubecow_api_smoke \ --cubecow-cli /usr/local/bin/cubecow-cli \ --json-config-inline {log:{},backend:{kind:reflink,reflink:{root_dir:/tmp/cbc}}} # 端到端跑 S3 后端含 export/status/import # 最多等待 300s 让异步 COS 上传达到 DONE cubecow_api_smoke \ --cubecow-cli /usr/local/bin/cubecow-cli \ --config /etc/cubecow/cubecow-s3.toml \ --backend s3 \ --upload-timeout-secs 300 # 保留创建的产物以便离线检查 cubecow_api_smoke --config /etc/cubecow/cubecow.toml --keep全部命令行参数上述选项全部在 main.rs 的Args::parse与print_usage中实现完整清单如下参数默认值说明--cubecow-cli PATHcubecow-cliPATH 中查找指向构建好的cubecow-cli二进制--config PATH无TOML 配置原样转发给cubecow-cli --config--json-config PATH无JSON 配置文件转发给--json-config与--config、--json-config-inline互斥--json-config-inline STR无内联 JSON 配置字符串转发给--json-config-inline--backend reflink\|s3reflink仅用于决定是否尝试 S3 专属的 export/import 步骤--prefix STRcbc-smoke-pid-ts创建对象的命名前缀随机化避免重跑冲突--size-bytes N10737418241 GiBcreate-volume步骤的卷大小字节--resize-bytes N21474836482 GiB扩容目标大小必须 ≥--size-bytes否则参数解析报错--skip-exportfalse跳过 S3 专属的导出步骤reflink 后端自动强制为 true--skip-importfalse仅跳过import-lvol仍执行export-snapshotget-volume-info--upload-timeout-secs N0轮询export_status DONE的等待秒数0表示单次采样仅在 S3 后端有意义--keepfalse退出时不删除创建的产物改为打印名称供人工清理-h, --help—打印帮助测试启动时会打印运行概要CLI 路径、配置来源、backend hint、命名前缀、卷大小、跳过开关、keep 开关随后先执行一次metrics作为 sanity 探针——这是只读调用、对任何后端都可用用于确认cubecow-cli可执行且引擎能初始化。配置的三种来源与校验三种配置来源互斥这一约束与cubecow-cli及库层的配置加载契约完全一致。cubecow/src/config/mod.rs 中AppConfig::loadTOML 文件、from_json_strJSON 字符串在反序列化后都会执行validate()其中reflink 后端要求[backend.reflink] root_dir非空且为绝对路径默认/var/lib/cubecow/reflink且该目录必须位于支持FICLONEioctl 的文件系统典型为开启reflink1的 xfsBtrfs/OCFS2 亦可上——引擎启动时会探测并拒绝初始化S3 后端要求socket_path默认/var/run/s3lvol.sock与state_dir为绝对路径size_policy只能取round_up或strict[log]的format只能取json/compact/prettyrotation只能取daily/hourly/never。这也解释了内联示例{log:{},backend:{kind:reflink,reflink:{root_dir:/tmp/cbc}}}为何能生效缺省字段如日志 level 默认info由 serde 的#[serde(default)]补齐而root_dir满足绝对路径校验。七、退出码与结果解读cubecow_api_smoke的退出码定义如下退出码含义0所有未跳过的步骤在 SUMMARY 中均报告[ OK ]1至少一个步骤失败详情见SUMMARY块2非法 CLI 参数例如--resize-bytes --size-bytes或同时传入多个互斥配置项3无法通过cubecow-cli metrics触达 cubecow 引擎sanity 探针失败运行时每个步骤打印[NN/15] 子命令 横幅响应以美化 JSON 形式输出子步骤以缩进-标注。结束时的SUMMARY块逐条列出[ OK ]/[WARN]/[FAIL]及对应的 32 字符宽步骤名和详情并统计总数。WARN不算失败典型场景包括S3 后端导出后单次采样未达DONE未传--upload-timeout-secs、返回的size_bytes与请求不一致等。清理逻辑与--keep清理在退出前执行且成功与失败路径都会触发先删快照、再删卷顺序保证origin_volume引用关系不被破坏每个对象删除两次以验证幂等性。若指定--keep则跳过清理退出前打印遗留的快照与卷名供运维用cubecow-cli delete-snapshot/delete-volume人工回收。八、源码实现要点如何通过子进程驱动 Engine从 main.rs 可以看到整套实现的骨架Runner结构把「配置参数 --json 子命令 子参数」拼成一次cubecow-cli子进程调用。config_flags()根据三种互斥来源生成--config/--json-config/--json-config-inline参数。run_rawvscall的分层run_raw返回(ok, status, stdout, stderr)四元组从不报错进程启动失败也被包装成okfalse的合成结果call在run_raw之上要求退出码为 0 且 stdout 可解析为 JSON空输出如空引擎上的metrics、已去激活条目的deactivate-volume按{}处理。JSON 契约所有成功响应都来自cubecow-cli --json字段直接对应 cubecow/docs/cubecow-api.md §2 定义的对象字段name、size_bytes、device_path、origin_volume、export_uuid、export_status等。上传状态轮询第 13 步以 500ms 起步、指数退避上限 5s的方式循环调用get-volume-info直到export_status DONE或超时--upload-timeout-secs 0时只做单次采样。这套「真实进程 机器可读 JSON」的设计让 smoke 测试验证的是完整的发布链路——包括cubecow-cli的打包、配置加载、后端初始化与全部 API 调用——而非库内 mock因此它既是回归测试也是部署验收工具。九、延伸用它验证两种后端cubecow 目前在后端选择上支持reflink默认、唯一随仓库发布的 xfs-reflink 后端与s3委托给外部 S3LVOL/RCOW 服务见 cubecow/src/engine/s3.rs。smoke 测试通过--backend提示切换行为reflink自动跳过 export/import 步骤skip_export被强制置真全程验证本地卷/快照/克隆/激活语义s3额外执行export-snapshot→ 轮询get-volume-info→import-lvol三段跨节点能力验证需要真实可用的 COS 环境推荐配合--upload-timeout-secs使用。对部署侧而言把cubecow_api_smoke跑通退出码 0、SUMMARY 全[ OK ]即可认为当前节点的 cubecow 引擎具备完整、幂等的卷快照服务能力。【免费下载链接】CubeSandboxInstant, Concurrent, Secure Lightweight Sandbox for AI Agents.项目地址: https://gitcode.com/GitHub_Trending/cu/CubeSandbox创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考