Server adapters

服务端适配器让你使用自己的 HTTP 服务器运行 Mastra，而不是使用 mastra build 生成的 Hono 服务器。它们让你对服务端设置有更多控制，包括自定义中间件顺序、认证、日志和部署配置。你仍然可以将 Mastra 集成到任意 Node.js 应用中，而无需改变 agent 或工作流的执行方式。

注意

服务端适配器使用你传入的 mastra 实例，不会执行基于文件的发现。请在该实例上通过代码注册 agents。如需使用基于文件的 agents，请通过 mastra dev 或 mastra build 将 Mastra 作为独立服务器运行。

何时使用服务端适配器

• 你希望将 Mastra 的端点自动添加到现有应用中
• 你需要直接访问服务器实例以进行自定义配置
• 你的团队更愿意使用其他服务器框架，而不是 mastra build 创建的 Hono 服务器。

提示

如果部署没有自定义服务器需求，请改用 mastra build。它会配置服务端设置并注册中间件，还会根据项目配置应用部署设置。参见 服务器配置。

如果你想在服务端适配器中使用 Studio，请使用 mastra studio 仅启动 Studio UI。

可用的适配器

Mastra 目前提供以下官方服务端适配器：

• @mastra/elysia
• @mastra/express
• @mastra/hono
• @mastra/fastify
• @mastra/koa
• @mastra/nestjs
• @mastra/next
• @mastra/tanstack-start

你也可以构建自己的适配器，详情请阅读自定义适配器。

安装

安装你所选框架对应的适配器。

Elysia

npm

npm install @mastra/elysia@latest elysia

pnpm

pnpm add @mastra/elysia@latest elysia

Yarn

yarn add @mastra/elysia@latest elysia

Bun

bun add @mastra/elysia@latest elysia

Express

npm

npm install @mastra/express@latest

pnpm

pnpm add @mastra/express@latest

Yarn

yarn add @mastra/express@latest

Bun

bun add @mastra/express@latest

Hono

npm

npm install @mastra/hono@latest

pnpm

pnpm add @mastra/hono@latest

Yarn

yarn add @mastra/hono@latest

Bun

bun add @mastra/hono@latest

Fastify

npm

npm install @mastra/fastify@latest

pnpm

pnpm add @mastra/fastify@latest

Yarn

yarn add @mastra/fastify@latest

Bun

bun add @mastra/fastify@latest

Koa

npm

npm install @mastra/koa@latest

pnpm

pnpm add @mastra/koa@latest

Yarn

yarn add @mastra/koa@latest

Bun

bun add @mastra/koa@latest

NestJS

npm

npm install @mastra/nestjs@latest

pnpm

pnpm add @mastra/nestjs@latest

Yarn

yarn add @mastra/nestjs@latest

Bun

bun add @mastra/nestjs@latest

Next.js

npm

npm install @mastra/next@latest hono

pnpm

pnpm add @mastra/next@latest hono

Yarn

yarn add @mastra/next@latest hono

Bun

bun add @mastra/next@latest hono

TanStack Start

npm

npm install @mastra/tanstack-start@latest hono

pnpm

pnpm add @mastra/tanstack-start@latest hono

Yarn

yarn add @mastra/tanstack-start@latest hono

Bun

bun add @mastra/tanstack-start@latest hono

配置

像往常一样初始化你的应用，然后传入 app 和来自 src/mastra/index.ts 的主 mastra 实例来创建 MastraServer。调用 init() 会自动注册 Mastra 中间件和所有可用端点。你可以在 init() 之前或之后继续添加自己的路由。它们会与 Mastra 的端点一起运行。

Elysia

src/elysia-server.ts

import { Elysia } from 'elysia'
import { MastraServer } from '@mastra/elysia'
import { mastra } from './mastra'

const app = new Elysia()
const server = new MastraServer({ app, mastra })

await server.init()

app.listen(4111)

console.log('Server running on http://localhost:4111')

note

完整配置选项请参阅 Elysia Adapter 文档。

Express

src/express-server.ts

import express from 'express'
import { MastraServer } from '@mastra/express'
import { mastra } from './mastra'

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

const server = new MastraServer({ app, mastra })

await server.init()

app.listen(4111, () => {
  console.log('Server running on port 4111')
})

完整配置选项请参阅 Express Adapter 文档。

Hono

src/hono-server.ts

import { Hono } from 'hono'
import { serve } from '@hono/node-server'
import { HonoBindings, HonoVariables, MastraServer } from '@mastra/hono'
import { mastra } from './mastra'

const app = new Hono<{ Bindings: HonoBindings; Variables: HonoVariables }>()

const server = new MastraServer({ app, mastra })

await server.init()

serve({ fetch: app.fetch, port: 4111 }, () => {
  console.log('Server running on port 4111')
})

完整配置选项请参阅 Hono Adapter 文档。

Fastify

src/fastify-server.ts

import Fastify from 'fastify'
import { MastraServer } from '@mastra/fastify'
import { mastra } from './mastra'

const app = Fastify()
const server = new MastraServer({ app, mastra })

await server.init()

app.get('/health', async request => {
  const mastraInstance = request.mastra
  const agents = Object.keys(mastraInstance.listAgents())
  return { status: 'ok', agents }
})

const port = 4111

app.listen({ port }, () => {
  console.log(`Server running on http://localhost:${port}`)
  console.log(`Try: curl http://localhost:${port}/api/agents`)
})

完整配置选项请参阅 Fastify Adapter 文档。

Koa

src/koa-server.ts

import Koa from 'koa'
import bodyParser from 'koa-bodyparser'
import { MastraServer } from '@mastra/koa'
import { mastra } from './mastra'

const app = new Koa()
app.use(bodyParser()) // Required for body parsing

const server = new MastraServer({ app, mastra })

await server.init()

app.use(async (ctx, next) => {
  if (ctx.path === '/health' && ctx.method === 'GET') {
    const mastraInstance = ctx.state.mastra
    const agents = Object.keys(mastraInstance.listAgents())
    ctx.body = { status: 'ok', agents }
    return
  }
  await next()
})

const port = 4111

app.listen(port, () => {
  console.log(`Server running on http://localhost:${port}`)
  console.log(`Try: curl http://localhost:${port}/api/agents`)
})

完整配置选项请参阅 Koa Adapter 文档。

NestJS

src/app.module.ts

import { Module } from '@nestjs/common'
import { MastraModule } from '@mastra/nestjs'
import { mastra } from './mastra'

@Module({
  imports: [
    MastraModule.register({
      mastra,
    }),
  ],
})
export class AppModule {}

src/main.ts

import { NestFactory } from '@nestjs/core'
import { AppModule } from './app.module'

async function bootstrap() {
  const app = await NestFactory.create(AppModule)
  await app.listen(3000)
}

bootstrap()

完整配置选项请参阅 NestJS Adapter 文档。

初始化流程

调用 init() 会按顺序执行四个步骤。了解该流程有助于你在特定位置插入自己的中间件。

1. registerContextMiddleware()：为每个请求附加 Mastra 实例、请求上下文、工具和中止信号。这使后续所有中间件和路由处理器都可以访问 Mastra。
2. registerAuthMiddleware()：在初始化期间运行适配器的认证钩子。官方适配器会在 Mastra 注册内置路由和 registerApiRoute() 路由时内联执行认证，因此原始框架路由在需要 Mastra 认证时，应使用适配器导出的 createAuthMiddleware() 辅助函数。
3. registerUserMiddleware()：注册来自 server.middleware 配置和 mastra.setServerMiddleware() 的中间件。中间件处理器使用 Hono 签名，因此基于 Hono 的适配器（@mastra/hono 以及基于它构建的适配器）会挂载它们；其他适配器会记录警告，而不是静默忽略该配置。
4. registerRoutes()：为 agents、workflows 和其他功能注册所有 Mastra API 路由。如果配置了 MCP 服务器，还会注册 MCP 路由。

手动初始化

如需自定义中间件顺序，请分别调用各个方法，而不是调用 init()。当你需要在 Mastra 上下文建立之前运行中间件，或需要在初始化步骤之间插入逻辑时，这很有用。

server.ts

const server = new MastraServer({ app, mastra });

// Your middleware first
app.use(loggingMiddleware);

server.registerContextMiddleware();

// Middleware that needs Mastra context
app.use(customMiddleware);

// Registers `server.middleware` and `setServerMiddleware()` middleware
server.registerUserMiddleware();

await server.registerRoutes();

// Routes after Mastra
app.get('/health', ...);

提示

当你需要在 Mastra 上下文可用之前运行中间件，或需要在上下文与认证步骤之间插入中间件时，请使用手动初始化。

启动后台工作进程

init() 只注册中间件和路由，不会启动 Mastra 的后台工作进程。mastra build 生成的服务器会为你启动它们，但使用服务端适配器时，你需要自行调用 mastra.startWorkers()。

如果不调用它，以下功能将永远不会运行：

• 定时工作流：不会创建调度记录，cron 触发器也不会触发。
• 通过 mastra.schedules 创建的 Agent 调度
• 你在 Mastra 实例上注册的事件监听器

在服务器开始监听后调用一次 startWorkers()：

server.ts

import express from 'express'
import { MastraServer } from '@mastra/express'
import { mastra } from './mastra'

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

const server = new MastraServer({ app, mastra })
await server.init()

const httpServer = app.listen(4111, async () => {
  try {
    await mastra.startWorkers()
  } catch (error) {
    console.error('Failed to start background workers', error)
    httpServer.close(() => process.exit(1))
  }
})

process.on('SIGTERM', async () => {
  await mastra.shutdown()
  process.exit(0)
})

startWorkers() 是幂等的，因此第二次调用不会产生效果。mastra.shutdown() 会停止工作进程，并在拆除工作进程和 pub/sub 订阅之前，将正在运行的工作流运行排空到已完成或已挂起状态。排空受 drainTimeout（默认 5 秒）限制，未能在期限内结束的运行会被放弃并记录警告。

如果你在独立进程中运行工作进程，请跳过 API 进程中的 startWorkers()，改为在工作进程中启动它们。

添加自定义路由

你可以在 Mastra 路由之外，向应用添加自己的路由。

• 在 init() 之前添加的路由无法使用 Mastra 上下文。
• 在 init() 之后添加的路由可以访问 Mastra 上下文（Mastra 实例、请求上下文、已认证用户等）。
• 当你需要 Mastra 管理的认证和路由元数据（如 requiresAuth）时，优先使用 registerApiRoute()。
• 当你直接将路由挂载到框架应用上时，如果这些路由需要 Mastra 认证，请使用适配器导出的 createAuthMiddleware() 辅助函数。

有关更多信息，请参阅 Elysia、Express 和 Hono 的“添加自定义路由”部分。

路由前缀

默认情况下，Mastra 路由注册在 /api/agents、/api/workflows 等路径下。使用 prefix 选项可以更改。这适用于 API 版本管理，或与已有自己的 /api 路由的应用集成。

const server = new MastraServer({
  app,
  mastra,
  prefix: '/api/v2',
})

使用该前缀后，Mastra 路由变为 /api/v2/agents、/api/v2/workflows 等。直接添加到应用的自定义路由不受该前缀影响。

OpenAPI 规范

Mastra 可以为所有已注册路由生成 OpenAPI 规范。这适用于文档编写或客户端生成，包括与 API 工具集成。通过设置 openapiPath 选项启用：

const server = new MastraServer({
  app,
  mastra,
  openapiPath: '/openapi.json',
})

该规范根据每个路由上定义的 Zod schema 生成，并在指定路径提供。它包含所有 Mastra 路由以及通过 createRoute() 创建的自定义路由。

流数据脱敏

通过 HTTP 流式传输 agent 响应时，HTTP 流式层会在将流数据块发送给客户端之前，对其中的敏感信息进行脱敏。这可防止意外暴露：

• 系统提示词和 agent 指令
• 工具定义及其参数
• 请求体中的 API 密钥和其他凭据
• 内部配置数据

脱敏发生在 HTTP 边界，因此像 onStepFinish 这样的内部回调仍可访问完整请求数据，用于调试和可观测性目的。

默认情况下，脱敏是启用的。通过 streamOptions 配置此行为。仅当内部服务或调试场景需要在流式响应中访问完整请求数据时，才设置 redact: false。

const server = new MastraServer({
  app,
  mastra,
  streamOptions: {
    redact: true, // Default
  },
})

完整配置选项请参阅 MastraServer。

按路由覆盖认证

当你的 Mastra 实例配置了认证时，所有路由默认都需要认证。有时你需要例外：公开的健康检查端点或 webhook 接收器，或者需要更严格管控的管理路由。

使用 customRouteAuthConfig 为特定路由覆盖认证行为。键的格式为 METHOD:PATH，其中 method 为 GET、POST、PUT、DELETE 或 ALL。路径支持通配符（*）以匹配多个路由。将值设为 false 会使路由公开，而 true 要求认证。

const server = new MastraServer({
  app,
  mastra,
  customRouteAuthConfig: new Map([
    // Public health check
    ['GET:/api/health', false],
    // Public API spec
    ['GET:/api/openapi.json', false],
    // Public webhook endpoints
    ['POST:/api/webhooks/*', false],
    // Require auth even if globally disabled
    ['POST:/api/admin/reset', true],
    // Protect all methods on internal routes
    ['ALL:/api/internal/*', true],
  ]),
})

完整配置选项请参阅 MastraServer。

访问应用

创建适配器后，你可能仍需要访问底层框架应用。这在将其传递给平台的 serve 函数，或从其他模块添加路由时很有用。

// Via the MastraServer instance
const app = server.getApp()

// Via the Mastra instance (available after adapter construction)
const app = mastra.getServerApp()

两种方法返回同一个应用实例。根据作用域中的可用对象，选择更方便的一种。

服务端配置与适配器选项

使用服务端适配器时，配置来自两个地方：Mastra server 配置（传给 Mastra 构造函数）和适配器构造函数选项。了解哪些选项来自哪里，有助于在设置似乎未生效时避免困惑。

适配器使用的配置

适配器从 mastra.getServer() 读取以下设置：

选项	描述
auth	认证配置，由 registerAuthMiddleware() 使用。
bodySizeLimit	默认请求体大小限制（字节）。可通过 bodyLimitOptions 按适配器覆盖。
onError	路由处理器中发生未处理错误时调用的自定义错误处理器。参见 server.onError。
middleware	用户中间件，由 registerUserMiddleware() 注册。基于 Hono 的适配器会运行它；Express、Fastify 和 Koa 会记录警告，因为 Hono 处理器无法在其中运行。

仅适配器构造函数

以下选项直接传递给适配器构造函数，不从 Mastra 配置中读取：

选项	描述
prefix	路由路径前缀
openapiPath	OpenAPI 规范端点
bodyLimitOptions	带自定义错误处理器的请求体大小限制
streamOptions	流脱敏设置
customRouteAuthConfig	按路由的认证覆盖
mcpOptions	MCP 传输选项（例如用 setRequestAuth 控制 context.mcp.extra.authInfo）

适配器不使用的配置

以下 server 配置选项仅由 mastra build 使用，在直接使用适配器时不会生效：

选项	使用方
port、host	mastra dev、mastra build
cors	mastra build 会添加 CORS 中间件
timeout	mastra build
apiRoutes	供 mastra build 使用的 registerApiRoute()

使用适配器时，请直接通过你的框架配置这些功能。例如，使用 Hono 或 Express 的内置 CORS 包添加 CORS 中间件，并在调用框架的 listen 函数时设置端口。

MCP 支持

当 Mastra 实例中配置了 MCP 服务器时，服务端适配器会在 registerRoutes() 期间注册 MCP（Model Context Protocol）路由。MCP 允许外部工具和服务连接到你的 Mastra 服务器，并与你的 agents 交互。

每个服务器通过 Streamable HTTP 暴露在 /api/mcp/:serverId/mcp。默认情况下，传输层会在请求之间保留会话状态。对于 Cloudflare Workers 或 Vercel Edge 等无服务器环境，请设置 mcpOptions: { serverless: true } 以在无状态模式下运行，不进行会话管理。

传入 mcpOptions 可控制已认证主体如何到达工具。使用 Mastra deployer（标准 mastra dev / mastra build 路径）时，请在服务端配置中设置：

const mastra = new Mastra({
  server: {
    mcpOptions: {
      setRequestAuth: (req, requestContext) => {
        req.auth = requestContext.get('mcpAuth')
      },
    },
  },
})

手动创建服务端适配器时，直接传入 mcpOptions：

const server = new MastraServer({
  app,
  mastra,
  mcpOptions: {
    setRequestAuth: (req, requestContext) => {
      req.auth = requestContext.get('mcpAuth')
    },
  },
})

配置详情以及如何设置 MCP 服务器，请参阅 MCP。

相关内容

• Elysia Adapter：Elysia 特定设置
• Hono Adapter：Hono 特定设置
• Express Adapter：Express 特定设置
• NestJS Adapter：NestJS 特定设置
• Next.js Adapter：Next.js 特定设置
• TanStack Start Adapter：TanStack Start 特定设置
• Custom Adapters：为其他框架构建适配器
• Workers：运行调度器和其他后台工作进程
• Server Configuration：改用 mastra build
• Authentication：为服务器配置认证
• MastraServer Reference：完整 API 参考
• createRoute() Reference：创建类型安全的自定义路由