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

# 部署 Mastra worker

將 [Mastra worker](https://mastra.zisheng.pro/zh-HK/docs/deployment/workers) 作為獨立程序執行，讓你可以分開擴展協調、排程及背景工作，而不受 API 影響。本指南會逐步介紹使用 Docker Compose 或 Kubernetes 進行完全分拆部署的方法。

> **資訊:** 本指南涵蓋如何將 worker 分拆至各自的容器。如只需讓 worker 與 API 在同一程序內執行，請參閱 [Worker](https://mastra.zisheng.pro/zh-HK/docs/deployment/workers)，無需額外設定。

## 開始之前

你需要：

- 一個 [Mastra 應用程式](https://mastra.zisheng.pro/zh-HK/guides/getting-started/quickstart)
- [Docker](https://docs.docker.com/get-docker/) 及 [Docker Compose](https://docs.docker.com/compose/)，或配備 [`kubectl`](https://kubernetes.io/docs/tasks/tools/) 的 [Kubernetes](https://kubernetes.io/docs/setup/) 叢集
- 分散式 PubSub 後端：供 [`RedisStreamsPubSub`](https://mastra.zisheng.pro/zh-HK/reference/pubsub/redis-streams) 使用的 [Redis](https://redis.io/)，或供 [`GoogleCloudPubSub`](https://mastra.zisheng.pro/zh-HK/reference/pubsub/google-cloud-pubsub) 使用的 [Google Cloud](https://cloud.google.com/) 項目
- 所有容器均可連線的共用資料庫。完整清單請參閱[支援的儲存後端](https://mastra.zisheng.pro/zh-HK/reference/workers/overview)。

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

## 設定共用基礎設施

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

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

任何[支援的儲存後端](https://mastra.zisheng.pro/zh-HK/reference/workers/overview)都適用。請將儲存配接器換成你偏好的資料庫。

## 部署

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

   ```bash
   mastra build
   ```

   這會產生自包含的 `.mastra/output/` 目錄。有關建置輸出的詳情，請參閱[部署 Mastra 伺服器](https://mastra.zisheng.pro/zh-HK/docs/deployment/mastra-server)。

2. 建立 Dockerfile，以複製預先建置的輸出並安裝生產環境依賴套件：

   ```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 伺服器，以及三個 worker。每個 worker 都執行相同映像檔，並透過不同的 `MASTRA_WORKERS` 值控制啟動哪個 worker。

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

   所有服務共用一個 `MASTRA_WORKER_AUTH_TOKEN`。worker 向 API 發出請求時會附上此 token，讓 API 可驗證呼叫者是受信任的內部服務。詳情請參閱 [worker 驗證](https://mastra.zisheng.pro/zh-HK/docs/server/auth/workers)。

   **Docker Compose**:

   ```yaml
   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` 檔案：

   ```bash
   POSTGRES_PASSWORD=your-secure-password
   MASTRA_WORKER_AUTH_TOKEN=your-shared-secret-token
   ```

   > **備註:** 請記得設定應用程式所需的任何其他環境變數（例如你的[模型 Provider](https://mastra.zisheng.pro/zh-HK/models/providers) API 金鑰）。

   **Kubernetes**:

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

   ```yaml
   apiVersion: v1
   kind: Namespace
   metadata:
     name: mastra-workers
   ```

   ```bash
   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](https://mastra.zisheng.pro/zh-HK/models/providers) API 金鑰）加入 Secret，或新增為額外的 `--from-literal` 項目。

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

   ```bash
   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）。

   ```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`，或使用受管理的資料庫服務。

   ```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
   ```

   ```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
   ```

   ```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
   ```

   ```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
   ```

   ```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 準備就緒：

   ```bash
   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
   ```

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

   **Docker Compose**:

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

   **Kubernetes**:

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

   在另一個終端機中：

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

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

## 步驟執行 URL

在完全分拆的部署中，協調 worker 會在 API 以外的另一個容器中執行。處理 Workflow 事件時，它會透過 HTTP 將步驟執行工作交由 API 處理。

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

```bash
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**:

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

**Kubernetes**:

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

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

```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](https://github.com/kubernetes-sigs/metrics-server)。GKE、EKS 及 AKS 等受管理叢集預設已包含此元件。

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

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

## 當機復原

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

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

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

## 相關資源

- [Worker](https://mastra.zisheng.pro/zh-HK/docs/deployment/workers)：worker 的用途及適用時機
- [Worker 驗證](https://mastra.zisheng.pro/zh-HK/docs/server/auth/workers)：保護 worker 與 API 之間的通訊
- [Worker 參考資料](https://mastra.zisheng.pro/zh-HK/reference/workers/overview)：所有 worker 類型的詳細設定
- [CLI 參考資料](https://mastra.zisheng.pro/zh-HK/reference/cli/mastra)：`mastra worker build` 及 `mastra worker start`
- [PubSub](https://mastra.zisheng.pro/zh-HK/docs/server/pubsub)：事件傳送後端
- [部署 Mastra 伺服器](https://mastra.zisheng.pro/zh-HK/docs/deployment/mastra-server)：建置輸出及伺服器設定
- [將 Mastra 部署至 Kubernetes](https://mastra.zisheng.pro/zh-HK/guides/deployment/kubernetes)：配備持久 Agent 的多 pod 部署