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

# Workers

> **Beta:** 此功能目前為 beta 版。API 已足夠穩定，可用於正式環境，但部分細節仍可能變更。目前的缺漏請參閱[已知限制](#known-limitations)。

Workers 負責處理 request-response 循環以外的背景工作。Workflow 步驟執行、cron 排程及長時間執行的 Tool 呼叫都會在 worker 中執行，讓 API 保持回應能力。

Workers 預設與 API 在同一處理程序中執行。針對正式環境工作負載，你可以將它們拆分至不同處理程序或容器，並分別獨立擴展。

## 使用 worker 的時機

有下列任一情況時，worker 就相當重要：

- Workflow 步驟耗時超過數秒，不應阻塞 API 回應
- 需要事件持久性，讓執行中的工作能在處理程序重新啟動後繼續存在
- 系統不同部分需要獨立擴展（例如增加協調容量，但不增加 API 執行個體）
- 背景 Tool 呼叫應在專用運算資源上執行

若應用程式流量不大且 Workflow 很快完成，預設的處理程序內設定即可正常運作。等到確實需要時再加入 worker 基礎架構。

## Worker 類型

Mastra 內建三種 worker，每種各自處理特定類型的背景工作。

### 協調 worker

訂閱 [PubSub](https://mastra.zisheng.pro/zh-TW/docs/server/pubsub) 匯流排上的 Workflow 事件，並執行 Workflow 步驟。每個 `workflow.start`、步驟轉換及生命週期事件都會流經此 worker。

在拆分式部署中，協調 worker 會從分散式 PubSub backend 拉取事件，再透過 HTTP 將步驟執行委派回 API。在處理程序內模式中，則會直接執行步驟。

協調 worker 需要支援 pull 模式的 PubSub backend（例如 [`RedisStreamsPubSub`](https://mastra.zisheng.pro/zh-TW/reference/pubsub/redis-streams) 或 [`GoogleCloudPubSub`](https://mastra.zisheng.pro/zh-TW/reference/pubsub/google-cloud-pubsub)）。

### 排程 worker

輪詢儲存空間以尋找已到期的 cron 排程，並發布 `workflow.start` 事件。它只負責產生工作，交由協調 worker 接手。

排程器會自動讀取 Workflow 定義中的宣告式 `schedule` 欄位。宣告排程的方法請參閱[排程 Workflow](https://mastra.zisheng.pro/zh-TW/docs/workflows/scheduled-workflows)。

**請勿執行超過一個排程器執行個體。** 多個排程器輪詢同一儲存空間，會針對同一排程重複觸發事件。

### 背景工作 worker

執行標記為 `background: { enabled: true }` 的 Agent Tool 呼叫。Agent 叫用背景 Tool 時，API 會將工作派送至此 worker，而不會阻塞回應串流。

背景工作 worker 會透過 PubSub 匯流排管理並行限制、工作生命週期與結果傳遞。

## Worker 的執行方式

### 處理程序內模式（預設）

未提供設定時，Mastra 會在 API 處理程序內建立並啟動 worker。事件會流經記憶體內 PubSub，所有項目共用單一 Node.js runtime。

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

export const mastra = new Mastra({
  // Workers run in-process by default.
  // No pubsub or worker config needed.
})
```

除了儲存 Adapter，此設定不需要任何外部基礎架構。它無法在處理程序當機後繼續運作，也不能個別擴展元件。

### 拆分處理程序

若要讓 worker 在各自的處理程序中執行，請設定分散式 [PubSub](https://mastra.zisheng.pro/zh-TW/docs/server/pubsub) backend，並使用 `MASTRA_WORKERS` 環境變數控制各處理程序要啟動哪些 worker。

**Redis Streams + PostgreSQL**:

```typescript
import { Mastra } from '@mastra/core/mastra'
import { RedisStreamsPubSub } from '@mastra/redis-streams'
import { PostgresStore } from '@mastra/pg'

export const mastra = new Mastra({
  storage: new PostgresStore({
    connectionString: process.env.DATABASE_URL!,
  }),
  pubsub: new RedisStreamsPubSub({
    url: process.env.REDIS_URL!,
  }),
})
```

**Google Cloud Pub/Sub + LibSQL**:

```typescript
import { Mastra } from '@mastra/core/mastra'
import { GoogleCloudPubSub } from '@mastra/google-cloud-pubsub'
import { LibSQLStore } from '@mastra/libsql'

export const mastra = new Mastra({
  storage: new LibSQLStore({
    url: process.env.DATABASE_URL!,
  }),
  pubsub: new GoogleCloudPubSub({
    projectId: process.env.GCP_PROJECT_ID!,
  }),
})
```

任何[受支援的儲存 backend](https://mastra.zisheng.pro/zh-TW/reference/workers/overview) 都可使用。請將儲存 Adapter 替換為偏好的資料庫。

在多個容器中執行相同的建置產物，並為每個容器設定不同的 [`MASTRA_WORKERS`](https://mastra.zisheng.pro/zh-TW/reference/workers/overview) 值，以控制各處理程序啟動的 worker。

拆分式部署需要分散式 PubSub backend（[`RedisStreamsPubSub`](https://mastra.zisheng.pro/zh-TW/reference/pubsub/redis-streams) 或 [`GoogleCloudPubSub`](https://mastra.zisheng.pro/zh-TW/reference/pubsub/google-cloud-pubsub)）、共用的[儲存 backend](https://mastra.zisheng.pro/zh-TW/reference/workers/overview)，以及協調 worker 與 API 之間的網路連線。

[Worker 部署指南](https://mastra.zisheng.pro/zh-TW/guides/deployment/mastra-workers)以 Docker Compose 與 Kubernetes 範例逐步說明此設定。

## 網路架構

Workers 屬於內部基礎架構，不會公開給終端使用者，也不需要自己的子網域、公開 URL 或輸入 HTTP 路由。

在拆分式部署中：

- **API 伺服器是唯一公開的處理程序**：它處理所有用戶端 HTTP 要求，包括 REST 端點、Agent 互動、Workflow 觸發條件及任何自訂路由。
- **Workers 只建立對外連線**：它們從分散式 PubSub backend 拉取事件，並讀寫共用儲存資料庫；不接受來自用戶端的輸入流量。
- **協調 worker 會在內部呼叫 API**：它透過容器網路，使用 `MASTRA_STEP_EXECUTION_URL` 將步驟執行要求傳送至 API。這是內部服務間通訊，不是公開端點。

三種 worker（協調、排程、背景工作）全都位於私有網路的 API 後方。它們共用 PubSub backend 與儲存資料庫的存取權，但絕不直接接收用戶端流量。若 worker 相關功能需要 HTTP 路由（例如為語音整合簽發 token），該路由會在 API 伺服器上執行，而非 worker 處理程序。

## 已知限制

- **沒有 dead-letter queue**：失敗事件會收到 nack 並重試，但沒有 DLQ 可處理用盡所有重試次數後仍失敗的事件。
- **沒有內建健康狀態端點**：Workers 不會公開 HTTP 健康狀態檢查。請使用容器層級的 liveness probe 或處理程序監控。
- **排程器僅限單一執行個體**：執行多個排程器處理程序會導致排程重複觸發。
- **API 當機後執行停滯於「running」**：若 API 處理程序在執行 Workflow 步驟時當機，該次執行會停留在 `running` 狀態，且不會自動重試。若使用[持久 Agent](https://mastra.zisheng.pro/zh-TW/docs/long-running-agents/durable-agents)，請在 Mastra 設定中將 `recovery.durableAgents` 設為 `'auto'`，以便伺服器重新啟動時自動重新驅動孤立的執行。詳情請參閱[當機復原](https://mastra.zisheng.pro/zh-TW/docs/long-running-agents/durable-agents)。

## 相關資源

- [Worker 部署指南](https://mastra.zisheng.pro/zh-TW/guides/deployment/mastra-workers)：Docker Compose 與 Kubernetes 範例
- [Worker 驗證](https://mastra.zisheng.pro/zh-TW/docs/server/auth/workers)：保護 worker 對 API 的通訊
- [Workers 參考](https://mastra.zisheng.pro/zh-TW/reference/workers/overview)：Worker 環境變數與類型的詳細資訊，以及受支援儲存 backend 的清單
- [CLI 參考](https://mastra.zisheng.pro/zh-TW/reference/cli/mastra)：`mastra worker build` 與 `mastra worker start`
- [PubSub](https://mastra.zisheng.pro/zh-TW/docs/server/pubsub)：事件傳遞 backend
- [排程 Workflow](https://mastra.zisheng.pro/zh-TW/docs/workflows/scheduled-workflows)：在 Workflow 上宣告 cron 排程