部署 Mastra worker

將 Mastra worker 作為獨立程序執行，讓你可以分開擴展協調、排程及背景工作，而不受 API 影響。本指南會逐步介紹使用 Docker Compose 或 Kubernetes 進行完全分拆部署的方法。

資訊

本指南涵蓋如何將 worker 分拆至各自的容器。如只需讓 worker 與 API 在同一程序內執行，請參閱 Worker，無需額外設定。

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

你需要：

一個 Mastra 應用程式
Docker 及 Docker Compose，或配備 kubectl 的 Kubernetes 叢集
分散式 PubSub 後端：供 RedisStreamsPubSub 使用的 Redis，或供 GoogleCloudPubSub 使用的 Google Cloud 項目
所有容器均可連線的共用資料庫。完整清單請參閱支援的儲存後端。

注意

預設的記憶體內 PubSub 無法跨程序傳送事件。將 worker 分拆至不同容器前，必須先設定分散式 PubSub 後端。

設定共用基礎設施
設定共用基礎設施的直接連結

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

Redis Streams + PostgreSQL
Google Cloud Pub/Sub + LibSQL

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

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

任何支援的儲存後端都適用。請將儲存配接器換成你偏好的資料庫。

部署
部署的直接連結

建置 Mastra 應用程式。輸出會在每個容器中執行。
```
mastra build
```
這會產生自包含的 .mastra/output/ 目錄。有關建置輸出的詳情，請參閱部署 Mastra 伺服器。

建立 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"]

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

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

所有服務共用一個 MASTRA_WORKER_AUTH_TOKEN。worker 向 API 發出請求時會附上此 token，讓 API 可驗證呼叫者是受信任的內部服務。詳情請參閱 worker 驗證。

Docker Compose
Kubernetes

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 金鑰）。

建立 namespace，以及包含連線字串的 Secret：

k8s/namespace.yaml
apiVersion: v1
kind: Namespace
metadata:
  name: mastra-workers

kubectl apply -f k8s/namespace.yaml
kubectl create secret generic mastra-secrets -n mastra-workers \
  --from-literal=POSTGRES_PASSWORD='your-password' \
  --from-literal=DATABASE_URL='postgresql://mastra:your-password@postgres:5432/mastra' \
  --from-literal=REDIS_URL='redis://redis:6379' \
  --from-literal=MASTRA_WORKER_AUTH_TOKEN='your-shared-token'

備註

將應用程式所需的任何其他環境變數（例如你的模型 Provider API 金鑰）加入 Secret，或新增為額外的 --from-literal 項目。

建置 Docker 映像檔，並將它推送至叢集可提取映像檔的 registry：

docker build -t your-registry/mastra-workers:latest ./app
docker push your-registry/mastra-workers:latest

套用資料庫、PubSub 後端、API 及三個 worker 的 Deployment 和 Service。以下範例使用叢集內的 Postgres 及 Redis。在生產環境中，請使用受管理服務（例如 Amazon RDS、Cloud SQL、ElastiCache、Memorystore）。

k8s/postgres.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: postgres
  namespace: mastra-workers
spec:
  replicas: 1
  selector:
    matchLabels:
      app: postgres
  template:
    metadata:
      labels:
        app: postgres
    spec:
      containers:
        - name: postgres
          image: postgres:16-alpine
          ports:
            - containerPort: 5432
          env:
            - name: POSTGRES_USER
              value: mastra
            - name: POSTGRES_PASSWORD
              valueFrom:
                secretKeyRef:
                  name: mastra-secrets
                  key: POSTGRES_PASSWORD
            - name: POSTGRES_DB
              value: mastra
          volumeMounts:
            - name: pgdata
              mountPath: /var/lib/postgresql/data
      volumes:
        - name: pgdata
          emptyDir: {}
---
apiVersion: v1
kind: Service
metadata:
  name: postgres
  namespace: mastra-workers
spec:
  selector:
    app: postgres
  ports:
    - port: 5432
      targetPort: 5432

警告

上述 Postgres 範例使用 emptyDir 儲存資料，這表示 pod 重新啟動時資料會遺失。在生產環境中，請將它換成 PersistentVolumeClaim，或使用受管理的資料庫服務。

k8s/redis.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: redis
  namespace: mastra-workers
spec:
  replicas: 1
  selector:
    matchLabels:
      app: redis
  template:
    metadata:
      labels:
        app: redis
    spec:
      containers:
        - name: redis
          image: redis:7-alpine
          args: ['--appendonly', 'yes']
          ports:
            - containerPort: 6379
---
apiVersion: v1
kind: Service
metadata:
  name: redis
  namespace: mastra-workers
spec:
  selector:
    app: redis
  ports:
    - port: 6379
      targetPort: 6379

k8s/api.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: api
  namespace: mastra-workers
spec:
  replicas: 1
  selector:
    matchLabels:
      app: api
  template:
    metadata:
      labels:
        app: api
    spec:
      containers:
        - name: api
          image: your-registry/mastra-workers:latest
          ports:
            - containerPort: 4111
          env:
            - name: MASTRA_WORKERS
              value: 'false'
          envFrom:
            - secretRef:
                name: mastra-secrets
          readinessProbe:
            httpGet:
              path: /api/agents
              port: 4111
            initialDelaySeconds: 10
            periodSeconds: 5
          livenessProbe:
            httpGet:
              path: /api/agents
              port: 4111
            initialDelaySeconds: 15
            periodSeconds: 10
          resources:
            requests:
              cpu: 500m
              memory: 512Mi
---
apiVersion: v1
kind: Service
metadata:
  name: api
  namespace: mastra-workers
spec:
  selector:
    app: api
  ports:
    - port: 4111
      targetPort: 4111

k8s/orchestration-worker.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: orchestration-worker
  namespace: mastra-workers
spec:
  replicas: 1
  selector:
    matchLabels:
      app: orchestration-worker
  template:
    metadata:
      labels:
        app: orchestration-worker
    spec:
      containers:
        - name: worker
          image: your-registry/mastra-workers:latest
          env:
            - name: MASTRA_WORKERS
              value: orchestration
            - name: MASTRA_STEP_EXECUTION_URL
              value: http://api:4111/api
          envFrom:
            - secretRef:
                name: mastra-secrets
          resources:
            requests:
              cpu: 250m
              memory: 256Mi

k8s/scheduler-worker.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: scheduler-worker
  namespace: mastra-workers
spec:
  replicas: 1
  selector:
    matchLabels:
      app: scheduler-worker
  template:
    metadata:
      labels:
        app: scheduler-worker
    spec:
      containers:
        - name: worker
          image: your-registry/mastra-workers:latest
          env:
            - name: MASTRA_WORKERS
              value: scheduler
          envFrom:
            - secretRef:
                name: mastra-secrets
          resources:
            requests:
              cpu: 250m
              memory: 256Mi

k8s/background-task-worker.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: background-task-worker
  namespace: mastra-workers
spec:
  replicas: 1
  selector:
    matchLabels:
      app: background-task-worker
  template:
    metadata:
      labels:
        app: background-task-worker
    spec:
      containers:
        - name: worker
          image: your-registry/mastra-workers:latest
          env:
            - name: MASTRA_WORKERS
              value: backgroundTasks
          envFrom:
            - secretRef:
                name: mastra-secrets
          resources:
            requests:
              cpu: 250m
              memory: 256Mi

套用所有 manifest，並等待 API 準備就緒：

kubectl apply -f k8s/
kubectl wait -n mastra-workers --for=condition=ready pod -l app=api --timeout=90s
kubectl wait -n mastra-workers --for=condition=ready pod -l app=orchestration-worker --timeout=60s
kubectl wait -n mastra-workers --for=condition=ready pod -l app=scheduler-worker --timeout=60s
kubectl wait -n mastra-workers --for=condition=ready pod -l app=background-task-worker --timeout=60s

驗證技術棧正在執行，且 API 能夠回應：

Docker Compose
Kubernetes

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

kubectl get pods -n mastra-workers
kubectl port-forward -n mastra-workers svc/api 4111:4111

在另一個終端機中：

curl http://localhost:4111/api/agents

如傳回 Agent 的 JSON 清單，即表示 API 及 worker 正在執行。

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

在完全分拆的部署中，協調 worker 會在 API 以外的另一個容器中執行。處理 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 runtime，因此會執行失敗。

擴展
擴展的直接連結

協調 worker 及背景工作 worker 可以安全地水平擴展。PubSub consumer group 會在各實例之間分配事件，因此每個事件只會處理一次：

Docker Compose
Kubernetes

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

kubectl scale deployment/orchestration-worker -n mastra-workers --replicas=3
kubectl scale deployment/background-task-worker -n mastra-workers --replicas=2

如要自動擴展，請加入 HorizontalPodAutoscaler：

k8s/hpa.yaml
apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
  name: orchestration-worker
  namespace: mastra-workers
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: orchestration-worker
  minReplicas: 1
  maxReplicas: 10
  metrics:
    - type: Resource
      resource:
        name: cpu
        target:
          type: Utilization
          averageUtilization: 70

備註

以 CPU 為基礎的自動擴展需要在叢集中執行 metrics-server。GKE、EKS 及 AKS 等受管理叢集預設已包含此元件。

API 亦可在負載平衡器後方水平擴展。

**請勿擴展排程 worker。**只能執行一個實例。如有多個排程器輪詢相同儲存空間，便會為同一排程觸發重複事件。

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

由於分散式 PubSub 後端會保留尚未確認的事件，worker 可在當機後復原：

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

注意

如 API 在步驟執行期間當機（例如 sleep 途中），該步驟的工作便會遺失。Workflow 執行可能一直停留在 running 狀態。Mastra 目前尚未針對此情況提供以逾時為基礎的自動復原機制。

Worker：worker 的用途及適用時機
Worker 驗證：保護 worker 與 API 之間的通訊
Worker 參考資料：所有 worker 類型的詳細設定
CLI 參考資料：mastra worker build 及 mastra worker start
PubSub：事件傳送後端
部署 Mastra 伺服器：建置輸出及伺服器設定
將 Mastra 部署至 Kubernetes：配備持久 Agent 的多 pod 部署

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

設定共用基礎設施設定共用基礎設施 的直接連結

部署部署 的直接連結

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

擴展擴展 的直接連結

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

相關資源相關資源 的直接連結