Skip to content

Volume 操作

volume 命令是对云沙箱存储卷操作的命令：主要包括存储卷的创建、查看、列举、状态更新、删除等功能。

命令解析

当执行命令volume -h/volume --help时，可以获取帮助文档。

Volume 是 Team 下的资源，因此每个子命令都需要先定位 Team：

  • --team-id：直接指定 Team ID；
  • --team-name：指定 Team 名称，未显式传入时回落到 s.yaml 的 props.teamName。

定位 Volume 自身则用 --volume-id 或 --volume-name（Team 内的身份键）。

⚠️ 最重要的约束：Volume 的 ossVolumeConfig / agenticFSVolumeConfig 创建后不可修改，服务端的 UpdateVolume 只接受 status。要变更存储配置只能删除重建，详见 Yaml 规范中的约束。

volume create 命令

volume create 命令，是创建存储卷的命令。

当执行命令volume create -h/volume create --help时，可以获取帮助文档。

参数解析

参数全称 参数缩写 Yaml 模式下必填 Cli 模式下必填 参数含义
region - 选填 必填 地域名称，取值参见支持的地域
team-id - 选填 选填 Team ID，与 --team-name 二选一
team-name - 选填 选填 Team 名称，--team-id 缺省时使用
volume-name - 必填 必填 Volume 名称
oss-bucket-name - 选填 选填 OSS 类型：Bucket 名称
oss-bucket-path - 选填 选填 OSS 类型：挂载路径
oss-endpoint - 选填 选填 OSS 类型：Bucket endpoint
oss-read-only - 选填 选填 OSS 类型：以只读方式挂载，--oss-read-only 表示开启
agenticfs-server-addr - 选填 选填 AgenticFS 类型：服务端地址
agenticfs-user-id - 选填 选填 AgenticFS 类型：user id
agenticfs-group-id - 选填 选填 AgenticFS 类型：group id

当前命令还支持部分全局参数（例如-a/--access, --debug等），详情可参考 Serverless Devs 全局参数文档

OSS 参数与 AgenticFS 参数二选一，必须指定其中一组，否则报错：

No volume config specified, please specify OSS options (--oss-bucket-name ...) or AgenticFS options (--agenticfs-server-addr ...)

操作案例

创建 OSS 类型存储卷：

s cli fc-sandbox volume create --team-name dev --volume-name data \
    --oss-bucket-name my-bkt --oss-bucket-path /data --oss-endpoint oss-cn-hangzhou.aliyuncs.com \
    --region cn-hangzhou -a default

创建 AgenticFS 类型存储卷：

s cli fc-sandbox volume create --team-name dev --volume-name fs \
    --agenticfs-server-addr 1.2.3.4:2049 --agenticfs-user-id 0 --agenticfs-group-id 0 \
    --region cn-hangzhou -a default

上述命令的执行结果示例：

volumeID:     v-9fquxxxxxxxx
volumeName:   data
teamID:       t-5lycxxxxxxxx
status:       active
storageClass: OSS
createdAt:    2026-08-16T03:25:10Z
ossVolumeConfig:
  bucketName: my-bkt
  bucketPath: /data
  endpoint:   oss-cn-hangzhou.aliyuncs.com
  readOnly:   false

volume get 命令

volume get 命令，是获取指定存储卷详情的命令。

当执行命令volume get -h/volume get --help时，可以获取帮助文档。

参数解析

参数全称 参数缩写 Yaml 模式下必填 Cli 模式下必填 参数含义
region - 选填 必填 地域名称，取值参见支持的地域
team-id - 选填 选填 Team ID，与 --team-name 二选一
team-name - 选填 选填 Team 名称，--team-id 缺省时使用
volume-id - 选填 选填 Volume ID，与 --volume-name 二选一
volume-name - 选填 选填 Volume 名称，--volume-id 缺省时使用

当前命令还支持部分全局参数（例如-a/--access, --debug等），详情可参考 Serverless Devs 全局参数文档

操作案例

s cli fc-sandbox volume get --team-name dev --volume-name data --region cn-hangzhou -a default

上述命令的执行结果示例：

volumeID:     v-9fquxxxxxxxx
volumeName:   data
teamID:       t-5lycxxxxxxxx
status:       active
storageClass: OSS
statusReason:
createdAt:    2026-08-16T03:25:10Z
ossVolumeConfig:
  bucketName: my-bkt
  bucketPath: /data
  endpoint:   oss-cn-hangzhou.aliyuncs.com
  readOnly:   false

volume list 命令

volume list 命令，是列举存储卷列表的命令。

当执行命令volume list -h/volume list --help时，可以获取帮助文档。

参数解析

参数全称 参数缩写 Yaml 模式下必填 Cli 模式下必填 参数含义
region - 选填 必填 地域名称，取值参见支持的地域
team-id - 选填 选填 按 Team ID 过滤
team-name - 选填 选填 按 Team 名称过滤，--team-id 缺省时使用
volume-name - 选填 选填 按 Volume 名称过滤
status - 选填 选填 按状态过滤
resource-group-id - 选填 选填 按资源组 ID 过滤
table - 选填 选填 是否以表格形式输出，--table 表示以表格形式输出

当前命令还支持部分全局参数（例如-a/--access, --debug等），详情可参考 Serverless Devs 全局参数文档

操作案例

s cli fc-sandbox volume list --team-name dev --table --region cn-hangzhou -a default

上述命令的执行结果示例：

-
  volumeID:     v-9fquxxxxxxxx
  volumeName:   data
  teamID:       t-5lycxxxxxxxx
  status:       active
  storageClass: OSS
  createdAt:    2026-08-16T03:25:10Z

如果指定了--table参数，输出示例：

volumeID volumeName teamID status storageClass statusReason createdAt
v-9fquxxxxxxxx data t-5lycxxxxxxxx active OSS 2026-08-16T03:25:10Z

list 内部已做全量翻页（Volume 用的是 maxResults + nextToken 风格），无需自行处理翻页。不指定 Team 时列举当前地域下的全部存储卷。

volume update 命令

volume update 命令，是更新存储卷状态的命令。

当执行命令volume update -h/volume update --help时，可以获取帮助文档。

参数解析

参数全称 参数缩写 Yaml 模式下必填 Cli 模式下必填 参数含义
region - 选填 必填 地域名称，取值参见支持的地域
team-id - 选填 选填 Team ID，与 --team-name 二选一
team-name - 选填 选填 Team 名称，--team-id 缺省时使用
volume-id - 选填 选填 Volume ID，与 --volume-name 二选一
volume-name - 选填 选填 Volume 名称，--volume-id 缺省时使用
status - 必填 必填 期望的 Volume 状态

当前命令还支持部分全局参数（例如-a/--access, --debug等），详情可参考 Serverless Devs 全局参数文档

操作案例

s cli fc-sandbox volume update --team-name dev --volume-name data --status inactive \
    --region cn-hangzhou -a default

注意事项

  • 只能更新 status。不传 --status 直接报错：

    Only volume status can be updated, please specify --status. The volume config is immutable after creation.

  • 同时传入 OSS / AgenticFS 参数时会被忽略并 warn，只有 --status 会被下发：

    Volume config (OSS / AgenticFS) cannot be modified after creation; only --status is sent. To change the config, remove the volume and create it again.

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

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

volume remove 命令

volume remove 命令，是删除存储卷的命令。

当执行命令volume remove -h/volume remove --help时，可以获取帮助文档。

参数解析

参数全称 参数缩写 Yaml 模式下必填 Cli 模式下必填 参数含义
region - 选填 必填 地域名称，取值参见支持的地域
team-id - 选填 选填 Team ID，与 --team-name 二选一
team-name - 选填 选填 Team 名称，--team-id 缺省时使用
volume-id - 选填 选填 Volume ID，与 --volume-name 二选一
volume-name - 选填 选填 Volume 名称，--volume-id 缺省时使用
assume-yes y 选填 选填 在交互时，默认选择y

当前命令还支持部分全局参数（例如-a/--access, --debug等），详情可参考 Serverless Devs 全局参数文档

操作案例

s cli fc-sandbox volume remove --team-name dev --volume-name data --region cn-hangzhou -a default -y

上述命令的执行结果示例：

? Are you sure you want to delete the volume v-9fquxxxxxxxx? yes
Volume v-9fquxxxxxxxx removed

⚠️ 注意：删除存储卷会丢失挂载关系，删除前请确认没有沙箱正在使用它。Volume 不支持改名，改名场景也只能删除重建。

权限与策略说明

  • create / update / remove：AliyunFCFullAccess
  • get / list：AliyunFCReadOnlyAccess