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

# 파일SDK파일 시스템

지원되는 모든 스토리지 백엔드에 파일을 저장합니다.[FilesSDK](https://files-sdk.dev): S3, Cloudflare R2, Google Cloud Storage, Azure Blob, Vercel Blob, MinIO, 로컬 파일 시스템 등에 대한 통합 추상화입니다. 인터페이스에 대한 자세한 내용은 다음을 참조하세요.[Workspace파일 시스템 인터페이스](https://mastra.zisheng.pro/ko/reference/workspace/filesystem).

동일한 코드로 여러 스토리지 백엔드를 대상으로 할 수 있는 단일 어댑터가 필요하면 `FilesSDKFilesystem`을 사용하세요. Workspace 설정을 변경하지 않고 기본 드라이버를 교체할 수 있습니다. 하나의 백엔드만 대상으로 하고 해당 백엔드의 일급 옵션을 사용하려면 전용 Provider(예: [`S3Filesystem`](https://mastra.zisheng.pro/ko/reference/workspace/s3-filesystem) 또는 [`GCSFilesystem`](https://mastra.zisheng.pro/ko/reference/workspace/gcs-filesystem))를 사용하는 것이 좋습니다.

## 설치

**npm**:

```bash
npm install @mastra/files-sdk files-sdk
```

**pnpm**:

```bash
pnpm add @mastra/files-sdk files-sdk
```

**Yarn**:

```bash
yarn add @mastra/files-sdk files-sdk
```

**Bun**:

```bash
bun add @mastra/files-sdk files-sdk
```

`files-sdk`사용하려는 어댑터로 구성하는 피어 종속성입니다.

## 용법

원하는 어댑터로 FilesSDK의 `Files` 인스턴스를 생성한 다음 `FilesSDKFilesystem`에 전달합니다:

```typescript
import { Agent } from '@mastra/core/agent'
import { Workspace } from '@mastra/core/workspace'
import { FilesSDKFilesystem } from '@mastra/files-sdk'
import { Files } from 'files-sdk'
import { s3 } from 'files-sdk/s3'

const files = new Files({
  adapter: s3({
    bucket: 'my-bucket',
    region: 'us-east-1',
  }),
})

const workspace = new Workspace({
  filesystem: new FilesSDKFilesystem({ files }),
})

const agent = new Agent({
  id: 'file-agent',
  name: 'file-agent',
  model: 'anthropic/claude-opus-4-7',
  workspace,
})
```

### 어댑터 교환

동일한 `FilesSDKFilesystem`을 모든 FilesSDK 어댑터와 함께 사용할 수 있습니다. 백엔드를 전환하려면 드라이버 팩터리를 교체합니다:

```typescript
import { Files } from 'files-sdk'
import { r2 } from 'files-sdk/r2'
import { gcs } from 'files-sdk/gcs'
import { azure } from 'files-sdk/azure'
import { fs } from 'files-sdk/fs'

// Cloudflare R2
const r2Files = new Files({ adapter: r2({ accountId, bucket, accessKeyId, secretAccessKey }) })

// Google Cloud Storage
const gcsFiles = new Files({ adapter: gcs({ bucket, projectId }) })

// Azure Blob
const azureFiles = new Files({ adapter: azure({ container, connectionString }) })

// Local filesystem (useful for tests and development)
const localFiles = new Files({ adapter: fs({ root: './workspace' }) })
```

전체 어댑터 카탈로그와 구성 옵션은 [FilesSDK 문서](https://files-sdk.dev)를 참조하세요.

### 읽기 전용 마운트

```typescript
const filesystem = new FilesSDKFilesystem({
  files,
  readOnly: true,
})
```

모든 쓰기 작업(`writeFile`, `appendFile`, `deleteFile`, `copyFile`, `moveFile`, `mkdir`, `rmdir`) throw `WorkspaceReadOnlyError`읽는 동안 성공합니다.

## 생성자 매개변수

**files** (`Files`): 사용하려는 어댑터 및 자격 증명에 바인딩된 사전 구성된 FilesSDK Files 인스턴스입니다.

**id** (`string`): 이 파일 시스템 인스턴스의 고유 식별자입니다. (Default: `자동 생성`)

**displayName** (`string`): UI에 표시할 사용자 친화적인 이름입니다.

**icon** (`FilesystemIcon`): UI에 사용할 아이콘 식별자입니다.

**description** (`string`): UI에 표시할 이 파일 시스템의 짧은 설명입니다.

**readOnly** (`boolean`): true이면 모든 쓰기 작업이 차단됩니다. (Default: `false`)

## 속성

**id** (`string`): 파일 시스템 인스턴스 식별자입니다.

**name** (`string`): Provider 이름입니다('FilesSDKFilesystem').

**provider** (`string`): Provider 식별자입니다('files-sdk').

**readOnly** (`boolean | undefined`): 파일 시스템이 읽기 전용 모드인지 여부입니다.

## 행동 양식

`FilesSDKFilesystem`구현[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: 'FilesSDKFilesystem', provider: 'files-sdk', status: 'ready' }
```

### `files`

어댑터별 API를 직접 호출해야 하는 경우 기본 FilesSDK `Files` 인스턴스가 public 속성으로 노출됩니다.

```typescript
const url = await filesystem.files.url('reports/q3.pdf')
```

## 객체 저장소 의미론

`FilesSDKFilesystem`은 기본 어댑터가 계층형인 경우에도(예: `fs`) 객체 스토리지 의미 체계를 적용합니다. 따라서 어댑터 전반에서 동작이 일관되게 유지됩니다:

- **`mkdir`**은 아무 작업도 하지 않습니다. 해당 접두사가 있는 키가 있으면 디렉터리는 암시적으로 존재합니다.
- **`exists`**는 정확한 키가 파일로 존재하거나 경로가 하나 이상의 하위 키를 포함하는 접두사인 경우에만 `true`를 반환합니다. 계층형 어댑터에 남아 있는 빈 디렉터리는 포함되지 않습니다.
- **`deleteFile`**은 키가 존재하지 않으면 `{ force: true }`가 전달된 경우를 제외하고 `FileNotFoundError`를 발생시킵니다.
- **`deleteFile`**은 디렉터리를 `rmdir({ recursive: true })`에 위임하며, 이는 [`S3Filesystem`](https://mastra.zisheng.pro/ko/reference/workspace/s3-filesystem) 및 [`GCSFilesystem`](https://mastra.zisheng.pro/ko/reference/workspace/gcs-filesystem)의 동작과 일치합니다.
- **`moveFile`**은 `copyFile`을 실행한 후 `deleteFile`을 실행하는 방식으로 구현됩니다. 이 작업은 **원자적이지 않습니다**. 복사에 성공한 후 소스 삭제에 실패하면 대상은 남아 있고 소스는 제거되지 않습니다.
- **`appendFile`**은 읽기-수정-쓰기 작업입니다. 동일한 키에 동시에 추가하면 서로 덮어쓸 수 있습니다. 이는 객체 스토리지의 본질적인 특성이며 FilesSDK에만 국한되지 않습니다.
- **`readdir({ recursive: true })`**은 중간 디렉터리 항목을 내보냅니다(예: `a/b/c.txt`와 함께 `a/b`도 내보냅니다).

## 관련된

- [WorkspaceFilesystem 인터페이스](https://mastra.zisheng.pro/ko/reference/workspace/filesystem)
- [S3파일 시스템 참조](https://mastra.zisheng.pro/ko/reference/workspace/s3-filesystem)
- [GCS파일 시스템 참조](https://mastra.zisheng.pro/ko/reference/workspace/gcs-filesystem)
- [AzureBlob파일 시스템 참조](https://mastra.zisheng.pro/ko/reference/workspace/azure-blob-filesystem)
- [작업공간 개요](https://mastra.zisheng.pro/ko/docs/workspace/overview)
- [FilesSDK 문서](https://files-sdk.dev)