运维与排障
CubeSandbox 是一套多组件系统。学习运维时，不要先背所有服务名；先建立“从用户现象反推组件”的思路。
WebUI 是第一入口
默认访问：
text
http://<控制节点 IP>:12088最常用页面：
| 页面 | 用途 |
|---|---|
| Overview | 看集群健康、运行中沙箱、CPU/内存压力。 |
| Sandboxes | 管理沙箱，查看状态、日志、暂停、恢复、销毁。 |
| Templates | 查看模板状态、构建进度、节点分布。 |
| Nodes | 检查每台节点的资源和健康状态。 |
| Versions | 查看组件版本矩阵，定位混部或升级不一致。 |
| Template Store | 安装官方预置模板。 |
学习阶段建议每次跑 SDK 示例时都打开 Sandboxes 页面，这会让生命周期变化更直观。
端口速查
| 端口 | 组件 | 说明 |
|---|---|---|
3000 | CubeAPI | SDK / REST API 入口。 |
12088 | WebUI | 浏览器控制台。 |
80/443 | CubeProxy / CubeEgress 相关 | 取决于部署和域名配置。 |
9999 | Cubelet gRPC | 控制节点到计算节点的生命周期操作。 |
实际端口可能被 .env 或部署脚本覆盖，生产环境以安装目录配置为准。
日志从哪里看
| 问题 | 优先查看 |
|---|---|
| API 请求失败 | CubeAPI 日志、CubeMaster 日志。 |
| 创建沙箱卡住 | CubeMaster、Cubelet、CubeShim、containerd。 |
| 模板构建失败 | 模板 job、CubeMaster templatecenter、Cubelet artifact。 |
| 自动暂停/恢复异常 | /data/log/cube-proxy/sidecar.log。 |
| 出网被拒或注入异常 | /data/log/cube-egress/access.jsonl。 |
| 网络策略不生效 | network-agent 日志、CubeVS map dump。 |
| WebUI 无数据 | WebUI 请求、CubeAPI /cubeapi/v1、鉴权配置。 |
相关服务管理见 服务管理与日志。
定位问题的顺序
1. 先判断是控制面还是节点面
| 现象 | 更可能在哪里 |
|---|---|
| API 返回 401/403 | 鉴权或 API 网关。 |
| API 返回调度失败 | CubeMaster、节点资源、模板状态。 |
| 沙箱创建后无法执行 | Cubelet、CubeShim、VMM、沙箱内服务。 |
| 访问沙箱 HTTP 服务失败 | CubeProxy、域名、端口暴露、TLS。 |
| 出网失败 | CubeVS、CubeEgress、DNS、网络策略。 |
2. 再看资源和状态
- 节点是否 Ready。
- 模板是否 READY。
/data/cubelet是否还有空间。- 版本矩阵是否一致。
- 沙箱是否 running、paused 或 terminated。
3. 最后看具体日志
先用 WebUI 缩小范围，再进入宿主机看日志。不要一开始就在所有日志里全文搜索。
常用健康检查
bash
# API
curl -s http://127.0.0.1:3000/health || true
# 端口监听
ss -lntp | grep -E '3000|12088|9999' || true
# 文件系统
df -h /data/cubelet
findmnt /data/cubelet
# KVM
ls -la /dev/kvm
lsmod | grep kvm升级与版本矩阵
CubeSandbox 由多个组件共同工作，升级时要避免“控制面已经升级、节点仍是旧组件”的混合状态。WebUI 的 Versions 页面可以帮助你观察：
- CubeAPI、CubeMaster、Cubelet 版本是否一致。
- network-agent、CubeShim、CubeEgress 是否与发布包匹配。
- guest 镜像或模板是否需要重建。
学习源码时可能会看到比当前文档更新的版本常量或测试数据，这是正常的。部署环境应以 Release 包和 changelog 为准。
常见问题入口
| 问题类型 | 文档 |
|---|---|
| 部署失败、服务拉不起来 | 部署相关排障 |
| 模板创建失败、模板不可用 | 模板相关排障 |
| 局域网网段冲突 | 本地网络 CIDR 冲突 |
| Host Mount 权限 | Host Mount 权限排障 |
| WebUI 使用 | WebUI 控制台 |
| 日志与服务 | 服务管理与日志 |
下一步
继续阅读 场景与集成，通过示例项目把基础能力组合起来。