全栈应用服务器

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

    沙箱实例

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

    沙箱实例

    沙箱实例 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：

    参数名称 参数类型 必填 描述
    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

    响应字段

    字段名称 字段类型 描述
    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"
    }
  }'

    响应示例

    {
  "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 总磁盘，单位为字节

    相关文档

    以上内容是否对您有帮助？