> Discover all available pages from the documentation index: https://mastra.zisheng.pro/llms.txt

# 服务器概览

Mastra 以 HTTP 服务器运行，将 Agent、Workflow 和其他功能公开为 API 端点。服务器负责请求路由、中间件执行、身份验证和流式响应。

> **信息:** 本页介绍传递给 `Mastra` 构造函数的 [`server`](https://mastra.zisheng.pro/reference/configuration) 配置选项。要使用自己的 HTTP 服务器（Hono、Express 等）运行 Mastra，请参阅[服务器 Adapter](https://mastra.zisheng.pro/docs/server/server-adapters)。

## 服务器功能

- **[中间件](https://mastra.zisheng.pro/docs/server/middleware)**：拦截请求以进行身份验证、日志记录、CORS，或注入请求特定的上下文。
- **[自定义 API 路由](https://mastra.zisheng.pro/docs/server/custom-api-routes)**：使用可访问 Mastra 实例的自定义 HTTP 端点扩展服务器。
- **[请求上下文](https://mastra.zisheng.pro/docs/server/request-context)**：根据运行时条件将请求特定的值传递给 Agent、Tool 和 Workflow。
- **[服务器 Adapter](https://mastra.zisheng.pro/docs/server/server-adapters)**：使用 Express、Hono 或自己的 HTTP 服务器运行 Mastra，而不是使用生成的服务器。
- **[自定义 Adapter](https://mastra.zisheng.pro/docs/server/custom-adapters)**：为未获官方支持的框架构建 Adapter。
- **[Mastra Client SDK](https://mastra.zisheng.pro/docs/server/mastra-client)**：用于从浏览器或服务器环境调用 Agent、Workflow 和 Tool 的类型安全客户端。
- **[A2A](https://mastra.zisheng.pro/docs/agents/a2a)**：通过 A2A Agent 卡片和任务流以及推送通知公开 Agent。
- **[身份验证](https://mastra.zisheng.pro/docs/server/auth)**：使用 JWT、Clerk、Supabase、Firebase、Auth0 或 WorkOS 保护端点。

## 配置

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

```typescript
import { Mastra } from '@mastra/core'

export const mastra = new Mastra({
  server: {
    port: 3000, // Defaults to PORT env var or 4111
    host: '0.0.0.0', // Defaults to MASTRA_HOST env var or 'localhost'
  },
})
```

有关可用服务器选项的完整列表，请参阅[配置参考](https://mastra.zisheng.pro/reference/configuration)。

## 部署服务器

Mastra 服务器可以部署到任何兼容 Node.js 的环境。使用 [Mastra 平台](https://mastra.zisheng.pro/docs/mastra-platform/overview)或自己的基础设施将其部署到生产环境。有关方法，请参阅[部署文档](https://mastra.zisheng.pro/docs/deployment/overview)。

## 服务器架构

Mastra 使用 [Hono](https://hono.dev) 作为底层 HTTP 服务器框架。使用 `mastra build` 构建 Mastra 应用时，它会在 `.mastra` 目录中生成基于 Hono 的 HTTP 服务器。

服务器提供：

- 所有已注册 Agent 和 Workflow 的 API 端点
- 自定义 API 路由和中间件
- 跨 Provider 身份验证
- 用于运行时配置的请求上下文
- 用于安全响应的流数据删减

## REST API

可以在 <http://localhost:4111/api/openapi.json> 的 OpenAPI 规范中查看所有可用端点，其中详细说明了每个端点及其请求和响应 schema。

要以交互方式浏览 API，请访问 <http://localhost:4111/swagger-ui> 的 Swagger UI。在这里可以发现端点并直接从浏览器进行测试。

> **备注:** OpenAPI 和 Swagger 端点在生产环境中默认禁用。要启用它们，请分别将 [`server.build.openAPIDocs`](https://mastra.zisheng.pro/reference/configuration) 和 [`server.build.swaggerUI`](https://mastra.zisheng.pro/reference/configuration) 设置为 `true`。

## OpenAI Responses API

Mastra 公开兼容 OpenAI 的 Responses 和 Conversations 路由，使你可以将 Mastra Agent 用作 Responses API。这些路由是在 Mastra Agent、内存和存储之上由 Agent 支持的 Adapter，因此请求会通过所选 Mastra Agent 运行，而不是充当原始 Provider 代理。

这些 API 目前处于实验阶段。

使用 `agent_id` 选择应处理请求的 Mastra Agent。初始请求直接以 Agent 为目标，存储的后续轮次可以通过 `previous_response_id` 继续。也可以传递 `model`，为单个请求覆盖 Agent 配置的模型。如果省略 `model`，Mastra 会使用 Agent 上已配置的模型。

Responses 路由支持流式传输、函数调用（Tool）、使用 `previous_response_id` 的存储延续、通过 `conversation_id` 使用对话 Thread、使用 `providerOptions` 进行 Provider 特定的透传，以及通过 `text.format` 输出 JSON。

有关完整的请求和响应契约，请参阅 [Responses API 参考](https://mastra.zisheng.pro/reference/client-js/responses)和 [Conversations API 参考](https://mastra.zisheng.pro/reference/client-js/conversations)。有关 HTTP 路由的完整列表，请参阅[服务器路由](https://mastra.zisheng.pro/reference/server/routes)。

## 流数据删减

流式传输 Agent 响应时，HTTP 层会在向客户端发送每个数据块之前删减系统提示、Tool 定义、API 密钥和类似数据。此功能默认启用。

只有使用[服务器 Adapter](https://mastra.zisheng.pro/docs/server/server-adapters) 时才能配置此行为。服务器 Adapter 也默认启用流数据删减。

## TypeScript 配置

Mastra 要求 `module` 和 `moduleResolution` 设置与现代 Node.js 兼容。不支持 `CommonJS` 或 `node` 等旧选项。

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

## 后续步骤

- 添加[中间件](https://mastra.zisheng.pro/docs/server/middleware)
- 创建[自定义 API 路由](https://mastra.zisheng.pro/docs/server/custom-api-routes)
- 添加[身份验证](https://mastra.zisheng.pro/docs/server/auth)
- 将服务器[部署](https://mastra.zisheng.pro/docs/deployment/overview)到生产环境