部署 Mastra Worker

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

信息

本指南介绍如何将 Worker 拆分到各自容器中。如果只需让 Worker 与 API 一起在进程内运行，请参阅 Worker，无需额外设置。

开始之前
开始之前的直接链接

你需要：

一个 Mastra 应用
Docker 和 Docker Compose，或一个带有 kubectl 的 Kubernetes 集群
一个分布式 PubSub 后端：用于 RedisStreamsPubSub 的 Redis，或用于 GoogleCloudPubSub 的 Google Cloud 项目
一个所有容器均可访问的共享数据库。完整列表请参阅支持的 Storage 后端。

注意

默认内存 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!,
  }),
})

可以使用任意受支持的 Storage 后端。请将 Storage 适配器替换为你偏好的数据库。

部署
部署的直接链接

构建 Mastra 应用。输出会在每个容器中运行。
```
mastra build
```
这会生成自包含的 .mastra/output/ 目录。有关构建输出的详情，请参阅部署 Mastra Server。

创建 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 Server 和三个 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 Key）。

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

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

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

崩溃恢复
崩溃恢复的直接链接

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

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

注意

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

Worker：Worker 的定义及适用场景
Worker 身份验证：保护 Worker 到 API 的通信
Worker Reference：所有 Worker 类型的配置详情
CLI Reference：mastra worker build 和 mastra worker start
PubSub：事件传递后端
部署 Mastra Server：构建输出和 Server 配置
将 Mastra 部署到 Kubernetes：使用持久化 Agent 进行多 Pod 部署

开始之前开始之前的直接链接

配置共享基础设施配置共享基础设施的直接链接

部署部署的直接链接

步骤执行 URL步骤执行 URL的直接链接

扩缩扩缩的直接链接

崩溃恢复崩溃恢复的直接链接

相关内容相关内容的直接链接