Skip to main content

Cloudflare 存储

🌐 Cloudflare Storage

Cloudflare KV 存储实现提供了一个全局分布、无服务器的键值存储解决方案，使用 Cloudflare Workers KV。

🌐 The Cloudflare KV storage implementation provides a globally distributed, serverless key-value store solution using Cloudflare Workers KV.

Observability Not Supported

Cloudflare KV storage does not support the observability domain. Traces from the DefaultExporter cannot be persisted to KV, and Mastra Studio's observability features won't work with Cloudflare KV as your only storage provider. To enable observability, use composite storage to route observability data to a supported provider like ClickHouse or PostgreSQL.

安装
Direct link to 安装

🌐 Installation

npm install @mastra/cloudflare@latest

用法
Direct link to 用法

🌐 Usage

import { CloudflareStore } from "@mastra/cloudflare";

// --- Example 1: Using Workers Binding ---
const storageWorkers = new CloudflareStore({
  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 CloudflareStore({
  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
});

参数
Direct link to 参数

🌐 Parameters

id:

string
Unique identifier for this storage instance.

bindings?:

Record<string, KVNamespace>
Cloudflare Workers KV bindings (for Workers runtime)

accountId?:

string
Cloudflare Account ID (for REST API)

apiToken?:

string
Cloudflare API Token (for REST API)

namespacePrefix?:

string
Optional prefix for all namespace names (useful for environment isolation)

keyPrefix?:

string
Optional prefix for all keys (useful for environment isolation)

附加说明
Direct link to 附加说明

🌐 Additional Notes

模式管理
Direct link to 模式管理

🌐 Schema Management

存储实现会自动处理模式的创建和更新。它会创建以下表格：

🌐 The storage implementation handles schema creation and updates automatically. It creates the following tables:

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

一致性与传播
Direct link to 一致性与传播

🌐 Consistency & Propagation

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

🌐 Cloudflare KV is an eventually consistent store, meaning that data may not be immediately available across all regions after a write.

键结构与命名空间
Direct link to 键结构与命名空间

🌐 Key Structure & Namespacing

Cloudflare KV 中的键结构为可配置前缀和表特定格式的组合（例如，threads:threadId）。 对于 Workers 部署，使用 keyPrefix 来在命名空间内隔离数据；对于 REST API 部署，使用 namespacePrefix 来在环境或应用之间隔离整个命名空间。

🌐 Keys in Cloudflare KV are structured as a combination of a configurable prefix and a table-specific format (e.g., threads:threadId). For Workers deployments, keyPrefix is used to isolate data within a namespace; for REST API deployments, namespacePrefix is used to isolate entire namespaces between environments or applications.

目录