Cloudflare 儲存

Mastra 提供兩種 Cloudflare 儲存實作：

• Cloudflare KV（CloudflareKVStorage）：全域分散式、最終一致的 key-value store
• Cloudflare Durable Objects（CloudflareDOStorage）：使用 Durable Objects、具強一致性並以 SQLite 為基礎的儲存實作

不支援 Observability

Cloudflare storage 不支援 observability domain。MastraStorageExporter 的 Trace 無法保存，而當 Cloudflare 是唯一 storage provider 時，Studio 的 observability 功能亦無法運作。如要啟用 observability，請使用 composite storage，將 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 key-value store 方案。

用法

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 instance 的唯一識別碼。

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 為基礎的儲存。這非常適合要求 transaction 一致性及 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 instance

tablePrefix?:

string

資料表名稱的選用 prefix（只允許英文字母、數字及底線）

disableInit?:

boolean

設為 true 時會停用自動建立資料表及 migration。適用於另行執行 migration 的 CI/CD pipeline。

強一致性

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

SQL 能力

Durable Objects storage 的底層使用 SQLite，能夠高效地執行 key-value storage 無法做到的查詢、篩選及分頁。

Schema 管理

兩種儲存實作都會自動處理 schema 的建立及更新，並建立以下資料表：

• threads：儲存對話 thread
• messages：儲存個別訊息
• workflow_snapshot：儲存 Workflow 運行狀態

已棄用的 alias

為保持向後相容，以下 alias 仍可使用：

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