跳至主要內容

Workers

beta

此功能目前為 beta 版。API 已足夠穩定，可用於正式環境，但部分細節仍可能變更。目前的缺漏請參閱已知限制。

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

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

使用 worker 的時機
「使用 worker 的時機」的直接連結

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

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

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

Worker 類型
「Worker 類型」的直接連結

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

協調 worker
「協調 worker」的直接連結

訂閱 PubSub 匯流排上的 Workflow 事件，並執行 Workflow 步驟。每個 workflow.start、步驟轉換及生命週期事件都會流經此 worker。

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

協調 worker 需要支援 pull 模式的 PubSub backend（例如 RedisStreamsPubSub 或 GoogleCloudPubSub）。

排程 worker
「排程 worker」的直接連結

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

排程器會自動讀取 Workflow 定義中的宣告式 schedule 欄位。宣告排程的方法請參閱排程 Workflow。

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

背景工作 worker
「背景工作 worker」的直接連結

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

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

Worker 的執行方式
「Worker 的執行方式」的直接連結

處理程序內模式（預設）
「處理程序內模式（預設）」的直接連結

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

src/mastra/index.ts
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 backend，並使用 MASTRA_WORKERS 環境變數控制各處理程序要啟動哪些 worker。

src/mastra/index.ts
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!,
  }),
})

任何受支援的儲存 backend 都可使用。請將儲存 Adapter 替換為偏好的資料庫。

在多個容器中執行相同的建置產物，並為每個容器設定不同的 MASTRA_WORKERS 值，以控制各處理程序啟動的 worker。

拆分式部署需要分散式 PubSub backend（RedisStreamsPubSub 或 GoogleCloudPubSub）、共用的儲存 backend，以及協調 worker 與 API 之間的網路連線。

Worker 部署指南以 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，請在 Mastra 設定中將 recovery.durableAgents 設為 'auto'，以便伺服器重新啟動時自動重新驅動孤立的執行。詳情請參閱當機復原。
On this page