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

# Déployer des workers Mastra

Exécutez les [workers Mastra](https://mastra.zisheng.pro/fr/docs/deployment/workers) comme processus distincts afin de dimensionner indépendamment de l’API l’orchestration, la planification et les tâches d’arrière-plan. Ce guide décrit un déploiement entièrement séparé avec Docker Compose ou Kubernetes.

> **Info:** Ce guide couvre la séparation des workers dans leurs propres conteneurs. Si vous avez seulement besoin que les workers s’exécutent dans le même processus que l’API, consultez [Workers](https://mastra.zisheng.pro/fr/docs/deployment/workers). Aucune configuration supplémentaire n’est nécessaire.

## Avant de commencer

Vous aurez besoin de :

- Une [application Mastra](https://mastra.zisheng.pro/fr/guides/getting-started/quickstart)
- [Docker](https://docs.docker.com/get-docker/) et [Docker Compose](https://docs.docker.com/compose/), ou un cluster [Kubernetes](https://kubernetes.io/docs/setup/) avec [`kubectl`](https://kubernetes.io/docs/tasks/tools/)
- Un backend PubSub distribué : [Redis](https://redis.io/) pour [`RedisStreamsPubSub`](https://mastra.zisheng.pro/fr/reference/pubsub/redis-streams), ou un projet [Google Cloud](https://cloud.google.com/) pour [`GoogleCloudPubSub`](https://mastra.zisheng.pro/fr/reference/pubsub/google-cloud-pubsub)
- Une base de données partagée accessible depuis chaque conteneur. Consultez les [backends de stockage pris en charge](https://mastra.zisheng.pro/fr/reference/workers/overview) pour la liste complète.

> **Attention:** Le PubSub en mémoire par défaut ne peut pas transmettre des événements entre processus. Vous devez configurer un backend PubSub distribué avant de séparer les workers dans des conteneurs distincts.

## Configurer l’infrastructure partagée

Dirigez l’instance `Mastra` vers un backend PubSub distribué et une base de données partagée. Utilisez des variables d’environnement afin que la même image s’exécute dans chaque conteneur.

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

Tout [backend de stockage pris en charge](https://mastra.zisheng.pro/fr/reference/workers/overview) convient. Remplacez l’adaptateur de stockage par celui de votre base de données préférée.

## Déployer

1. Compilez votre application Mastra. La sortie s’exécute dans chaque conteneur.

   ```bash
   mastra build
   ```

   Cette opération produit un répertoire `.mastra/output/` autonome. Consultez [Déployer un serveur Mastra](https://mastra.zisheng.pro/fr/docs/deployment/mastra-server) pour les détails sur la sortie de compilation.

2. Créez un Dockerfile qui copie la sortie précompilée et installe les dépendances de production :

   ```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. Définissez la topologie entièrement séparée. Cette configuration exécute six services : une base de données, un backend PubSub, le serveur API et trois workers. Chaque worker exécute la même image avec une valeur `MASTRA_WORKERS` différente pour contrôler le worker qui démarre.

   L’API définit `MASTRA_WORKERS: "false"` pour désactiver tout traitement d’événements. Le worker d’orchestration définit `MASTRA_STEP_EXECUTION_URL` pour diriger les requêtes d’exécution d’étapes vers l’URL interne de l’API. Consultez l’[URL d’exécution d’étapes](#step-execution-url) pour plus de détails.

   Tous les services partagent un `MASTRA_WORKER_AUTH_TOKEN`. Les workers incluent ce jeton dans leurs requêtes à l’API afin qu’elle puisse vérifier que l’appelant est un service interne de confiance. Consultez l’[authentification des workers](https://mastra.zisheng.pro/fr/docs/server/auth/workers) pour plus de détails.

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

   Créez un fichier `.env` à côté de votre `docker-compose.yml` :

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

   > **Remarque:** N’oubliez pas de définir les autres variables d’environnement nécessaires à votre application, par exemple la clé API de votre [fournisseur de modèles](https://mastra.zisheng.pro/fr/models/providers).

   **Kubernetes**:

   Créez un espace de noms et un Secret contenant vos chaînes de connexion :

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

   > **Remarque:** Ajoutez les autres variables d’environnement nécessaires à votre application, par exemple la clé API de votre [fournisseur de modèles](https://mastra.zisheng.pro/fr/models/providers), au Secret ou sous forme d’entrées `--from-literal` supplémentaires.

   Compilez et poussez l’image Docker vers un registre depuis lequel votre cluster peut la récupérer :

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

   Appliquez les Deployments et Services pour la base de données, le backend PubSub, l’API et les trois workers. L’exemple ci-dessous utilise Postgres et Redis dans le cluster. En production, utilisez des services gérés, par exemple Amazon RDS, Cloud SQL, ElastiCache ou 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
   ```

   > **Attention:** L’exemple Postgres ci-dessus utilise `emptyDir` pour le stockage, ce qui signifie que les données sont perdues lorsque le pod redémarre. En production, remplacez-le par un `PersistentVolumeClaim` ou utilisez un service de base de données géré.

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

   Appliquez tous les manifestes et attendez que l’API soit prête :

   ```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. Vérifiez que la pile est en cours d’exécution et que l’API répond :

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

   Dans un terminal distinct :

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

   Une liste JSON de vos Agents confirme que l’API et les workers sont en cours d’exécution.

## URL d’exécution d’étapes

Dans un déploiement entièrement séparé, le worker d’orchestration s’exécute dans un conteneur distinct de l’API. Lorsqu’il traite un événement de Workflow, il délègue l’exécution des étapes à l’API via HTTP.

Définissez `MASTRA_STEP_EXECUTION_URL` sur l’URL interne de l’API, avec le préfixe `/api` :

```bash
MASTRA_STEP_EXECUTION_URL=http://api:4111/api
```

Le worker d’orchestration envoie une requête `POST` à `${MASTRA_STEP_EXECUTION_URL}/workflows/:workflowId/runs/:runId/steps/execute` pour chaque étape. L’API résout le Workflow et exécute l’étape localement.

Sans cette variable, le worker d’orchestration tente d’exécuter les étapes dans le processus. Cela fonctionne lorsque le worker s’exécute avec l’API, mais échoue dans les déploiements séparés, où il n’a pas accès au runtime Mastra complet.

## Mise à l’échelle

Les workers d’orchestration et de tâches d’arrière-plan peuvent être mis à l’échelle horizontalement en toute sécurité. Les groupes de consommateurs PubSub distribuent les événements entre les instances : chaque événement n’est donc traité qu’une fois.

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

Pour la mise à l’échelle automatique, ajoutez un 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
```

> **Remarque:** La mise à l’échelle automatique fondée sur le processeur nécessite que [metrics-server](https://github.com/kubernetes-sigs/metrics-server) s’exécute dans le cluster. Les clusters gérés tels que GKE, EKS et AKS l’incluent par défaut.

L’API peut également être mise à l’échelle horizontalement derrière un équilibreur de charge.

**Ne mettez pas à l’échelle le worker planificateur.** Exécutez exactement une instance. Plusieurs planificateurs qui interrogent le même stockage déclenchent des événements dupliqués pour une même planification.

## Récupération après incident

Les workers se remettent d’un incident, car le backend PubSub distribué conserve les événements non acquittés :

- **Worker d’orchestration** : les événements en attente restent dans le backend PubSub. Au redémarrage, le worker reprend là où il s’était arrêté.
- **Worker planificateur** : aucun événement n’est manqué de façon permanente. Au redémarrage, le planificateur calcule l’heure du prochain déclenchement à partir de l’heure actuelle, et non de l’endroit où il s’était arrêté.
- **API durant l’exécution d’une étape** : la requête HTTP du worker d’orchestration échoue. L’événement est rejeté puis renvoyé à la tentative suivante.

> **Attention:** Si l’API se bloque alors qu’une étape est déjà en cours d’exécution, par exemple au milieu d’une veille, le travail de cette étape est perdu. L’exécution de Workflow peut rester bloquée dans l’état `running`. Mastra ne dispose pas encore d’une récupération automatique fondée sur un délai d’attente pour ce scénario.

## À consulter également

- [Workers](https://mastra.zisheng.pro/fr/docs/deployment/workers) : ce que sont les workers et quand les utiliser
- [Authentification des workers](https://mastra.zisheng.pro/fr/docs/server/auth/workers) : communication sécurisée entre worker et API
- [Référence des workers](https://mastra.zisheng.pro/fr/reference/workers/overview) : détails de configuration pour tous les types de workers
- [Référence de la CLI](https://mastra.zisheng.pro/fr/reference/cli/mastra) : `mastra worker build` et `mastra worker start`
- [PubSub](https://mastra.zisheng.pro/fr/docs/server/pubsub) : backends de transmission des événements
- [Déployer un serveur Mastra](https://mastra.zisheng.pro/fr/docs/deployment/mastra-server) : sortie de compilation et configuration du serveur
- [Déployer Mastra sur Kubernetes](https://mastra.zisheng.pro/fr/guides/deployment/kubernetes) : déploiement multi-pods avec Agents durables