第4章 命令行工具

命令行工具 ​CubeSandbox 随宿主机安装包提供多种运维和排障命令行工具。一键安装会把它们安装到宿主机；Kubernetes 部署会把 cubecli、cube-runtime 等节点本地工具放进组件镜像或节点 toolbox 中。这些工具应只在可信运维机器上使用。它们绕过面向用户的 CubeAPI 体验，能够直接查看或修改集群、节点和运行时状态。工具总览 ​工具运行位置访问对象主要用途cubemastercli控制节点、跳板机，或任何能访问 CubeMaster 的机器CubeMaster HTTP API，默认端口 8089集群级 sandbox、模板、快照、volume 运维cubeopscli控制节点、跳板机，或任何能访问 CubeOps 的机器CubeOps HTTP API，默认端口 3010节点列表、隔离/解除隔离、删除节点cubecli运行 Cubelet 和 containerd 的计算节点本地 Cubelet/containerd 状态单节点 sandbox/container 查看、容器 shell、日志、存储清理、本地运行时排障cube-runtime承载目标 sandbox MVM 的计算节点本地 CubeShim hybrid-vsock/debug console登录 guest MVM 或执行底层 VM snapshot 辅助操作一键安装会为 cube-runtime、containerd-shim-cube-rs、cubecli、cubemastercli 和 cubeopscli 创建 /usr/local/bin 软链接。cubemastercli 和 cubeopscli 包含在发布包中，Terraform 跳板机也会安装它们。cubemastercli ​cubemastercli 是集群级管理 CLI。它访问 CubeMaster，因此除非运行位置的默认地址正好可用，通常都需要指定 --address 和 --port。bashcubemastercli --address --port 8089 --help cubemastercli --address --port 8089 version常用集群检查：bash# 查看 CubeMaster 已知的所有 sandbox。 cubemastercli --address --port 8089 list --all # 查看单个 sandbox。 cubemastercli --address --port 8089 info --sandboxid 模板操作：bash# 查看模板列表。 cubemastercli --address --port 8089 tpl ls # 查看模板元数据和各节点副本状态。 cubemastercli --address --port 8089 tpl info # 新增计算节点后，在指定节点重新构建或分发模板。 cubemastercli --address --port 8089 tpl redo \ --template-id \ --node # 从 OCI 镜像创建模板。 cubemastercli --address --port 8089 tpl create-from-image \ --image /: \ --writable-layer-size 1G \ --expose-port 49983 \ --probe 49983 # 把一个 READY 模板的 rootfs artifact 迁入 TC 存储。 # CLI 叫 merge，对应 API 是 /cube/template/migrate。 # 存量模板如果不迁移，artifact 仍留在 CubeMaster 本地盘上。 cubemastercli --address --port 8089 tpl merge # 如果场景是把历史 artifact 从本地盘迁到 S3 托管存储，且还要重新覆盖节点，可在 merge 完成后再 redo。 # redo 负责节点侧重新分发；原 artifact 不可复用时会回退到重建流程。 cubemastercli --address --port 8089 tpl redo --template-id # 只提交 migrate job，不等待结束。 cubemastercli --address --port 8089 tpl merge --detach对于存量镜像 / 历史模板，文档口径应统一为：tpl merge 解决历史 artifact 的存储收敛问题，tpl redo 解决节点侧重新分发 / 必要时重建问题。典型场景是：模板最初的 artifact 仍保存在 CubeMaster 本地盘，后续集群开启了 s3Backed=true，需要将这批历史 artifact 从本地盘迁移到 S3 托管存储。如果同一次运维还需要让模板重新覆盖目标节点，则在 tpl merge 完成后继续执行 tpl redo。高亮提醒 在默认共盘 / 共享 PVC 部署里，不执行 tpl merge 通常不会立刻影响现有模板下载；真正的问题是旧 artifact 仍未完成从本地盘到 S3 托管存储的收敛。存储侧：开启 s3Backed=true 后，旧模板不会自动补做迁移。恢复侧：如果本地 ext4 已经丢失，再补跑 tpl merge 也修不回来，因为已经没有可上传的文件；这时只能对可重建的 from-image 模板执行 tpl redo，回退到重建流程。破坏性操作需要谨慎执行：bash# 通过 CubeMaster 删除一个 sandbox。 cubemastercli --address --port 8089 cubebox destroy 多节点部署和模板分发背景见多节点集群。cubeopscli ​cubeopscli 是节点管理 CLI。它访问 CubeOps，因此除非运行位置的默认地址正好可用，通常都需要指定 --address 和 --port。bashcubeopscli --address --port 3010 node list cubeopscli --address --port 3010 node isolate cubeopscli --address --port 3010 node unisolate cubeopscli --address --port 3010 node delete cubeopscli --version cubeopscli version cubeopscli version --versiononly删除节点要求节点已隔离且无沙箱；批量删除时单个节点失败不会中断后续节点，命令最终返回非零退出码。delete 的别名是 rm；用 --force 可在无法校验沙箱清单时强制删除（仍要求先隔离）。cubeopscli --version 与 cubeopscli version 输出发布版本（如 cubeopscli v0.7.0 () built at ）；cubeopscli version --versiononly 只输出语义化版本号。增加、隔离与删除节点的详细用法见节点相关操作。cubecli ​cubecli 是计算节点本地工具。除非命令明确指定远端 Cubelet 地址，否则应在目标 sandbox 所在计算节点上运行。bashcubecli --help cubecli version常用节点本地检查：bash# 查看本机 Cubelet 上的 sandbox。 cubecli cubebox ls # 按 sandbox ID 过滤本机 Cubelet 的 sandbox 列表。 cubecli cubebox ls --sandbox # 查看 containerd container 元数据。 cubecli container info # 查看 sandbox 或模板 stdout/stderr 日志。 cubecli logs cubecli logs --stderr # 查看 Cubelet 记录的本地存储 volume。 cubecli storage ls # 先 dry-run 检查本地孤儿存储，再决定是否清理。 cubecli storage cleanup --dry-run # 查看 Cubelet network runtime 的 tap 状态。需要 Cubelet toolbox 配置，并会提示确认。 cubecli network ls进入 sandbox 容器/rootfs 视角：bashcubecli exec -it bash这个命令通过本地容器运行时创建 exec 进程，适合检查用户进程、文件系统、环境变量、命令执行行为和容器级日志。它不是登录 guest MVM。unsafe 命令只应在明确理解本地节点影响范围时使用：bash# 示例：只删除当前节点上的所有本地 sandbox。 cubecli unsafe rm --all在多节点集群中，cubecli 只覆盖命令所在节点。集群级操作优先使用 cubemastercli。cube-runtime ​cube-runtime 是 CubeShim workspace 中的底层运行时辅助工具。运维上最常用的是通过 debug console 进入 sandbox MVM。bashcube-runtime --help cube-runtime login --help登录 sandbox MVM：bashcube-runtime login login 会连接 sandbox 的本地 hybrid-vsock 路径，再进入 debug console 端口。默认 debug console 端口是 1026，默认连接超时是 10 秒。bashcube-runtime login --port 1026 --timeout 10当需要 guest VM 视角时使用 cube-runtime login，例如排查 guest 内核状态、guest 网络接口、agent 状态、挂载点或 MVM 级 pause/resume 行为。cube-runtime snapshot 是底层 snapshot 工作流使用的命令，通常由 Cubelet/CubeMaster 的上层流程调用。除非正在排查运行时内部问题，否则应优先使用 cubemastercli 提供的模板和快照操作。如何选择工具 ​如果问题是集群级的，使用 cubemastercli：哪些节点健康？哪些模板副本 ready？某个 sandbox 在哪个节点上？新增节点后如何 redo 模板？如何通过控制面删除 sandbox？如果问题是节点本地的，使用 cubecli：这个 sandbox 是否在本机 Cubelet 上？能否进入 sandbox 容器？本地容器日志是什么？是否有孤儿本地存储 volume？Cubelet 看到的本地 tap/network 状态是什么？如果问题发生在 MVM 内部，使用 cube-runtime：能否进入 guest debug console？guest 内核或 VM 级网络看到的状态是什么？问题是否位于 container/rootfs 层之下？安全注意事项 ​不要把密钥、API key、镜像仓库凭据或私有 endpoint 粘贴进 shell history。收集 issue 证据时，优先使用支持的 --json 输出；对外分享前先脱敏。多节点集群中，先用 cubemastercli info --sandboxid 确认 sandbox 所在节点，再到该计算节点执行 cubecli 或 cube-runtime。cubecli unsafe ... 和破坏性 cubemastercli 命令属于运维变更，不是只读诊断。