Schema

完整的示例请参考 fc-sandbox example

fc-sandbox 组件用于管理阿里云函数计算云沙箱（FC Sandbox）资源。一个 fc-sandbox resource 等于一个 Team，volumes（存储卷）与 apiKeys（访问密钥）作为内嵌数组随 Team 一起编排。

资源配额（Quota）是账号 / tag 级别的资源，不属于某个 Team，因此不进 s.yaml，只通过 quota 命令管理。

参数名	必填	类型	参数描述
region	True	Enum	地域，取值参见支持的地域
teamName	True	String	Team 名称，s.yaml 中的身份键，改名等价于新建资源，参见身份解析
description	False	String	Team 描述
plan	False	String	Team 套餐，默认 `base`
resourceGroupID	False	String	资源组 ID
endpoint	False	String	自定义 endpoint，为空时按 region 推导
volumes	False	List<Struct>	Team 内的存储卷。存储配置创建后不可修改，参见约束一
apiKeys	False	List<Struct>	Team 内的访问密钥。`apiKeyValue` 不是声明字段，参见约束二

支持的地域

云沙箱目前在以下 8 个地域提供服务：

cn-hangzhou  cn-shanghai  cn-beijing  cn-shenzhen  cn-hongkong  ap-southeast-1  us-west-1  us-east-1

填写其他地域时，组件只会输出 warn 提示而不会阻断，以便新地域上线后无需升级组件：

Invalid region, The allowed regions are cn-hangzhou,cn-shanghai,cn-beijing,cn-shenzhen,cn-hongkong,ap-southeast-1,us-west-1,us-east-1

组件不需要为每个地域预置接入点：endpoint 按 fcsandbox.<region>.aliyuncs.com 的规则推导，所以地域一旦开服就能直接用，即使还不在上面的列表里。

⚠️ 因此看到这条 warn 有两种可能：地域已开服、只是组件的列表还没跟上（请求会正常成功，警告可忽略），或者地域尚未开服（请求会失败）。后者请先用列表内的地域验证，或用 endpoint 显式指定接入点。完全不填 region 会直接报错 Region not specified, please specify --region。

volumes

Team 内的存储卷列表。ossVolumeConfig 与 agenticFSVolumeConfig 二选一。

参数名	必填	类型	参数描述
volumeName	True	String	Volume 名称，Team 内的身份键
status	False	String	期望状态，Volume 唯一可更新的字段，取值以服务端返回的 `status` 为准
ossVolumeConfig	False	Struct	OSS 类型存储卷配置，与 `agenticFSVolumeConfig` 二选一
agenticFSVolumeConfig	False	Struct	AgenticFS 类型存储卷配置，与 `ossVolumeConfig` 二选一

ossVolumeConfig

参数名	必填	类型	参数描述
bucketName	False	String	OSS Bucket 名称
bucketPath	False	String	挂载的 Bucket 路径，如 `/data`
endpoint	False	String	Bucket 的 endpoint，如 `oss-cn-hangzhou.aliyuncs.com`
readOnly	False	Boolean	是否以只读方式挂载

agenticFSVolumeConfig

参数名	必填	类型	参数描述
serverAddr	False	String	服务端地址，如 `1.2.3.4:2049`
userID	False	Number	挂载使用的 user id
groupID	False	Number	挂载使用的 group id

apiKeys

Team 内的访问密钥列表。

参数名	必填	类型	参数描述
apiKeyName	True	String	ApiKey 名称，Team 内的身份键
expireTime	False	String	过期时间，RFC3339 格式，如 `2027-01-01T00:00:00Z`
status	False	String	期望状态，取值以服务端返回的 `status` 为准
ipWhitelist	False	List<Struct>	IP 白名单
ipBlacklist	False	List<Struct>	IP 黑名单

⚠️ apiKeyValue（密钥明文）不是声明字段，由服务端生成，写在 s.yaml 里无效，也不会出现在 info / plan / sync 的输出中。需要取回明文用 apikey get，参见约束二。

ipWhitelist / ipBlacklist

参数名	必填	类型	参数描述
ipAddress	False	String	IP 或网段，如 `1.2.3.0/24`
description	False	String	该条目的描述

字段名是 ipAddress（不是 ip）。

身份解析：名字 → ID

云沙箱的 OpenAPI 用服务端生成的 teamID / volumeID / apiKeyID 寻址，而 s.yaml 里只有名字。组件在每次操作前会先按名字查询线上资源（全量翻页后做精确匹配，因为服务端的 name 过滤是模糊语义），据此决定是 create 还是 update。

因此：

改名等价于新建资源 —— 旧资源不会被自动回收，需要显式 s remove 或 s cli fc-sandbox <group> remove；
只想改名而保留资源，走 CLI 的 --new-team-name（需要服务端 allowUpdateTeamName 为 true），再同步修改 s.yaml。Volume 与 ApiKey 不支持改名，只能删除重建。

三个必须知道的约束

1. Volume 存储配置创建后不可修改

服务端的 UpdateVolume 只接受 status。当本地的 ossVolumeConfig / agenticFSVolumeConfig 与线上不一致时，组件会明确 warn 出具体差异与修复命令，然后只下发 status 变更——既不静默忽略，也不报错中断：

Volume "data" config differs from the remote one, but the OSS / AgenticFS config is IMMUTABLE after creation — only the status change is sent.
  local : {"ossVolumeConfig":{"bucketName":"my-bkt"}}
  remote: {"ossVolumeConfig":{"bucketName":"other-bkt"}}
  To apply it, remove the volume first: s cli fc-sandbox volume remove --volume-name data --team-id t-xxx

要应用配置变更只能重建（⚠️ 会丢失挂载关系，重建前确认没有沙箱正在使用它）：

s cli fc-sandbox volume remove --volume-name data --team-id t-xxx --region cn-hangzhou -a default -y
s deploy --volume data

2. apiKeyValue 的可见性取决于接口

apiKeyValue 是凭证，但并非任何地方都看不到——服务端把"单个精确读取"和"批量列举"分开了，组件沿用同一条线：

出口	对应接口	`apiKeyValue`
`apikey get`	`DescribeApiKey`	明文
`apikey create` / `reset` / `s deploy` 新建	`CreateApiKey` / `ResetApiKey`	命令返回值里是 `***`，明文由单独一行 warn 打印（`s deploy` 常在 CI 里跑，返回值会进构建日志）
`apikey list` / `s info` / `s plan` diff	`ListApiKeys`	接口本身不返回该字段，只有 `apiKeyMask`
`--debug` 日志	全部接口	一律脱敏为 `***`
`s sync` 产物	——	字段白名单里没有它，绝不写入

两条推论：

明文丢了不用重置，直接 s cli fc-sandbox apikey get --team-name dev --api-key-name ci 取回（也因此不必为了保存密钥去管道 create 的输出）；
反过来说，apikey get 的输出是凭证。不要接进 CI 日志或在共享终端里执行——debug 日志始终脱敏，但命令的正常输出不会。

apikey reset 的用途是轮换凭证（怀疑泄露、定期更换），它会立即失效旧值。

3. Team 与内嵌资源的编排顺序固定

deploy 的顺序是 team → volumes → apiKeys（后两者需要 teamID），remove 严格逆序 apiKeys → volumes → team（Team 上还挂着资源时删除会失败）。

权限与策略说明

云沙箱专属的 RAM 策略尚未最终确认，当前按函数计算全量权限配置即可：AliyunFCFullAccess。

只读命令（plan / info / sync / 各 list、get）可以使用只读权限：AliyunFCReadOnlyAccess。