Environment 数据结构

Environment 对象

创建、查询、列表、更新接口都会返回该结构。

字段	类型	说明
`id`	string	Environment ID，前缀为 `env_`
`type`	string	固定值 `"environment"`
`name`	string	Environment 名称，最长 255 字符；去除首尾空白后不能为空
`description`	string	Environment 描述
`config`	Environment config	规范化后的 Environment 配置；缺省的 package manager 字段会被补齐
`metadata`	object	Environment metadata，省略时为 `{}`
`archived_at`	string \| null	归档时间，RFC 3339 格式；active 时为 `null`
`created_at`	string	创建时间，RFC 3339 格式
`updated_at`	string	最后更新时间，RFC 3339 格式
`identity_id`	string \| null	Forward 归属身份。归属为某个 Identity 时返回该 Identity ID，否则为 `null`。详见 Identity 归属
`icon_url`	string \| null	Forward 关联的 icon URL
`binding_info`	Binding 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 或空对象。

字段	类型	必填	说明
`type`	string	是	`"cloud"` 或 `"self_hosted"`。仅当整个 `config` 省略时，才默认使用 `cloud`
`packages`	Environment packages	否	`cloud` Environment 的预装包声明；不能为 `null`
`setup_script`	string	否	见 Environment setup script

`self_hosted` config

self_hosted Environment 只允许 type 和可选的 setup_script；传入 packages 或其他不支持的字段返回 400 invalid_request_error。

{"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 packages

packages 是"包管理器名称 → 软件包规格字符串数组"的映射。当前实际执行安装的管理器为 apt / npm / pip；cargo / gem / go 是响应中的保留字段，暂不支持通过这里安装依赖。

key	类型	说明	示例
`type`	string	响应中固定为 `"packages"`，请求侧不要传入	`"packages"`
`apt`	string 数组	Debian/Ubuntu 包声明，通过 `apt-get install -y` 安装	`["git", "curl"]`
`npm`	string 数组	Node.js 全局包声明，通过 `npm install -g` 安装	`["pnpm@9"]`
`pip`	string 数组	Python 包声明，通过 `pip install` 安装	`["PyYAML==6.0.1"]`
`cargo`	string 数组	响应保留字段；当前不支持通过该字段安装依赖	`[]`
`gem`	string 数组	响应保留字段；当前不支持通过该字段安装依赖	`[]`
`go`	string 数组	响应保留字段；当前不支持通过该字段安装依赖	`[]`

每个 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 metadata

Environment 的自定义元数据键值对；created_by 为 Forward 保留字段，调用方不可传入（传入返回 400）。

约束	值
调用方提交上限	通常 15 个自定义键值对
key 最长	64 个字符
value 类型	string
value 最长	512 个字符

Binding info

Forward 在 Environment 响应中携带的引用聚合。

字段	类型	说明
`agent_template_count`	integer	当前绑定该 Environment 的 Template 数量

列表分页字段

字段	类型	说明
`data`	Environment 对象数组	当前页记录
`has_more`	boolean	是否还有下一页
`next_page`	string \| null	下一页向后游标（推荐使用）；`has_more=true` 时等于当前页 `last_id`，否则为 `null`
`first_id`	string \| null	当前页第一条记录 ID
`last_id`	string \| null	当前页最后一条记录 ID

请求侧的三种游标参数 page / after_id / before_id 互斥，同时提供多个返回 400；推荐使用 page，语义等价于 after_id。

​Environment 对象

​Identity 归属

​如何指定归属

​归属隔离

​支持的接口

​Environment config

​self_hosted config

​cloud config 响应形态

​Environment packages

​Environment setup script

​Environment metadata

​Binding info

​列表分页字段

Environment 对象

Identity 归属

如何指定归属

归属隔离

支持的接口

Environment config

`self_hosted` config

`cloud` config 响应形态

Environment packages

Environment setup script

Environment metadata

Binding info

列表分页字段