Skip to main content

服务器概览

🌐 Server Overview

Mastra 作为一个 HTTP 服务器运行，将你的代理、工作流和其他功能作为 API 端点暴露出来。该服务器负责请求路由、中间件执行、身份验证以及流式响应。

🌐 Mastra runs as an HTTP server that exposes your agents, workflows, and other functionality as API endpoints. The server handles request routing, middleware execution, authentication, and streaming responses.

info

本页面介绍传递给 Mastra 构造函数的 server 配置选项。如需使用你自己的 HTTP 服务器（Hono、Express 等）运行 Mastra，请访问 服务器适配器。

🌐 This page covers the server configuration options passed to the Mastra constructor. For running Mastra with your own HTTP server (Hono, Express, etc.), visit Server Adapters.

服务器架构
Direct link to 服务器架构

🌐 Server architecture

Mastra 使用 Hono 作为其底层的 HTTP 服务器框架。当你使用 mastra build 构建 Mastra 应用时，它会在 .mastra 目录下生成一个基于 Hono 的 HTTP 服务器。

🌐 Mastra uses Hono as its underlying HTTP server framework. When you build a Mastra application using mastra build, it generates a Hono-based HTTP server in the .mastra directory.

服务器提供：

🌐 The server provides:

  • 所有注册代理和工作流的 API 端点
  • 自定义 API 路由和中间件
  • 使用多个提供商进行身份验证
  • 请求动态配置的上下文
  • 流数据编辑以确保响应安全

配置
Direct link to 配置

🌐 Configuration

通过将 server 对象传递给 Mastra 构造函数来配置服务器：

🌐 Configure the server by passing a server object to the Mastra constructor:

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

export const mastra = new Mastra({
  server: {
    port: 3000, // Defaults to 4111
    host: "0.0.0.0", // Defaults to 'localhost'
  },
});
info

访问配置参考以获取可用服务器选项的完整列表。

🌐 Visit the configuration reference for a full list of available server options.

服务器功能
Direct link to 服务器功能

🌐 Server features

  • 中间件：拦截请求以进行身份验证、日志记录、跨域资源共享（CORS）或注入与请求相关的上下文。
  • 自定义 API 路由：通过你自己的 HTTP 端点扩展服务器，这些端点可以访问 Mastra 实例。
  • 请求上下文：根据运行时条件将请求特定的值传递给代理、工具和工作流。
  • 服务器适配器：使用 Express、Hono 或你自己的 HTTP 服务器运行 Mastra，而不是使用生成的服务器。
  • 自定义适配器：为官方不支持的框架构建适配器。
  • Mastra 客户端 SDK：用于在浏览器或服务器环境中调用代理、工作流和工具的类型安全客户端。
  • 认证：使用 JWT、Clerk、Supabase、Firebase、Auth0 或 WorkOS 保护端点。

流数据脱敏
Direct link to 流数据脱敏

🌐 Stream data redaction

在流式传输代理响应时，HTTP 层会在将每个数据块发送给客户端之前，删除系统提示、工具定义、API 密钥及类似数据。此功能默认启用。

🌐 When streaming agent responses, the HTTP layer redacts system prompts, tool definitions, API keys, and similar data from each chunk before sending it to clients. This is enabled by default.

此行为只能通过使用服务器适配器进行配置。对于服务器适配器，流数据屏蔽默认也是启用的。

🌐 This behavior is only configurable by using server adapters. For server adapters, stream data redaction is enabled by default, too.

TypeScript 配置
Direct link to TypeScript 配置

🌐 TypeScript configuration

Mastra 需要与现代 Node.js 兼容的 module 和 moduleResolution 设置。不支持像 CommonJS 或 node 这样的旧选项。

🌐 Mastra requires module and moduleResolution settings compatible with modern Node.js. Legacy options like CommonJS or node are not supported.

tsconfig.json
{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ES2022",
    "moduleResolution": "bundler",
    "esModuleInterop": true,
    "forceConsistentCasingInFileNames": true,
    "strict": true,
    "skipLibCheck": true,
    "noEmit": true,
    "outDir": "dist"
  },
  "include": ["src/**/*"]
}
目录