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

# Cloudflare 스토리지

Mastra는 두 가지 Cloudflare 스토리지 구현을 제공합니다.

- **Cloudflare KV** (`CloudflareKVStorage`): 전 세계에 분산된 최종 일관성 키-값 저장소
- **Cloudflare Durable Objects** (`CloudflareDOStorage`): Durable Objects를 사용하는 강한 일관성의 SQLite 기반 저장소 :::warning\[관측성이 지원되지 않음]

Cloudflare 저장소는 **Observability 도메인을 지원하지 않습니다**. `MastraStorageExporter`의 Trace를 영구 저장할 수 없으며, Cloudflare가 유일한 저장소 Provider인 경우 [Studio의](https://mastra.zisheng.pro/ko/docs/studio/overview) Observability 기능이 작동하지 않습니다. Observability를 활성화하려면 [복합 저장소](https://mastra.zisheng.pro/ko/reference/storage/composite)를 사용하여 Observability 데이터를 ClickHouse와 같은 지원되는 Provider로 라우팅하세요. :::

## 설치

**npm**:

```bash
npm install @mastra/cloudflare@latest
```

**pnpm**:

```bash
pnpm add @mastra/cloudflare@latest
```

**Yarn**:

```bash
yarn add @mastra/cloudflare@latest
```

**Bun**:

```bash
bun add @mastra/cloudflare@latest
```

## Cloudflare KV 저장소

KV 저장소 구현은 Cloudflare Workers KV를 사용하여 전 세계적으로 분산된 서버리스 키-값 저장소 솔루션을 제공합니다.

### 용법

```typescript
import { CloudflareKVStorage } from '@mastra/cloudflare/kv'

// --- Example 1: Using Workers Binding ---
const storageWorkers = new CloudflareKVStorage({
  id: 'cloudflare-workers-storage',
  bindings: {
    threads: THREADS_KV, // KVNamespace binding for threads table
    messages: MESSAGES_KV, // KVNamespace binding for messages table
    // Add other tables as needed
  },
  keyPrefix: 'dev_', // Optional: isolate keys per environment
})

// --- Example 2: Using REST API ---
const storageRest = new CloudflareKVStorage({
  id: 'cloudflare-rest-storage',
  accountId: process.env.CLOUDFLARE_ACCOUNT_ID!, // Cloudflare Account ID
  apiToken: process.env.CLOUDFLARE_API_TOKEN!, // Cloudflare API Token
  namespacePrefix: 'dev_', // Optional: isolate namespaces per environment
})
```

### 매개변수

**id** (`string`): 이 저장소 인스턴스의 고유 식별자입니다.

**bindings** (`Record<string, KVNamespace>`): Cloudflare Workers KV 바인딩(Workers 런타임용)

**accountId** (`string`): Cloudflare 계정 ID(REST API용)

**apiToken** (`string`): Cloudflare API 토큰(REST API용)

**namespacePrefix** (`string`): 모든 네임스페이스 이름에 적용할 선택적 접두사(환경 격리에 유용)

**keyPrefix** (`string`): 모든 키에 적용할 선택적 접두사(환경 격리에 유용)

### 추가 참고사항

### 스키마 관리

저장소 구현은 스키마 생성 및 업데이트를 자동으로 처리합니다. 다음 테이블이 생성됩니다.

- `threads`: 대화 스레드를 저장합니다.
- `messages`: 개별 메시지를 저장합니다.
- `metadata`: 스레드 및 메시지에 대한 추가 메타데이터를 저장합니다.

### 일관성 및 전파

Cloudflare KV는 최종적으로 일관된 저장소입니다. 즉, 쓰기 후 모든 지역에서 데이터를 즉시 사용하지 못할 수도 있습니다.

### 주요 구조 및 네임스페이스

Cloudflare KV의 키는 구성 가능한 접두사와 테이블별 형식의 조합으로 구성됩니다(예: `threads:threadId`). Workers 배포에서는 `keyPrefix`를 사용하여 네임스페이스 내의 데이터를 격리하고, REST API 배포에서는 `namespacePrefix`를 사용하여 환경이나 애플리케이션 간에 전체 네임스페이스를 격리합니다.

## Cloudflare 내구성 개체 스토리지

내구성 개체 스토리지 구현은 Cloudflare 내구성 개체를 사용하여 강력하게 일관된 SQLite 기반 스토리지를 제공합니다. 이는 트랜잭션 일관성과 SQL 쿼리 기능이 필요한 애플리케이션에 이상적입니다.

### 용법

```typescript
import { DurableObject } from 'cloudflare:workers'
import { CloudflareDOStorage } from '@mastra/cloudflare/do'

class AgentDurableObject extends DurableObject<Env> {
  private storage: CloudflareDOStorage

  constructor(ctx: DurableObjectState, env: Env) {
    super(ctx, env)
    this.storage = new CloudflareDOStorage({
      sql: ctx.storage.sql,
      tablePrefix: 'mastra_', // Optional: prefix for table names
    })
  }

  async run() {
    const memory = await this.storage.getStore('memory')
    await memory?.saveThread({
      thread: { id: 'thread-1', resourceId: 'user-1', title: 'Chat', metadata: {} },
    })
  }
}
```

### 매개변수

**sql** (`SqlStorage`): Durable Objects ctx.storage.sql의 SqlStorage 인스턴스

**tablePrefix** (`string`): 테이블 이름에 적용할 선택적 접두사(문자, 숫자, 밑줄만 허용)

**disableInit** (`boolean`): true이면 자동 테이블 생성 및 마이그레이션이 비활성화됩니다. 마이그레이션을 별도로 실행하는 CI/CD 파이프라인에 유용합니다.

### 강력한 일관성

KV와 달리 지속성 개체는 강력한 일관성을 보장합니다. 지속성 개체 내의 모든 읽기 및 쓰기는 직렬화되므로 빠르고 오래 실행되는 Agent에 매우 적합합니다.

### SQL 기능

내구성 있는 개체 스토리지는 내부적으로 SQLite를 사용하여 키-값 스토리지에서는 불가능한 효율적인 쿼리, 필터링 및 페이지 매김을 가능하게 합니다.

## 스키마 관리

두 저장소 구현 모두 스키마 생성 및 업데이트를 자동으로 처리합니다. 그들은 다음과 같은 테이블을 생성합니다:

- `threads`: 대화 스레드를 저장합니다.
- `messages`: 개별 메시지를 저장합니다.
- `workflow_snapshot`: Workflow 실행 상태를 저장합니다.

## 더 이상 사용되지 않는 별칭

이전 버전과의 호환성을 위해 다음 별칭을 사용할 수 있습니다.

```typescript
// These are deprecated - use CloudflareKVStorage and CloudflareDOStorage instead
import { CloudflareStore } from '@mastra/cloudflare/kv' // alias for CloudflareKVStorage
import { DOStore } from '@mastra/cloudflare/do' // alias for CloudflareDOStorage
```