第18章 Server（服务器）

Server Mastra 以 HTTP server 的形式运行，把你的 agents、workflows 和其他功能暴露为 API 端点。server 负责请求路由、middleware 执行、身份验证以及流式响应。 注意：本页介绍传给 Mastra 构造函数的 server 配置项。如果想用你自己的 HTTP server（Hono、Express 等）来运行 Mastra，请参考 Server Adapters。 Server 功能 Middleware：拦截请求，实现身份验证、日志记录、CORS 或注入请求级上下文。 Custom API Routes：添加自定义 HTTP 端点来扩展 server，这些端点可以访问 Mastra 实例。 Request Context：根据运行时条件，把请求相关的值传递给 agents、tools 和 workflows。 Server Adapters：用 Express、Hono 或你自己的 HTTP server 运行 Mastra，替代内置生成的 server。 Custom Adapters：为尚未官方支持的框架构建适配器。 Mastra Client SDK：类型安全的客户端，可在浏览器或 server 环境中调用 agents、workflows 和 tools。 A2A：通过 A2A agent cards 和 task streams 暴露 agents，并支持推送通知。 Authentication：使用 JWT、Clerk、Supabase、Firebase、Auth0 或 WorkOS 保护端点安全。 配置 给 Mastra 构造函数传入一个 server 对象即可完成配置： src/mastra/index.tsimport { Mastra } from '@mastra/core'

export const mastra = new Mastra({
server: {
port: 3000, // 默认取 PORT 环境变量或 4111
host: '0.0.0.0', // 默认取 MASTRA_HOST 环境变量或 'localhost'
},
})
完整的服务器配置选项请查阅配置参考文档。 部署服务器Direct link to 部署服务器 Mastra 服务器可以部署到任何兼容 Node.js 的环境。你可以使用 Mastra 平台或自己的基础设施将其部署到生产环境，具体方法请参阅部署文档。 服务器架构Direct link to 服务器架构 Mastra 底层使用 Hono 作为 HTTP 服务器框架。使用 mastra build 构建 Mastra 应用时，会在 .mastra 目录中生成一个基于 Hono 的 HTTP 服务器。 该服务器提供： 所有已注册 agent 和 workflow 的 API 端点 自定义 API 路由和中间件 跨多种提供商的认证 用于运行时配置的请求上下文 流数据脱敏，保障响应安全 REST APIDirect link to REST API 你可以在 http://localhost:4111/api/openapi.json 查看符合 OpenAPI 规范的接口文档，其中详细列出了每个端点及其请求和响应的数据结构。 如果想交互式地探索 API，可以访问 http://localhost:4111/swagger-ui 的 Swagger UI，在浏览器中直接浏览端点并进行测试。 note默认情况下，生产环境中 OpenAPI 和 Swagger 端点是关闭的。如需开启，请将 server.build.openAPIDocs 和 server.build.swaggerUI 分别设为 true。 OpenAI Responses APIDirect link to OpenAI Responses API Mastra 提供了兼容 OpenAI 的 Responses 和 Conversations 路由，让你可以像使用 Responses API 一样使用 Mastra Agent。这些路由是基于 Mastra agent、内存和存储封装的适配层，请求会由所选的 Mastra agent 处理，而不是直接代理给底层模型提供商。 这些 API 目前处于实验阶段。 使用 agent_id 指定处理请求的 Mastra agent。首次请求直接指向某个 agent，后续轮次可通过 previous_response_id 继续。可以通过传入 model 参数在单次请求中覆盖已配置的模型，省略该参数则使用 agent 原有的模型。 Responses 路由支持流式输出、函数调用（tools）、基于 previous_response_id 的存储式续聊、通过 conversation_id 管理会话线程、通过 providerOptions 透传提供商特有参数，以及通过 text.format 输出 JSON。 完整的请求和响应契约请参阅 Responses API 参考文档和 Conversations API 参考文档，全部 HTTP 路由列表请参阅 server routes。 流数据脱敏Direct link to 流数据脱敏 在流式输出 agent 响应时，HTTP 层会在每个数据块发送给客户端之前，脱敏其中的系统提示词、工具定义、API 密钥等敏感数据。该功能默认开启。 此行为只能通过 server adapters 进行配置，而在 server adapters 中，流数据脱敏同样是默认开启的。 TypeScript 配置Direct link to TypeScript 配置 Mastra 要求 module 和 moduleResolution 设置与现代 Node.js 兼容，不支持 CommonJS 或 node 等旧版选项。 tsconfig.json{
"compilerOptions": {
"target": "ES2022",
"module": "ES2022",
"moduleResolution": "bundler",
"esModuleInterop": true,
"forceConsistentCasingInFileNames": true,
"strict": true,
"skipLibCheck": true,
"noEmit": true,
"outDir": "dist"
},
"include": ["src//*"]
}
后续步骤直达链接 添加中间件 创建自定义 API 路由 添加身份验证 把服务器部署到生产环境