📚 编程进阶教程站

第 13 章 · Storage 存储层 ​

本章目标：理解 Mastra 存储的领域（domain）模型，学会为不同场景选择 LibSQL/Postgres 等适配器并持久化 workflow 状态。

13.1 存储是什么 ​

Storage 是 Mastra 运行时的持久化层。进程重启后依然可用的数据都由它保管：

  • Memory：消息历史、threads、resources、working memory；
  • Workflows：suspend/resume 所需的持久化快照；
  • Observability：traces、spans、metrics、logs、feedback；
  • Evals：分数、数据集、实验结果；
  • 后台任务与调度：background tasks、schedules、threadState。

默认是内存存储

不配置 storage 时 Mastra 使用 in-memory store——适合测试和短期实验，但进程退出即丢数据。

13.2 领域模型 ​

存储按 domain 组织，每个适配器实现一个或多个领域：

Domain存什么
memory线程、消息、资源、working memory
workflowsworkflow 挂起/恢复的快照
observability追踪、指标、日志
scores / datasets / experiments评估相关数据
backgroundTasks / schedules / threadState后台任务与调度状态

选型原则：memory 这类高频事务读写选 LibSQL/PostgreSQL；分析型查询选列式或专门后端。

13.3 配置 LibSQL（开发与中小生产） ​

typescript
// src/mastra/index.ts
import { Mastra } from '@mastra/core'
import { LibSQLStore } from '@mastra/libsql'

export const mastra = new Mastra({
  storage: new LibSQLStore({
    // 本地文件；生产可换成 libsql:// 远程实例（Turso）
    url: process.env.NODE_ENV === 'production'
      ? process.env.LIBSQL_URL!
      : 'file:./mastra.db',
    authToken: process.env.LIBSQL_AUTH_TOKEN, // 远程实例需要
  }),
  agents: { support: supportAgent },
  workflows: { refundFlow },
})

13.4 配置 Postgres（大规模生产） ​

typescript
// src/mastra/storage.ts
import { MastraStorage } from '@mastra/core/storage'
import { PgStore } from '@mastra/pg'

export const storage: MastraStorage = new PgStore({
  id: 'main-storage',
  connectionString: process.env.DATABASE_URL,
  // 可选：指定 schema 名实现多环境隔离
  schemaName: 'mastra_prod',
})

13.5 测试环境的内存存储 ​

单测不需要落盘——显式声明内存存储，跑完即弃：

typescript
// tests/setup.ts
import { Mastra } from '@mastra/core'
import { InMemoryStore } from '@mastra/core/storage'

export const testMastra = new Mastra({
  // 隔离且零残留，每个测试实例互不干扰
  storage: new InMemoryStore(),
  agents: { support: supportAgent },
})

13.6 Workflow 状态持久化验证 ​

13.5 Workflow 状态持久化验证 ​

typescript
// src/verify-persistence.ts
import { mastra } from './mastra'

// 启动一个含 suspend 的 workflow 后 kill 进程，
// 重启后用相同 runId resume——状态从存储中恢复
const run = await mastra.getWorkflow('refundFlow').createRunAsync()
const result = await run.start({ inputData: { orderId: 'A-1001' } })
console.log(result.status) // 'suspended'（等待审批）
// 进程重启后：
// const resumed = await run.resume({ resumeData: { approved: true } })

本章小结 ​

  • Storage 是 memory/workflows/observability/evals 的统一持久化层；
  • 默认内存存储仅适合测试，生产必须配置持久适配器；
  • LibSQL（本地文件或 Turso）适合开发与中小规模，Postgres 适合大规模；
  • workflow 的 suspend/resume 依赖存储快照，重启后可无缝恢复。

🧪 随堂测验

点击你认为正确的选项。答错时会展示正确答案与原因解析。

1. 不配置 storage 时 Mastra 使用什么存储？

2. 以下哪项不是 Mastra storage 管理的数据？

3. workflow 的 suspend/resume 机制依赖存储层的什么能力？

4. memory domain 的读写特点决定了它适合哪类后端？

🛠️ 动手实践 ​

  1. 分别用默认内存存储和 LibSQLStore 跑同一个含 suspend 的 workflow，重启进程对比 resume 结果。
  2. 注册 Turso 云端 LibSQL 实例，把本地数据迁移上去。
  3. 查看你所用适配器支持哪些 domain，找出缺失的领域并思考替代方案。