沙箱运行时

沙箱运行时 API 由沙箱内的 envd 提供，用于获取运行时状态、环境变量和资源指标，并作为进程 API、文件系统 API 的访问入口。

与区域级 Open API 不同，envd API 需要先通过沙箱实例 API获取沙箱连接信息，再访问沙箱运行时代理地址。

接入方式

获取连接信息

调用 POST /sandboxes/{sandboxID}/connect，确保沙箱处于运行状态，并获取 domain 与 envdAccessToken。

curl -X POST "$QINIU_SANDBOX_API_URL/sandboxes/$SANDBOX_ID/connect" \
  -H "X-API-Key: $QINIU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"timeout": 300}'

响应中的关键字段：

字段名称	字段类型	描述
domain	string	沙箱流量访问域名
envdAccessToken	string	访问 envd 的运行时令牌

构造 envd Endpoint

envd 默认通过端口 49983 暴露。通过沙箱代理访问时，Endpoint 形式如下：

https://49983-{sandboxID}.{domain}

例如：

export ENVD_API_BASE="https://49983-$SANDBOX_ID.$SANDBOX_DOMAIN"

如果 domain 为空，说明当前沙箱连接信息不足以直接从浏览器或外部 HTTP 客户端访问 envd，需要重新连接沙箱或使用 SDK/CLI 提供的封装能力。

认证方式

envd 使用 X-Access-Token 请求头认证：

X-Access-Token: <envdAccessToken>

部分文件下载、上传接口也支持签名参数，但常规调用建议直接使用 X-Access-Token。

Go SDK 的文件读写接口默认使用带签名的 /files URL；进程、PTY、文件系统 Connect RPC 接口使用 X-Access-Token。

Connect RPC 接口还可以通过 Basic Auth 指定执行用户：

Authorization: Basic <base64("user:")>

未指定用户时，envd 使用沙箱默认用户。

通用请求头

请求头	是否必填	说明
X-Access-Token	是	envd 运行时访问令牌
Authorization	否	Basic Auth 用户名，用于指定执行用户
Content-Type	是	REST JSON 接口使用 application/json；Connect RPC JSON 请求使用 application/json
Connect-Protocol-Version	Connect RPC 请求必填	固定为 1

健康检查

请求路径

GET /health

健康时返回 204 No Content。

请求示例

curl -I "$ENVD_API_BASE/health"

查询运行时指标

请求路径

GET /metrics

响应字段

字段名称	字段类型	描述
ts	integer	当前沙箱时间，Unix 秒级时间戳
cpu_count	integer	CPU 核数
cpu_used_pct	number	CPU 使用率
mem_total	integer	总内存，单位为字节
mem_used	integer	已使用内存，单位为字节
disk_total	integer	总磁盘，单位为字节
disk_used	integer	已使用磁盘，单位为字节

请求示例

curl -X GET "$ENVD_API_BASE/metrics" \
  -H "X-Access-Token: $ENVD_ACCESS_TOKEN"

查询环境变量

请求路径

GET /envs

返回环境变量对象，键和值均为字符串。

请求示例

curl -X GET "$ENVD_API_BASE/envs" \
  -H "X-Access-Token: $ENVD_ACCESS_TOKEN"

初始化运行时

描述

POST /init 用于系统侧初始化或更新 envd 运行时状态，例如同步时间和元数据、设置访问令牌、默认用户、默认工作目录、环境变量、挂载和初始化动作。

这是高权限接口，普通业务场景通常不需要直接调用。创建沙箱和恢复沙箱时，平台会完成必要的初始化。

请求路径

POST /init

请求参数

参数名称	参数类型	必填	描述
hyperloopIP	string	否	hyperloop 服务 IP
envVars	object	否	需要合并到运行时的环境变量
accessToken	string	否	envd 访问令牌；设置后不可改为其他值
timestamp	string	否	RFC3339 时间戳；旧于最近一次初始化的请求会被跳过
defaultUser	string	否	默认执行用户
defaultWorkdir	string	否	默认工作目录
mounts	array	否	需要设置的文件系统挂载
postInitActions	array	否	初始化后执行的命令
caCertPEM	string	否	注入系统信任存储的 CA 证书

成功时返回 204 No Content。

相关文档

• 沙箱实例
• 进程与终端
• 文件系统