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

# 伺服器概覽

Mastra 以 HTTP 伺服器形式運行，將你的 Agent、Workflow 和其他功能公開為 API 端點。伺服器會處理請求路由、中介軟件執行、驗證和串流回應。

> **資訊:** 本頁介紹傳遞至 `Mastra` 建構函式的 [`server`](https://mastra.zisheng.pro/zh-HK/reference/configuration) 配置選項。如要以你自己的 HTTP 伺服器（Hono、Express 等）運行 Mastra，請參閱[伺服器適配器](https://mastra.zisheng.pro/zh-HK/docs/server/server-adapters)。

## 伺服器功能

- **[中介軟件](https://mastra.zisheng.pro/zh-HK/docs/server/middleware)**：攔截請求以進行驗證、記錄、CORS，或注入請求專用的上下文。
- **[自訂 API 路由](https://mastra.zisheng.pro/zh-HK/docs/server/custom-api-routes)**：使用可存取 Mastra 實例的自訂 HTTP 端點擴充伺服器。
- **[請求上下文](https://mastra.zisheng.pro/zh-HK/docs/server/request-context)**：根據運行時條件，將請求專用的值傳遞至 Agent、Tool 和 Workflow。
- **[伺服器適配器](https://mastra.zisheng.pro/zh-HK/docs/server/server-adapters)**：使用 Express、Hono 或你自己的 HTTP 伺服器運行 Mastra，而非使用產生的伺服器。
- **[自訂適配器](https://mastra.zisheng.pro/zh-HK/docs/server/custom-adapters)**：為官方未支援的框架建立適配器。
- **[Mastra Client SDK](https://mastra.zisheng.pro/zh-HK/docs/server/mastra-client)**：用於從瀏覽器或伺服器環境調用 Agent、Workflow 和 Tool 的型別安全客戶端。
- **[A2A](https://mastra.zisheng.pro/zh-HK/docs/agents/a2a)**：透過 A2A Agent 卡片和工作串流公開 Agent，並支援推送通知。
- **[驗證](https://mastra.zisheng.pro/zh-HK/docs/server/auth)**：使用 JWT、Clerk、Supabase、Firebase、Auth0 或 WorkOS 保護端點。

## 配置

將 `server` 物件傳遞至 `Mastra` 建構函式，以配置伺服器：

```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/zh-HK/reference/configuration)。

## 部署伺服器

Mastra 伺服器可部署至任何與 Node.js 相容的環境。你可以使用 [Mastra 平台](https://mastra.zisheng.pro/zh-HK/docs/mastra-platform/overview)或自己的基礎設施將其部署至生產環境。請參閱[部署文件](https://mastra.zisheng.pro/zh-HK/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 規格中瀏覽所有可用端點；當中詳細說明每個端點及其請求和回應結構描述。

如要以互動方式探索 API，請前往 <http://localhost:4111/swagger-ui> 的 Swagger UI。你可以在此尋找端點，並直接透過瀏覽器進行測試。

> **備註:** OpenAPI 和 Swagger 端點在生產環境中預設為停用。如要啟用，請分別將 [`server.build.openAPIDocs`](https://mastra.zisheng.pro/zh-HK/reference/configuration) 和 [`server.build.swaggerUI`](https://mastra.zisheng.pro/zh-HK/reference/configuration) 設為 `true`。

## OpenAI Responses API

Mastra 提供與 OpenAI 相容的 Responses 和 Conversations 路由，讓你可以將 Mastra Agent 用作 Responses API。這些路由是建基於 Agent 的適配器，底層使用 Mastra Agent、記憶和儲存空間，因此請求會經由所選的 Mastra Agent 運行，而非充當原始 Provider 的代理。

這些 API 目前仍屬實驗性質。

使用 `agent_id` 選擇應處理請求的 Mastra Agent。首次請求會直接以某個 Agent 為目標，而已儲存的後續輪次則可透過 `previous_response_id` 延續。你亦可傳入 `model`，為單次請求覆寫 Agent 已配置的模型。如果省略 `model`，Mastra 會使用 Agent 上已配置的模型。

Responses 路由支援串流、函式調用（Tool）、透過 `previous_response_id` 延續已儲存的內容、透過 `conversation_id` 建立對話執行緒、使用 `providerOptions` 傳遞 Provider 專用選項，以及透過 `text.format` 輸出 JSON。

如需完整的請求和回應合約，請參閱 [Responses API 參考](https://mastra.zisheng.pro/zh-HK/reference/client-js/responses)和 [Conversations API 參考](https://mastra.zisheng.pro/zh-HK/reference/client-js/conversations)。如需完整的 HTTP 路由清單，請參閱[伺服器路由](https://mastra.zisheng.pro/zh-HK/reference/server/routes)。

## 串流資料遮蔽

串流傳送 Agent 回應時，HTTP 層會先從每個資料區塊中遮蔽系統提示、Tool 定義、API 金鑰和類似資料，才傳送至客戶端。此功能預設為啟用。

此行為只能透過[伺服器適配器](https://mastra.zisheng.pro/zh-HK/docs/server/server-adapters)配置。伺服器適配器亦預設啟用串流資料遮蔽。

## TypeScript 配置

Mastra 要求使用與現代 Node.js 相容的 `module` 和 `moduleResolution` 設定。不支援 `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/zh-HK/docs/server/middleware)
- 建立[自訂 API 路由](https://mastra.zisheng.pro/zh-HK/docs/server/custom-api-routes)
- 加入[驗證](https://mastra.zisheng.pro/zh-HK/docs/server/auth)
- 將你的伺服器[部署](https://mastra.zisheng.pro/zh-HK/docs/deployment/overview)至生產環境