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

# Storage 概覽

Storage 是 Mastra 執行環境的持久化層。處理程序重新啟動後，它仍會保留記憶體、Workflow 狀態、可觀測性資料、Eval 結果、排程，以及長時間執行 Agent 的狀態。

Storage 支援：

- [記憶體](https://mastra.zisheng.pro/zh-TW/docs/memory/overview)：訊息歷程、討論串、資源與工作記憶體。
- [Workflow](https://mastra.zisheng.pro/zh-TW/docs/workflows/overview)：用於暫停及繼續 Workflow 執行的耐久快照。
- [可觀測性](https://mastra.zisheng.pro/zh-TW/docs/observability/overview)：Trace、span、指標、記錄與意見回饋。
- [Evals](https://mastra.zisheng.pro/zh-TW/docs/evals/overview)：分數、資料集、實驗與評估結果。
- [長時間執行的 Agent](https://mastra.zisheng.pro/zh-TW/docs/long-running-agents/durable-agents)：背景工作、排程、目標與討論串狀態。

## 何時設定 Storage

當狀態必須在重新啟動後保留，或必須在多個處理程序之間共用時，請設定持久性 Storage 介面卡。持久性 Storage 也能讓 Studio 跨工作階段顯示狀態。預設的記憶體內儲存適合測試與短期本機實驗，但處理程序結束時資料便會遺失。

應用程式需要下列任一行為時，請使用 Storage：

- Agent 記住過去的訊息或使用者資訊。
- Workflow 在重新啟動後暫停並繼續執行。
- Trace、指標、記錄、分數或意見回饋可持續供分析使用。
- 排程與背景工作可跨部署繼續執行。
- 多個執行環境處理程序讀寫相同狀態。

## Storage 的運作方式

Mastra Storage 由數個\*\*領域（domain）\*\*組成。每個領域擁有一種類型的執行階段資料，而 Storage 介面卡會實作一或多個領域。

| 領域                | 儲存內容                            |
| ----------------- | ------------------------------- |
| `memory`          | 討論串、訊息、資源、工作記憶體及其他 Agent 記憶體狀態。 |
| `workflows`       | 用於暫停及繼續執行的 Workflow 快照。         |
| `observability`   | Trace、span、指標、記錄與意見回饋。          |
| `scores`          | Eval 分數記錄。                      |
| `datasets`        | Evals 與實驗所使用的資料集記錄及資料集項目。       |
| `experiments`     | 實驗執行及各項目的實驗結果。                  |
| `backgroundTasks` | 背景工作記錄與執行狀態。                    |
| `schedules`       | 排程定義與觸發歷程。                      |
| `threadState`     | 耐久的工作、目標與討論串狀態。                 |

各介面卡支援的領域不盡相同。如需完整領域清單與內建結構描述，請參閱 [Storage 概覽參考資料](https://mastra.zisheng.pro/zh-TW/reference/storage/overview)。

## 依資料形態選擇後端

不同領域會寫入及查詢不同種類的資料。請依領域的存取模式選擇後端：

- `memory`：每次需要記憶的 Agent 呼叫都會讀寫資料列。請使用 libSQL、PostgreSQL 或 MongoDB 等交易式資料庫。
- `observability`：寫入大量遙測資料，且經常查詢彙總結果。請使用專用的可觀測性儲存區，或 ClickHouse、DuckDB 等線上分析處理（OLAP）後端。
- `workflows`：儲存執行繼續時必須可用的耐久快照。請使用可靠的持久性資料庫。
- `scores`、`datasets` 與 `experiments`：儲存頻率較低、通常稍後才會讀取以供分析的評估資料。
- `schedules`：儲存排程定義與觸發歷程。請使用已實作 schedules 領域的介面卡。

當各領域的營運需求不同時，請使用[複合 Storage](#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 會在首次使用時初始化所需的 Storage 結構。

## 正式環境設定

正式環境請使用持久性的受管理資料庫。PostgreSQL 很適合作為大多數團隊的預設選擇，因為它能妥善處理交易式執行階段狀態，而且普遍可由受管理服務提供。

正式環境指引：

- 使用具備備份、監控與連線集區的受管理資料庫。
- 請勿在多處理程序正式環境部署中使用 `file:./mastra.db` 等本機檔案資料庫。
- 使用[複合 Storage](#composite-storage)，將高流量領域（尤其是 `observability`）路由至專用後端。
- 在 Storage 介面卡或複合儲存區設定[保留](https://mastra.zisheng.pro/zh-TW/reference/storage/retention)政策，再透過排程器或維護工作呼叫 `storage.prune()`。
- 根據應用程式使用的領域選擇 Provider。例如，排程需要已實作 `schedules` 領域的介面卡。

## 設定範圍

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

### 執行個體層級 Storage

執行個體層級 Storage 由註冊至同一個 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,
  }),
})
```

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

### Agent 層級 Storage

Agent 層級 Storage 是在 `Memory` 執行個體上設定。它只會覆寫該 Agent 記憶體資料所使用的執行個體層級 Storage。

```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 層級 Storage。

## 複合 Storage

[`MastraCompositeStore`](https://mastra.zisheng.pro/zh-TW/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-TW/docs/observability/overview)。

## 支援的 Provider

每個 Provider 頁面都包含安裝說明、設定參數與使用範例：

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

> **提示:** libSQL 是本機開發的最快途徑，因為不需要執行獨立的資料庫伺服器。

## 後續步驟

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