メインコンテンツへ移動

Mastra Worker をデプロイする

Mastra Worker を別プロセスとして実行し、Orchestration、Schedule、バックグラウンドタスクを API とは独立してスケーリングします。このガイドでは、Docker Compose または Kubernetes を使用した完全分離型のデプロイについて説明します。

情報

このガイドでは、Worker を独自のコンテナに分離する方法を説明します。API と同じプロセス内で Worker を実行するだけでよい場合は、Worker を参照してください。追加設定は必要ありません。

始める前に
始める前にへの直接リンク

次のものが必要です。

警告

デフォルトの In-memory PubSub はプロセス間でイベントを配信できません。Worker を別のコンテナに分離する前に、分散 PubSub Backend を設定する必要があります。

共有インフラストラクチャを設定する
共有インフラストラクチャを設定するへの直接リンク

Mastra インスタンスを分散 PubSub Backend と共有データベースに接続します。すべてのコンテナで同じイメージを実行できるように、環境変数を使用します。

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

サポートされるストレージ Backend はどれでも使用できます。使用するデータベースに合わせてストレージ Adapter を置き換えてください。

デプロイする
デプロイするへの直接リンク

  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. 完全分離型の Topology を定義します。この構成は、データベース、PubSub Backend、API サーバー、3 つの Worker の計 6 つの Service を実行します。各 Worker は同じイメージを異なる MASTRA_WORKERS 値で実行し、起動する Worker を制御します。

    API は MASTRA_WORKERS: "false" を設定し、すべてのイベント処理を無効にします。Orchestration Worker は MASTRA_STEP_EXECUTION_URL を設定し、Step 実行リクエストを API の内部 URL に送ります。詳しくは Step 実行 URLを参照してください。

    すべての Service が MASTRA_WORKER_AUTH_TOKEN を共有します。Worker は API へのリクエストにこの Token を含めるため、API は呼び出し元が信頼できる内部 Service であることを検証できます。詳しくは 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. Stack が実行され、API が応答することを確認します。

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

Step 実行 URL
Step 実行 URLへの直接リンク

完全分離型のデプロイでは、Orchestration Worker が API とは別のコンテナで実行されます。Workflow イベントを処理するとき、HTTP 経由で Step の実行を API に委任します。

MASTRA_STEP_EXECUTION_URL に /api Prefix を含む API の内部 URL を設定します。

MASTRA_STEP_EXECUTION_URL=http://api:4111/api

Orchestration Worker は、Step ごとに ${MASTRA_STEP_EXECUTION_URL}/workflows/:workflowId/runs/:runId/steps/execute へ POST リクエストを送ります。API が Workflow を解決し、Step をローカル実行します。

この変数を設定しない場合、Orchestration Worker はプロセス内で Step の実行を試みます。Worker が API と同じプロセスで実行される場合は動作しますが、Worker が完全な Mastra Runtime にアクセスできない分離型デプロイでは失敗します。

スケーリング
スケーリングへの直接リンク

Orchestration Worker とバックグラウンドタスク Worker は安全に水平スケーリングできます。PubSub Consumer Group がインスタンス間でイベントを分散するため、各イベントは一度だけ処理されます。

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

API も Load Balancer の背後で水平スケーリングできます。

Scheduler Worker はスケーリングしないでください。 インスタンスを 1 つだけ実行します。複数の Scheduler が同じストレージを Poll すると、同じ Schedule に対して重複したイベントが発生します。

Crash Recovery
Crash Recoveryへの直接リンク

分散 PubSub Backend が未確認のイベントを永続化するため、Worker は Crash から復旧できます。

  • Orchestration Worker：保留中のイベントは PubSub Backend に残ります。Worker を再起動すると、中断した場所から処理を再開します。
  • Scheduler Worker：イベントが完全に失われることはありません。再起動時に Scheduler は、中断した場所ではなく現在時刻から次の実行時刻を計算します。
  • Step 実行中の API：Orchestration Worker の HTTP リクエストが失敗します。イベントは Nack され、次の試行で再配信されます。
警告

Step の実行中に API が Crash した場合（Sleep の途中など）、その Step の作業は失われます。Workflow の Run は running 状態のまま停止することがあります。現時点では、この状況に対する Timeout ベースの自動復旧はありません。

On this page