S3Filesystem

將檔案儲存在 Amazon S3，或 Cloudflare R2、MinIO、DigitalOcean Spaces 與 Tigris 等 S3 相容儲存服務中。介面詳情請參閱 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 package：

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（提供自訂 endpoint 時，預設值為 true）。請從 Tigris 儀表板 建立憑證。access key 的前綴為 tid_，secret 的前綴為 tsec_。

建構函式參數

bucket:

string

S3 bucket 名稱。

region:

string

AWS 區域（R2 請使用 'auto'）。

credentials?:

AwsCredentialIdentity | AwsCredentialIdentityProvider

AWS 憑證或憑證 Provider 函式。接受靜態憑證，或會自動更新的 Provider（例如來自 @aws-sdk/credential-providers 的 fromNodeProviderChain()）。優先於 accessKeyId/secretAccessKey/sessionToken。省略所有憑證選項時，會使用 SDK 預設憑證 Provider 鏈。

accessKeyId?:

string

AWS access key ID。與 secretAccessKey 和 credentials 一併省略時，會使用 SDK 預設憑證 Provider 鏈。

secretAccessKey?:

string

AWS secret access key。與 accessKeyId 和 credentials 一併省略時，會使用 SDK 預設憑證 Provider 鏈。

sessionToken?:

string

用於靜態暫時憑證的 AWS session token。僅在手動傳入完整暫時憑證集時，與 accessKeyId/secretAccessKey 一併使用。對於自動更新的 SSO、AssumeRole 或容器憑證，請使用 credentials Provider 參數或 SDK 預設憑證 Provider 鏈。

endpoint?:

string

S3 相容儲存（R2、MinIO、Tigris 等）的自訂 endpoint URL。

forcePathStyle?:

boolean

= true（設定 endpoint 時）

強制使用路徑樣式 URL，而非虛擬主機樣式。MinIO 等部分 S3 相容服務必須使用。提供自訂 endpoint 時，預設值為 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 bucket 名稱。

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

初始化檔案系統。驗證 bucket 存取與憑證。

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，讓 bucket 可作為本機目錄存取：

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 概觀