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

# 伺服器概覽

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

> **資訊:** 本頁說明傳入 `Mastra` 建構函式的 [`server`](https://mastra.zisheng.pro/zh-TW/reference/configuration) 設定選項。如要搭配自己的 HTTP 伺服器（Hono、Express 等）執行 Mastra，請參閱[伺服器轉接器](https://mastra.zisheng.pro/zh-TW/docs/server/server-adapters)。

## 伺服器功能

- **[Middleware](https://mastra.zisheng.pro/zh-TW/docs/server/middleware)**：攔截請求，以進行驗證、記錄、CORS，或注入請求專屬的 context。
- **[自訂 API 路由](https://mastra.zisheng.pro/zh-TW/docs/server/custom-api-routes)**：使用可存取 Mastra 執行個體的自訂 HTTP 端點擴充伺服器。
- **[請求 Context](https://mastra.zisheng.pro/zh-TW/docs/server/request-context)**：根據執行階段條件，將請求專屬的值傳給 Agent、Tool 及 Workflow。
- **[伺服器轉接器](https://mastra.zisheng.pro/zh-TW/docs/server/server-adapters)**：使用 Express、Hono 或自己的 HTTP 伺服器來執行 Mastra，而非使用產生的伺服器。
- **[自訂轉接器](https://mastra.zisheng.pro/zh-TW/docs/server/custom-adapters)**：為官方尚未支援的框架建置轉接器。
- **[Mastra Client SDK](https://mastra.zisheng.pro/zh-TW/docs/server/mastra-client)**：型別安全的用戶端，可從瀏覽器或伺服器環境呼叫 Agent、Workflow 及 Tool。
- **[A2A](https://mastra.zisheng.pro/zh-TW/docs/agents/a2a)**：透過 A2A Agent 卡片與任務串流公開 Agent，並支援推播通知。
- **[驗證](https://mastra.zisheng.pro/zh-TW/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-TW/reference/configuration)。

## 部署伺服器

Mastra 伺服器可以部署至任何與 Node.js 相容的環境。你可以透過 [Mastra 平台](https://mastra.zisheng.pro/zh-TW/docs/mastra-platform/overview)或自己的基礎架構部署至正式環境。詳情請參閱[部署文件](https://mastra.zisheng.pro/zh-TW/docs/deployment/overview)。

## 伺服器架構

Mastra 使用 [Hono](https://hono.dev) 作為底層 HTTP 伺服器框架。使用 `mastra build` 建置 Mastra 應用程式時，系統會在 `.mastra` 目錄中產生以 Hono 為基礎的 HTTP 伺服器。

伺服器提供：

- 所有已註冊 Agent 與 Workflow 的 API 端點
- 自訂 API 路由與 middleware
- 跨 Provider 的驗證
- 用於執行階段設定的請求 context
- 確保回應安全的串流資料遮蔽

## 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-TW/reference/configuration) 與 [`server.build.swaggerUI`](https://mastra.zisheng.pro/zh-TW/reference/configuration) 設為 `true`。

## OpenAI Responses API

Mastra 公開與 OpenAI 相容的 Responses 與 Conversations 路由，讓你能將 Mastra Agent 當作 Responses API 使用。這些路由是在 Mastra Agent、記憶體及儲存空間之上，由 Agent 支援的轉接器，因此請求會透過所選的 Mastra Agent 執行，而非作為原始 Provider Proxy 運作。

這些 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-TW/reference/client-js/responses)與 [Conversations API 參考](https://mastra.zisheng.pro/zh-TW/reference/client-js/conversations)。如需完整的 HTTP 路由清單，請參閱[伺服器路由](https://mastra.zisheng.pro/zh-TW/reference/server/routes)。

## 串流資料遮蔽

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

只有使用[伺服器轉接器](https://mastra.zisheng.pro/zh-TW/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/**/*"]
}
```

## 後續步驟

- 新增 [middleware](https://mastra.zisheng.pro/zh-TW/docs/server/middleware)
- 建立[自訂 API 路由](https://mastra.zisheng.pro/zh-TW/docs/server/custom-api-routes)
- 新增[驗證](https://mastra.zisheng.pro/zh-TW/docs/server/auth)
- 將伺服器[部署](https://mastra.zisheng.pro/zh-TW/docs/deployment/overview)至正式環境