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

# Cloudflare 儲存空間

Mastra 提供兩種 Cloudflare 儲存空間實作：

- **Cloudflare KV**（`CloudflareKVStorage`）：全域分散式、最終一致的 key-value store
- **Cloudflare Durable Objects**（`CloudflareDOStorage`）：使用 Durable Objects、以 SQLite 為基礎的強一致性儲存空間

> **不支援可觀測性:** Cloudflare 儲存空間**不支援 observability domain**。`MastraStorageExporter` 的 Trace 無法持久化；若 Cloudflare 是唯一的儲存 Provider，[Studio](https://mastra.zisheng.pro/zh-TW/docs/studio/overview) 的可觀測性功能也無法運作。若要啟用可觀測性，請使用[複合儲存空間](https://mastra.zisheng.pro/zh-TW/reference/storage/composite)，將可觀測性資料路由至 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，提供全域分散式的 serverless key-value store 解決方案。

### 使用方式

```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 binding（用於 Workers runtime）

**accountId** (`string`): Cloudflare Account ID（用於 REST API）

**apiToken** (`string`): Cloudflare API Token（用於 REST API）

**namespacePrefix** (`string`): 所有 namespace 名稱的選用 prefix（適合用於隔離環境）

**keyPrefix** (`string`): 所有 key 的選用 prefix（適合用於隔離環境）

### 其他注意事項

### Schema 管理

儲存空間實作會自動處理 schema 的建立與更新，並建立下列資料表：

- `threads`：儲存對話 thread
- `messages`：儲存個別訊息
- `metadata`：儲存 thread 與訊息的其他 metadata

### 一致性與傳播

Cloudflare KV 是最終一致的 store，表示寫入資料後，該資料可能不會立即在所有區域中可用。

### Key 結構與 namespace

Cloudflare KV 的 key 結合可設定的 prefix 與資料表專用格式（例如 `threads:threadId`）。 對於 Workers 部署，`keyPrefix` 用於隔離 namespace 內的資料；對於 REST API 部署，`namespacePrefix` 用於隔離不同環境或應用程式的完整 namespace。

## Cloudflare Durable Objects 儲存空間

Durable Objects 儲存空間實作採用 Cloudflare Durable Objects，提供以 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`): 資料表名稱的選用 prefix（僅允許字母、數字與底線）

**disableInit** (`boolean`): 設為 true 時，將停用自動建立資料表與 migration。適合在另行執行 migration 的 CI/CD pipeline 中使用。

### 強一致性

與 KV 不同，Durable Objects 提供強一致性保證。Durable Object 內的所有讀寫操作都會序列化，因此非常適合快速且長時間執行的 Agent。

### SQL 功能

Durable Objects 儲存空間底層採用 SQLite，因此能進行 key-value 儲存空間無法提供的高效查詢、篩選與分頁。

## Schema 管理

這兩種儲存空間實作都會自動處理 schema 的建立與更新，並建立下列資料表：

- `threads`：儲存對話 thread
- `messages`：儲存個別訊息
- `workflow_snapshot`：儲存 Workflow 執行狀態

## 已棄用的 alias

為維持向後相容性，可使用下列 alias：

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