Cloudflare 스토리지

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

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

Cloudflare 저장소는 Observability 도메인을 지원하지 않습니다. MastraStorageExporter의 Trace를 영구 저장할 수 없으며, Cloudflare가 유일한 저장소 Provider인 경우 Studio의 Observability 기능이 작동하지 않습니다. Observability를 활성화하려면 복합 저장소를 사용하여 Observability 데이터를 ClickHouse와 같은 지원되는 Provider로 라우팅하세요. :::

설치

npm

npm install @mastra/cloudflare@latest

pnpm

pnpm add @mastra/cloudflare@latest

Yarn

yarn add @mastra/cloudflare@latest

Bun

bun add @mastra/cloudflare@latest

Cloudflare KV 저장소

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

용법

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 쿼리 기능이 필요한 애플리케이션에 이상적입니다.

용법

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 실행 상태를 저장합니다.

더 이상 사용되지 않는 별칭

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

// 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