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

# GCS파일 시스템

Google Cloud Storage에 파일을 저장합니다. 인터페이스에 대한 자세한 내용은 다음을 참조하세요.[WorkspaceFilesystem Interface](https://mastra.zisheng.pro/ko/reference/workspace/filesystem).

## 설치

**npm**:

```bash
npm install @mastra/gcs
```

**pnpm**:

```bash
pnpm add @mastra/gcs
```

**Yarn**:

```bash
yarn add @mastra/gcs
```

**Bun**:

```bash
bun add @mastra/gcs
```

## 용법

Workspace에 `GCSFilesystem`을 추가하고 Agent에 할당합니다:

```typescript
import { Agent } from '@mastra/core/agent'
import { Workspace } from '@mastra/core/workspace'
import { GCSFilesystem } from '@mastra/gcs'

const workspace = new Workspace({
  filesystem: new GCSFilesystem({
    bucket: 'my-gcs-bucket',
    projectId: 'my-project-id',
    credentials: JSON.parse(process.env.GCS_SERVICE_ACCOUNT_KEY),
  }),
})

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

### 애플리케이션 기본 자격 증명 사용

`gcloud` CLI가 구성된 Google Cloud 환경에서 실행하는 경우 자격 증명을 생략할 수 있습니다:

```typescript
import { GCSFilesystem } from '@mastra/gcs'

const filesystem = new GCSFilesystem({
  bucket: 'my-gcs-bucket',
  // Uses Application Default Credentials automatically
})
```

[애플리케이션 기본 자격 증명(ADC)](https://cloud.google.com/docs/authentication/application-default-credentials)다음 순서로 자격 증명을 자동으로 검색합니다.

1. `GOOGLE_APPLICATION_CREDENTIALS` 환경 변수(서비스 계정 키 파일 경로)
2. GCP(Compute Engine, Cloud Run, GKE 등)에서 실행할 때의 기본 서비스 계정
3. 사용자 자격 증명: `gcloud auth application-default login`(로컬 개발용)

### 키 파일 경로 사용

서비스 계정 키 파일의 경로를 전달할 수도 있습니다.

```typescript
import { GCSFilesystem } from '@mastra/gcs'

const filesystem = new GCSFilesystem({
  bucket: 'my-gcs-bucket',
  projectId: 'my-project-id',
  credentials: '/path/to/service-account-key.json',
})
```

## 생성자 매개변수

**bucket** (`string`): GCS 버킷 이름

**projectId** (`string`): GCS 프로젝트 ID입니다. 서비스 계정 자격 증명을 사용할 때 필요합니다.

**credentials** (`object | string`): 서비스 계정 키 JSON 객체 또는 키 파일 경로입니다. 제공하지 않으면 애플리케이션 기본 자격 증명을 사용합니다.

**prefix** (`string`): 모든 키에 적용할 선택적 접두사(하위 디렉터리처럼 작동)

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

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

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

**description** (`string`): UI에 표시할 이 파일 시스템의 간단한 설명

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

**endpoint** (`string`): 사용자 지정 API 엔드포인트 URL입니다. 에뮬레이터를 사용하는 로컬 개발에 사용됩니다.

## 속성

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

**name** (`string`): Provider 이름('GCSFilesystem')

**provider** (`string`): Provider 식별자('gcs')

**bucket** (`string`): GCS 버킷 이름

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

## 행동 양식

GCSFilesystem은 다음을 구현합니다.[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: 'GCSFilesystem', provider: 'gcs', status: 'ready' }
```

### `getMountConfig()`

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

```typescript
const config = filesystem.getMountConfig()
// { type: 'gcs', bucket: 'my-bucket', ... }
```

## E2B 샌드박스에 탑재

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

```typescript
import { Workspace } from '@mastra/core/workspace'
import { GCSFilesystem } from '@mastra/gcs'
import { E2BSandbox } from '@mastra/e2b'

const workspace = new Workspace({
  mounts: {
    '/data': new GCSFilesystem({
      bucket: 'my-gcs-bucket',
      projectId: 'my-project-id',
      credentials: JSON.parse(process.env.GCS_SERVICE_ACCOUNT_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)
- [S3파일 시스템 참조](https://mastra.zisheng.pro/ko/reference/workspace/s3-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)