跳至主要內容

部署 Mastra workers

將 Mastra workers 作為獨立處理程序執行，讓你能夠分別擴展協調、排程與背景任務，而不受 API 影響。本指南將說明如何使用 Docker Compose 或 Kubernetes 完成全分離式部署。

資訊

本指南說明如何將 workers 分離至各自的容器中。如果你只需要讓 workers 與 API 在同一處理程序內執行，請參閱 Workers，不需要額外設定。

開始之前
「開始之前」的直接連結

你需要準備：

警告

預設的記憶體內 PubSub 無法跨處理程序傳遞事件。將 workers 分離至不同容器之前，必須先設定分散式 PubSub 後端。

設定共用基礎架構
「設定共用基礎架構」的直接連結

將 Mastra 執行個體連接至分散式 PubSub 後端與共用資料庫。使用環境變數，讓每個容器都能執行相同的映像檔。

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!,
  }),
})

任何支援的儲存後端皆可使用。請將儲存配接器替換為你偏好的資料庫。

部署
「部署」的直接連結

  1. 建置 Mastra 應用程式。產出的內容會在每個容器中執行。

    mastra build

    這會產生獨立完整的 .mastra/output/ 目錄。如需建置輸出的詳細資訊，請參閱部署 Mastra 伺服器。

  2. 建立 Dockerfile，複製預先建置的輸出並安裝正式環境相依套件：

    app/Dockerfile
    FROM node:22-alpine

    WORKDIR /app

    COPY .mastra/output/package.json .mastra/output/.npmrc* ./
    RUN npm install --omit=dev

    COPY .mastra/output/ .

    EXPOSE 4111
    CMD ["node", "index.mjs"]

  3. 定義全分離式拓撲。此設定會執行六項服務：一個資料庫、一個 PubSub 後端、API 伺服器，以及三個 workers。每個 worker 都執行相同的映像檔，並透過不同的 MASTRA_WORKERS 值控制要啟動的 worker。

    API 將 MASTRA_WORKERS: "false" 設為停用所有事件處理。協調 worker 會設定 MASTRA_STEP_EXECUTION_URL，將步驟執行請求導向 API 的內部 URL。詳細資訊請參閱步驟執行 URL。

    所有服務共用一個 MASTRA_WORKER_AUTH_TOKEN。Workers 向 API 傳送請求時會帶上此權杖，讓 API 能驗證呼叫者是受信任的內部服務。詳細資訊請參閱 worker 驗證。

    docker-compose.yml
    services:
      postgres:
        image: postgres:16-alpine
        environment:
          POSTGRES_USER: mastra
          POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
          POSTGRES_DB: mastra
        ports:
          - '5432:5432'
        volumes:
          - pgdata:/var/lib/postgresql/data
        healthcheck:
          test: ['CMD-SHELL', 'pg_isready -U mastra']
          interval: 5s
          timeout: 3s
          retries: 5

      redis:
        image: redis:7-alpine
        ports:
          - '6379:6379'
        healthcheck:
          test: ['CMD', 'redis-cli', 'ping']
          interval: 5s
          timeout: 3s
          retries: 5

      api:
        build: ./app
        ports:
          - '4111:4111'
        environment:
          DATABASE_URL: postgres://mastra:${POSTGRES_PASSWORD}@postgres:5432/mastra
          REDIS_URL: redis://redis:6379
          MASTRA_WORKERS: 'false'
          MASTRA_WORKER_AUTH_TOKEN: ${MASTRA_WORKER_AUTH_TOKEN}
        depends_on:
          postgres:
            condition: service_healthy
          redis:
            condition: service_healthy
        healthcheck:
          test: ['CMD', 'wget', '-qO-', 'http://localhost:4111/api/agents']
          interval: 5s
          timeout: 3s
          retries: 5

      orchestration-worker:
        build: ./app
        environment:
          DATABASE_URL: postgres://mastra:${POSTGRES_PASSWORD}@postgres:5432/mastra
          REDIS_URL: redis://redis:6379
          MASTRA_WORKERS: orchestration
          MASTRA_STEP_EXECUTION_URL: http://api:4111/api
          MASTRA_WORKER_AUTH_TOKEN: ${MASTRA_WORKER_AUTH_TOKEN}
        depends_on:
          api:
            condition: service_healthy

      scheduler-worker:
        build: ./app
        environment:
          DATABASE_URL: postgres://mastra:${POSTGRES_PASSWORD}@postgres:5432/mastra
          REDIS_URL: redis://redis:6379
          MASTRA_WORKERS: scheduler
          MASTRA_WORKER_AUTH_TOKEN: ${MASTRA_WORKER_AUTH_TOKEN}
        depends_on:
          api:
            condition: service_healthy

      background-task-worker:
        build: ./app
        environment:
          DATABASE_URL: postgres://mastra:${POSTGRES_PASSWORD}@postgres:5432/mastra
          REDIS_URL: redis://redis:6379
          MASTRA_WORKERS: backgroundTasks
          MASTRA_WORKER_AUTH_TOKEN: ${MASTRA_WORKER_AUTH_TOKEN}
        depends_on:
          api:
            condition: service_healthy

    volumes:
      pgdata:

    在 docker-compose.yml 旁建立 .env 檔案：

    .env
    POSTGRES_PASSWORD=your-secure-password
    MASTRA_WORKER_AUTH_TOKEN=your-shared-secret-token
    備註

    請記得設定應用程式所需的其他環境變數（例如模型 Provider 的 API 金鑰）。

  4. 驗證整組服務正在執行，且 API 能正常回應：

    docker compose up -d
    docker compose ps
    curl http://localhost:4111/api/agents

步驟執行 URL
「步驟執行 URL」的直接連結

在全分離式部署中，協調 worker 與 API 會在不同容器中執行。協調 worker 處理 Workflow 事件時，會透過 HTTP 將步驟執行委派給 API。

將 MASTRA_STEP_EXECUTION_URL 設為 API 的內部 URL，並包含 /api 前綴：

MASTRA_STEP_EXECUTION_URL=http://api:4111/api

協調 worker 會針對每個步驟，向 ${MASTRA_STEP_EXECUTION_URL}/workflows/:workflowId/runs/:runId/steps/execute 傳送 POST 請求。API 會解析 Workflow，並在本機執行該步驟。

若未設定此變數，協調 worker 會嘗試在處理程序內執行步驟。當 worker 與 API 一同執行時可正常運作，但在分離式部署中，worker 無法存取完整的 Mastra 執行階段，因此會執行失敗。

擴展
「擴展」的直接連結

協調與背景任務 workers 可安全地進行水平擴展。PubSub 消費者群組會將事件分配給不同執行個體，因此每個事件只會處理一次：

docker compose up -d --scale orchestration-worker=3
docker compose up -d --scale background-task-worker=2

API 也能在負載平衡器後方進行水平擴展。

請勿擴展排程 worker。 只執行一個執行個體。若有多個排程器輪詢相同儲存空間，會針對同一排程觸發重複事件。

當機復原
「當機復原」的直接連結

分散式 PubSub 後端會保留尚未確認的事件，因此 workers 能從當機狀態復原：

  • 協調 worker：待處理事件會保留在 PubSub 後端。Worker 重新啟動後，會從先前中斷處繼續處理。
  • 排程 worker：不會永久遺漏任何事件。排程器重新啟動時，會根據當下時間計算下一次觸發時間，而不是從中斷處繼續。
  • 步驟執行期間的 API：協調 worker 的 HTTP 請求會失敗。系統會對事件傳送否定確認，並在下次嘗試時重新傳遞。
警告

如果 API 在步驟執行期間當機（例如休眠途中），該步驟的工作會遺失。Workflow 執行可能持續卡在 running 狀態。Mastra 目前尚未針對此情境提供以逾時為基礎的自動復原機制。

On this page