管理 API 总览

管理 API 是 Cube Sandbox 的控制面接口集合，主要服务于：

• Web Dashboard
• 内部运维工具
• 平台集成脚本
• 值班巡检与状态查询

当前首批文档只覆盖已经在 CubeSandbox/openapi.yml 中明确导出的接口。

如果你已经拿到了返回状态码，想先按错误类型快速判断问题，可以直接查看 管理 API 错误码与排障矩阵。

基础路径

当前管理 API 的基础路径是：

/cubeapi/v1

这意味着完整路径通常形如：

/cubeapi/v1/health
/cubeapi/v1/cluster/overview
/cubeapi/v1/v2/sandboxes

当前已明确导出的资源分组

健康检查

• GET /health

适合用来确认管理面是否基础可达，也常用于 Dashboard 和运维脚本做快速连通性判断。

集群与节点

• GET /cluster/overview
• GET /nodes
• GET /nodes/{nodeID}

这组接口适合支撑：

• 集群资源总览
• 节点健康列表
• 单节点详情查看

模板

• GET /templates
• GET /templates/{templateID}

这组接口适合支撑：

• 模板列表
• 模板摘要与详情
• 模板状态、版本、副本和错误信息查询

沙箱与日志

• GET /sandboxes/{sandboxID}
• DELETE /sandboxes/{sandboxID}
• POST /sandboxes/{sandboxID}/pause
• POST /sandboxes/{sandboxID}/resume
• GET /v2/sandboxes
• GET /v2/sandboxes/{sandboxID}/logs

这组接口是管理 API 中最常用的一组，适合支撑：

• 沙箱查询
• 生命周期操作
• 结构化日志读取
• 条件筛选与巡检脚本

更完整说明请继续阅读：

• 管理 API：沙箱与日志

当前文档范围与边界

这份首批管理 API 文档刻意保持克制，只覆盖已经在 OpenAPI 合同中明确出现的接口。

因此，下面这些能力虽然在 Dashboard UI 中存在，但本页暂不当作“已稳定公开接口”来承诺：

• 新建模板
• 新建沙箱
• 模板重建、删除、构建日志
• 模板商店安装
• API Key 本地保存

这些功能可以在 UI 使用，但若要写成正式 API 合同，应以更明确的后端接口导出为准。

适合谁使用

运维和值班同学

可以基于这些接口做：

• 健康检查
• 节点巡检
• 沙箱列表与日志读取
• 故障初筛脚本

平台或控制台集成同学

可以基于这些接口做：

• 管理面二次封装
• 内部状态看板
• 自动化生命周期操作

推荐阅读顺序

1. 先看 API 鉴权说明
2. 再看本页，建立管理 API 的资源心智
3. 如果重点关注实例与日志，继续看 管理 API：沙箱与日志
4. 如果要按状态码做第一轮定位，继续看 管理 API 错误码与排障矩阵
5. 如需 UI 视角配合，再回看 Web Dashboard 快速上手

相关文档

• API 总览
• API 鉴权说明
• 管理 API 错误码与排障矩阵
• 管理 API：沙箱与日志
• Web Dashboard 快速上手