全栈应用服务器 > API 文档 > 沙箱概述

沙箱概述

最近更新时间: 2026-05-19 18:00:56

七牛沙箱 Open API 用于通过 HTTP 直接管理沙箱实例、模板和密钥注入规则。所有接口均以区域接入点为 Host，请根据沙箱所在区域选择对应的 Endpoint。

服务接入点

区域	区域标识符	API Endpoint
中国（扬州1）	`cn-yangzhou-1`	`https://cn-yangzhou-1-sandbox.qiniuapi.com`
美国（达拉斯1）	`us-south-1`	`https://us-south-1-sandbox.qiniuapi.com`

沙箱实例和模板管理接口使用 X-API-Key 请求头认证：

X-API-Key: <QINIU_API_KEY>

部分模板构建接口也接受 Bearer 形式的 API Key：

Authorization: Bearer <QINIU_API_KEY>

Go SDK 和 qshell 会同时设置 X-API-Key 与 Authorization: Bearer <QINIU_API_KEY>，一般不需要手动处理这两个请求头的差异。

密钥注入规则管理接口使用七牛账户鉴权请求头：

Authorization: Qiniu <SignedToken>

SignedToken 由七牛 AK/SK 对请求签名生成。Go SDK 和 qshell 会使用客户端配置的七牛凭证自动签名。

QINIU_API_KEY 可从七牛云 API 密钥管理获取。

请求头	是否必填	说明
`X-API-Key`	部分接口必填	沙箱实例和模板管理接口的 API Key
`Authorization`	部分接口必填	模板构建接口的 Bearer API Key，或密钥注入规则接口的七牛签名
`Content-Type`	有请求体时必填	固定为 `application/json`

分组	文档	说明
沙箱实例	沙箱实例	创建、查询、连接、暂停、恢复、删除沙箱，并查看日志和监控指标
模板	模板	创建模板、上传构建文件、启动构建、查看模板和构建状态
密钥注入	密钥注入	管理平台侧保存的 HTTPS 请求密钥注入规则
沙箱运行时	沙箱运行时	访问 envd 运行时状态、环境变量和资源指标
进程与终端	进程与终端	通过 envd 启动命令、连接进程、发送输入和管理 PTY
文件系统	文件系统	通过 envd 读写文件、列目录、移动删除文件和监听目录变化

接口错误响应统一返回 JSON：

字段	类型	说明
`code`	`integer`	错误码
`message`	`string`	错误信息

示例：

{
  "code": 400,
  "message": "invalid request"
}

curl -X GET "$QINIU_SANDBOX_API_URL/v2/sandboxes" \
  -H "X-API-Key: $QINIU_API_KEY"