Skip to main content

Environment 数据结构

Forward Environment API 复用的响应结构、配置对象与元数据约束。

Environment 对象

创建、查询、列表、更新接口都会返回该结构。
字段类型说明
idstringEnvironment ID,前缀为 env_
typestring固定值 "environment"
namestringEnvironment 名称,最长 255 字符;去除首尾空白后不能为空
descriptionstringEnvironment 描述
configEnvironment config规范化后的 Environment 配置;缺省的 package manager 字段会被补齐
metadataobjectEnvironment metadata,省略时为 {}
archived_atstring | null归档时间,RFC 3339 格式;active 时为 null
created_atstring创建时间,RFC 3339 格式
updated_atstring最后更新时间,RFC 3339 格式
identity_idstring | nullForward 归属身份。归属为某个 Identity 时返回该 Identity ID,否则为 null。详见 Identity 归属
icon_urlstring | nullForward 关联的 icon URL
binding_infoBinding info绑定信息(Template 引用计数等)

Identity 归属

一个账户(或 Workspace)下可以创建多个 Identity,每个 Identity 表示该账户(或 Workspace)接入产品中的一个终端用户。 Environment 可以归属于账户(或 Workspace),也可以归属于某个 Identity。归属决定了谁能看到和操作该 Environment。

如何指定归属

调用方归属如何指定
PAT账户 / Workspace不传 identity_id(默认,与此前行为一致)
PAT指定 Identity传查询参数 identity_id=<identity_id>
SAT(管理员)Workspace自动解析,不能通过参数切换
SAT(绑定 Identity)该 Identity自动解析,不能通过参数切换
identity_id 仅在操作 Identity 归属资源时使用,非必填;PAT 场景可显式传入,未传时为管理员视角;SAT 场景请签发 Identity 维度凭证且不要显式携带该参数(包括传空值),否则返回 HTTP 400。 PAT 指定的 Identity 必须属于当前 PAT 所代表的账户或 Workspace,且处于启用状态。不存在、已禁用、已删除或不属于当前调用方时返回 404。

归属隔离

  • 不传 identity_id 的调用看不到归属于 Identity 的 Environment。
  • 一个 Identity 看不到账户(或 Workspace)本身的 Environment,也看不到同账户下其他 Identity 的 Environment。
  • 在有效 Identity Scope 下(PAT 传入有效 identity_id,或使用 Identity SAT),跨 Scope 按 ID 查询、更新、归档或删除统一返回 404,不区分「不存在」与「不属于你」。
  • 未传 identity_id 的 PAT 和 Admin SAT 保持存量行为,Owner mismatch 返回 403。

支持的接口

创建、搜索、列出、查询、更新、归档、删除 Environment 均支持 identity_id 查询参数。
GET /api/v1/forward/resources/batch 暂不支持 identity_id,其可见性规则保持不变。

Environment config

Environment 运行时配置对象。省略时默认使用 {"type":"cloud"};显式传入时不能为 null 或空对象。
字段类型必填说明
typestring是"cloud" 或 "self_hosted"。仅当整个 config 省略时,才默认使用 cloud
packagesEnvironment packages否cloud Environment 的预装包声明;不能为 null
setup_scriptstring否见 Environment setup script
startup_scriptstring否见 Environment startup script
storageEnvironment storage否自有 OSS bucket 挂载,仅 cloud config 支持

self_hosted config

self_hosted Environment 只允许 type 和可选的 setup_script、startup_script;传入 packages 或其他不支持的字段返回 400 invalid_request_error。self_hosted 的 startup_script 只保存并原样返回,由外部 worker 决定是否执行。
{"type": "self_hosted", "setup_script": "./initialize-worker.sh"}

cloud config 响应形态

响应中的 cloud config 会补齐 packages 中所有保留的 package manager 数组(未声明的返回 []),示例:
{
  "type": "cloud",
  "packages": {
    "type": "packages",
    "apt": [],
    "cargo": [],
    "gem": [],
    "go": [],
    "npm": [],
    "pip": []
  }
}

Environment storage

storage.buckets[] 声明挂载到沙箱 /mnt/buckets/<name> 的自有 OSS bucket,仅 cloud config 支持,最多 7 个。完整说明(凭证、授权、权限策略、沙箱行为)见 挂载自有 OSS Bucket(Beta)。
字段类型必填说明
namestring是挂载目录名,同一 Environment 内唯一
providerstring是固定为 "aliyun-oss"
regionstring是OSS region ID,例如 cn-hangzhou
bucketstring是bucket 名称
prefixstring否只挂载该前缀;省略表示整个 bucket
accessstring否read_only(默认)或 read_write
accelerator_endpointstring否<label>.oss-data-acc.aliyuncs.com
credentialobject是{"type":"ram_role","role_arn":"..."} 或 {"type":"access_key","access_key_id":"...","access_key_secret":"..."}
credential 只写不读:响应只返回 type;access_key 还会返回打码的 access_key_id(如 LTAI****sKey)。更新时省略该字段或原样回传打码值会保留已保存的凭证。
{
  "type": "cloud",
  "storage": {
    "buckets": [
      {
        "name": "datasets",
        "provider": "aliyun-oss",
        "region": "cn-hangzhou",
        "bucket": "my-bucket",
        "prefix": "team/data/",
        "access": "read_only",
        "credential": {"type": "ram_role", "role_arn": "acs:ram::1234567890123456:role/qoder-oss-mount"}
      }
    ]
  }
}

Environment packages

packages 是"包管理器名称 → 软件包规格字符串数组"的映射。当前实际执行安装的管理器为 apt / npm / pip;cargo / gem / go 是响应中的保留字段,暂不支持通过这里安装依赖。
key类型说明示例
typestring响应中固定为 "packages",请求侧不要传入"packages"
aptstring 数组Debian/Ubuntu 包声明,通过 apt-get install -y 安装["git", "curl"]
npmstring 数组Node.js 全局包声明,通过 npm install -g 安装["pnpm@9"]
pipstring 数组Python 包声明,通过 pip install 安装["PyYAML==6.0.1"]
cargostring 数组响应保留字段;当前不支持通过该字段安装依赖[]
gemstring 数组响应保留字段;当前不支持通过该字段安装依赖[]
gostring 数组响应保留字段;当前不支持通过该字段安装依赖[]
每个 value 都必须是字符串数组。未声明的 package manager 数组会在响应中补为 []。

Environment setup script

setup_script 是 sandbox 准备阶段、packages 安装完成之后执行的一段 shell 脚本,常用于克隆代码、写配置文件、warmup 缓存等无法用 packages 表达的初始化步骤。
约束值
类型string
最大长度64 KB
解释器/bin/bash -lc
执行时机sandbox 准备阶段,packages 安装完成之后
超时10 分钟
非零退出本次 sandbox 准备失败
重复执行同一个 sandbox 中成功执行后不再重复;sandbox 回收重建后会再次执行
{
  "config": {
    "type": "cloud",
    "setup_script": "set -euo pipefail\n[ -d /workspace/.git ] || git clone https://github.com/me/repo /workspace\ncd /workspace && pnpm install --frozen-lockfile"
  }
}

Environment startup script

startup_script 是沙箱每次启动都会执行的一段 shell 脚本:首次启动时在 setup_script 之后执行,之后每次从暂停中恢复都会再执行一次。沙箱恢复后磁盘上的文件还在、进程不在,安装类步骤放 setup_script,启动数据库、dev server 等进程放 startup_script。
约束值
类型string
最大长度64 KB
解释器/bin/bash -lc,工作目录、环境变量与 setup_script 相同
执行时机沙箱每次启动后、执行第一个工具之前;首次启动时在 setup_script 之后
超时5 分钟;超时后脚本连同它启动的后台进程一起被停止
重复执行同一次启动内最多一次(开始执行前就记录);下次启动再执行
失败不影响 Session;每次启动失败产生一条 session.error,error.type 为 environment_startup_failed_error,本次启动内不重试
脚本必须能退出:常驻进程放到后台并把输出重定向到文件(如 nohup pnpm dev > /tmp/dev.log 2>&1 &)。恢复时旧进程可能仍在运行(部分运行时暂停时保留内存),脚本要自己判断服务是否已在运行。
{
  "config": {
    "type": "cloud",
    "packages": {"apt": ["redis-server"]},
    "startup_script": "pgrep -x redis-server || redis-server --daemonize yes"
  }
}

Environment metadata

Environment 的自定义元数据键值对;created_by 为 Forward 保留字段,调用方不可传入(传入返回 400)。
约束值
调用方提交上限通常 15 个自定义键值对
key 最长64 个字符
value 类型string
value 最长512 个字符

Binding info

Forward 在 Environment 响应中携带的引用聚合。
字段类型说明
agent_template_countinteger当前绑定该 Environment 的 Template 数量

列表分页字段

字段类型说明
dataEnvironment 对象 数组当前页记录
has_moreboolean是否还有下一页
next_pagestring | null下一页向后游标(推荐使用);has_more=true 时等于当前页 last_id,否则为 null
first_idstring | null当前页第一条记录 ID
last_idstring | null当前页最后一条记录 ID
请求侧的三种游标参数 page / after_id / before_id 互斥,同时提供多个返回 400;推荐使用 page,语义等价于 after_id。