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

# S3파일 시스템

Cloudflare R2, MinIO, DigitalOcean Spaces 및 Tigris와 같은 Amazon S3 또는 S3 호환 스토리지 서비스에 파일을 저장합니다. 인터페이스에 대한 자세한 내용은 다음을 참조하세요.[WorkspaceFilesystem Interface](https://mastra.zisheng.pro/ko/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
```

## 용법

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

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

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

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

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

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

### 미니IO

```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',
})
```

### 티그리스

```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 대시보드](https://console.tigris.dev/)에서 자격 증명을 생성하세요. 액세스 키에는 `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`): 가상 호스트 방식 대신 경로 방식 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 interface](https://mastra.zisheng.pro/ko/reference/workspace/filesystem), 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()`

파일 시스템을 초기화합니다. 버킷 액세스 및 자격 증명을 확인합니다.

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

### `getInfo()`

이 파일 시스템 인스턴스에 대한 메타데이터를 반환합니다.

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

### `getMountConfig()`

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

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

## E2B 샌드박스에 탑재

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

```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/ko/reference/workspace/e2b-sandbox)를 참조하세요.

## 관련된

- [WorkspaceFilesystem 인터페이스](https://mastra.zisheng.pro/ko/reference/workspace/filesystem)
- [Archil파일 시스템 참조](https://mastra.zisheng.pro/ko/reference/workspace/archil-filesystem)
- [GCS파일 시스템 참조](https://mastra.zisheng.pro/ko/reference/workspace/gcs-filesystem)
- [AzureBlob파일 시스템 참조](https://mastra.zisheng.pro/ko/reference/workspace/azure-blob-filesystem)
- [E2B샌드박스 참조](https://mastra.zisheng.pro/ko/reference/workspace/e2b-sandbox)
- [작업공간 개요](https://mastra.zisheng.pro/ko/docs/workspace/overview)