S3Filesystem

将文件存储在 Amazon S3 或兼容 S3 的存储服务中，例如 Cloudflare R2、MinIO、DigitalOcean Spaces 和 Tigris。有关接口的详细信息，请参阅 WorkspaceFilesystem 接口。

安装

npm

npm install @mastra/s3

pnpm

pnpm add @mastra/s3

Yarn

yarn add @mastra/s3

Bun

bun add @mastra/s3

使用方法

将 S3Filesystem 添加到 Workspace 并分配给 Agent：

import { Agent } from '@mastra/core/agent'
import { Workspace } from '@mastra/core/workspace'
import { S3Filesystem } from '@mastra/s3'

const workspace = new Workspace({
  filesystem: new S3Filesystem({
    bucket: 'my-bucket',
    region: 'us-east-1',
    accessKeyId: process.env.AWS_ACCESS_KEY_ID,
    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
  }),
})

const agent = new Agent({
  id: 'file-agent',
  name: 'file-agent',
  model: 'anthropic/claude-opus-4-7',
  workspace,
})

AWS 凭证 Provider 链

未提供凭证时，S3Filesystem 使用 AWS SDK 的默认凭证 Provider 链。该链会自动从环境变量、~/.aws 配置文件、ECS 容器凭证、EC2 实例配置文件及其他标准来源中发现凭证。

import { S3Filesystem } from '@mastra/s3'

// SDK discovers credentials from the environment automatically
const filesystem = new S3Filesystem({
  bucket: 'my-bucket',
  region: 'us-east-1',
})

传入凭证 Provider 函数可自动刷新凭证。这适用于部署到 ECS、Lambda 的情况，也适用于使用 SSO/AssumeRole 时临时凭证会过期并需要刷新的情况。

直接调用 fromNodeProviderChain() 时，请安装 AWS SDK 凭证 Provider 包：

npm

npm install @aws-sdk/credential-providers

pnpm

pnpm add @aws-sdk/credential-providers

Yarn

yarn add @aws-sdk/credential-providers

Bun

bun add @aws-sdk/credential-providers

import { S3Filesystem } from '@mastra/s3'
import { fromNodeProviderChain } from '@aws-sdk/credential-providers'

const filesystem = new S3Filesystem({
  bucket: 'my-bucket',
  region: 'us-east-1',
  credentials: fromNodeProviderChain(),
})

Provider 函数仅适用于 S3Filesystem API 调用。将文件系统挂载到 E2B Sandbox 时，挂载配置仅支持静态的 accessKeyId、secretAccessKey 和 sessionToken 值，因此凭证刷新必须在挂载外部处理。

Cloudflare R2

import { S3Filesystem } from '@mastra/s3'

const filesystem = new S3Filesystem({
  bucket: 'my-r2-bucket',
  region: 'auto',
  endpoint: `https://${process.env.R2_ACCOUNT_ID}.r2.cloudflarestorage.com`,
  accessKeyId: process.env.R2_ACCESS_KEY_ID,
  secretAccessKey: process.env.R2_SECRET_ACCESS_KEY,
})

MinIO

import { S3Filesystem } from '@mastra/s3'

const filesystem = new S3Filesystem({
  bucket: 'my-bucket',
  region: 'us-east-1',
  endpoint: 'http://localhost:9000',
  accessKeyId: 'minioadmin',
  secretAccessKey: 'minioadmin',
})

Tigris

import { S3Filesystem } from '@mastra/s3'

const filesystem = new S3Filesystem({
  bucket: 'my-bucket',
  region: 'auto',
  endpoint: 'https://t3.storage.dev',
  accessKeyId: process.env.TIGRIS_ACCESS_KEY_ID,
  secretAccessKey: process.env.TIGRIS_SECRET_ACCESS_KEY,
  forcePathStyle: false,
})

Tigris 使用虚拟主机样式寻址，因此必须将 forcePathStyle 设置为 false（提供自定义端点时，默认为 true）。请从 Tigris Dashboard 创建凭证。访问密钥以 tid_ 为前缀，机密以 tsec_ 为前缀。

构造函数参数

bucket:

string

S3 存储桶名称

region:

string

AWS 区域（R2 请使用 'auto'）

credentials?:

AwsCredentialIdentity | AwsCredentialIdentityProvider

AWS 凭证或凭证 Provider 函数。接受静态凭证或能够自动刷新的 Provider（例如 fromNodeProviderChain()，来自 @aws-sdk/credential-providers）。优先级高于 accessKeyId/secretAccessKey/sessionToken。省略所有凭证选项时，使用 SDK 的默认凭证 Provider 链。

accessKeyId?:

string

AWS 访问密钥 ID。与 secretAccessKey 和 credentials 一同省略时，使用 SDK 的默认凭证 Provider 链。

secretAccessKey?:

string

AWS 机密访问密钥。与 accessKeyId 和 credentials 一同省略时，使用 SDK 的默认凭证 Provider 链。

sessionToken?:

string

用于静态临时凭证的 AWS 会话令牌。仅在手动传入一套完整的临时凭证时与 accessKeyId/secretAccessKey 一起使用。对于可自动刷新的 SSO、AssumeRole 或容器凭证，请使用 credentials Provider 参数或 SDK 的默认凭证 Provider 链。

endpoint?:

string

用于 S3 兼容存储（R2、MinIO、Tigris 等）的自定义端点 URL

forcePathStyle?:

boolean

= true（设置 endpoint 时）

强制使用路径样式 URL，而不是虚拟主机样式。MinIO 等部分 S3 兼容服务要求使用此项。提供自定义端点时默认为 true。

prefix?:

string

所有键的可选前缀（作用类似子目录）

id?:

string

= 自动生成

此文件系统实例的唯一标识符

displayName?:

string

在 UI 中显示的易读名称

icon?:

FilesystemIcon

用于 UI 的图标标识符

description?:

string

在 UI 中显示的此文件系统的简短说明

readOnly?:

boolean

= false

为 true 时，阻止所有写入操作

属性

id:

string

文件系统实例标识符

name:

string

Provider 名称（'S3Filesystem'）

provider:

string

Provider 标识符（'s3'）

bucket:

string

S3 存储桶名称

readOnly:

boolean | undefined

文件系统是否处于只读模式

方法

S3Filesystem 实现了 WorkspaceFilesystem 接口，提供所有标准文件系统方法：

• readFile(path, options?) - 读取文件内容
• writeFile(path, content, options?) - 将内容写入文件
• appendFile(path, content) - 将内容追加到文件
• deleteFile(path, options?) - 删除文件
• copyFile(src, dest, options?) - 复制文件
• moveFile(src, dest, options?) - 移动文件或重命名
• mkdir(path, options?) - 创建目录
• rmdir(path, options?) - 删除目录
• readdir(path, options?) - 列出目录内容
• exists(path) - 检查路径是否存在
• stat(path) - 获取文件或目录元数据

init()

初始化文件系统。验证存储桶访问权限和凭证。

await filesystem.init()

getInfo()

返回有关此文件系统实例的元数据。

const info = filesystem.getInfo()
// { id: '...', name: 'S3Filesystem', provider: 's3', status: 'ready' }

getMountConfig()

返回支持挂载此文件系统类型的 Sandbox 所需的挂载配置。

const config = filesystem.getMountConfig()
// { type: 's3', bucket: 'my-bucket', region: 'us-east-1', ... }

挂载到 E2B Sandbox

可以将 S3Filesystem 挂载到 E2B Sandbox，使存储桶能以本地目录的形式访问：

import { Workspace } from '@mastra/core/workspace'
import { S3Filesystem } from '@mastra/s3'
import { E2BSandbox } from '@mastra/e2b'

const workspace = new Workspace({
  mounts: {
    '/data': new S3Filesystem({
      bucket: 'my-bucket',
      region: 'us-east-1',
      accessKeyId: process.env.AWS_ACCESS_KEY_ID,
      secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
    }),
  },
  sandbox: new E2BSandbox({ id: 'dev-sandbox' }),
})

有关挂载的更多详细信息，请参阅 E2BSandbox 参考文档。

相关内容

• WorkspaceFilesystem 接口
• ArchilFilesystem 参考文档
• GCSFilesystem 参考文档
• AzureBlobFilesystem 参考文档
• E2BSandbox 参考文档
• Workspace 概述