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

# Cloudflare 存储

Mastra 提供两种 Cloudflare 存储实现：

- **Cloudflare KV** (`CloudflareKVStorage`)：全球分布式、最终一致的键值存储
- **Cloudflare Durable Objects** (`CloudflareDOStorage`)：使用 Durable Objects 的强一致性、基于 SQLite 的存储

> **不支持 Observability:** Cloudflare 存储**不支持 observability 域**。来自 `MastraStorageExporter` 的 Trace 无法持久化，并且仅将 Cloudflare 作为存储 Provider 时，[Studio](https://mastra.zisheng.pro/docs/studio/overview) 的 observability 功能无法使用。若要启用 observability，请使用[组合存储](https://mastra.zisheng.pro/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 提供全球分布式、serverless 键值存储方案。

### 使用方法

```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`): 此 storage 实例的唯一标识符。

**bindings** (`Record<string, KVNamespace>`): Cloudflare Workers KV bindings（用于 Workers runtime）

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

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

**namespacePrefix** (`string`): 所有 namespace 名称的可选前缀（有助于隔离环境）

**keyPrefix** (`string`): 所有键的可选前缀（有助于隔离环境）

### 补充说明

### Schema 管理

该存储实现会自动处理 schema 创建和更新。它会创建以下表：

- `threads`：存储对话线程
- `messages`：存储单条消息
- `metadata`：存储线程和消息的附加元数据

### 一致性和传播

Cloudflare KV 是最终一致的存储，这意味着写入后数据可能不会立即在所有区域可用。

### 键结构和命名空间

Cloudflare KV 中的键由可配置前缀与表特定格式组合而成（例如 `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`): 表名的可选前缀（仅允许字母、数字和下划线）

**disableInit** (`boolean`): 为 true 时，禁用自动建表/迁移。适用于单独运行迁移的 CI/CD pipeline。

### 强一致性

与 KV 不同，Durable Objects 提供强一致性保证。一个 Durable Object 内的所有读写均会串行化，因此非常适合快速、长时间运行的 Agent。

### SQL 功能

Durable Objects 存储底层使用 SQLite，可实现键值存储无法做到的高效查询、筛选和分页。

## Schema 管理

两种存储实现都会自动处理 schema 创建和更新。它们会创建以下表：

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