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

# 儲存概覽

儲存是 Mastra 執行階段的持久化層。即使程序重新啟動，它仍可保留記憶、Workflow 狀態、可觀測性數據、Eval 結果、排程及長時間運行的 Agent 狀態。

儲存支援以下功能：

- [記憶](https://mastra.zisheng.pro/zh-HK/docs/memory/overview)：訊息記錄、對話串、資源及工作記憶。
- [Workflow](https://mastra.zisheng.pro/zh-HK/docs/workflows/overview)：用於暫停及恢復 Workflow 執行的持久快照。
- [可觀測性](https://mastra.zisheng.pro/zh-HK/docs/observability/overview)：Trace、span、指標、日誌及意見回饋。
- [Evals](https://mastra.zisheng.pro/zh-HK/docs/evals/overview)：評分、數據集、實驗及評估結果。
- [長時間運行的 Agent](https://mastra.zisheng.pro/zh-HK/docs/long-running-agents/durable-agents)：背景任務、排程、目標及對話串狀態。

## 何時設定儲存

當狀態必須在重新啟動後保留，或需要在多個程序之間共享時，請設定持久儲存適配器。持久儲存亦可讓 Studio 在不同工作階段中持續顯示狀態。預設的記憶體內儲存適合測試及短期本機實驗，但程序結束時便會遺失數據。

如應用程式需要以下任何行為，請使用儲存：

- Agent 記得過往訊息或用戶資料。
- Workflow 在重新啟動後暫停及恢復。
- Trace、指標、日誌、評分或意見回饋可繼續用於分析。
- 排程及背景任務在不同部署之間持續運行。
- 多個執行階段程序讀寫相同狀態。

## 儲存的運作方式

Mastra 儲存劃分為多個**領域**。每個領域負責一種執行階段數據，而儲存適配器可實作一個或多個領域。

| 領域                | 儲存的內容                         |
| ----------------- | ----------------------------- |
| `memory`          | 對話串、訊息、資源、工作記憶及其他 Agent 記憶狀態。 |
| `workflows`       | 用於暫停及恢復執行的 Workflow 快照。       |
| `observability`   | Trace、span、指標、日誌及意見回饋。        |
| `scores`          | Eval 評分記錄。                    |
| `datasets`        | Evals 及實驗所使用的數據集記錄與數據集項目。     |
| `experiments`     | 實驗執行及個別項目的實驗結果。               |
| `backgroundTasks` | 背景任務記錄及執行狀態。                  |
| `schedules`       | 排程定義及觸發記錄。                    |
| `threadState`     | 持久保存的任務、目標及對話串狀態。             |

各適配器支援的領域不盡相同。如要查看完整領域清單及內置結構描述，請參閱[儲存概覽參考資料](https://mastra.zisheng.pro/zh-HK/reference/storage/overview)。

## 按數據形態選擇後端

不同領域會寫入及查詢不同類型的數據。請根據領域的存取模式選擇後端：

- `memory`：每次需要使用記憶的 Agent 呼叫都會讀寫資料列。請使用 libSQL、PostgreSQL 或 MongoDB 等交易式數據庫。
- `observability`：寫入大量遙測數據，並經常查詢彙總結果。請使用專用的可觀測性儲存，或 ClickHouse、DuckDB 等線上分析處理（OLAP）後端。
- `workflows`：儲存持久快照，讓執行恢復時仍可使用。請使用可靠的持久數據庫。
- `scores`、`datasets` 及 `experiments`：儲存頻率較低的評估數據，通常稍後才讀取作分析用途。
- `schedules`：儲存排程定義及觸發記錄。請使用已實作 schedules 領域的適配器。

當各領域有不同的運作需求時，請使用[複合儲存](#composite-storage)，將每個領域路由至合適的後端。

## 開始本機開發

進行本機開發時，請使用採用檔案式數據庫的 libSQL。它毋須獨立的數據庫伺服器，並可在重新啟動之間持久保存狀態。

```typescript
import { Mastra } from '@mastra/core'
import { LibSQLStore } from '@mastra/libsql'

export const mastra = new Mastra({
  storage: new LibSQLStore({
    id: 'mastra-storage',
    url: 'file:./mastra.db',
  }),
})
```

> **與 Studio 共用數據庫:** 當 `mastra dev` 與應用程式同時運行時，請使用絕對路徑，讓兩個程序都能存取同一個數據庫：
>
> ```typescript
> url: 'file:/absolute/path/to/your/project/mastra.db'
> ```
>
> `file:./mastra.db` 等相對路徑會按各程序的工作目錄解析，而兩者的工作目錄可能不同。

Mastra 會在首次使用時初始化所需的儲存結構。

## 設定生產環境

在生產環境中，請使用持久的託管數據庫。PostgreSQL 適合作為大多數團隊的預設選擇，因為它能妥善處理交易式執行階段狀態，而且託管服務供應廣泛。

生產環境指引：

- 使用具備備份、監察及連線池功能的託管數據庫。
- 請勿在多程序生產部署中使用 `file:./mastra.db` 等本機檔案數據庫。
- 使用[複合儲存](#composite-storage)，將高流量領域（尤其是 `observability`）路由至專用後端。
- 在儲存適配器或複合儲存上設定[保留](https://mastra.zisheng.pro/zh-HK/reference/storage/retention)政策，然後透過排程器或維護工作呼叫 `storage.prune()`。
- 根據應用程式使用的領域選擇 Provider。例如，排程需要已實作 `schedules` 領域的適配器。

## 設定範圍

儲存可在 Mastra 執行個體層級或 Agent 層級設定。

### 執行個體層級儲存

執行個體層級儲存由註冊於同一 Mastra 執行個體的 Agent、Workflow、可觀測性、Evals、排程及其他執行階段功能共用。

**PostgreSQL**:

```typescript
import { Mastra } from '@mastra/core'
import { PostgresStore } from '@mastra/pg'

export const mastra = new Mastra({
  storage: new PostgresStore({
    id: 'mastra-storage',
    connectionString: process.env.DATABASE_URL,
  }),
})
```

**MongoDB**:

```typescript
import { Mastra } from '@mastra/core'
import { MongoDBStore } from '@mastra/mongodb'

export const mastra = new Mastra({
  storage: new MongoDBStore({
    id: 'mastra-storage',
    uri: process.env.MONGODB_URI,
    dbName: process.env.MONGODB_DB_NAME,
  }),
})
```

當大多數執行階段領域可以共用同一個數據庫時，請使用執行個體層級儲存。

### Agent 層級儲存

Agent 層級儲存在 `Memory` 執行個體上設定。它只會覆寫該 Agent 記憶數據的執行個體層級儲存。

```typescript
import { Agent } from '@mastra/core/agent'
import { Memory } from '@mastra/memory'
import { PostgresStore } from '@mastra/pg'

export const supportAgent = new Agent({
  id: 'support-agent',
  name: 'Support agent',
  instructions: 'Answer customer support questions.',
  model: 'openai/gpt-5.6-sol',
  memory: new Memory({
    storage: new PostgresStore({
      id: 'support-agent-storage',
      connectionString: process.env.SUPPORT_AGENT_DATABASE_URL,
    }),
  }),
})
```

當 Agent 需要獨立的記憶邊界或不同的記憶後端時，請使用 Agent 層級儲存。

## 複合儲存

[`MastraCompositeStore`](https://mastra.zisheng.pro/zh-HK/reference/storage/composite) 會將不同領域路由至不同後端。當單一數據庫並不適合所有領域時，請使用它。

以下範例使用 libSQL 作為預設儲存，並將 Workflow 狀態路由至 PostgreSQL：

```typescript
import { Mastra } from '@mastra/core'
import { MastraCompositeStore } from '@mastra/core/storage'
import { LibSQLStore } from '@mastra/libsql'
import { WorkflowsPG } from '@mastra/pg'

export const mastra = new Mastra({
  storage: new MastraCompositeStore({
    id: 'composite-storage',
    default: new LibSQLStore({
      id: 'default-storage',
      url: 'file:./mastra.db',
    }),
    domains: {
      workflows: new WorkflowsPG({
        connectionString: process.env.DATABASE_URL,
      }),
    },
  }),
})
```

你亦可將 `observability` 路由至專用的分析後端。如要查看可觀測性的專屬範例，請參閱[可觀測性快速入門](https://mastra.zisheng.pro/zh-HK/docs/observability/overview)。

## 支援的 Provider

每個 Provider 頁面均包含安裝指示、設定參數及使用範例：

- [libSQL](https://mastra.zisheng.pro/zh-HK/reference/storage/libsql)
- [PostgreSQL](https://mastra.zisheng.pro/zh-HK/reference/storage/postgresql)
- [MongoDB](https://mastra.zisheng.pro/zh-HK/reference/storage/mongodb)
- [OracleDB](https://mastra.zisheng.pro/zh-HK/reference/storage/oracledb)
- [Upstash](https://mastra.zisheng.pro/zh-HK/reference/storage/upstash)
- [Redis](https://mastra.zisheng.pro/zh-HK/reference/storage/redis)
- [Cloudflare D1](https://mastra.zisheng.pro/zh-HK/reference/storage/cloudflare-d1)
- [Cloudflare KV & Durable Objects](https://mastra.zisheng.pro/zh-HK/reference/storage/cloudflare)
- [Convex](https://mastra.zisheng.pro/zh-HK/reference/storage/convex)
- [DynamoDB](https://mastra.zisheng.pro/zh-HK/reference/storage/dynamodb)
- [LanceDB](https://mastra.zisheng.pro/zh-HK/reference/storage/lance)
- [Microsoft SQL Server](https://mastra.zisheng.pro/zh-HK/reference/storage/mssql)
- [Google Cloud Spanner](https://mastra.zisheng.pro/zh-HK/reference/storage/spanner)

> **提示:** libSQL 是開始本機開發最快捷的方式，因為它毋須運行獨立的數據庫伺服器。

## 下一步

- [複合儲存](https://mastra.zisheng.pro/zh-HK/reference/storage/composite)
- [儲存保留政策](https://mastra.zisheng.pro/zh-HK/reference/storage/retention)
- [儲存結構描述](https://mastra.zisheng.pro/zh-HK/reference/storage/overview)
- [記憶](https://mastra.zisheng.pro/zh-HK/docs/memory/overview)
- [可觀測性儲存](https://mastra.zisheng.pro/zh-HK/docs/observability/overview)