S3파일 시스템

Cloudflare R2, MinIO, DigitalOcean Spaces 및 Tigris와 같은 Amazon S3 또는 S3 호환 스토리지 서비스에 파일을 저장합니다. 인터페이스에 대한 자세한 내용은 다음을 참조하세요.WorkspaceFilesystem Interface.

설치

npm

npm install @mastra/s3

pnpm

pnpm add @mastra/s3

Yarn

yarn add @mastra/s3

Bun

bun add @mastra/s3

용법

Workspace에 S3Filesystem을 추가하고 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 자격 증명 공급자 체인

자격 증명이 제공되지 않으면 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',
})

자격 증명 자동 새로 고침을 위해 자격 증명 공급자 기능을 전달합니다. 이는 ECS, Lambda 배포에 유용하거나 임시 자격 증명이 만료되어 새로 고쳐야 하는 SSO/AssumeRole을 사용할 때 유용합니다.

호출 시 AWS SDK 자격 증명 공급자 패키지를 설치합니다.fromNodeProviderChain() directly:

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 값만 지원하므로 자격 증명 갱신은 마운트 외부에서 처리해야 합니다.

클라우드플레어 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,
})

미니IO

import { S3Filesystem } from '@mastra/s3'

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

티그리스

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 대시보드에서 자격 증명을 생성하세요. 액세스 키에는 tid_, 비밀 키에는 tsec_ 접두사가 붙습니다.

생성자 매개변수

bucket:

string

S3 버킷 이름

region:

string

AWS 리전(R2에는 'auto' 사용)

credentials?:

AwsCredentialIdentity | AwsCredentialIdentityProvider

AWS 자격 증명 또는 자격 증명 Provider 함수입니다. 정적 자격 증명이나 자동 갱신 Provider(예: @aws-sdk/credential-providers의 fromNodeProviderChain())를 허용합니다. accessKeyId/secretAccessKey/sessionToken보다 우선합니다. 모든 자격 증명 옵션을 생략하면 SDK 기본 자격 증명 Provider 체인을 사용합니다.

accessKeyId?:

string

secretAccessKey 및 credentials와 함께 생략하면 SDK 기본 자격 증명 Provider 체인을 사용하는 AWS 액세스 키 ID입니다.

secretAccessKey?:

string

accessKeyId 및 credentials와 함께 생략하면 SDK 기본 자격 증명 Provider 체인을 사용하는 AWS 비밀 액세스 키입니다.

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 interface, providing all standard filesystem methods:

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

이 파일 시스템 유형 마운트를 지원하는 샌드박스에 대한 마운트 구성을 반환합니다.

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

E2B 샌드박스에 탑재

S3Filesystem은 E2B 샌드박스에 마운트될 수 있으므로 버킷을 로컬 디렉터리로 액세스할 수 있습니다.

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 인터페이스
• Archil파일 시스템 참조
• GCS파일 시스템 참조
• AzureBlob파일 시스템 참조
• E2B샌드박스 참조
• 작업공간 개요