Cloudflare 存储

Mastra 提供两种 Cloudflare 存储实现：

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

不支持 Observability

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 提供全球分布式、serverless 键值存储方案。

使用方法

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 查询能力的应用。

使用方法

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 运行状态

已弃用的别名

为实现向后兼容，可使用以下别名：

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