跳至主要內容

Cloudflare 儲存空間

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

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

Cloudflare 儲存空間不支援 observability domain。MastraStorageExporter 的 Trace 無法持久化；若 Cloudflare 是唯一的儲存 Provider，Studio 的可觀測性功能也無法運作。若要啟用可觀測性，請使用複合儲存空間，將可觀測性資料路由至 ClickHouse 等受支援的 Provider。

安裝
「安裝」的直接連結

npm install @mastra/cloudflare@latest

Cloudflare KV 儲存空間
「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
此儲存空間執行個體的唯一識別碼。

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 管理」的直接連結

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

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

一致性與傳播
「一致性與傳播」的直接連結

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

Key 結構與 namespace
「Key 結構與 namespace」的直接連結

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

Cloudflare Durable Objects 儲存空間
「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
資料表名稱的選用 prefix（僅允許字母、數字與底線）

disableInit?:

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

強一致性
「強一致性」的直接連結

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

SQL 功能
「SQL 功能」的直接連結

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

Schema 管理
「Schema 管理」的直接連結

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

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

已棄用的 alias
「已棄用的 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
On this page