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

# Serveur sur la plateforme Mastra

Le serveur de la plateforme Mastra est une cible de déploiement en production qui exécute votre application Mastra comme serveur d'API. Utilisez-le lorsque vous souhaitez que la plateforme compile, déploie, héberge et gère votre serveur Mastra.

Vous bénéficiez immédiatement d'un point de terminaison d'API stable, de la gestion des variables d'environnement, de la prise en charge des domaines personnalisés et d'un historique des déploiements.

> **Remarque:** `mastra server deploy` correspond à l'ancienne méthode de déploiement séparé. Les nouveaux projets doivent utiliser la commande unifiée [`mastra deploy`](https://mastra.zisheng.pro/fr/docs/mastra-platform/deploy), qui ajoute une validation préalable, les environnements et les bases de données gérées par la CLI.

> **Remarque:** Le déploiement du serveur provisionne automatiquement un stockage hébergé. Si vous remplacez le stockage par [LibSQLStore](https://mastra.zisheng.pro/fr/reference/storage/libsql) avec une URL de fichier, utilisez plutôt une base de données hébergée à distance, car la plateforme Mastra emploie un système de fichiers éphémère.

## Démarrage rapide

1. Suivez le [guide de démarrage](https://mastra.zisheng.pro/fr/docs) pour créer votre premier projet Mastra.

2. Installez globalement la CLI `mastra` :

   **npm**:

   ```bash
   npm install -g mastra
   ```

   **pnpm**:

   ```bash
   pnpm add -g mastra
   ```

   **Yarn**:

   ```bash
   yarn global add mastra
   ```

   **Bun**:

   ```bash
   bun add --global mastra
   ```

3. Déployez votre projet :

   ```bash
   mastra server deploy
   ```

   Si vous n'êtes pas encore authentifié, la CLI vous invite à vous connecter. Elle enregistre vos identifiants localement et les réutilise pour les commandes suivantes.

   La commande exécute `mastra build`, téléverse l'artefact, construit une image Docker puis la déploie. Lors du premier déploiement, la CLI crée un fichier `.mastra-project.json` qui relie votre projet local à la plateforme. Validez ce fichier dans Git afin que les déploiements suivants et la CI/CD ciblent le même projet.

   > **Remarque:** Les variables d'environnement de `.env`, `.env.local` et `.env.production` sont incluses automatiquement. Lors du premier déploiement, elles initialisent le projet si aucune variable n'a encore été définie. Gérez ensuite les variables d'environnement depuis le tableau de bord web. Vérifiez et nettoyez ces fichiers avant le premier déploiement afin de ne pas téléverser de secrets personnels ou réservés au développement.

   Consultez la [référence de la CLI](https://mastra.zisheng.pro/fr/reference/cli/mastra) pour la liste complète des options.

4. Vérifiez votre déploiement à l'URL affichée par la CLI. Ajoutez `/api/agents` pour confirmer qu'elle renvoie la liste JSON de vos Agents.

   > **Attention:** Configurez l'[authentification](https://mastra.zisheng.pro/fr/docs/server/auth) avant d'exposer publiquement vos points de terminaison.

## Cycle de vie d'un déploiement

Un déploiement passe par les états **queued → uploading → building → deploying → running**, ou par **failed**, **cancelled**, **crashed** ou **stopped**. Un seul build peut s'exécuter à la fois pour un projet. Si plusieurs déploiements sont mis en file d'attente, seul le plus récent se poursuit et les autres sont annulés. Les builds qui durent plus de 15 minutes échouent automatiquement. Le premier déploiement provisionne l'infrastructure et initialise les variables d'environnement depuis votre fichier `.env` local. L'URL du serveur reste stable d'un déploiement à l'autre.

## Comportement en cas d'inactivité

Le serveur de la plateforme Mastra peut mettre un service en veille après une période d'inactivité afin d'économiser des ressources. L'inactivité est mesurée d'après le trafic réseau sortant. Un service n'est considéré comme inactif qu'après environ dix minutes sans paquet sortant. Tout trafic sortant récurrent réinitialise ce délai et maintient le service actif.

Un serveur qui ne se met jamais en veille possède généralement une tâche d'arrière-plan ou une connexion persistante qui émet périodiquement du trafic. Vérifiez les causes courantes suivantes.

### Connexions persistantes aux bases de données

Un client de base de données qui reste ouvert maintient la connexion active même lorsque le serveur est inactif. De nombreux pilotes exécutent également en arrière-plan un contrôle de santé qui interroge périodiquement la base de données ; cette activité est comptabilisée comme trafic sortant. Par exemple, un client MongoDB qui n'est jamais fermé conserve un socket de surveillance ouvert et envoie un signal environ toutes les dix secondes.

Les paramètres du pool de connexions qui ferment les connexions inactives ne suffisent pas, car la connexion de surveillance du pilote reste ouverte et continue d'émettre des requêtes. Pour permettre la mise en veille du serveur, fermez le client après une période d'inactivité et reconnectez-le lors de la requête suivante.

> **Remarque:** La fermeture du client ajoute un court délai de reconnexion à la première requête après le réveil du serveur. Si votre charge ne peut pas tolérer ce délai, maintenez la connexion ouverte et ne comptez pas sur la mise en veille automatique.

### Tâches planifiées et minuteurs

Un `setInterval`, un job cron ou une boucle d'interrogation qui effectue des appels réseau maintient le serveur actif. Si vous avez besoin de tâches planifiées, exécutez-les comme service distinct ou utilisez un planificateur externe qui réveille le serveur au moyen d'une requête.

### Pings externes et contrôles de maintien en vie

Un moniteur de disponibilité, un contrôle de santé ou un ping de maintien en vie qui appelle périodiquement le serveur réinitialise le délai d'inactivité. Supprimez ces contrôles ou augmentez leur intervalle au-delà de la période d'inactivité si vous souhaitez que le serveur se mette en veille.

### Exporters d'observabilité

Un exporter qui diffuse des traces, des journaux ou des métriques vers un point de terminaison distant génère du trafic sortant. Vérifiez qu'il regroupe les données et cesse de les envoyer lorsque le serveur est inactif, au lieu de les vider à intervalle fixe.

### Flux persistants

Un flux SSE ouvert, un WebSocket ou toute autre connexion persistante maintient le trafic ouvert jusqu'à sa fermeture. Une réponse en streaming qui reste abonnée en arrière-plan garde la connexion active. Vérifiez que les flux se ferment lorsque le client se déconnecte et qu'aucun flux ne reste ouvert lorsque le serveur est autrement inactif.

### Intégrations de chat

Certaines intégrations de chat maintiennent une connexion persistante et envoient régulièrement un signal, ce qui garde le serveur actif. Par exemple, une application Slack en Socket Mode ouvre un WebSocket et émet un ping environ toutes les trente secondes, tandis qu'un bot Discord maintient le WebSocket de sa passerelle ouvert avec un signal périodique. Le socket ouvert comme le signal empêchent la mise en veille.

Si vous souhaitez que le serveur se mette en veille, recevez les événements par webhooks HTTP plutôt que par connexion persistante lorsque l'intégration le permet. Les applications Slack peuvent par exemple utiliser l'Events API avec une URL de requête à la place de Socket Mode. Si votre application nécessite une connexion persistante, maintenez le service actif grâce au module complémentaire **Persistent Server** décrit ci-dessous.

### Inspecter les connexions actives

Pour déterminer ce qui maintient le serveur actif, inspectez les handles actifs du processus pendant les périodes d'inactivité. Un handle qui subsiste après la fin de toutes les requêtes est une piste à examiner. Les sockets ouverts signalent une connexion persistante à fermer, tandis que les minuteurs actifs indiquent un `setInterval` ou un `setTimeout` qui se reprogramme lui-même.

Ajoutez la fonction d'assistance suivante à votre application, puis observez le journal après l'arrêt du trafic. Tout élément encore répertorié lorsque le serveur est inactif le maintient éveillé :

```typescript
export function logActiveHandles() {
  // process._getActiveHandles is undocumented but useful for diagnosis.
  const handles = (process as any)._getActiveHandles() as Array<any>

  const summary = handles.map(handle => {
    const type = handle?.constructor?.name ?? typeof handle
    if (type === 'Socket') {
      return `Socket -> ${handle.remoteAddress}:${handle.remotePort}`
    }
    return type
  })

  console.log(`[idle] ${handles.length} active handles:`, summary)
}

// Log every 30 seconds so you can see what persists while the server is idle.
setInterval(logActiveHandles, 30_000).unref()
```

Appelez `unref()` sur l'intervalle de diagnostic afin que la fonction d'assistance ne maintienne pas elle-même le serveur actif.

### Maintenir un service actif

Certaines applications ont réellement besoin des connexions ou tâches décrites ci-dessus, par exemple une connexion persistante à une base de données pour réduire la latence de la première requête, un planificateur en arrière-plan ou un flux de longue durée. Si votre application en dépend, ne forcez pas la mise en veille du service. Utilisez plutôt le module complémentaire **Persistent Server** pour maintenir le service actif en permanence.

Lorsque le module complémentaire **Persistent Server** est activé, le service reste actif même en l'absence de trafic. Les connexions persistantes, les tâches planifiées et les flux ouverts continuent donc de fonctionner sans être interrompus par la mise en veille.

## CI/CD

Automatisez les déploiements depuis GitHub Actions, GitLab CI ou tout autre Provider de CI. Après votre premier déploiement interactif, la CI/CD a besoin de deux éléments : un jeton d'API et le fichier `.mastra-project.json` validé dans votre dépôt.

> **Astuce:** Si votre code se trouve sur GitHub, l'[intégration GitHub](https://mastra.zisheng.pro/fr/docs/mastra-platform/github) permet de déployer à chaque push sans écrire de fichier de Workflow. Utilisez le flux CI/CD fondé sur la CLI ci-dessous si vous avez besoin de GitLab, d'un autre Provider de CI ou d'étapes de build personnalisées avant le déploiement.

### Créer un jeton d'API

1. Exécutez localement la commande suivante :

   ```bash
   mastra auth tokens create ci-deploy
   ```

   La CLI n'affiche le jeton qu'une fois. Copiez-le immédiatement, car il ne pourra pas être récupéré ultérieurement.

2. Ajoutez le jeton comme secret dans votre Provider de CI. Dans GitHub Actions, ouvrez **Settings → Secrets and variables → Actions** puis créez un secret nommé `MASTRA_API_TOKEN`.

3. Vérifiez que votre fichier `.mastra-project.json` est validé dans le dépôt. La CLI y lit `organizationId` et `projectId` afin de cibler le bon projet pendant les déploiements de CI.

### L'option `--yes`

Transmettez `--yes` (ou `-y`) pour ignorer toutes les demandes de confirmation. Sans cette option, la CLI attend une saisie interactive et votre job de CI reste bloqué.

```bash
mastra server deploy --yes
```

### GitHub Actions

Le Workflow suivant déploie l'application à chaque push vers `main` :

```yaml
name: Deploy to Mastra platform

on:
  push:
    branches: [main]
    paths: ['src/mastra/**']

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '22'
          cache: 'npm'
      - name: Install dependencies
        run: npm install
      - name: Deploy to Mastra platform
        run: npx mastra server deploy --yes
        env:
          MASTRA_API_TOKEN: ${{ secrets.MASTRA_API_TOKEN }}
```

Adaptez le filtre `paths` et `working-directory` si votre projet Mastra se trouve dans un sous-répertoire, par exemple dans un monorepo.

> **Remarque:** Pour les déploiements de Studio, remplacez `mastra server deploy` par `mastra studio deploy`. Les options et les variables d'environnement restent identiques.

### GitLab CI

Le pipeline suivant effectue un déploiement à chaque push vers `main` :

```yaml
deploy:
  image: node:22
  stage: deploy
  only:
    - main
  before_script:
    - npm install
  script:
    - npx mastra server deploy --yes
```

Ajoutez `MASTRA_API_TOKEN` comme variable de CI/CD dans **Settings → CI/CD → Variables**.

### Autres Providers de CI

Tout système de CI capable d'exécuter Node.js et des commandes shell fonctionne avec Mastra :

1. Installez les dépendances.
2. Définissez `MASTRA_API_TOKEN` comme variable d'environnement.
3. Exécutez `mastra server deploy --yes` (ou `mastra studio deploy --yes`).

### Vérifier le déploiement

Une fois le Workflow terminé, vérifiez le déploiement en appelant le point de terminaison de santé :

```bash
curl -f https://<your-project>.server.mastra.cloud/health
```

Vous pouvez également vérifier le point de terminaison des Agents, qui renvoie leur liste au format JSON :

```bash
curl -f https://<your-project>.server.mastra.cloud/api/agents
```

L'exemple suivant ajoute une étape de vérification à un Workflow GitHub Actions :

```yaml
- name: Verify deployment
  run: |
    sleep 30
    curl -f https://<your-project>.server.mastra.cloud/health
```

### Remplacer la configuration du projet avec des variables d'environnement

Par défaut, la CLI lit `organizationId` et `projectId` dans `.mastra-project.json`. Pour remplacer ces valeurs, par exemple afin de déployer vers un autre projet depuis le même dépôt, définissez les variables d'environnement suivantes :

| Variable            | Description                                                              |
| ------------------- | ------------------------------------------------------------------------ |
| `MASTRA_ORG_ID`     | Remplace l'identifiant de l'organisation lu dans `.mastra-project.json`. |
| `MASTRA_PROJECT_ID` | Remplace l'identifiant du projet lu dans `.mastra-project.json`.         |

## Voir aussi

- [`mastra server deploy`](https://mastra.zisheng.pro/fr/reference/cli/mastra)
- [`mastra server pause`](https://mastra.zisheng.pro/fr/reference/cli/mastra)
- [`mastra server restart`](https://mastra.zisheng.pro/fr/reference/cli/mastra)
- [`mastra studio deploy`](https://mastra.zisheng.pro/fr/reference/cli/mastra)
- [`mastra auth tokens`](https://mastra.zisheng.pro/fr/reference/cli/mastra)