CubeSandbox 运维 CLI 工具全解cubemastercli / cubeopscli / cubecli / cube-runtime 实战指南【免费下载链接】CubeSandboxInstant, Concurrent, Secure Lightweight Sandbox for AI Agents.项目地址: https://gitcode.com/GitHub_Trending/cu/CubeSandboxCubeSandbox 为宿主侧运维与排障提供了四款命令行工具分别覆盖集群级沙箱/模板管理cubemastercli、节点生命周期管理cubeopscli、计算节点本地容器/存储排查cubecli以及沙箱 MVM 内核级调试cube-runtime。本文以官方文档 docs/guide/cli-tools.md 为主线结合仓库源码逐一讲解每个工具的定位、默认参数、常用命令与调用链帮助你按“集群级 → 节点级 → 虚拟机级”的层次快速定位问题。工具总览与部署位置四款工具在集群中的定位、运行位置与通信对象截然不同先看下表建立整体认知工具运行位置通信对象主要用途cubemastercli控制节点、跳板机或任何能访问 CubeMaster 的主机CubeMaster HTTP API默认端口8089集群级沙箱、模板、快照、卷操作cubeopscli控制节点、跳板机或任何能访问 CubeOps 的主机CubeOps HTTP API默认端口3010节点列表、隔离/解除隔离、删除节点cubecli运行 Cubelet 与 containerd 的计算节点本地 Cubelet/containerd 状态单节点沙箱/容器查看、容器 shell、日志、存储清理、本地运行时调试cube-runtime承载沙箱 MVM 的计算节点本地 CubeShim hybrid-vsock/调试控制台进入客户机 MVM、执行底层 VM 快照辅助操作部署方式上一键安装包会在宿主创建/usr/local/bin符号链接包含cube-runtime、containerd-shim-cube-rs、cubecli、cubemastercli和cubeopscli而在 Kubernetes 部署形态下cubecli、cube-runtime这类节点本地工具会被打入组件镜像或宿主 toolbox 中。cubemastercli与cubeopscli随发布包分发并安装在 Terraform 部署的跳板机上。注意这些工具会绕过公开的 CubeAPI 用户体验直接查看/变更集群与运行时状态只允许在受信任的运维机器上使用。cubemastercli集群级沙箱与模板管理cubemastercli面向 CubeMaster因此除默认参数恰好正确的主机外命令通常都需要显式指定--address与--port。其入口位于 CubeMaster/cmd/cubemastercli/main.go基于urfave/cli构建命令行应用定义在 CubeMaster/cmd/cubemastercli/app/main.go 中全局标志-a/--addressCubeMaster 服务地址支持逗号分隔的 IP 列表默认值0.0.0.0全局标志-p/--port默认值8089全局标志--timeout命令总超时默认 35 秒。从 app/main.go 注册的命令列表可以看到除version外全部功能都挂在cubebox命令组下包括list、info、sandbox、snapshot、storage、operation、template、volume等子命令源码位于 CubeMaster/cmd/cubemastercli/commands/cubebox 目录。基础用法与集群健康检查cubemastercli --address cubemaster-host --port 8089 --help cubemastercli --address cubemaster-host --port 8089 version常用的集群级检查命令# 列出 CubeMaster 已知的全部沙箱。 cubemastercli --address cubemaster-host --port 8089 list --all # 查看单个沙箱详情。 cubemastercli --address cubemaster-host --port 8089 info --sandboxid sandbox-idinfo是排查“沙箱在哪台节点上”的关键命令可用于确定沙箱所在计算节点随后再在该节点上执行cubecli或cube-runtime做更深入的定位。模板管理list / info / redo / create-from-image / merge模板相关的命令组在 commands/cubebox/template.go 中实现# 列出模板。 cubemastercli --address cubemaster-host --port 8089 tpl ls # 展示模板元数据与节点副本情况。 cubemastercli --address cubemaster-host --port 8089 tpl info template-id # 新增计算节点后在指定节点上重建或重新分发模板。 cubemastercli --address cubemaster-host --port 8089 tpl redo \ --template-id template-id \ --node node-id-or-host # 从 OCI 镜像创建模板。 cubemastercli --address cubemaster-host --port 8089 tpl create-from-image \ --image registry/repo:tag \ --writable-layer-size 1G \ --expose-port 49983 \ --probe 49983 # 把 READY 状态的模板制品迁移到 TC 托管存储。 cubemastercli --address cubemaster-host --port 8089 tpl merge template-id # 若同次维护还需重新填充节点可在 merge 之后执行 redo。 cubemastercli --address cubemaster-host --port 8089 tpl redo --template-id template-id从源码看tpl redo的内部实现对应 CubeMaster 的/cube/template/redoHTTP 接口见 template.go支持以下细化参数--template-id指定要 redo 的模板--node限定只 redo 指定节点可重复传参指定多个节点 ID 或主机 IP不传则作用于全部节点--failed-only只对失败节点执行 redo--detach/--no-wait提交作业后立即退出不再等待作业完成默认会阻塞直到作业结束。tpl redo会返回一个 job_id适合在运维脚本中异步跟踪cubemastercli ... tpl redo --template-id template-id --detach而tpl merge在源码中明确标注为/cube/template/migrate接口的 CLI 拼写见 template.go同样支持--detach/--no-wait提交后立即退出。运维 runbook 中请保持措辞一致避免歧义tpl merge解决历史制品存储收敛问题典型场景是模板已存在于 CubeMaster 本地磁盘之后集群启用了s3Backedtruetpl merge把这些历史制品迁移进 S3 托管存储tpl redo解决节点侧重新分发/重建问题仅在需要重新填充目标节点时才需要执行旧制品不可复用时redo 会负责重建。危险操作销毁沙箱是破坏性操作务必确认沙箱 ID 后再执行# 通过 CubeMaster 销毁一个沙箱。 cubemastercli --address cubemaster-host --port 8089 cubebox destroy sandbox-id多节点部署与模板分发上下文可参考 多节点集群部署。cubeopscli节点生命周期管理cubeopscli面向 CubeOps命令同样需要显式提供--address与--port。其入口位于 CubeOps/cmd/cubeopscli/main.go应用定义在 CubeOps/cmd/cubeopscli/app/main.go-a/--addressCubeOps 服务 IP 列表逗号分隔默认值127.0.0.1-p/--portCubeOps 内部路由端口默认值3010--timeoutHTTP 请求超时默认 35 秒。注册的命令只有version与node两组node 命令实现见 CubeOps/cmd/cubeopscli/commands/nodecubeopscli --address cubeops-host --port 3010 node list cubeopscli --address cubeops-host --port 3010 node isolate node-id cubeopscli --address cubeops-host --port 3010 node unisolate node-id cubeopscli --address cubeops-host --port 3010 node delete node-id cubeopscli --version cubeopscli version cubeopscli version --versiononly删除节点有两个硬性前置条件节点必须已隔离isolated且不承载任何沙箱。批量删除时单个节点失败不会中断其余节点但只要有任何节点删除失败命令就以非零码退出。delete的别名是rm当沙箱清单无法核验时可用--force强制删除隔离状态仍然必须满足。版本输出的行为值得注意cubeopscli --version与cubeopscli version都打印发布版本格式类似cubeopscli v0.7.0 (commit) built at timestamp实现见 CubeOps/cmd/cubeopscli/commands/version/version.go而cubeopscli version --versiononly只输出语义化版本号适合脚本解析。节点的添加、隔离与删除完整流程可参考 节点运维。cubecli计算节点本地沙箱/容器排查cubecli是计算节点工具除非命令显式通过配置的地址指向 Cubelet否则应在目标沙箱所在节点上执行。入口位于 Cubelet/cmd/cubecli/main.go基于urfave/cli/v2应用定义在 Cubelet/cmd/cubecli/app/main.go。全局标志体现了它与本地运行时的紧耦合-a/--addressCubelet gRPC 服务的 unix socket默认/data/cubelet/cubelet.sock--tcpaddressCubelet gRPC 的 TCP 地址ctr 命令使用默认0.0.0.0:9999--state状态目录默认/data/cubelet/state--timeoutctr 命令总超时默认 60 秒-n/--namespacecontainerd 命名空间默认与 containerd 默认命名空间一致。命令组非常丰富containerinfo/exec、cubeboxlist/logs/destroy 等、image、volume、vm、storagels/cleanup、networkls、metadata、unsafe、ctrcommands并且直接嵌入了 containerd 的namespaces命令。基础用法cubecli --help cubecli version常用节点本地检查# 列出本地 Cubelet 上的沙箱。 cubecli cubebox ls # 按沙箱 ID 过滤本地 Cubelet 沙箱列表。 cubecli cubebox ls --sandbox sandbox-id # 查看某个容器 ID 的 containerd 元数据。 cubecli container info container-id # 读取沙箱或模板的 stdout/stderr 日志。 cubecli logs sandbox-id cubecli logs --stderr sandbox-id # 列出 Cubelet 已知的本地存储卷。 cubecli storage ls # 删除任何内容前先对本地孤儿存储清理做干跑。 cubecli storage cleanup --dry-run # 展示 Cubelet 网络运行时的 tap 状态需要 Cubelet toolbox 配置并会提示确认。 cubecli network ls其中logs的实现位于 Cubelet/cmd/cubecli/commands/cubebox/logs.gostorage cleanup的干跑逻辑见 Cubelet/cmd/cubecli/commands/storage/cleanup.gonetwork ls见 Cubelet/cmd/cubecli/commands/network/ls.go。进入沙箱容器视图cubecli exec -it sandbox-id bash该命令通过本地容器运行时创建一个 exec 进程适合检查用户进程、文件、环境变量、命令行为和容器级日志。注意它与登录客户机 MVM 是两回事——前者进入的是容器/rootfs 视图。unsafe 命令只有充分理解本地节点的影响半径时才应使用 unsafe 命令# 示例仅移除本节点的全部本地沙箱。 cubecli unsafe rm --all多节点集群中本地的cubecli操作只覆盖命令运行所在的节点集群级操作请优先使用cubemastercli。cube-runtime进入沙箱 MVM 的底层调试工具cube-runtime来自 CubeShim 工作区入口见 CubeShim/cube-runtime/src/main.rs是一个更底层的运行时辅助工具运维人员主要用它通过调试控制台进入沙箱 MVM。它基于clap构建子命令定义在 CubeShim/cube-runtime/src/parser.rs共三个login进入客户机调试控制台、snapshot底层快照、completions生成 shell 补全。cube-runtime --help cube-runtime login --help登录沙箱 MVMcube-runtime login sandbox-idlogin首先校验沙箱 ID然后通过该沙箱的本地 hybrid-vsock 路径连接调试控制台端口。从 CubeShim/cube-runtime/src/parser.rs 可见其参数默认值--port调试控制台端口默认1026--timeout连接超时秒默认10秒。显式指定参数的形式cube-runtime login sandbox-id --port 1026 --timeout 10连接建立后login会向 hybrid-vsock 发送CONNECT port握手并等待OK响应见 CubeShim/cube-runtime/src/login.rs 中的hybrid_vsock_dialer随后把终端切换到 raw 模式并双向转发 stdin/stdout让你获得类似串口控制台的交互体验。需要客户机虚拟机视角时使用cube-runtime login典型场景包括查看客户机内核状态、客户机网络接口、agent 状态、挂载点以及 MVM 级别的 pause/resume 行为。cube-runtime snapshot面向底层快照工作流通常由更上层的 Cubelet/CubeMaster 路径驱动。除非在调试运行时内部机制否则模板与快照的日常操作请优先走cubemastercli中文档化的命令。如何选择合适的工具按问题所在的层次选择工具集群级问题用cubemastercli哪些节点健康哪些模板副本已就绪沙箱由哪台节点承载新增节点后如何 redo 模板如何通过控制面销毁沙箱节点本地问题用cubecli该沙箱是否存在于本台 Cubelet 上能否进入沙箱容器本地容器日志说了什么是否存在本地孤儿存储卷Cubelet 看到的本地 tap/网络状态如何MVM 内部问题用cube-runtime能否进入客户机调试控制台客户机内核或 VM 级网络看到了什么问题是否位于容器/rootfs 层之下安全注意事项避免把密钥、API Key、镜像仓库凭据或私有端点值粘贴进 shell 历史收集问题证据时优先使用--json可用处分享日志前先脱敏敏感值多节点集群中先用cubemastercli info --sandboxid sandbox-id确认沙箱所在计算节点再到该节点执行cubecli或cube-runtime把cubecli unsafe ...以及cubemastercli的破坏性命令视为运维变更而非只读诊断执行前确认影响范围。相关文档与源码速查本主题官方文档docs/guide/cli-tools.md多节点部署多节点集群部署节点运维节点运维cubemastercli入口与命令组CubeMaster/cmd/cubemastercli/app/main.go 与 CubeMaster/cmd/cubemastercli/commands/cubeboxcubeopscli入口与节点命令CubeOps/cmd/cubeopscli/app/main.go 与 CubeOps/cmd/cubeopscli/commands/nodecubecli入口与命令组Cubelet/cmd/cubecli/app/main.go 与 Cubelet/cmd/cubecli/commandscube-runtime入口、参数与 login 实现CubeShim/cube-runtime/src/main.rs、CubeShim/cube-runtime/src/parser.rs、CubeShim/cube-runtime/src/login.rs【免费下载链接】CubeSandboxInstant, Concurrent, Secure Lightweight Sandbox for AI Agents.项目地址: https://gitcode.com/GitHub_Trending/cu/CubeSandbox创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考