文档反馈官招募中，报名立赚积分兑换代金券！> HOT
文档中心>Agent Runtime>操作指南>沙箱管理>存储挂载

存储挂载

最近更新时间：2026-05-27 20:38:30

我的收藏

本页目录：

目标

为 Sandbox Tool 的实例挂载外部存储，实现数据持久化、跨实例共享和目录隔离。
配置分为两层：
创建 Tool 时，通过 StorageMounts 定义默认存储来源、挂载路径和读写权限。
启动 Instance 时，通过 MountOptions 按需覆盖路径、收紧只读权限，或追加 SubPath 做子目录隔离。
当前支持的存储来源：COS 对象存储、CFS 文件存储和镜像内置存储。

开始前准备

已有创建或更新 Sandbox Tool 的权限。
使用 COS 挂载时，准备好可访问目标存储桶的 RoleArn。
使用 CFS 挂载时，确认 FileSystemId 有效，且目标地域存在可用挂载点。
使用镜像挂载时，准备带 tag 的镜像引用；非 system 镜像需要可访问镜像仓库的 RoleArn。
如果使用 CLI，请先安装 agr 并配置云 API 凭证。

配置模型

配置层级
字段
作用
Tool 级
StorageMounts
定义默认存储来源、默认 MountPath 和默认 ReadOnly。
Instance 级
MountOptions
引用已定义的 StorageMount.Name，覆盖 MountPath、收紧只读权限，或为本次实例追加 SubPath。
约束：
MountOptions 只能引用 Tool 中已存在的 StorageMount.Name，不能在启动实例时新增存储来源。
同一个 Tool 最多定义 10 条 StorageMounts；实例级展开后的最终挂载数量也不能超过 10。
同一个 StorageMount.Name 可被多个 MountOptions 复用；当同名挂载被多次引用时，每条 MountOption 必须显式设置 MountPath，且 SubPath 不能重复。
ReadOnly 只能在实例级收紧，不能把 Tool 级只读挂载放宽为可写。
请注意：当前 agr tool update 的公开字段不包含 StorageMounts。需要调整默认配置时，建议创建新 Tool 并让后续实例切换到新 Tool。

存储选项

存储来源
必填字段
角色要求
典型用途
持久化行为
COS
BucketName、BucketPath、MountPath
需要 RoleArn
数据集、素材、模型、任务输出
数据保存在 COS 中。实例销毁后，重新挂载同一对象路径即可继续访问。
CFS
FileSystemId、MountPath
仅配置 CFS 且沙箱类型不是 Custom 时可不传 RoleArn；Custom 类型仍需 RoleArn
共享工作目录、缓存目录、需要 POSIX 访问的文件集
数据保存在 CFS 文件系统中。实例销毁后，重新挂载同一路径即可继续访问。
Image
Reference、MountPath
非 system 镜像需要 RoleArn
预置脚本、依赖、只读基线内容
镜像内容不会因实例内写入而更新。需要保留结果时，应写入 COS 或 CFS。
各来源的补充行为：
COS： BucketPath 会被归一化为以 / 开头的目录路径；未传入 Endpoint 时，系统按当前地域补全默认值。
CFS： Path 建议显式填写。未填写时按根目录 / 处理。
Image： 挂载要求 Reference 带 tag；提交后系统会解析并回填镜像 digest。

使用 CLI 配置存储挂载

创建带 COS 挂载的 Tool

当前 agr tool create 使用 --storage-mounts 传入 JSON 数组；以下示例创建一个默认挂载到 /mnt/assets 的 COS 存储：
cat <<'JSON' | agr tool create \\
  --tool-name analysis-runtime \\
  --tool-type code-interpreter \\
  --network-configuration '{"NetworkMode":"PUBLIC"}' \\
  --role-arn <role-arn> \\
  --storage-mounts - \\
  --non-interactive \\
  -o json
[
  {
    "Name": "cos-assets",
    "StorageSource": {
      "Cos": {
        "BucketName": "team-shared-1250000000",
        "BucketPath": "/datasets"
      }
    },
    "MountPath": "/mnt/assets",
    "ReadOnly": false
  }
]
JSON

创建带 CFS 和镜像挂载的 Tool

CFS 和镜像挂载通过 --request 传入完整 JSON 请求体；示例中显式声明 NetworkConfiguration：
cat <<'JSON' | agr tool create --request - --non-interactive -o json
{
  "ToolName": "analysis-runtime",
  "ToolType": "custom",
  "NetworkConfiguration": {
    "NetworkMode": "PUBLIC"
  },
  "RoleArn": "<role-arn>",
  "StorageMounts": [
    {
      "Name": "cfs-workspace",
      "StorageSource": {
        "Cfs": {
          "FileSystemId": "cfs-12345678",
          "Path": "/team/project-a"
        }
      },
      "MountPath": "/workspace/project-a",
      "ReadOnly": false
    },
    {
      "Name": "image-seed",
      "StorageSource": {
        "Image": {
          "Reference": "ccr.ccs.tencentyun.com/team/bootstrap:v1",
          "ImageRegistryType": "CCR",
          "SubPath": "/seed"
        }
      },
      "MountPath": "/opt/seed",
      "ReadOnly": true
    }
  ]
}
JSON

保存创建结果

agr tool create 命令成功后，请记录返回中的 ToolId，供后续查询 Tool 详情或启动实例时使用。
如需确认默认挂载是否已写入，请继续执行：
agr tool get <tool-id> -o json
不要仅凭创建命令的返回内容判断挂载明细。

启动实例时覆盖挂载路径和子目录

agr instance create 当前使用 --mount-options 传入 JSON 数组。以下示例把同一个 COS 挂载拆成两个实例内路径，分别指向不同的远端子目录；--timeout 也按公开 CLI 要求使用字符串时长格式：
cat <<'JSON' | agr instance create \\
  --tool-name analysis-runtime \\
  --mount-options - \\
  --timeout 30m \\
  --non-interactive \\
  -o json
[
  {
    "Name": "cos-assets",
    "MountPath": "/workspace/input",
    "SubPath": "run-001",
    "ReadOnly": true
  },
  {
    "Name": "cos-assets",
    "MountPath": "/workspace/output",
    "SubPath": "run-002",
    "ReadOnly": false
  }
]
JSON
使用 MountOptions 时注意：
Name 必须对应 Tool 中已存在的 StorageMount.Name。
同一个 Name 被多次引用时，每条都必须显式设置 MountPath，且 SubPath 不能重复。
ReadOnly 只能收紧为只读，不能把 Tool 级只读挂载改回可写。

验证

创建或启动后，按以下顺序验证：
1. 查看 Tool 详情，确认默认挂载已写入：
agr tool get <tool-id> -o json
2. 查看 Instance 详情，确认实例已从目标 Tool 启动：
agr instance get <instance-id> -o json
3. 在实例内检查挂载路径是否存在，并确认读写权限符合预期：
agr instance exec <instance-id> -- ls -ld /workspace/input /workspace/output
如需验证实际读写行为，可在目标目录内执行文件创建或写入测试，根据返回结果判断权限。

路径映射

存储来源
远端路径字段
实例内路径字段
映射结果
COS
BucketName + BucketPath [+ SubPath]
MountPath
将 COS 存储桶中的目录映射到实例内路径。
CFS
FileSystemId + Path [+ SubPath]
MountPath
将 CFS 文件系统中的目录映射到实例内路径。
Image
Reference + SubPath
MountPath
将镜像根目录或镜像内子目录映射到实例内路径。
SubPath 不改写 Tool 上保存的默认远端路径，仅在本次实例启动时追加隔离层级。适合把同一份共享存储按任务、用户或批次拆分成独立子目录。
例如，Tool 级配置把 COS 存储桶 team-shared-1250000000 的 BucketPath 设为 /datasets，并把默认挂载点设为 /mnt/assets。如果实例启动时传入上面的 MountOptions：
/workspace/input 会映射到存储桶中的 /datasets/run-001 目录，适合读取输入数据。
/workspace/output 会映射到同一存储桶中的 /datasets/run-002 目录，适合写回运行结果。
在实例内读取 /workspace/input 时，看到的是 run-001 目录中的对象；写入 /workspace/output 的文件会保存到 run-002 目录。

挂载路径和权限规则

MountPath 规则

所有 StorageMounts[].MountPath 和 MountOptions[].MountPath 必须满足：
以 / 开头的绝对路径。
不能是根路径 /。
不能包含连续 //。
不能包含 . 或 .. 相对路径片段。
同一个 Tool 或同一次实例启动中，最终解析出的 MountPath 不能重复。
不同沙箱类型的额外限制：
mobile 和 android-world：只允许 /data/local/tmp/mnt 或其子目录。
osworld：只允许 /tmp/mnt 或其子目录。
其他类型采用黑名单校验：/bin、/etc、/tmp、/usr、/var 等系统目录及其子路径不可用；/home、/data、/workspace、/mnt 本身不可直接作为挂载点，但它们的子目录可用。
/nix 是单独放开的固定路径，仅允许 /nix 本身，不可使用其子目录。

SubPath 规则

SubPath 只能是相对路径：
不能以 / 开头。
不能包含 .、.. 相对路径片段。
不能包含连续 //。

读写权限和持久化行为

场景
读写权限
持久化说明
Tool 级 ReadOnly: false，实例未覆盖
读写
写入落到对应的 COS 或 CFS 存储上；镜像挂载不建议写入。
Tool 级 ReadOnly: false，实例使用 readonly
只读
本次实例只读访问，其他实例仍按各自配置决定权限。
Tool 级 ReadOnly: true，实例未覆盖或显式传 readonly
只读
Tool 级只读约束始终生效，实例不能放宽。
Image 挂载
建议只读
镜像内容不会被实例内写入回写；需要保留结果时，应写入 COS 或 CFS。
选择存储来源的参考：
需要跨实例复用、实例销毁后保留数据：优先 COS 或 CFS。
需要 POSIX 目录访问、共享缓存或共享工作目录：优先 CFS。
需要把固定版本的脚本、依赖或种子数据随镜像分发：使用 Image，结果输出到 COS 或 CFS。

更新挂载配置与清理

修改默认挂载配置的建议操作：
1. 复制现有 Tool 配置，创建新 Tool 并写入更新后的 StorageMounts。
2. 使用新 Tool 启动实例并完成验证。
3. 将流量或自动化流程切换到新 Tool。
4. 确认旧实例可下线后，删除旧实例和旧 Tool。
清理命令：
agr instance delete <instance-id>
agr tool delete <tool-id>
删除实例或 Tool 不会删除 COS 存储桶对象、CFS 文件系统内容或镜像仓库中的镜像。需要回收远端数据时，请在对应存储服务中单独处理。

相关文档

创建沙箱工具
中国站