第九章 部署与生产实践

9.1 运行时支持

Mastra 支持多种 JavaScript 运行时：

运行时	最低版本	说明
Node.js	v22.13.0	官方主要支持
Bun	最新版	完全兼容
Deno	最新版	兼容
Cloudflare Workers	—	部分功能受限（无文件系统）

Node.js 22 的要求可能让部分人意外。原因是 Mastra 使用了 Node.js 22 引入的一些原生 API（如更好的 fetch 支持、structuredClone 等）。确保部署环境满足版本要求。

9.2 Mastra Server

mastra build 会将你的 Mastra 应用编译为一个独立的 HTTP 服务器：

构建

npx mastra build

构建产物在 .mastra/ 目录下，输出一个 Hono 框架的 HTTP 服务。

自动生成的 API 端点

端点	方法	说明
/api/agents/:agentId/generate	POST	调用 Agent 生成
/api/agents/:agentId/stream	POST	流式调用 Agent
/api/agents/:agentId/instructions	GET/POST	获取/更新指令
/api/workflows/:workflowId/start	POST	启动 Workflow
/api/workflows/:workflowId/resume	POST	恢复挂起的 Workflow
/api/tools/:toolId/execute	POST	执行 Tool
/api/memory/threads	GET/POST	管理会话线程

启动服务

node .mastra/output/index.mjs
# 默认监听端口 4111

自定义中间件

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

export const mastra = new Mastra({
  agents: { myAgent },
  server: {
    middleware: [
      {
        handler: async (c, next) => {
          // 自定义认证逻辑
          const token = c.req.header('Authorization')
          if (!token || !isValidToken(token)) {
            return c.json({ error: 'Unauthorized' }, 401)
          }
          await next()
        },
      },
    ],
    cors: {
      origin: ['https://myapp.com'],
      methods: ['GET', 'POST'],
    },
  },
})

9.3 不使用 Mastra Server

如果你不想用 Mastra 自带的 Server，可以把 Agent/Workflow 当普通的 TypeScript 对象使用，集成到任何框架中：

Next.js App Router

// app/api/chat/route.ts
import { myAgent } from '@/mastra/agents'

export async function POST(request: Request) {
  const { message, threadId } = await request.json()

  const stream = await myAgent.stream(message, {
    threadId,
    resourceId: 'user-123',
  })

  return stream.toTextStreamResponse()
}

Express

import express from 'express'
import { myAgent } from './mastra/agents'

const app = express()
app.use(express.json())

app.post('/chat', async (req, res) => {
  const { message } = req.body
  const result = await myAgent.generate(message)
  res.json({ reply: result.text })
})

app.listen(3000)

Astro

// src/pages/api/chat.ts
import type { APIRoute } from 'astro'
import { myAgent } from '../../mastra/agents'

export const POST: APIRoute = async ({ request }) => {
  const { message } = await request.json()
  const result = await myAgent.generate(message)
  return new Response(JSON.stringify({ reply: result.text }), {
    headers: { 'Content-Type': 'application/json' },
  })
}

9.4 云平台部署

Vercel

// mastra.config.ts
import { MastraDeployer } from '@mastra/deployer-vercel'

export default {
  deployer: new MastraDeployer({
    // Vercel 特定配置
    scope: 'my-team',
  }),
}

npx mastra deploy

Cloudflare Workers

import { MastraDeployer } from '@mastra/deployer-cloudflare'

export default {
  deployer: new MastraDeployer({
    workerName: 'my-mastra-agent',
  }),
}

Cloudflare 限制：Workers 不支持文件系统操作，某些依赖 fs 的功能（如本地文件的 RAG 处理）不可用。内存也有限制（128MB），大型 RAG 索引需要外部存储。

Netlify

import { MastraDeployer } from '@mastra/deployer-netlify'

export default {
  deployer: new MastraDeployer({
    scope: 'my-team',
  }),
}

npx mastra deploy

Mastra Cloud（Beta）

Mastra 官方提供的托管服务，一键部署，无需管理基础设施：

import { CloudExporter } from '@mastra/observability'

// 在 Mastra 实例中配置 Cloud
const mastra = new Mastra({
  agents: { myAgent },
  observability: new Observability({
    exporter: new CloudExporter({
      apiKey: process.env.MASTRA_CLOUD_API_KEY,
    }),
  }),
})

部署到 Mastra Cloud：

npx mastra deploy --cloud

Mastra Cloud 提供开箱即用的 Studio UI、Traces 监控、Evals 仪表盘和自动扩缩容。目前处于 Beta 阶段，适合快速验证和小规模上线。

Docker 自托管

FROM node:22-slim

WORKDIR /app

# 复制构建产物
COPY .mastra/ .mastra/
COPY package.json package-lock.json ./
RUN npm ci --production

EXPOSE 4111

CMD ["node", ".mastra/output/index.mjs"]

docker build -t my-mastra-app .
docker run -p 4111:4111 \
  -e OPENAI_API_KEY=your-key \
  my-mastra-app

9.5 Workflow Runner：Inngest

长时间运行的 Workflow（包含 suspend/resume 的）需要外部 Runner：

import { Mastra } from '@mastra/core'
import { InngestWorkflowRunner } from '@mastra/inngest'

const mastra = new Mastra({
  agents: { myAgent },
  workflows: { approvalWorkflow },
  workflowRunner: new InngestWorkflowRunner({
    inngestId: 'my-app',
    url: process.env.INNGEST_URL,
  }),
})

Inngest 是一个事件驱动的后台任务框架，特别适合处理 Mastra Workflow 中的 suspend/resume。它自动处理重试、超时、并发控制等。

9.6 环境配置最佳实践

环境变量管理

# .env（开发环境）
OPENAI_API_KEY=sk-xxx
DATABASE_URL=postgresql://localhost:5432/mastra
MASTRA_LOG_LEVEL=debug

# .env.production（生产环境）
OPENAI_API_KEY=sk-xxx-prod
DATABASE_URL=postgresql://prod-host:5432/mastra
MASTRA_LOG_LEVEL=warn

模型降级策略

import { Agent } from '@mastra/core/agent'

// 生产环境用更稳定的模型配置
const model = process.env.NODE_ENV === 'production'
  ? 'openai/gpt-4.1'       // 生产用旗舰模型
  : 'openai/gpt-4.1-mini'  // 开发用小模型省钱

export const myAgent = new Agent({
  id: 'my-agent',
  name: 'My Agent',
  instructions: '你是一个助手。',
  model,
})

9.7 生产清单

在上线之前，对照这个清单检查：

安全

• [ ] API 密钥通过环境变量管理，不在代码中硬编码
• [ ] Mastra Server 开启了身份验证中间件
• [ ] CORS 配置了具体域名，非 *
• [ ] 敏感数据过滤（Observability 的 SensitiveDataFilter）已开启
• [ ] Agent Instructions 做了 Prompt 注入防护

可靠性

• [ ] 数据库连接配置了连接池
• [ ] 外部 API 调用有超时和重试机制
• [ ] Workflow 长任务使用了 Inngest 等 Runner
• [ ] 错误处理覆盖了关键路径

可观测性

• [ ] Observability 已配置并输出到监控平台
• [ ] 关键 Agent 绑定了 Live Evals
• [ ] 日志级别设为 warn 或 info
• [ ] 设置了 Token 用量和成本告警

性能

• [ ] 高频 Agent 考虑了流式响应（stream）
• [ ] RAG 向量索引有适当的缓存
• [ ] 静态 MCP 工具列表而非动态加载
• [ ] 选择了合适的模型（不是所有场景都需要旗舰模型）

9.8 成本控制

AI 应用的主要成本来自 LLM 调用。几个实用建议：

1. 分级模型：简单任务用 gpt-4.1-nano，复杂推理用 gpt-4.1
2. 缓存：相同输入的结果可以缓存（特别是 RAG 查询）
3. Prompt 精简：Instructions 越短，每次调用的 Token 开销越小
4. 采样评估：生产环境的 Evals 采样率控制在 5-10%
5. 监控 Token：通过 Observability 监控每个 Agent 的 Token 用量

9.9 本章小结

部署选项
├── Mastra Server
│   ├── mastra build → HTTP 服务
│   ├── 自动生成 API 端点
│   └── 支持中间件、CORS
├── 框架集成
│   ├── Next.js / Express / Astro / 任意框架
│   └── Agent/Workflow 当普通对象使用
├── 云平台
│   ├── Vercel / Netlify（Deployer）
│   ├── Cloudflare Workers（有限制）
│   └── Docker 自托管
└── 生产实践
    ├── 环境变量管理
    ├── 安全清单
    ├── 可观测性
    └── 成本控制

恭喜，你已经完成了 Mastra 框架的系统学习！回到 README 查看完整目录。