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

# Storage 概述

Storage 是 Mastra 运行时的持久化层。进程重启后，它仍会保留 Memory、Workflow 状态、Observability 数据、Eval 结果、Schedule 和长时间运行的 Agent 状态。

Storage 为以下功能提供支持：

- [Memory](https://mastra.zisheng.pro/docs/memory/overview)：消息历史记录、thread、资源和 working memory。
- [Workflow](https://mastra.zisheng.pro/docs/workflows/overview)：用于暂停和恢复 Workflow 运行的持久快照。
- [Observability](https://mastra.zisheng.pro/docs/observability/overview)：Trace、span、指标、日志和反馈。
- [Evals](https://mastra.zisheng.pro/docs/evals/overview)：评分、数据集、实验和评估结果。
- [长时间运行的 Agent](https://mastra.zisheng.pro/docs/long-running-agents/durable-agents)：后台任务、Schedule、目标和 thread 状态。

## 何时配置 Storage

当状态必须在重启后继续存在或需要跨进程共享时，请配置持久化 Storage adapter。持久化 Storage 还能让 Studio 在不同会话间持续显示状态。默认的内存存储适用于测试和短期本地实验，但进程退出时会丢失数据。

如果应用需要以下任一行为，请使用 Storage：

- Agent 记住过去的消息或用户信息。
- Workflow 在重启后暂停并恢复。
- Trace、指标、日志、评分或反馈可供后续分析。
- Schedule 和后台任务在部署之间持续运行。
- 多个运行时进程读写同一状态。

## Storage 的工作原理

Mastra Storage 按**域**组织。每个域负责一种运行时数据，Storage adapter 会实现一个或多个域。

| 域                 | 存储内容                                             |
| ----------------- | ------------------------------------------------ |
| `memory`          | Thread、消息、资源、working memory 和其他 Agent Memory 状态。 |
| `workflows`       | 用于暂停和恢复运行的 Workflow 快照。                          |
| `observability`   | Trace、span、指标、日志和反馈。                             |
| `scores`          | Eval 评分记录。                                       |
| `datasets`        | Eval 和实验使用的数据集记录及数据集条目。                          |
| `experiments`     | 实验运行和逐条目实验结果。                                    |
| `backgroundTasks` | 后台任务记录和执行状态。                                     |
| `schedules`       | Schedule 定义和触发历史记录。                              |
| `threadState`     | 持久化的任务、目标和 thread 状态。                            |

不同 adapter 支持的域有所差异。有关完整域列表和内置 schema，请参阅 [Storage 概述 Reference](https://mastra.zisheng.pro/reference/storage/overview)。

## 根据数据形态选择后端

不同域写入和查询的数据类型不同。请根据域的访问模式选择后端：

- `memory`：每次需要记忆的 Agent 调用都会读写数据行。请使用 libSQL、PostgreSQL 或 MongoDB 等事务型数据库。
- `observability`：写入大量遥测数据，并且经常查询聚合结果。请使用专用 Observability 存储，或 ClickHouse、DuckDB 等在线分析处理（OLAP）后端。
- `workflows`：存储运行恢复时必须可用的持久快照。请使用可靠的持久化数据库。
- `scores`、`datasets` 和 `experiments`：存储写入频率较低、通常在之后读取用于分析的评估数据。
- `schedules`：存储 Schedule 定义和触发历史记录。请使用实现了 schedules 域的 adapter。

当各域的运维需求不同时，请使用[组合式 Storage](#composite-storage)，将各域路由到适合的后端。

## 在本地开始使用

本地开发时，使用基于文件的 libSQL 数据库。它不需要单独的数据库 Server，并且可在重启之间保留状态。

```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 adapter 或组合存储上配置[保留策略](https://mastra.zisheng.pro/reference/storage/retention)，然后通过 Scheduler 或维护任务调用 `storage.prune()`。
- 根据应用使用的域选择 Provider。例如，Schedule 需要实现了 `schedules` 域的 adapter。

## 配置范围

Storage 可以在 Mastra 实例级别或 Agent 级别配置。

### 实例级 Storage

实例级 Storage 由注册在同一 Mastra 实例上的 Agent、Workflow、Observability、Evals、Schedule 和其他运行时功能共享。

**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 Memory 数据的实例级 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 需要隔离的 Memory 边界或不同的 Memory 后端时，请使用 Agent 级 Storage。

## 组合式 Storage

[`MastraCompositeStore`](https://mastra.zisheng.pro/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` 路由到专用分析后端。有关针对 Observability 的示例，请参阅 [Observability 快速入门](https://mastra.zisheng.pro/docs/observability/overview)。

## 支持的 Provider

每个 Provider 页面都包含安装说明、配置参数和使用示例：

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

> **提示:** libSQL 是本地开发的最快上手方式，因为它不需要运行单独的数据库 Server。

## 后续步骤

- [组合式 Storage](https://mastra.zisheng.pro/reference/storage/composite)
- [Storage 保留策略](https://mastra.zisheng.pro/reference/storage/retention)
- [Storage schema](https://mastra.zisheng.pro/reference/storage/overview)
- [Memory](https://mastra.zisheng.pro/docs/memory/overview)
- [Observability Storage](https://mastra.zisheng.pro/docs/observability/overview)