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 套件：

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 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 存取金鑰 ID。如連同 secretAccessKey 及 credentials 一併省略，便會使用 SDK 的預設憑證 Provider 鏈。

secretAccessKey?:

string

AWS 秘密存取金鑰。如連同 accessKeyId 及 credentials 一併省略，便會使用 SDK 的預設憑證 Provider 鏈。

sessionToken?:

string

靜態臨時憑證所用的 AWS session token。只有在手動傳入一套完整臨時憑證時，才應與 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

所有 key 的可選前綴（作用類似子目錄）

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) - 取得檔案或目錄的 metadata

init()

初始化檔案系統，並驗證 bucket 存取權及憑證。

await filesystem.init()

getInfo()

傳回此檔案系統執行個體的 metadata。

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