伺服器適配器

伺服器適配器讓你使用自己的 HTTP 伺服器執行 Mastra，而非使用由 mastra build 產生的 Hono 伺服器。你可以更全面地控制伺服器設定，包括自訂中介軟件次序、身份驗證、日誌記錄及部署配置。你仍可將 Mastra 整合至任何 Node.js 應用程式，而毋須改變 Agent 或 Workflow 的執行方式。

注意

伺服器適配器會使用你傳入的 mastra 實例，並不會執行以檔案為基礎的探索。請在程式碼中將 Agent 註冊至該實例。如要使用以檔案為基礎的 Agent，請透過 mastra dev 或 mastra build 將 Mastra 作為獨立伺服器執行。

何時使用伺服器適配器

• 你想將 Mastra 的端點自動加入現有應用程式
• 你需要直接存取伺服器實例以進行自訂配置
• 你的團隊偏好使用其他伺服器框架，而非由 mastra build 建立的 Hono 伺服器。

提示

如果部署沒有自訂伺服器需求，請改用 mastra build。它會配置伺服器設定並註冊中介軟件，亦會根據你的項目配置套用部署設定。詳情請參閱伺服器配置。

如要配合伺服器適配器使用 Studio，請使用 mastra studio 只啟動 Studio UI。

可用的適配器

Mastra 目前提供以下官方伺服器適配器：

• @mastra/express
• @mastra/hono
• @mastra/fastify
• @mastra/koa
• @mastra/nestjs

你亦可自行建立適配器，詳情請參閱自訂適配器。

安裝

安裝你所選框架的適配器。

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

配置

如常初始化你的應用程式，然後建立 MastraServer，並傳入 app 及主要 mastra 實例（後者來自 src/mastra/index.ts）。呼叫 init() 會自動註冊 Mastra 中介軟件及所有可用端點。你可以繼續如常加入自己的路由，不論在 init() 之前或之後加入，它們都會與 Mastra 的端點一同運作。

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 適配器文件。

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 適配器文件。

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 適配器文件。

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 適配器文件。

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 適配器文件。

初始化流程

呼叫 init() 會依次執行三個步驟。了解此流程，有助你在特定位置插入自己的中介軟件。

1. registerContextMiddleware()：將 Mastra 實例、請求內容、Tool 及中止訊號附加至每個請求，讓所有後續中介軟件及路由處理程式都可使用 Mastra。
2. registerAuthMiddleware()：在初始化期間執行適配器的身份驗證掛鈎。當 Mastra 註冊內置路由及 registerApiRoute() 路由時，官方適配器會在路由內強制執行身份驗證。因此，原生框架路由如需 Mastra 身份驗證，應使用適配器匯出的 createAuthMiddleware() 輔助函數。
3. registerRoutes()：註冊 Agent、Workflow 及其他功能的所有 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);

await server.registerRoutes();

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

提示

如需在 Mastra 內容可用前執行中介軟件，或在內容與身份驗證步驟之間插入中介軟件，請使用手動初始化。

加入自訂路由

你可以在應用程式中加入自己的路由，與 Mastra 路由並用。

• 在 init() 之前加入的路由無法使用 Mastra 內容。
• 在 init() 之後加入的路由可存取 Mastra 內容（Mastra 實例、請求內容、已驗證身份的用戶等）。
• 如需由 Mastra 管理身份驗證及 requiresAuth 等路由 metadata，建議使用 registerApiRoute()。
• 如果直接在框架應用程式掛載路由，而這些路由需要 Mastra 身份驗證，請使用適配器匯出的 createAuthMiddleware() 輔助函數。

如需更多資訊，請參閱 Express 及 Hono 的「加入自訂路由」：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 Tool 整合。設定 openapiPath 選項即可啟用：

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

此規格會根據每個路由所定義的 Zod schema 產生，並於指定路徑提供。當中包括所有 Mastra 路由，以及使用 createRoute() 建立的任何自訂路由。

串流資料遮蔽

透過 HTTP 串流傳送 Agent 回應時，HTTP 串流層會先遮蔽串流區塊中的敏感資料，然後才傳送至用戶端。這可防止意外洩露以下資料：

• 系統提示及 Agent 指示
• Tool 定義及其參數
• 請求內容中的 API 金鑰及其他憑證
• 內部配置資料

遮蔽處理會在 HTTP 邊界進行，因此 onStepFinish 等內部回呼仍可存取完整請求資料，以供偵錯及可觀測性用途。

遮蔽功能預設啟用。請透過 streamOptions 配置此行為。只有內部服務或偵錯情境需要存取串流回應中的完整請求資料時，才應設定 redact: false。

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

如需完整配置選項，請參閱 MastraServer。

覆寫個別路由的身份驗證設定

在 Mastra 實例配置身份驗證後，所有路由預設都需要身份驗證。有時你需要例外情況，例如公開的健康狀態檢查端點或 webhook 接收器；又或需要更嚴格控制的管理員路由。

使用 customRouteAuthConfig 覆寫特定路由的身份驗證行為。key 採用 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 constructor）及適配器 constructor 選項。了解各選項的來源，有助避免設定看似沒有生效時產生混淆。

適配器會使用的設定

適配器會從 mastra.getServer() 讀取以下設定：

選項	說明
auth	身份驗證配置，由 registerAuthMiddleware() 使用。
bodySizeLimit	預設內容大小上限（以 byte 為單位）。可透過 bodyLimitOptions 針對個別適配器覆寫。
onError	路由處理程式發生未處理錯誤時呼叫的自訂錯誤處理程式。請參閱 server.onError。

僅限適配器 constructor

以下選項會直接傳入適配器 constructor，而不會從 Mastra 配置讀取：

選項	說明
prefix	路由路徑前綴
openapiPath	OpenAPI 規格端點
bodyLimitOptions	附有自訂錯誤處理程式的內容大小上限
streamOptions	串流遮蔽設定
customRouteAuthConfig	個別路由的身份驗證覆寫設定
mcpOptions	MCP 傳輸選項（例如，無狀態環境使用 serverless: true）

適配器不會使用的設定

以下 server 配置選項只供 mastra build 使用，直接使用適配器時不會產生任何作用：

選項	使用者
port, host	mastra dev, mastra build
cors	mastra build 會加入 CORS 中介軟件
timeout	mastra build
apiRoutes	registerApiRoute()，供 mastra build 使用
middleware	mastra build 的中介軟件配置

使用適配器時，請直接透過框架配置這些功能。例如，使用 Hono 或 Express 的內置 CORS 依賴套件加入 CORS 中介軟件，並在呼叫框架的 listen 函數時設定連接埠。

MCP 支援

如果 Mastra 實例已配置 MCP 伺服器，伺服器適配器會在 registerRoutes() 期間註冊 MCP（Model Context Protocol）路由。MCP 讓外部 Tool 及服務連接至你的 Mastra 伺服器，並與 Agent 互動。

適配器會同時為 HTTP 及 SSE（Server-Sent Events）傳輸方式註冊路由，以支援不同的用戶端連接模式。

Serverless 模式

對於 Cloudflare Workers 或 Vercel Edge 等 serverless 環境，請透過 mcpOptions 啟用無狀態模式。

使用 Mastra deployer（標準 mastra dev／mastra build 路徑）時，請在伺服器配置中設定 mcpOptions：

const mastra = new Mastra({
  server: {
    mcpOptions: {
      serverless: true,
    },
  },
})

手動建立伺服器適配器時，請直接傳入 mcpOptions：

const server = new MastraServer({
  app,
  mastra,
  mcpOptions: {
    serverless: true,
  },
})

設定 serverless: true 後，MCP HTTP 請求會在沒有 session 管理的情況下執行，因而能與無狀態執行環境兼容。

有關配置詳情及如何設定 MCP 伺服器，請參閱 MCP。

相關內容

• Hono 適配器 - Hono 專用設定
• Express 適配器 - Express 專用設定
• NestJS 適配器 - NestJS 專用設定
• 自訂適配器 - 為其他框架建立適配器
• 伺服器配置 - 改用 mastra build
• 身份驗證 - 為伺服器配置身份驗證
• MastraServer 參考資料 - 完整 API 參考資料
• createRoute() 參考資料 - 建立型別安全的自訂路由