> Discover all available pages from the documentation index: https://mastra.zisheng.pro/llms.txt

# S3Filesystem

将文件存储在 Amazon S3 或兼容 S3 的存储服务中，例如 Cloudflare R2、MinIO、DigitalOcean Spaces 和 Tigris。有关接口的详细信息，请参阅 [WorkspaceFilesystem 接口](https://mastra.zisheng.pro/reference/workspace/filesystem)。

## 安装

**npm**:

```bash
npm install @mastra/s3
```

**pnpm**:

```bash
pnpm add @mastra/s3
```

**Yarn**:

```bash
yarn add @mastra/s3
```

**Bun**:

```bash
bun add @mastra/s3
```

## 使用方法

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

```typescript
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 实例配置文件及其他标准来源中发现凭证。

```typescript
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**:

```bash
npm install @aws-sdk/credential-providers
```

**pnpm**:

```bash
pnpm add @aws-sdk/credential-providers
```

**Yarn**:

```bash
yarn add @aws-sdk/credential-providers
```

**Bun**:

```bash
bun add @aws-sdk/credential-providers
```

```typescript
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

```typescript
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

```typescript
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

```typescript
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](https://console.tigris.dev/) 创建凭证。访问密钥以 `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`): 强制使用路径样式 URL，而不是虚拟主机样式。MinIO 等部分 S3 兼容服务要求使用此项。提供自定义端点时默认为 true。 (Default: `true（设置 endpoint 时）`)

**prefix** (`string`): 所有键的可选前缀（作用类似子目录）

**id** (`string`): 此文件系统实例的唯一标识符 (Default: `自动生成`)

**displayName** (`string`): 在 UI 中显示的易读名称

**icon** (`FilesystemIcon`): 用于 UI 的图标标识符

**description** (`string`): 在 UI 中显示的此文件系统的简短说明

**readOnly** (`boolean`): 为 true 时，阻止所有写入操作 (Default: `false`)

## 属性

**id** (`string`): 文件系统实例标识符

**name** (`string`): Provider 名称（'S3Filesystem'）

**provider** (`string`): Provider 标识符（'s3'）

**bucket** (`string`): S3 存储桶名称

**readOnly** (`boolean | undefined`): 文件系统是否处于只读模式

## 方法

S3Filesystem 实现了 [WorkspaceFilesystem 接口](https://mastra.zisheng.pro/reference/workspace/filesystem)，提供所有标准文件系统方法：

- `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()`

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

```typescript
await filesystem.init()
```

### `getInfo()`

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

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

### `getMountConfig()`

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

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

## 挂载到 E2B Sandbox

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

```typescript
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 参考文档](https://mastra.zisheng.pro/reference/workspace/e2b-sandbox)。

## 相关内容

- [WorkspaceFilesystem 接口](https://mastra.zisheng.pro/reference/workspace/filesystem)
- [ArchilFilesystem 参考文档](https://mastra.zisheng.pro/reference/workspace/archil-filesystem)
- [GCSFilesystem 参考文档](https://mastra.zisheng.pro/reference/workspace/gcs-filesystem)
- [AzureBlobFilesystem 参考文档](https://mastra.zisheng.pro/reference/workspace/azure-blob-filesystem)
- [E2BSandbox 参考文档](https://mastra.zisheng.pro/reference/workspace/e2b-sandbox)
- [Workspace 概述](https://mastra.zisheng.pro/docs/workspace/overview)