沙箱实例

沙箱实例 API 用于创建、查询和管理沙箱生命周期，并获取沙箱日志和资源监控指标。

创建沙箱

描述

从指定模板创建一个沙箱实例。

请求路径

POST /sandboxes

请求参数

参数名称	参数类型	必填	描述
templateID	string	是	模板 ID 或模板名称
timeout	integer	否	沙箱超时时间，单位为秒；默认为 15
autoPause	boolean	否	超时后是否自动暂停沙箱；默认为 false
secure	boolean	否	是否启用沙箱系统通信安全模式
allow_internet_access	boolean	否	是否允许沙箱访问公网；为 false 时等价于在网络配置中禁止 0.0.0.0/0 出站
network.allowPublicTraffic	boolean	否	沙箱对外访问地址是否允许公开访问；默认为 true
network.allowOut	string[]	否	允许出站访问的 CIDR 或 IP 列表
network.denyOut	string[]	否	禁止出站访问的 CIDR 或 IP 列表
network.maskRequestHost	string	否	沙箱请求使用的 Host 掩码
metadata	object	否	自定义元数据，键和值均为字符串
envVars	object	否	沙箱启动时注入的环境变量
mcp	object	否	MCP 配置
injections	array	否	内联密钥注入规则，最多 20 项
resources	array	否	沙箱启动前准备并挂载的外部资源，最多 20 项

resources 当前支持 github_repository 和 kodo。

GitHub 仓库资源字段：

参数名称	参数类型	必填	描述
resources[].type	string	是	资源类型；GitHub 仓库资源填写 github_repository
resources[].url	string	是	GitHub 仓库 URL，支持 HTTPS 地址，或 git@github.com:owner/repo.git 这种 GitHub SSH 风格地址；平台会统一转为 HTTPS 处理
resources[].mount_path	string	是	仓库内容在沙箱内的绝对挂载路径
resources[].authorization_token	string	是	访问仓库的 GitHub Token；同一沙箱内多个 GitHub 仓库资源当前必须使用同一个 Token

Kodo 存储桶资源字段：

Kodo 资源只支持使用七牛 AK/SK 鉴权创建沙箱；仅使用沙箱 API Key 的创建请求不支持挂载 Kodo 资源。AK/SK 用于平台侧访问 Bucket，不会以明文暴露给沙箱。

参数名称	参数类型	必填	描述
resources[].type	string	是	资源类型；Kodo 存储桶资源填写 kodo
resources[].bucket	string	是	Kodo Bucket 名称
resources[].mount_path	string	是	Bucket 内容在沙箱内的绝对挂载路径
resources[].prefix	string	否	Bucket 内的对象 key 前缀；传入后只暴露该前缀下的内容
resources[].read_only	boolean	否	是否只读挂载；显式传 true 时只校验读取权限，未传或传 false 时平台会尝试校验写权限，无写权限时自动降级为只读挂载

响应字段

字段名称	字段类型	描述
templateID	string	创建沙箱使用的模板 ID
sandboxID	string	沙箱实例 ID
alias	string	模板别名
envdVersion	string	沙箱内 envd 版本
envdAccessToken	string	访问沙箱内 envd 服务的令牌
trafficAccessToken	string	访问沙箱代理流量所需的令牌
domain	string	沙箱流量访问域名

请求示例

curl -X POST "$QINIU_SANDBOX_API_URL/sandboxes" \
  -H "X-API-Key: $QINIU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "templateID": "base",
    "timeout": 300,
    "metadata": {
      "project": "demo"
    },
    "envVars": {
      "APP_ENV": "dev"
    }
  }'

创建沙箱并挂载 Kodo 存储桶资源：

curl -X POST "$QINIU_SANDBOX_API_URL/sandboxes" \
  -H "X-API-Key: $QINIU_API_KEY" \
  -H "Authorization: Qiniu <SignedToken>" \
  -H "Content-Type: application/json" \
  -d '{
    "templateID": "base",
    "resources": [
      {
        "type": "kodo",
        "bucket": "my-bucket",
        "mount_path": "/mnt/kodo",
        "prefix": "datasets/demo",
        "read_only": true
      }
    ]
  }'

其中 SignedToken 需要用七牛 AK/SK 生成。只带 X-API-Key、不带 AK/SK 签名的请求不支持创建 Kodo 资源沙箱。

响应示例

{
  "templateID": "base",
  "sandboxID": "sbx_123456",
  "envdVersion": "0.1.0",
  "envdAccessToken": "envd-token",
  "trafficAccessToken": "traffic-token",
  "domain": "sbx_123456.example.qiniuapi.com"
}

查询沙箱列表

描述

查询当前账号下的沙箱列表。推荐使用 GET /v2/sandboxes，支持状态过滤和分页。

请求路径

GET /v2/sandboxes

兼容路径：

GET /sandboxes

请求参数

参数名称	参数类型	必填	描述
metadata	string	否	元数据过滤条件，例如 user=abc&app=prod；键和值需要 URL 编码
state	string[]	否	沙箱状态过滤，可取 running、paused
nextToken	string	否	分页游标
limit	integer	否	每页返回数量，范围 1 到 100，默认 100

响应字段

返回沙箱对象数组：

字段名称	字段类型	描述
templateID	string	创建沙箱使用的模板 ID
sandboxID	string	沙箱实例 ID
alias	string	模板别名
startedAt	string	沙箱启动时间
endAt	string	沙箱过期时间
cpuCount	integer	CPU 核数
memoryMB	integer	内存大小，单位为 MiB
diskSizeMB	integer	磁盘大小，单位为 MiB
metadata	object	自定义元数据
state	string	沙箱状态，取值为 running 或 paused
envdVersion	string	沙箱内 envd 版本
executionId	string	沙箱执行 ID
uid	string	七牛用户 UID

请求示例

curl -G "$QINIU_SANDBOX_API_URL/v2/sandboxes" \
  -H "X-API-Key: $QINIU_API_KEY" \
  --data-urlencode "state=running" \
  --data-urlencode "limit=20"

获取沙箱详情

请求路径

GET /sandboxes/{sandboxID}

路径参数

参数名称	参数类型	必填	描述
sandboxID	string	是	沙箱实例 ID

响应字段

字段名称	字段类型	描述
templateID	string	创建沙箱使用的模板 ID
sandboxID	string	沙箱实例 ID
startedAt	string	沙箱启动时间
endAt	string	沙箱过期时间
cpuCount	integer	CPU 核数
memoryMB	integer	内存大小，单位为 MiB
diskSizeMB	integer	磁盘大小，单位为 MiB
metadata	object	自定义元数据
state	string	沙箱状态
envdVersion	string	沙箱内 envd 版本
envdAccessToken	string	访问沙箱内 envd 服务的令牌
domain	string	沙箱流量访问域名

删除沙箱

描述

终止并删除指定沙箱。

请求路径

DELETE /sandboxes/{sandboxID}

路径参数

参数名称	参数类型	必填	描述
sandboxID	string	是	沙箱实例 ID

响应字段

成功时返回 204 No Content，无响应体。

暂停沙箱

请求路径

POST /sandboxes/{sandboxID}/pause

成功时返回 204 No Content。

恢复沙箱

请求路径

POST /sandboxes/{sandboxID}/resume

请求参数

参数名称	参数类型	必填	描述
timeout	integer	否	恢复后沙箱超时时间，单位为秒；默认为 15
autoPause	boolean	否	已废弃，恢复后超时是否自动暂停

成功时返回沙箱连接信息，字段同创建沙箱响应。

连接沙箱

描述

获取沙箱连接信息。如果沙箱处于暂停状态，会先恢复沙箱；如果沙箱正在运行，只延长 TTL。

请求路径

POST /sandboxes/{sandboxID}/connect

请求参数

参数名称	参数类型	必填	描述
timeout	integer	是	从当前时间开始计算的超时时间，单位为秒

成功时返回沙箱连接信息，字段同创建沙箱响应。

设置沙箱超时时间

请求路径

POST /sandboxes/{sandboxID}/timeout

请求参数

参数名称	参数类型	必填	描述
timeout	integer	是	从当前时间开始计算的超时时间，单位为秒

成功时返回 204 No Content。

延长沙箱存活时间

请求路径

POST /sandboxes/{sandboxID}/refreshes

请求参数

参数名称	参数类型	必填	描述
duration	integer	否	延长时长，单位为秒，最大 3600

成功时返回 204 No Content。

查询沙箱日志

请求路径

GET /sandboxes/{sandboxID}/logs

请求参数

参数名称	参数类型	必填	描述
start	integer	否	日志起始时间戳，单位为毫秒
limit	integer	否	返回日志数量

响应字段

字段名称	字段类型	描述
logs[].timestamp	string	日志时间
logs[].line	string	日志内容
logEntries[].timestamp	string	结构化日志时间
logEntries[].level	string	日志级别
logEntries[].message	string	日志消息
logEntries[].fields	object	结构化字段

查询沙箱指标

请求路径

GET /sandboxes/{sandboxID}/metrics

请求参数

参数名称	参数类型	必填	描述
start	integer	否	起始 Unix 时间戳，单位为秒
end	integer	否	结束 Unix 时间戳，单位为秒

响应字段

返回指标对象数组：

字段名称	字段类型	描述
timestampUnix	integer	指标时间，Unix 秒级时间戳
cpuCount	integer	CPU 核数
cpuUsedPct	number	CPU 使用率
memUsed	integer	已使用内存，单位为字节
memTotal	integer	总内存，单位为字节
diskUsed	integer	已使用磁盘，单位为字节
diskTotal	integer	总磁盘，单位为字节

批量查询沙箱指标

请求路径

GET /sandboxes/metrics

请求参数

参数名称	参数类型	必填	描述
sandbox_ids	string[]	是	沙箱 ID 列表，使用单个逗号分隔的 query 参数传递，最多 100 个

请求示例

curl -G "$QINIU_SANDBOX_API_URL/sandboxes/metrics" \
  -H "X-API-Key: $QINIU_API_KEY" \
  --data-urlencode "sandbox_ids=sbx_123456,sbx_789012"

响应字段

返回以沙箱 ID 为 key 的指标对象：

字段名称	字段类型	描述
sandboxes	object	沙箱指标映射，key 为沙箱 ID
sandboxes.<sandboxID>.timestampUnix	integer	指标时间，Unix 秒级时间戳
sandboxes.<sandboxID>.cpuCount	integer	CPU 核数
sandboxes.<sandboxID>.cpuUsedPct	number	CPU 使用率
sandboxes.<sandboxID>.memUsed	integer	已使用内存，单位为字节
sandboxes.<sandboxID>.memTotal	integer	总内存，单位为字节
sandboxes.<sandboxID>.diskUsed	integer	已使用磁盘，单位为字节
sandboxes.<sandboxID>.diskTotal	integer	总磁盘，单位为字节

相关文档

• API 概述
• 沙箱生命周期
• 沙箱监控指标
• 沙箱元数据
• 沙箱网络访问
• 资源挂载