PM2 en production : redémarrer Node.js sans couper les requêtes

Vendredi 17 h, déploiement urgent : pm2 restart api. Pendant trente secondes, la sonde externe affiche des 502, le support est submergé, et un partenaire relance ses webhooks en boucle. Lundi matin, quelqu'un teste pm2 reload api en mode cluster : même version, même code — et la sonde ne détecte aucune interruption.

PM2 n'est pas qu'un daemon « pour que Node.js tourne ». C'est un orchestrateur de processus avec une sémantique de redémarrage précise. Confondre restart et reload en production, c'est choisir volontairement une micro-coupure à chaque mise en ligne.

ecosystem.config.js : la base d'un déploiement propre

Un fichier ecosystem.config.js versionné évite les commandes ad hoc oubliées au prochain départ. Voici une configuration de départ pour une API Node.js en production :

module.exports = {

  apps: [{

    name: 'api',

    script: './dist/server.js',

    instances: 'max',

    exec_mode: 'cluster',

    wait_ready: true,

    listen_timeout: 10000,

    kill_timeout: 5000,

    max_memory_restart: '600M',

    env_production: {

      NODE_ENV: 'production',

      PORT: 3000,

    },

  }],

};

Si vous activez wait_ready: true, l'application doit signaler sa disponibilité avec process.send('ready') une fois le serveur HTTP prêt à recevoir du trafic. Le paramètre kill_timeout définit le délai laissé aux workers pour terminer les requêtes en cours avant un arrêt forcé.

Un kill_timeout trop court transforme un reload gracieux en restart déguisé.

Graceful shutdown : ce que PM2 ne fera pas à votre place

PM2 peut attendre — mais seulement si votre code sait se fermer proprement. Sans gestionnaire SIGINT ou SIGTERM, reload et restart se ressemblent : connexions coupées en plein traitement.

process.on('SIGINT', () => {

  server.close(() => process.exit(0));

  setTimeout(() => process.exit(1), 8000).unref();

});

Pensez aussi à fermer le pool de connexions base de données, vider les buffers de logs et arrêter les consommateurs de file d'attente. Pour les WebSockets, deux options : notifier les clients qu'ils doivent se reconnecter, ou drainer les connexions actives avant l'arrêt.

Workflow de déploiement recommandé

Un déploiement sans coupure suit généralement cette séquence :

1. Récupérer la release (pull Git ou bascule de symlink atomique).
2. Installer les dépendances avec npm ci --production.
3. Lancer pm2 reload ecosystem.config.js --env production --update-env.
4. Enregistrer la configuration avec pm2 save pour qu'elle survive à un redémarrage serveur.
5. Exécuter un smoke test sur l'endpoint de santé.

Pour un rollback, repointez le symlink vers l'artifact précédent et relancez un reload. Évitez pm2 delete suivi d'un start sauf lors de la première installation : vous perdriez l'historique des métriques et des redémarrages.

Nginx devant PM2 : répartition des rôles

En production, nginx termine le TLS et transmet le trafic dynamique à PM2 :

proxy_pass http://127.0.0.1:3000;

proxy_http_version 1.1;

Alignez les timeouts nginx (proxy_read_timeout, proxy_connect_timeout) sur le kill_timeout PM2. Pour les WebSockets, consultez notre guide sur le temps réel avec WebSocket.

Sur un VPS, configurez pm2 startup systemd avec un utilisateur non-root. Dimensionnez la RAM en fonction du nombre de workers et de la consommation mémoire maximale par instance. Sur un PaaS type Heroku, la plateforme gère souvent le cycle de vie des processus : PM2 reste surtout pertinent en auto-hébergement sur VPS ou bare metal.

Le sommet : PM2 masque l'absence de graceful — jusqu'au reload

Avant chaque merge en production, testez SIGINT et SIGTERM en local, puis exécutez un reload sur staging. C'est la différence entre un déploiement invisible et une demi-minute de 502 mesurée par vos clients.

Décider et avancer sans angle mort

Sur une demi-journée, vous pouvez sécuriser vos déploiements Node.js :

1. Passez en mode cluster si votre API HTTP est sans état, et remplacez restart par reload dans tous vos scripts de déploiement.
2. Implémentez et testez les gestionnaires SIGINT/SIGTERM — fermeture serveur, pool base de données, consommateurs de queue.
3. Versionnez un ecosystem.config.js complet avec variables d'environnement de production et limites mémoire.
4. Placez nginx devant PM2 pour le TLS, les fichiers statiques et la limitation de débit.
5. Surveillez le nombre de redémarrages et la latence de la boucle d'événements pour détecter les fuites mémoire avant qu'elles ne déclenchent un restart automatique.

Pour aller plus loin sur les fuites mémoire Node.js, consultez Fuite mémoire Node.js. Pour comparer les hébergeurs adaptés au déploiement VPS, parcourez notre annuaire.

Questions fréquentes

Différence pm2 restart et pm2 reload ?

restart arrête brutalement puis relance — coupure garantie. reload envoie un arrêt gracieux, attend la fin des requêtes en cours, puis relance les workers un par un en mode cluster. En production, reload est le choix par défaut.

Quand utiliser cluster mode ?

Dès qu'une application HTTP sans état doit exploiter plusieurs cœurs CPU. Limitez-vous à un worker par cœur. Pour les WebSockets, ajoutez une session persistante ou un adaptateur Redis partagé entre workers.

PM2 suffit-il sans nginx ?

C'est possible, mais nginx reste recommandé pour le chiffrement TLS, la diffusion des fichiers statiques et la protection contre les abus. PM2 écoute le port applicatif ; nginx fait le reverse proxy public.

Comment gérer variables env au deploy ?

Centralisez la configuration dans un ecosystem.config.js versionné et utilisez --update-env lors du reload. Les secrets restent hors Git — fichier sur le serveur ou coffre-fort dédié.

PM2 en production, c'est reload avec arrêt gracieux — pas restart pendant que les utilisateurs sont encore connectés.