📚 编程进阶教程站

第 18 章 · 独立部署与服务端 ​

本章目标：掌握 Mastra 的三种部署形态——开发服务器、Node 独立部署与 Serverless，理解各自的存储与状态注意事项。

18.1 三种运行形态 ​

形态命令/方式适用
开发mastra dev本地开发，自带 Studio（默认 :4111）
Node 独立服务node dist/index.mjs自管服务器/Docker，功能最全
ServerlessVercel/Vercel-like 平台弹性伸缩，需注意有状态能力

18.2 开发服务器 ​

bash
npm run dev        # 内部执行 mastra dev
# 打开 http://localhost:4111 进入 Mastra Studio：
# 可视化调试 agents / workflows / traces / evals

18.3 Node 独立部署（Docker） ​

dockerfile
# Dockerfile
FROM node:22-slim AS build
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build        # 产出 dist/

FROM node:22-slim
WORKDIR /app
COPY --from=build /app ./
EXPOSE 4111
CMD ["node", "dist/index.mjs"]
typescript
// src/index.ts —— 生产入口
import { mastra } from './mastra'

// mastra 实例自带 HTTP 服务能力；生产务必外置存储
export default mastra

关键点：容器里不要用 file: 本地数据库——多副本会各写各的。改用 Postgres 或 Turso：

typescript
storage: new PgStore({ connectionString: process.env.DATABASE_URL })

18.4 Serverless 注意事项 ​

Serverless 函数无本地盘、可能随时冻结重启，因此：

  1. 存储必须外置——LibSQL 云端（Turso）或 Postgres；
  2. suspend/resume 依赖快照——第 13 章的持久化配置在此场景是刚需；
  3. 后台代理受限——Observational Memory 的后台任务在短生命周期函数中不可靠；
  4. 冷启动——按需懒加载 agent，避免初始化时拉全量模型目录。

18.5 生产入口与环境校验 ​

启动前先 fail-fast 校验配置，避免带病上线：

typescript
// src/env.ts —— 缺失关键变量时直接拒绝启动
const required = ['LIBSQL_URL', 'LIBSQL_AUTH_TOKEN', 'OPENAI_API_KEY'] as const
for (const key of required) {
  if (!process.env[key]) {
    console.error(`缺少环境变量: ${key}`)
    process.exit(1)
  }
}
export const env = { LIBSQL_URL: process.env.LIBSQL_URL! }
typescript
// src/server.ts —— 显式指定监听端口与主机
import { createServer } from 'node:http'
import { mastra } from './mastra'
import './env'

const port = Number(process.env.PORT ?? 4111)
createServer(mastra.getServerHandler?.() ?? undefined)
console.log(`Mastra 服务已启动: http://0.0.0.0:${port}`)

18.6 部署验证清单 ​

18.5 部署验证清单 ​

bash
# 冒烟测试：健康检查 + 一次真实调用
curl -s https://your-host/healthz
curl -s -X POST https://your-host/api/agents/support/generate \
  -H 'Content-Type: application/json' \
  -d '{"messages":[{"role":"user","content":"你好"}]}'

确认：环境变量齐全、存储连通、追踪导出正常、Studio 已关闭或加了访问控制。

本章小结 ​

  • mastra dev 附带 Studio 是日常调试主力；
  • Node/Docker 形态功能最全，但必须外置存储避免多副本数据割裂；
  • Serverless 下 suspend/resume 与 OM 后台任务要特别设计；
  • 上线前跑一遍冒烟清单：env → 存储 → 追踪 → Studio 安全。

🧪 随堂测验

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

1. mastra dev 启动的 Studio 默认监听哪个端口？

2. Docker 多副本部署时使用 file: 本地数据库的最大问题是？

3. Serverless 环境下 workflow 的 suspend/resume 为什么仍能工作？

4. 以下哪项不属于上线前冒烟检查项？

🛠️ 动手实践 ​

  1. 用 Docker 把课程项目打包并在本机运行，从宿主机 curl 调用成功。
  2. 把 storage 从 file: 切换到 Turso 云实例，验证两个容器副本共享同一条对话记忆。
  3. 在 Vercel 部署一个最小 Agent 路由，故意使用 file: 存储观察报错，再修复。