本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。 # AgentCore 浏览器的文件系统配置 AgentCore 浏览器支持通过`filesystemConfigurations`参数将您自己的文件系统挂载到浏览器会话中。每种配置都会在您指定的路径上挂载一个 Amazon S3 文件或 Amazon EFS 接入点。您不需要自定义挂载代码、特权容器或下载编排—— AgentCore 在会话沙箱内执行所有挂载操作。 Bring-your-own 文件系统是共享存储：多个会话、多个浏览器或外部应用程序可以同时访问同一个接入点。数据将在您自己的 Amazon 账户中保存和管理。您可以在创建浏览器`filesystemConfigurations`时提供 [ CreateBrowser](https://docs.amazonaws.cn/bedrock-agentcore-control/latest/APIReference/API_CreateBrowser.html)（从该浏览器启动的每个会话都继承挂载），或者在启动会话时使用 [ StartBrowserSession](https://docs.amazonaws.cn/bedrock-agentcore/latest/APIReference/API_StartBrowserSession.html)（挂载适用于该会话）。两个地方的参数和形状是相同的。 **注意** 与 AgentCore Runtime 不同， AgentCore 浏览器不提供托管会话存储选项。浏览器仅支持自带亚马逊 S3 文件和 Amazon EFS 接入点。 ## 存储选项一览下表比较了可用的文件系统类型。 | Type | 隔离 | Persistence | 需要 VPC | 适用于 | | --- | --- | --- | --- | --- | | Amazon S3 Files | 共享 — 多个会话和浏览器访问相同的数据 | Customer-managed （永久，同步到备份 S3 存储桶） | 是 | 可通过标准文件操作和 S3 API 访问数据集和对象 | | Amazon EFS | 共享 — 多个会话和浏览器访问相同的数据 | Customer-managed （永久有效，直到你将其删除） | 是 | 跨会话共享参考数据、下载、读写协作 | ## 快速入门以下清单提供了配置每种文件系统类型的简要步骤。 ### 亚马逊 S3 文件接入点 1. 将带`s3files:AccessPointArn`条件`s3files:GetAccessPoint`的浏览器执行角色添加`s3files:ClientMount``s3files:ClientWrite`、和。 1. 允许 TCP 端口 2049 从您的浏览器安全组出站到您的 S3 文件挂载目标安全组。 1. 确认 S3 文件挂载目标与您的浏览器子网位于同一 VPC 和可用区中。 1. 在您的`CreateBrowser`或`StartBrowserSession`电话中添加`filesystemConfigurations`一个`s3FilesConfiguration`条目。 1. 开始会话。您的挂载路径上的文件（例如，`/mnt/s3data`）与后备的 S3 存储桶双向同步。 ### 亚马逊 EFS 接入点 1. 将`elasticfilesystem:ClientMount`和`elasticfilesystem:ClientWrite`添加到您的浏览器执行角色中，并附带`elasticfilesystem:AccessPointArn`条件。 1. 允许 TCP 端口 2049 从浏览器安全组出站到 EFS 挂载目标安全组。 1. 确认 EFS 挂载目标与您的至少一个浏览器子网位于同一个可用区内。 1. 在您的`CreateBrowser`或`StartBrowserSession`电话中添加`filesystemConfigurations`一个`efsConfiguration`条目。 1. 开始会话。您的文件可在您的装载路径中找到（例如，`/mnt/efs`）。 S3 文件和 EFS 都需要浏览器上的 VPC 连接。 ## 工作原理当您配置自带文件系统时， AgentCore 浏览器会将指定的接入点安装到您配置的路径的会话沙箱中。数据是共享的 — 多个会话、多个浏览器或外部应用程序可以同时访问同一个文件系统。 AgentCore 自动处理所有装载操作。您无需安装挂载助手、管理 TLS 证书或编写挂载代码。 **注意** 创建接入点（S3 文件或 EFS）时，需要指定 POSIX 用户 ID (UID) 和群组 ID (GID)。通过接入点进行的所有文件操作都以此身份运行。 ### 亚马逊 S3 文件挂载流程 1. 您可以创建 S3 文件文件系统（由 S3 存储桶支持）并在 VPC 中挂载目标。 1. 您可以创建一个 S3 文件访问点，指定 POSIX UID/GID 和根目录。 1. 您可以使用接入点 ARN、文件系统 ARN 和装载路径配置浏览器（或会话）。 1. 会话启动时，预 AgentCore 置一个可以访问您的 VPC 的网络沙箱。 1. 沙箱通过您的 VPC NFSv4.2 通过 TLS 和 IAM 身份验证（端口 2049）通过 TLS 挂载文件系统。 1. 您的代理在装载路径上读取和写入文件。更改会自动同步到备份 S3 存储桶。 ### 亚马逊 EFS 挂载流程 1. 您可以创建 EFS 文件系统并在 VPC 中挂载目标（每个可用区一个）。 1. 您可以创建一个 EFS 接入点，指定 POSIX UID/GID 和根目录。 1. 您可以使用接入点 ARN、文件系统 ARN 和装载路径配置浏览器（或会话）。 1. 会话启动时，预 AgentCore 置一个可以访问您的 VPC 的网络沙箱。 1. 沙箱通过挂载目标 NFSv4.1 通过 TLS（端口 2049）在同一可用区中挂载文件系统。 1. 您的代理使用标准文件操作在装载路径上读取和写入文件。 ## 先决条件在配置自带文件系统之前，请完成以下先决条件。 ### VPC 配置您的浏览器必须使用`VPC`网络模式。您指定的子网必须与文件系统挂载目标可用区重叠。 ### IAM 权限您的浏览器执行角色必须包含挂载文件系统的权限。 **S3 文件的 IAM 权限 ** ``` { "Effect": "Allow", "Action": [ "s3files:ClientMount", "s3files:ClientWrite", "s3files:GetAccessPoint" ], "Resource": "arn:aws:s3files:::file-system/", "Condition": { "ArnEquals": { "s3files:AccessPointArn": "arn:aws:s3files:::file-system//access-point/" } } } ``` **EFS 的 IAM 权限 ** ``` { "Effect": "Allow", "Action": [ "elasticfilesystem:ClientMount", "elasticfilesystem:ClientWrite" ], "Resource": "arn:aws:elasticfilesystem:::file-system/", "Condition": { "ArnEquals": { "elasticfilesystem:AccessPointArn": "arn:aws:elasticfilesystem:::access-point/" } } } ``` `ClientWrite`如果您的代理只需要读取权限，则省略。 ### 安全组允许通过端口 2049 将出站 TCP 从浏览器安全组发送到挂载目标安全组。允许来自浏览器安全组的装载目标安全组上端口 2049 的入站 TCP。 ## 配置文件系统将中的每个文件系统指定`filesystemConfigurations`为`s3FilesConfiguration`或`efsConfiguration`。两者都需要三个字段： + `accessPointArn`— 要挂载的 S3 文件或 EFS 接入点的 ARN。 + `fileSystemArn`— 拥有接入点的文件系统的 ARN。此字段为**必填字段**。 + `mountPath`— 安装接入点的会话内的绝对路径（例如，`/mnt/s3data`）。你可以使用相同的形状`filesystemConfigurations`在两个地方供应： + **控制平面 `CreateBrowser` ** — — 挂载由浏览器启动的每个会话继承。浏览器必须使用 VPC 网络模式。 + **数据平面 `StartBrowserSession` ** — — 挂载适用于该特定会话。 **注意** 只要浏览器使用 VPC 网络模式并且 S3 文件或 EFS 接入点配置正确（挂载目标、IAM 权限和安全组`StartBrowserSession`），您就可以在控制平面 ()、数据平面 () 或两者上提供文件系统配置。`CreateBrowser`来自的`CreateBrowser`配置由每个会话继承；中的配置`StartBrowserSession`适用于该会话。当两者都提供时，它们将组合到会话中，并且每个装载路径在组合集合中必须是唯一的。以下部分显示了每种文件系统类型的两个 API 调用。 ### 配置 Amazon S3 文件接入点 **控制平面：`CreateBrowser`** **Example** 1. ``` aws bedrock-agentcore-control create-browser \ --name "data-browser" \ --execution-role-arn "arn:aws:iam:::role/BrowserExecutionRole" \ --network-configuration '{ "networkMode": "VPC", "vpcConfig": { "subnets": ["", ""], "securityGroups": [""] } }' \ --filesystem-configurations '[{ "s3FilesConfiguration": { "accessPointArn": "arn:aws:s3files:::file-system//access-point/", "fileSystemArn": "arn:aws:s3files:::file-system/", "mountPath": "/mnt/s3data" } }]' ``` 1. 使用 boto3 创建带有 S3 文件访问点的浏览器的 Python 示例。 ``` import boto3 cp = boto3.client("bedrock-agentcore-control", region_name="us-west-2") response = cp.create_browser( name="data-browser", executionRoleArn="arn:aws:iam:::role/BrowserExecutionRole", networkConfiguration={ "networkMode": "VPC", "vpcConfig": { "subnets": ["", ""], "securityGroups": [""] } }, filesystemConfigurations=[ { "s3FilesConfiguration": { "accessPointArn": "arn:aws:s3files:::file-system//access-point/", "fileSystemArn": "arn:aws:s3files:::file-system/", "mountPath": "/mnt/s3data" } } ] ) ``` **数据平面：`StartBrowserSession`** **Example** 1. ``` aws bedrock-agentcore start-browser-session \ --browser-identifier "" \ --name "byos-session" \ --session-timeout-seconds 3600 \ --filesystem-configurations '[{ "s3FilesConfiguration": { "accessPointArn": "arn:aws:s3files:::file-system//access-point/", "fileSystemArn": "arn:aws:s3files:::file-system/", "mountPath": "/mnt/s3data" } }]' ``` 1. 使用 boto3 启动与 S3 文件接入点的浏览器会话的 Python 示例。 ``` import boto3 dp = boto3.client("bedrock-agentcore", region_name="us-west-2") response = dp.start_browser_session( browserIdentifier="", name="byos-session", sessionTimeoutSeconds=3600, filesystemConfigurations=[ { "s3FilesConfiguration": { "accessPointArn": "arn:aws:s3files:::file-system//access-point/", "fileSystemArn": "arn:aws:s3files:::file-system/", "mountPath": "/mnt/s3data" } } ] ) session_id = response["sessionId"] ``` ### 配置 Amazon EFS 接入点 **控制平面：`CreateBrowser`** **Example** 1. ``` aws bedrock-agentcore-control create-browser \ --name "shared-tools-browser" \ --execution-role-arn "arn:aws:iam:::role/BrowserExecutionRole" \ --network-configuration '{ "networkMode": "VPC", "vpcConfig": { "subnets": ["", ""], "securityGroups": [""] } }' \ --filesystem-configurations '[{ "efsConfiguration": { "accessPointArn": "arn:aws:elasticfilesystem:::access-point/", "fileSystemArn": "arn:aws:elasticfilesystem:::file-system/", "mountPath": "/mnt/efs" } }]' ``` 1. 使用 boto3 创建带有 EFS 接入点的浏览器的 Python 示例。 ``` import boto3 cp = boto3.client("bedrock-agentcore-control", region_name="us-west-2") response = cp.create_browser( name="shared-tools-browser", executionRoleArn="arn:aws:iam:::role/BrowserExecutionRole", networkConfiguration={ "networkMode": "VPC", "vpcConfig": { "subnets": ["", ""], "securityGroups": [""] } }, filesystemConfigurations=[ { "efsConfiguration": { "accessPointArn": "arn:aws:elasticfilesystem:::access-point/", "fileSystemArn": "arn:aws:elasticfilesystem:::file-system/", "mountPath": "/mnt/efs" } } ] ) ``` **数据平面：`StartBrowserSession`** **Example** 1. ``` aws bedrock-agentcore start-browser-session \ --browser-identifier "" \ --name "byos-session" \ --session-timeout-seconds 3600 \ --filesystem-configurations '[{ "efsConfiguration": { "accessPointArn": "arn:aws:elasticfilesystem:::access-point/", "fileSystemArn": "arn:aws:elasticfilesystem:::file-system/", "mountPath": "/mnt/efs" } }]' ``` 1. 使用 boto3 启动与 EFS 接入点的浏览器会话的 Python 示例。 ``` import boto3 dp = boto3.client("bedrock-agentcore", region_name="us-west-2") response = dp.start_browser_session( browserIdentifier="", name="byos-session", sessionTimeoutSeconds=3600, filesystemConfigurations=[ { "efsConfiguration": { "accessPointArn": "arn:aws:elasticfilesystem:::access-point/", "fileSystemArn": "arn:aws:elasticfilesystem:::file-system/", "mountPath": "/mnt/efs" } } ] ) session_id = response["sessionId"] ``` ### 合并文件系统通过向添加更多条目，您可以在单个呼叫中连接多个接入点（不超过以下限制）`filesystemConfigurations`。每个条目都必须使用唯一的挂载路径。 ``` filesystemConfigurations=[ { "s3FilesConfiguration": { "accessPointArn": "arn:aws:s3files:::file-system//access-point/", "fileSystemArn": "arn:aws:s3files:::file-system/", "mountPath": "/mnt/s3data" } }, { "efsConfiguration": { "accessPointArn": "arn:aws:elasticfilesystem:::access-point/", "fileSystemArn": "arn:aws:elasticfilesystem:::file-system/", "mountPath": "/mnt/efs" } } ] ``` ### 确认已挂载的文件系统 [GetBrowser](https://docs.amazonaws.cn/bedrock-agentcore-control/latest/APIReference/API_GetBrowser.html)用于在浏览器`filesystemConfigurations`上确认，以及[GetBrowserSession](https://docs.amazonaws.cn/bedrock-agentcore/latest/APIReference/API_GetBrowserSession.html)确认正在运行的会话的有效配置。在浏览器创建和会话启动时设置的配置都出现在会话响应中。 ## 限制每个请求都强制执行文件系统配置限制。`CreateBrowser`配置由每个会话继承，`StartBrowserSession`配置适用于该会话。会话的有效坐骑是两者的组合。 | 配置类型 | 每 CreateBrowser | 每 StartBrowserSession | 每次会话合计 | | --- | --- | --- | --- | | 亚马逊 S3 文件访问点 | 2 | 2 | 4 | | 亚马逊 EFS 接入点 | 2 | 2 | 4 | | 文件系统配置总数 | 4 | 4 | 8 | 例如，您可以配置 1 个 S3 文件访问点和 1 个 EFS 接入点`CreateBrowser`，然后添加 1 个 S3 文件访问点和 1 个 EFS 接入点`StartBrowserSession`，这样会话中总共有 4 个挂载。每个装载路径在组合集合中都必须是唯一的。 ### 装载路径限制所有文件系统配置都必须遵循以下挂载路径规则： + 必须正好`/mnt/`位于一个子目录级别（例如，`/mnt/data`，`/mnt/s3data`）。 + 模式：`/mnt/[a-zA-Z0-9._-]+/?` + 在所有配置中，每个装载路径都必须是唯一的。 + 挂载路径不能是彼此的子目录。 ## 对文件系统装载进行故障排除当自带文件系统挂载失败时，会`StartBrowserSession`返回错误并且会话不会变成。`READY` | 症状 | 可能原因 | 快速修复 | | --- | --- | --- | | “访问被拒绝” | 执行角色缺失`ClientMount`或 `ClientWrite` | 使用`AccessPointArn`条件添加 IAM 权限 | | “ResourceNotFound” 或 “无法解决” | 接入点或挂载目标已删除或不可用 | 验证 ARN 存在且装载目标是否可用 | | 挂载挂起然后失败 | 安全组封锁端口 2049，或者会话的可用区域中没有挂载目标 | 允许 TCP 2049；验证可用区重叠 | | 写入时出现 “权限被拒绝” | 缺失`ClientWrite`或 POSIX UID/GID 不匹配 | 添加写入权限或调整接入点 POSIX 用户 | 所有配置的文件系统在会话启动时并行装载，单次装载失败会导致会话启动失败。