Cube Sandbox

简体中文

English

简体中文

English

Appearance

管理 API：沙箱与日志 ​

如果你最关心的是“怎么查沙箱、怎么暂停恢复、怎么拿日志”，这一页就是管理 API 里最值得先看的部分。

已导出的沙箱相关接口 ​

当前 OpenAPI 中已明确导出的沙箱相关接口包括：

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

沙箱详情 ​

GET /sandboxes/{sandboxID} ​

适合获取单个沙箱的详细信息，例如：

  • 状态
  • 模板 ID
  • CPU / 内存规格
  • 启动时间
  • 域名
  • Metadata
  • 运行时相关字段

它通常适合用在：

  • Dashboard 详情页
  • 值班工具的实例排查
  • 通过沙箱 ID 回溯实例上下文

沙箱生命周期操作 ​

DELETE /sandboxes/{sandboxID} ​

用于终止并删除沙箱。常见于清理异常实例、回收测试实例或主动停止业务实例。

POST /sandboxes/{sandboxID}/pause ​

用于暂停实例。常见于想保留实例状态、但暂时不需要活跃运行的场景。

POST /sandboxes/{sandboxID}/resume ​

用于恢复已暂停实例。该接口通常需要携带恢复请求体，服务端成功后会返回恢复后的沙箱信息。

沙箱列表接口 ​

GET /v2/sandboxes ​

这是一条更适合做巡检和筛选的列表接口，支持以下查询参数：

  • metadata
  • state
  • nextToken
  • limit

它更适合：

  • 按状态筛选实例
  • 面向值班场景批量查看实例
  • 为内部脚本提供分页与条件查询入口

结构化日志接口 ​

GET /v2/sandboxes/{sandboxID}/logs ​

这条接口提供结构化日志读取能力，支持以下查询参数：

  • cursor
  • limit
  • direction

它更适合：

  • 日志面板按方向读取
  • 分页式增量拉取
  • 结构化日志分析与排障

相比只看原始终端输出，这条接口更适合被 Dashboard 或运维工具消费。

典型排障流程 ​

场景一：实例异常但不知道原因 ​

  1. 先调用列表接口按状态筛选
  2. 再调用详情接口获取具体实例信息
  3. 最后调用日志接口确认运行时报错

场景二：实例需要临时冻结后再恢复 ​

  1. 调用 pause
  2. 在需要时调用 resume
  3. 恢复后重新检查详情和日志

场景三：批量值班巡检 ​

  1. 调用 /v2/sandboxes 拉取当前实例
  2. 只对异常状态或高关注实例继续调用详情与日志接口

与 Dashboard 的对应关系 ​

这些接口大体对应 Dashboard 中的：

如果你正在写内部工具，可以把 Dashboard 的实例视图当作“接口组合后的参考交互”。

常见边界说明 ​

当前首批文档不把“创建沙箱”写入已稳定公开的管理 API 合同，因为它没有出现在当前 OpenAPI 导出列表中。若后续合同补齐，再单独扩展文档会更稳妥。

相关文档 ​