文档首页/ AgentSphere/ 最佳实践/ 按用户隔离挂载SFS Turbo文件系统

更新时间：2026-10-29 GMT+08:00

按用户隔离挂载SFS Turbo文件系统

操作场景

在多租户的Agent应用场景下，您的业务系统（如企业服务端）会为每一个终端用户分配一个用户标识（userid），并为每个用户创建独立的运行环境（沙箱）。不同用户之间需要共享同一份SFS Turbo文件存储资源，但每个用户只能访问自己专属的存储目录，以避免用户间数据越权访问。

本文介绍如何通过Agent Identity与SFS Turbo的集成，实现SFS Turbo目录按用户隔离挂载：

根据指定的userid挂载对应的SFS Turbo隔离目录，若该目录不存在则自动创建。
限制该userid只能挂载其专属目录，无权限挂载其他用户的目录。

约束与限制

购买SFS Turbo实例后，需要提交工单开启该SFS Turbo实例的隔离挂载能力。
SFS Turbo隔离挂载只支持Sandbox级别，不支持Template级别挂载。
SFS Turbo隔离挂载场景下，Sandbox只能挂载1个目录。
SFS Turbo实例开启隔离挂载后则不支持共享挂载，在使用Sandbox隔离挂载目录的同时，可以通过Template配置共享挂载目录。

步骤一：为IAM子用户配置临时凭证权限

授予IAM子用户访问Agent Identity服务，换取代表隔离用户的临时凭证（Workload Access Token, WAT）的权限。

仅IAM子用户需要执行本步骤；主账号无需配置，默认拥有权限。

创建身份策略

使用管理员账号登录统一身份认证服务新版控制台。
在左侧导航栏中选择“身份策略”，单击“创建自定义身份策略”。

配置策略信息：

参数	说明
策略名称	本示例填写test-WAT-full。
策略配置方式	选择“JSON视图”。
策略内容	参考下方示例，允许IAM子用户换取隔离用户临时凭证。 { "Version": "5.0", "Statement": [ { "Effect": "Allow", "Action": [ "agentIdentity::createWorkloadAccessTokenForUserId" ] } ] }

参数

说明

策略名称

本示例填写test-WAT-full。

策略配置方式

选择“JSON视图”。

策略内容

参考下方示例，允许IAM子用户换取隔离用户临时凭证。

{
  "Version": "5.0",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "agentIdentity::createWorkloadAccessTokenForUserId"
      ]
    }
  ]
}

授权策略给IAM子用户
1. 单击上一步创建的test-WAT-full策略名称，切换至“授权记录”页签。
2. 单击“附加”，然后选择对应的IAM子用户，单击“确定”。

步骤二：授权AgentSphere获取STS Token

创建运行时委托（Runtime agency），允许AgentSphere代表用户获取运行环境访问Agent Identity服务的临时凭证。

创建身份策略

使用用户A的账号登录统一身份认证服务新版控制台。
在左侧导航栏中选择“身份策略”，单击“创建自定义身份策略”。

配置策略信息：

参数	说明
策略名称	本示例填写policy-WAT。
策略配置方式	选择“JSON视图”。
策略内容	参考下方示例，允许沙箱获取访问Agent Identity服务的STS Token。 { "Version": "5.0", "Statement": [ { "Effect": "Allow", "Action": [ "agentIdentity::getResourceStsToken" ] } ] }

参数

说明

策略名称

本示例填写policy-WAT。

策略配置方式

选择“JSON视图”。

策略内容

参考下方示例，允许沙箱获取访问Agent Identity服务的STS Token。

{
  "Version": "5.0",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "agentIdentity::getResourceStsToken"
      ]
    }
  ]
}

创建委托

在左侧导航栏中选择“委托”，单击“创建信任委托”。

配置委托信息：

参数	说明
委托名称	本示例填写test_metadata_trust_agency。
信任主体类型	选择“自定义信任策略”。
信任策略	参考下方示例，允许沙箱元数据服务使用该委托。 { "Version": "5.0", "Statement": [ { "Action": [ "sts:agencies:assume", "sts::tagSession" ], "Effect": "Allow", "Principal": { "Service": [ "service.WorkloadSandboxMetadata" ] } } ] }

参数

说明

委托名称

本示例填写test_metadata_trust_agency。

信任主体类型

选择“自定义信任策略”。

信任策略

参考下方示例，允许沙箱元数据服务使用该委托。

{
  "Version": "5.0",
  "Statement": [
    {
      "Action": [
        "sts:agencies:assume",
        "sts::tagSession"
      ],
      "Effect": "Allow",
      "Principal": {
        "Service": [
          "service.WorkloadSandboxMetadata"
        ]
      }
    }
  ]
}

为委托授权身份策略
1. 找到上一步创建的委托，单击“授权”。
2. 选择步骤1中创建的策略policy-WAT，单击“确定”。

步骤三：授权Agent Identity获取挂载SFS Turbo目录权限

允许Agent Identity获取SFS Turbo目录挂载权限，并限制只能挂载用户专属目录（通过${g:AgentIdentity/InboundUserId}动态解析，实现每个用户只能挂载以自身userid命名的目录）。

创建身份策略

使用用户A的账号登录统一身份认证服务新版控制台。
在左侧导航栏中选择“身份策略”，单击“创建自定义身份策略”。

配置策略信息：

参数	说明
策略名称	本示例填写policy-sfs1。
策略配置方式	选择“JSON视图”。
策略内容	参考下方示例，允许挂载SFS Turbo访问点下以userid命名的目录。 { "Version": "5.0", "Statement": [ { "Effect": "Allow", "Action": [ "sfsturbo:accesspoint:mount" ], "Resource": [ "sfsturbo:::accesspoint:eb2dba3c-bbd4-11f1-bb9d-fa163e188044/test/${g:AgentIdentity/InboundUserId}" ] } ] } Resource字段格式为sfsturbo:<region>:<account-id>:accesspoint:<share-id>/<dir-path>，其中<share-id>为SFS Turbo实例ID，<dir-path>末段固定以${g:AgentIdentity/InboundUserId}标识用户专属目录。

参数

说明

策略名称

本示例填写policy-sfs1。

策略配置方式

选择“JSON视图”。

策略内容

参考下方示例，允许挂载SFS Turbo访问点下以userid命名的目录。

{
  "Version": "5.0",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "sfsturbo:accesspoint:mount"
      ],
      "Resource": [
        "sfsturbo:*:*:accesspoint:eb2dba3c-bbd4-11f1-bb9d-fa163e188044/test/${g:AgentIdentity/InboundUserId}"
      ]
    }
  ]
}

Resource字段格式为sfsturbo:<region>:<account-id>:accesspoint:<share-id>/<dir-path>，其中<share-id>为SFS Turbo实例ID，<dir-path>末段固定以${g:AgentIdentity/InboundUserId}标识用户专属目录。

创建委托

在左侧导航栏中选择“委托”，单击“创建信任委托”。

配置委托信息：

参数	说明
委托名称	本示例填写agency-identity。
信任主体类型	选择“自定义信任策略”。
信任策略	参考下方示例，允许Agent Identity服务使用该委托。 { "Version": "5.0", "Statement": [ { "Action": [ "sts:agencies:assume", "sts::SetContext", "sts::setSourceIdentity", "sts::tagSession" ], "Effect": "Allow", "Principal": { "Service": [ "service.AgentIdentity" ] } } ] }

参数

说明

委托名称

本示例填写agency-identity。

信任主体类型

选择“自定义信任策略”。

信任策略

参考下方示例，允许Agent Identity服务使用该委托。

{
  "Version": "5.0",
  "Statement": [
    {
      "Action": [
        "sts:agencies:assume",
        "sts::SetContext",
        "sts::setSourceIdentity",
        "sts::tagSession"
      ],
      "Effect": "Allow",
      "Principal": {
        "Service": [
          "service.AgentIdentity"
        ]
      }
    }
  ]
}

为委托授权身份策略
1. 找到上一步创建的委托，单击“授权”。
2. 选择步骤1中创建的策略policy-sfs1，单击“确定”。

步骤四：创建Workload Identity

在Agent Identity服务中创建工作负载身份。工作负载身份是分配给沙箱模板、网关和Agent等工作负载的身份，用于沙箱访问Agent Identity服务时的身份验证。

登录Agent Identity控制台。
“工作负载身份”，单击“创建工作负载身份”。
填写必要的工作负载身份信息：

参数

说明

身份名称

本示例填写workload-test。

入站身份认证

选择“API Key认证”，沙箱通过API Key完成身份认证。
单击“立即创建”。

参数	说明
身份名称	本示例填写workload-test。
入站身份认证	选择“API Key认证”，沙箱通过API Key完成身份认证。

步骤五：创建出站身份并关联出站身份委托

在Agent Identity服务中创建出站身份（Credential Provider），将步骤2中创建的委托（agency-identity）关联到出站身份，使沙箱能够通过Agent Identity认证身份后，使用该委托获取SFS Turbo目录挂载临时凭证。

登录Agent Identity控制台。
“出站身份”，单击“创建出站身份”。
填写必要的出站身份信息：

参数

说明

身份名称

本示例填写sfs-turbo。

认证类型

选择“IAM委托”。

IAM 信任委托

选择步骤三中创建的委托：agency-identity。
单击“立即创建”。

参数	说明
身份名称	本示例填写sfs-turbo。
认证类型	选择“IAM委托”。
IAM 信任委托	选择步骤三中创建的委托：agency-identity。

步骤六：检查Agent Identity策略集配置

检查Agent Identity策略集配置，防止STS Token换取失败。

登录Agent Identity控制台。
在左侧导航栏中选择“策略集”，检查策略集配置情况：
- 如果无策略集，或策略集中无绑定实例，可忽略本步骤，无需额外配置。
- 如果已创建策略集且绑定了实例，且执行模式为拦截模式：
  
  则需要添加策略放通STS获取权限，策略语句可配置为更细粒度的权限。

步骤七：购买VPCEP打通Sandbox与Agent Identity的网络

当Sandbox出站网络为私有网络模式时，您需要通过VPCEP打通Sandbox与Agent Identity服务的网络。

登录VPC终端节点控制台。
在“终端节点”页面，单击“购买终端节点”。

根据界面提示配置必选参数。更多参数说明，请参见购买终端节点。

表1 终端节点配置参数
参数	说明
区域	终端节点所在区域，需要与AgentSphere沙箱所在区域保持一致。
计费模式	仅支持按需计费。按需计费是后付费模式，按终端节点的实际使用时长计费，可以随时开通/删除终端节点。
服务类别	选择“云服务”。
服务名称	搜索“agent-identity”，勾选对应的服务名称。
创建内网域名	如果您需要以域名的方式访问终端节点，则选择“创建内网域名”，终端节点创建完成后，即可通过内网域名直接访问终端节点。
虚拟私有云	需要选择AgentSphere沙箱所在的虚拟私有云。注意：选择的VPC和子网需要与SFS Turbo实例和Sandbox保持一致。
路由表	选择一个已有的路由表。

参数配置完成，单击“立即购买”，进行规格确认。

隔离挂载验证

前置配置完成后，您可以通过以下步骤验证按用户隔离挂载功能是否生效。

创建沙箱模板（template）并完成模板快照构建，为创建沙箱实例准备模板配置，详情请参见创建沙箱模板。

其中VPC和子网需要与后续SFS Turbo实例的VPC相同，“运行时信任委托”配置为步骤二中创建的委托test_metadata_trust_agency。

若要使用Sandbox隔离挂载目录的同时使用共享挂载目录，可以在模板中配置template级别的SFS Turbo共享目录挂载。

通过API创建Sandbox，并携带以下3个隔离挂载Header头，实现按userid隔离挂载SFS Turbo目录。

表2 隔离挂载header头说明
Header头	说明
X-HW-AgentSandbox-UserId	SFS Turbo隔离挂载的用户ID，用于标识SFS Turbo隔离目录。挂载目录时sharePath的末段须与该值一致，系统将基于该值获取此隔离目录的临时挂载凭证。
X-HW-AgentSandbox-Credential-Provider-Name	步骤五中创建的出站身份名称，本示例为sfs-turbo。
X-HW-AgentSandbox-Workload-Identity-Name	步骤四中创建的工作负载身份名称，本示例为workload-test。

上述3个隔离挂载Header头必须齐全；若Header头不齐全，将按普通挂载方式创建沙箱，不会启用隔离挂载。

表3 请求参数说明
参数	说明
templateID	验证1中创建的模板ID（templateID）和快照ID（buildID），格式为templateID:buildID。
sfsTurboId	SFS Turbo实例ID，该实例VPC需要与沙箱模板中配置的VPC一致。
sharePath	挂载目录路径，子目录需与userid一致（本示例为sandbox-002），否则会校验报错。

请求Header示例：

-H "X-HW-AgentSandbox-UserId: sandbox-002"
-H "X-HW-AgentSandbox-Credential-Provider-Name: sfs-turbo"
-H "X-HW-AgentSandbox-Workload-Identity-Name: workload-test"

body示例：

{
  "templateID": "00c73584-cb75-450e-a604-c692c5693473:c64f42d2-145e-4726-ab23-477c95c844de",
  "sfsTurboId": "eb2dba3c-bbd4-11f1-bb9d-fa163e188044",
  "sharePath": "/test/sandbox-002"
}

创建成功后，沙箱激活，并挂载目录/test/sandbox-002，说明隔离挂载成功。

SFS Turbo隔离挂载若传入的sharePath不存在，会自动创建该sharePath。

挂载无访问权限目录拦截验证

验证隔离挂载的权限校验能力，确认Sandbox无法挂载无访问权限的目录。

场景1：sharePath根目录与出站身份关联的访问权限目录不一致

请求示例：

-H "X-HW-AgentSandbox-UserId: sandbox-002"
-H "X-HW-AgentSandbox-Credential-Provider-Name: sfs-turbo"
-H "X-HW-AgentSandbox-Workload-Identity-Name: workload-test"
-H "X-API-KEY: e2b_xxx"

body示例：

{
  "templateID": "00c73584-cb75-450e-a604-c692c5693473:c64f42d2-145e-4726-ab23-477c95c844de",
  "name": "sandbox-test2",
  "secure": true,
  "autoPause": false,
  "autoResume": {
    "enable": false
  },
  "storageConfig": {
    "sfsTurboMounts": [
      {
        "sfsTurboId": "eb2dba3c-bbd4-11f1-bb9d-fa163e188044",
        "sharePath": "/test-another/sandbox-002"
      }
    ]
  }
}

预期返回结果：挂载被拦截，提示无挂载权限。

{
  "code": 403,
  "message": "no permission to mount SFS Turbo share path",
  "error_code": "AgentSphere.0108"
}

场景2：sharePath子目录与userid不一致

body示例（sharePath子目录为sandbox-011，与userid sandbox-002不一致）：

{
  "templateID": "00c73584-cb75-450e-a604-c692c5693473:c64f42d2-145e-4726-ab23-477c95c844de",
  "name": "sandbox-test2",
  "secure": true,
  "autoPause": false,
  "autoResume": {
    "enable": false
  },
  "storageConfig": {
    "sfsTurboMounts": [
      {
        "sfsTurboId": "eb2dba3c-bbd4-11f1-bb9d-fa163e188044",
        "sharePath": "/test/sandbox-011"
      }
    ]
  }
}

预期返回结果：校验失败，sharePath与userId不匹配。

{
  "code": 400,
  "message": "sharePath does not match userId",
  "error_code": "AgentSphere.0505"
}

进阶配置：限制IAM子用户隔离挂载权限

上文中已授权IAM子用户换取WAT的权限。如果需要进一步限制IAM子用户只能使用指定的Workload Identity和userid，可以参考本节配置，实现IAM子用户级别的隔离挂载权限管控。

限制IAM子用户WAT换取权限

创建身份策略，限制IAM子用户换取WAT的权限范围，可以从resource（workload identity）和condition（userid）两个维度进行配置。

使用管理员账号登录统一身份认证服务新版控制台。
在左侧导航栏中选择“身份策略”，单击“创建自定义身份策略”。

配置策略信息：

参数	说明
策略名称	本示例填写test-WAT。
策略配置方式	选择“JSON视图”。
策略内容	参考下方示例，仅允许使用sandbox-test1这个工作负载身份为sandbox-123这个userid换取Workload Access Token。 { "Version": "5.0", "Statement": [ { "Effect": "Allow", "Action": [ "agentIdentity::createWorkloadAccessTokenForUserId" ], "Resource": [ "agentidentity:::workloadIdentity:workloadIdentityDirectory/default/sandbox-test1", "agentidentity:::workloadIdentityDirectory:default" ], "Condition": { "StringEquals": { "agentIdentity:userId": [ "sandbox-123" ] } } } ] }

参数

说明

策略名称

本示例填写test-WAT。

策略配置方式

选择“JSON视图”。

策略内容

参考下方示例，仅允许使用sandbox-test1这个工作负载身份为sandbox-123这个userid换取Workload Access Token。

{
  "Version": "5.0",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "agentIdentity::createWorkloadAccessTokenForUserId"
      ],
      "Resource": [
        "agentidentity:*:*:workloadIdentity:workloadIdentityDirectory/default/sandbox-test1",
        "agentidentity:*:*:workloadIdentityDirectory:default"
      ],
      "Condition": {
        "StringEquals": {
          "agentIdentity:userId": [
            "sandbox-123"
          ]
        }
      }
    }
  ]
}

授权策略给IAM子用户
1. 单击上一步创建的test-WAT策略名称，切换至“授权记录”页签。
2. 单击“附加”，然后选择对应的IAM子用户，单击“确定”。
  
  授权子用户test-WAT时，需要确保前文中设置的test-WAT-full权限已移除，否则限制不生效。

验证策略是否生效

验证场景1：userid与策略中的不一致

请求中携带的userid为sandbox-001，与策略中授权的sandbox-123不一致，预期返回无权限。

-H "X-HW-AgentSandbox-UserId: sandbox-001"
-H "X-API-KEY: {授权子用户的API-KEY}"

预期返回结果：

{
  "code": 403,
  "message": "AgentIdentity denied WAT access, please check identity policy permissions"
}

验证场景2：workload identity与策略中授权的不一致

请求中携带的workload identity为sandbox-test2，与策略中授权的sandbox-test1不一致，预期返回无权限。

-H "X-HW-AgentSandbox-UserId: sandbox-123"
-H "X-HW-AgentSandbox-Workload-Identity-Name: sandbox-test2"
-H "X-API-KEY: {授权子用户的API-KEY}"

预期返回结果：

{
  "code": 403,
  "message": "AgentIdentity denied WAT access, please check identity policy permissions"
}

上一篇：沙箱指定路径日志采集最佳实践（Python）

下一篇：AgentSphere细粒度权限管理最佳实践

按用户隔离挂载SFS Turbo文件系统

操作场景

约束与限制

步骤一：为IAM子用户配置临时凭证权限

步骤二：授权AgentSphere获取STS Token

步骤三：授权Agent Identity获取挂载SFS Turbo目录权限

步骤四：创建Workload Identity

步骤五：创建出站身份并关联出站身份委托

步骤六：检查Agent Identity策略集配置

步骤七：购买VPCEP打通Sandbox与Agent Identity的网络

隔离挂载验证

挂载无访问权限目录拦截验证

进阶配置：限制IAM子用户隔离挂载权限

相关文档

您对此文档页面的整体评价？