openai-agents-python 沙箱 R2 远程存储挂载实战:R2Mount 配置、rclone 策略与凭据安全

原创2026-10-10 12:55:581,865 阅读
文章标签:人工智能AI AgentAgent 框架多智能体Agent 编排Agent 工作流Agent 沙箱Agent 记忆大模型工具调用语音

openai-agents-python 沙箱 R2 远程存储挂载实战:R2Mount 配置、rclone 策略与凭据安全

导读

R2Mount 是 openai-agents-python 沙箱(sandbox)体系中用于把 Cloudflare R2 对象存储桶挂载进 Agent 工作区的官方挂载条目。它面向"Agent 需要直接读写云端数据"的场景,例如让沙箱内的代码助手读取 R2 上的数据目录、把输出回写到 R2 桶。读完本文,你将掌握 R2Mount 的字段含义、两种挂载策略(容器内 rclone 与 Docker volume driver)的底层工作原理、rclone 配置的自动生成细节,以及凭据校验与安全边界的使用前提。

本文对应的官方参考文档为 docs/ref/sandbox/entries/mounts/providers/r2.md,其内容由 mkdocstrings 从 r2.py 自动提取,因此本文将以源码实现为主线展开。

R2Mount:一个面向 Cloudflare R2 的配置化挂载条目

R2Mount 定义在 src/agents/sandbox/entries/mounts/providers/r2.py,类型标识为 "r2_mount"。它继承自 providers/base.py 中的 _ConfiguredMount——这是一个"用同一模型同时驱动两种挂载策略形状"的抽象基类:既能生成容器内(in-container)rclone 运行时配置,也能生成 Docker volume driver 的驱动参数。

字段一览

字段 类型 默认值 说明
type Literal["r2_mount"] "r2_mount" 挂载条目标识,由 Pydantic 判别字段使用
bucket str 必填 要挂载的 R2 桶名称,同时充当 rclone 的 remote path
account_id str 必填 Cloudflare 账号 ID,用于拼接默认 endpoint
access_key_id str | None None R2 S3 API 访问密钥 ID
secret_access_key str | None None R2 S3 API 密钥
custom_domain str | None None 自定义 endpoint 域名,覆盖默认的 https://{account_id}.r2.cloudflarestorage.com

此外,Mount 基类(src/agents/sandbox/entries/mounts/base.py)还为所有挂载条目提供了公共字段:

  • mount_path: Path | None:显式指定挂载到工作区的路径;不指定时由会话按条目 key 解析;
  • read_only: bool:默认 True,只读挂载;
  • is_dir: bool:默认 True;
  • ephemeral: bool:默认 True,挂载被视为运行时附加的外部文件系统,不进入工作区快照的持久化范围;
  • mount_strategy:必须显式指定挂载策略(见下一节)。

需要特别注意的是,Mount.model_post_init 会校验 permissions 并发出告警:挂载级别的权限设置不会被强制生效,源码明确提示"请在云厂商侧配置访问权限,mount 级权限不可靠"(base.py),因此 R2 桶的读写权限应通过 Cloudflare R2 的桶策略与 Token 权限来控制。

凭据成对校验

_validate_credential_pair()(r2.py)强制 access_key_id 与 secret_access_key 要么同时提供、要么同时省略,否则抛出 MountConfigError:

r2 credentials must include both access_key_id and secret_access_key

该校验在容器内挂载配置构建与 Docker volume driver 配置构建两条路径上都会被调用,因此无论采用哪种策略都会生效。

挂载策略:容器内 rclone 与 Docker rclone volume

R2Mount 声明了自己支持的策略能力(r2.py):

def supported_in_container_patterns(self) -> tuple[builtins.type[MountPattern], ...]:
    return (RcloneMountPattern,)

def supported_docker_volume_drivers(self) -> frozenset[str]:
    return frozenset({"rclone"})

这决定了 R2 只有两种可行策略,且都以 rclone 为执行引擎:

  1. 容器内挂载(InContainerMountStrategy(pattern=RcloneMountPattern(...))):在沙箱镜像里运行 rclone 命令完成挂载,这也是最通用的方式。按官方文档 docs/sandbox/clients.md 的说明,RcloneMountPattern 同时支持 S3、GCS、R2、Azure Blob 与 Box,并可在 fuse 或 nfs 两种模式下运行。
  2. Docker volume 挂载(DockerVolumeMountStrategy(driver="rclone")):容器启动前由 Docker 的 rclone volume driver 挂载,仅适用于 Docker 后端。

若策略与挂载类型不匹配(例如给 R2Mount 配了 MountpointMountPattern),适配器会在校验阶段抛出 MountConfigError: invalid mount_pattern type——这一点有测试用例直接验证(tests/sandbox/test_mounts.py)。

容器内策略:rclone 配置如何生成

在容器内策略下,R2Mount.build_in_container_mount_config() 调用基类的 _build_rclone_config()(base.py),产出 RcloneMountConfig(定义于 patterns.py),其中包含 remote_name、remote_path、remote_kind(固定为 "r2")、config_text 与 read_only。

_rclone_required_lines()(r2.py)负责生成 R2 专属的 rclone 配置片段:

[<remote_name>]
type = s3
provider = Cloudflare
endpoint = https://<account_id>.r2.cloudflarestorage.com   # 或 custom_domain
acl = private
env_auth = false
access_key_id = <access_key_id>        # 仅当提供成对凭据时出现
secret_access_key = <secret_access_key>

关键点:

  • R2 走的是 S3 兼容协议,因此 rclone 侧 type = s3 + provider = Cloudflare;
  • endpoint 默认由 account_id 推导为 https://{account_id}.r2.cloudflarestorage.com,提供 custom_domain 时则完全替换(测试用例见 test_mounts.py);
  • acl = private 固定私有访问;
  • 无论是否提供凭据都会写入 env_auth = false;只有凭据成对提供时才写入 access_key_id / secret_access_key。也就是说,R2 也支持无凭据(credentialless)挂载,此时依赖沙箱运行时的环境凭据——官方文档 docs/sandbox/clients.md 明确 credentialless 的 rclone 挂载限定为 S3、GCS、R2 与 Azure Blob 四种。

若 RcloneMountPattern 指定了 config_file_path(一个存在于沙箱工作区内的 rclone 配置文件),SDK 会先读取该文件中与 remote 同名的 <a href="https://link.gitcode.com/i/4199924908689509b77532a2194a3033" target="_blank">section],再用上述必填行做合并补充(_supplement_rclone_config_text,[patterns.py):保留原 section 已有内容,把 R2 的必填行追加进该 section。合并行为同样有单测覆盖(test_mounts.py)。

remote name 的确定性解析

RcloneMountPattern.resolve_remote_name()(patterns.py)决定 remote 标识:

  • 若 pattern 显式设置了 remote_name,直接使用;
  • 否则生成按会话确定的名字 sandbox_r2_{session_id_hex},这样多个挂载可共存而不互相污染 rclone 配置 section。注意这里要求会话必须有 session_id(uuid.UUID),否则抛 MountConfigError。

挂载执行与卸载

RcloneMountPattern.apply()(patterns.py)的完整流程:

  1. 在沙箱内检查 rclone 是否可用(command -v rclone || test -x /usr/local/bin/rclone),缺失则抛 MountToolMissingError;
  2. 在工作区内创建隔离配置文件 .sandbox-rclone-config/{session_id_hex}/{remote_name}.conf,并写入配置文本;写入后执行 chmod 0600(见 _write_sensitive_config_file,patterns.py),防止同容器其他用户读取凭据;
  3. 注册该目录为"持久化跳过路径",避免快照时把临时凭据写进工作区状态;
  4. 按模式执行:
    • fuse 模式(默认):rclone mount <remote>:<bucket> <mount_path> --config <conf> --daemon,只读时追加 --read-only,extra_args 可透传附加参数;
    • nfs 模式:先在后台启动 rclone serve nfs --addr <nfs_addr> --config <conf>,再以 mount -t nfs 挂载本地 NFS 地址(默认 127.0.0.1:2049,NFS 挂载选项默认 vers=4.1,tcp,soft,timeo=50,retrans=1,最多重试 3 次)。

unapply() 则依次尝试 fusermount3 -u / umount 卸载,并用 pkill -f 'rclone (mount|serve nfs) <remote>:' 清理后台进程。

Docker volume 策略:driver 参数生成

build_docker_volume_driver_config()(r2.py)返回 (driver, options, read_only) 三元组,其中 options 为:

{
    "type": "s3",
    "path": self.bucket,
    "s3-provider": "Cloudflare",
    "s3-endpoint": self.custom_domain or f"https://{self.account_id}.r2.cloudflarestorage.com",
}

提供成对凭据时追加 s3-access-key-id 与 s3-secret-access-key;最终选项为 options | strategy.driver_options,允许策略层补充额外 driver 选项。DockerVolumeMountStrategy.activate() 在会话侧是 no-op——真正的挂载由后端在容器启动前完成(base.py),且要求会话后端 supports_docker_volume_mounts(),否则抛 MountConfigError。

生命周期与快照:挂载的挂载/卸载闭环

所有挂载通过 Mount.apply() / Mount.unmount() 进入策略适配器(base.py)。对于容器内策略,InContainerMountAdapter(base.py)实现了四个关键阶段:

  • activate:构建含配置文本的 RcloneMountConfig 并执行 pattern.apply();
  • deactivate:以 include_config_text=False 构建仅含 remote 身份的配置,供 unapply() 做卸载清理;
  • teardown_for_snapshot / restore_after_snapshot:快照前卸载、快照后重挂,保证挂载始终是临时(ephemeral)状态、不进入持久化数据。

InContainerMountStrategy.activate 还会调用 _mount_security.py 的 validate_mount_activation_credential_boundary 做凭据暴露边界校验。官方指南 docs/sandbox/guide.md 指出:会话状态与 RunState 序列化时会剥离云挂载凭据;恢复挂载会话时需要通过 trusted_manifest.with_in_container_mount_credential_exposure_acknowledged("data")(或针对宽泛凭据域的 with_in_container_mount_broad_credential_exposure_acknowledged)显式确认凭据暴露范围。这是使用含内联凭据的容器内 R2 挂载时需要注意的恢复流程。

后端兼容矩阵

官方文档 docs/sandbox/clients.md 给出的后端支持情况:

后端 R2 挂载方式
Docker InContainerMountStrategy(rclone)或 DockerVolumeMountStrategy(driver="rclone")
ModalSandboxClient ModalCloudBucketMountStrategy + S3Mount / R2Mount(支持内联凭据或命名 Secret)
CloudflareSandboxClient CloudflareBucketMountStrategy + S3Mount / R2Mount
BlaxelSandboxClient BlaxelCloudBucketMountStrategy + S3Mount / R2Mount / GCSMount
DaytonaSandboxClient DaytonaCloudBucketMountStrategy(rclone),支持 S3/GCS/R2/Azure Blob/Box
E2BSandboxClient E2BCloudBucketMountStrategy(rclone),同上
RunloopSandboxClient RunloopCloudBucketMountStrategy(rclone),同上

需要说明的是,各扩展后端的策略类位于 src/agents/extensions/sandbox/ 下,本文不展开其内部实现。

实战示例:把 R2 桶挂进沙箱工作区

仓库中的 examples/sandbox/extensions/cloudflare_runner.py 给出了真实用法——当检测到环境变量 CLOUDFLARE_ACCOUNT_ID 时,将 R2 桶作为 manifest 条目加入:

manifest.entries["cloud-bucket"] = R2Mount(
    bucket=native_cloud_bucket_name,                 # 桶名
    account_id=os.environ.get("CLOUDFLARE_ACCOUNT_ID"),
    access_key_id=os.environ.get("R2_ACCESS_KEY_ID"),
    secret_access_key=os.environ.get("R2_SECRET_ACCESS_KEY"),
    mount_path=Path(native_cloud_bucket_mount_path), # 挂载到工作区的位置
    read_only=False,                                 # 允许 Agent 写入
    mount_strategy=CloudflareBucketMountStrategy(),
)

要点:bucket 与 account_id 为必填;access_key_id/secret_access_key 成对出现;mount_path 决定工作区内的挂载位置;read_only=False 表示允许写入。

测试辅助文件 tests/sandbox/integration_tests/_helpers.py 还展示了最朴素的容器内 rclone 配置方式:

"mounts/r2": R2Mount(
    bucket="r2-bucket",
    account_id="r2-account-id",
    mount_strategy=InContainerMountStrategy(pattern=RcloneMountPattern()),
),

无凭据(credentialless)用法

R2Mount 允许省略密钥对。此时生成的 rclone 配置只包含 env_auth = false,不写密钥行,运行时依赖沙箱环境中的既有凭据(如 Cloudflare Workers 环境注入或挂载策略提供的身份)。这种用法常见于托管后端,因为凭据不需要出现在 manifest 里。

测试验证与错误排查

单元测试覆盖

tests/sandbox/test_mounts.py 围绕 R2Mount 提供了一组高价值回归测试:

  • 成对凭据时生成完整 rclone 配置:断言生成的 config_text 精确等于 type = s3、provider = Cloudflare、默认 endpoint、acl = private、env_auth = false 加密钥行的组合;
  • custom_domain 覆盖默认 endpoint;
  • 已有 rclone 配置文件的 section 合并:[remote] 中已有的 region = auto 行被保留,R2 必填行追加其后,且不影响文件中的其他 section(如 [other]);
  • 拒绝非 rclone 的 mount pattern(MountpointMountPattern);
  • 两种策略下都拒绝残缺凭据:只给 access_key_id 不给 secret_access_key(反之亦然)时,容器内与 Docker volume 两条路径都抛同一错误。

常见报错与原因

报错 原因与处理
r2 credentials must include both access_key_id and secret_access_key 密钥只提供了一半;补全成对凭据,或全部省略走 credentialless
invalid mount_pattern type InContainerMountStrategy 使用了非 RcloneMountPattern 的 pattern(如 MountpointMountPattern);R2 只支持 rclone
invalid Docker volume driver DockerVolumeMountStrategy 的 driver 不是 "rclone"
mount session is missing session_id 会话缺少 uuid.UUID 类型的 session_id,无法派生每会话 remote name
rclone config missing required remote section config_file_path 指向的文件中不存在与 remote 同名的 [section],或文件为空
mount tool not found: rclone 沙箱镜像未安装 rclone,需要选用预装 rclone 的镜像或预置 /usr/local/bin/rclone

小结

R2Mount 是 openai-agents-python 沙箱体系中接入 Cloudflare R2 的标准入口,其设计核心是"一份字段模型同时驱动容器内 rclone 与 Docker volume 两种策略":容器内策略自动生成按会话隔离的 rclone 配置(S3 兼容协议、Cloudflare provider、默认或自定义 endpoint、acl = private),Docker 策略则生成 rclone volume driver 的 options。凭据必须成对出现,也支持完全省略以依赖环境身份。若你需要为 Agent 接入其他对象存储,可对比参考同目录下的 s3.py、gcs.py、azure_blob.py 与 box.py 实现,它们共享同一套 _ConfiguredMount 基础设施。

登录后查看全文
openai-agents-python