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

# 部署 Mastra Worker

将 [Mastra Worker](https://mastra.zisheng.pro/docs/deployment/workers) 作为独立进程运行，以便单独扩缩编排、调度和后台任务，而不受 API 影响。本指南逐步介绍如何使用 Docker Compose 或 Kubernetes 进行完全拆分式部署。

> **信息:** 本指南介绍如何将 Worker 拆分到各自容器中。如果只需让 Worker 与 API 一起在进程内运行，请参阅 [Worker](https://mastra.zisheng.pro/docs/deployment/workers)，无需额外设置。

## 开始之前

你需要：

- 一个 [Mastra 应用](https://mastra.zisheng.pro/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/reference/pubsub/redis-streams) 的 [Redis](https://redis.io/)，或用于 [`GoogleCloudPubSub`](https://mastra.zisheng.pro/reference/pubsub/google-cloud-pubsub) 的 [Google Cloud](https://cloud.google.com/) 项目
- 一个所有容器均可访问的共享数据库。完整列表请参阅[支持的 Storage 后端](https://mastra.zisheng.pro/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!,
  }),
})
```

可以使用任意[受支持的 Storage 后端](https://mastra.zisheng.pro/reference/workers/overview)。请将 Storage 适配器替换为你偏好的数据库。

## 部署

1. 构建 Mastra 应用。输出会在每个容器中运行。

   ```bash
   mastra build
   ```

   这会生成自包含的 `.mastra/output/` 目录。有关构建输出的详情，请参阅[部署 Mastra Server](https://mastra.zisheng.pro/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 Server 和三个 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/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/models/providers) API Key）。

   **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/models/providers) API Key）添加到 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 消费者组会在实例之间分发事件，因此每个事件只会处理一次：

**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 也可以在负载均衡器后水平扩缩。

\*\*请勿扩缩 Scheduler Worker。\*\*必须只运行一个实例。多个 Scheduler 轮询同一个 Storage 时，会针对同一个 Schedule 触发重复事件。

## 崩溃恢复

Worker 可以从崩溃中恢复，因为分布式 PubSub 后端会持久化未确认事件：

- **编排 Worker**：待处理事件保留在 PubSub 后端中。Worker 重启时，会从中断处继续处理。
- **Scheduler Worker**：不会永久错过任何事件。重启时，Scheduler 会根据当前时间而非中断位置计算下次触发时间。
- **步骤执行期间的 API**：编排 Worker 的 HTTP 请求失败。事件会被 nack，并在下次尝试时重新传递。

> **注意:** 如果 API 在步骤执行期间崩溃（例如在 sleep 过程中），该步骤的工作会丢失。Workflow 运行可能会一直停留在 `running` 状态。Mastra 目前尚不支持在这种情况下基于超时自动恢复。

## 相关内容

- [Worker](https://mastra.zisheng.pro/docs/deployment/workers)：Worker 的定义及适用场景
- [Worker 身份验证](https://mastra.zisheng.pro/docs/server/auth/workers)：保护 Worker 到 API 的通信
- [Worker Reference](https://mastra.zisheng.pro/reference/workers/overview)：所有 Worker 类型的配置详情
- [CLI Reference](https://mastra.zisheng.pro/reference/cli/mastra)：`mastra worker build` 和 `mastra worker start`
- [PubSub](https://mastra.zisheng.pro/docs/server/pubsub)：事件传递后端
- [部署 Mastra Server](https://mastra.zisheng.pro/docs/deployment/mastra-server)：构建输出和 Server 配置
- [将 Mastra 部署到 Kubernetes](https://mastra.zisheng.pro/guides/deployment/kubernetes)：使用持久化 Agent 进行多 Pod 部署