pm2-dashboard-vision

Module PM2 de monitoring web : un dashboard temps réel pour tous les services gérés par PM2 sur une machine. Affiche CPU, RAM, uptime, restarts, métriques de latence (event loop, HTTP) et logs en direct, avec actions restart / pause / start / delete. Interface rendue en EJS, temps réel via Socket.io.

C'est un module PM2 : il s'installe, se configure et se met à jour via pm2 install / pm2 set / pm2 uninstall.

Installation

pm2 install pm2-dashboard-vision

Le dashboard est accessible sur http://:9615 (port par défaut, configurable — voir plus bas).

Développement local

Depuis le dossier du module :

pm2 install .

PM2 installe les dépendances, lance le module et le redémarre automatiquement à chaque modification d'un fichier.

pm2 logs pm2-dashboard-vision      # logs du module
pm2 describe pm2-dashboard-vision  # infos détaillées
pm2 uninstall pm2-dashboard-vision # désinstaller

Configuration

Toute la config se fait via pm2 set (sans réinstaller ; le module redémarre seul) :

pm2 set pm2-dashboard-vision:port 8090
pm2 set pm2-dashboard-vision:host 0.0.0.0
pm2 set pm2-dashboard-vision:refresh 2000
pm2 set pm2-dashboard-vision:max_log_lines 500

# Authentification (voir section Sécurité)
pm2 set pm2-dashboard-vision:user admin
pm2 set pm2-dashboard-vision:password MotDePasseSolide

# Compte observateur / lecture seule (voir section Sécurité)
pm2 set pm2-dashboard-vision:viewer_user observateur
pm2 set pm2-dashboard-vision:viewer_password AutreMotDePasse

# Allowlist d'IP (voir section Sécurité)
pm2 set pm2-dashboard-vision:allowed_ips "192.168.1.10,192.168.1.20"

# Voir la config courante
pm2 conf pm2-dashboard-vision

| Clé | Défaut | Description | |-----|--------|-------------| | port | 9615 | Port HTTP du dashboard | | host | 0.0.0.0 | Interface d'écoute | | refresh | 2000 | Intervalle de rafraîchissement (ms) | | max_log_lines | 500 | Lignes de log conservées côté navigateur | | user | (vide) | Identifiant admin (accès complet) — voir Sécurité | | password | (vide) | Mot de passe admin — voir Sécurité | | viewer_user | (vide) | Identifiant observateur (lecture seule) — voir Sécurité | | viewer_password | (vide) | Mot de passe observateur — voir Sécurité | | allowed_ips | (vide) | Allowlist d'IP autorisées, séparées par virgule/espace (voir Sécurité) | | max_attempts | 5 | Échecs d'auth tolérés par IP avant blocage (0 = désactivé) | | block_minutes | 15 | Durée du blocage d'une IP après trop d'échecs (minutes) | | audit_max | 500 | Nombre d'entrées du journal d'audit conservées en mémoire |

Note PM2 : les valeurs de config sont stockées comme chaînes dans ~/.pm2/module_conf.json. Le module les parse lui-même.

Sécurité — authentification

Le dashboard expose des actions destructives (delete / stop). Ne l'expose jamais publiquement sans protection.

Une authentification HTTP Basic s'active dès que user et password sont tous les deux définis :

pm2 set pm2-dashboard-vision:user admin
pm2 set pm2-dashboard-vision:password MotDePasseSolide
pm2 restart pm2-dashboard-vision

Une fois active, elle protège tout : le dashboard, l'API, l'endpoint JSON et la connexion websocket. Le navigateur affiche une fenêtre de connexion au chargement. Si un seul des deux champs est renseigné, l'authentification reste désactivée et un avertissement est écrit dans les logs.

Pour la désactiver :

pm2 set pm2-dashboard-vision:user ""

Deux rôles : admin et observateur

En plus du compte admin, tu peux déclarer un compte observateur (lecture seule). Il voit le dashboard, les métriques et les logs, mais les boutons Restart / Pause / Start / Delete n'apparaissent pas pour lui, et toute tentative d'action est refusée côté serveur (POST /api/action → 403). Masquer les boutons n'est donc pas qu'un effet visuel : l'API elle-même est verrouillée.

# compte admin (déjà configuré ci-dessus)
pm2 set pm2-dashboard-vision:user admin
pm2 set pm2-dashboard-vision:password MotDePasseAdmin

# compte observateur (lecture seule)
pm2 set pm2-dashboard-vision:viewer_user observateur
pm2 set pm2-dashboard-vision:viewer_password MotDePasseObs
pm2 restart pm2-dashboard-vision

• Le compte observateur n'est actif que si l'auth admin l'est aussi (user + password).
• Il faut renseigner les deux champs viewer_user et viewer_password, sinon le compte est ignoré (avertissement dans les logs).
• N'utilise pas le même identifiant pour user et viewer_user : en cas d'égalité, l'admin l'emporte.

Restreindre par IP (allowlist)

En complément (ou à la place) de l'authentification, tu peux n'autoriser que certaines machines par leur adresse IP. Une machine dont l'IP n'est pas listée voit sa connexion rejetée avec un 403, sur le dashboard comme sur le websocket.

pm2 set pm2-dashboard-vision:allowed_ips "192.168.1.10,192.168.1.20"
pm2 restart pm2-dashboard-vision

• Les IP se séparent par virgule ou espace.
• Le loopback (127.0.0.1) est toujours autorisé — l'accès local et le tunnel SSH continuent de fonctionner.
• Laisser vide (pm2 set pm2-dashboard-vision:allowed_ips "") désactive le filtrage.

Retirer une IP : PM2 stocke la liste comme une seule chaîne — il n'y a pas de suppression unitaire. On réécrit la liste sans l'IP à enlever :

pm2 conf pm2-dashboard-vision                            # voir la valeur actuelle
pm2 set pm2-dashboard-vision:allowed_ips "192.168.1.10"  # réécrit la liste (ici sans .20)

Pour que ce filtrage reste fiable, fige l'IP des machines autorisées via une réservation DHCP (IP liée à l'adresse MAC) ou une IP statique. Sinon une machine peut perdre son autorisation quand son bail DHCP change.

Anti-brute-force

Après plusieurs échecs d'authentification depuis une même IP, celle-ci est bloquée temporairement (réponse 429), ce qui casse les attaques par essais répétés de mots de passe. Le loopback n'est jamais compté.

pm2 set pm2-dashboard-vision:max_attempts 5     # 0 = désactive
pm2 set pm2-dashboard-vision:block_minutes 15
pm2 restart pm2-dashboard-vision

Le compteur d'une IP est remis à zéro dès une connexion réussie. La protection n'est active que si l'auth admin l'est aussi.

Journal d'audit

Chaque action (restart / stop / start / reload / delete / flush) est tracée : horodatage, IP, rôle, action, cible et résultat (ok, denied, error…). Les tentatives refusées d'un observateur y figurent aussi.

• Consultable depuis le bouton « Journal » du dashboard (admin uniquement).
• Également écrit dans les logs PM2 du module (préfixe [AUDIT]) — donc persistant même après redémarrage, alors que le journal en mémoire (dernières audit_max entrées) est réinitialisé.
• Accessible en API : GET /api/audit (admin).

Protection CSRF

Les requêtes destructives (POST /api/action) vérifient l'en-tête Origin : une page web tierce ne peut pas déclencher d'action depuis ton navigateur (rejet 403). Les appels sans navigateur (curl, scripts) ne sont pas concernés.

Limites à connaître

• HTTP Basic sur HTTP simple protège du curieux qui tombe sur l'URL, mais le mot de passe circule encodé (base64, non chiffré) si tu n'es pas en HTTPS. Pour une exposition publique, place un reverse-proxy HTTPS devant, ou restreins le port au firewall.
• Le mot de passe est stocké en clair dans ~/.pm2/module_conf.json (fonctionnement natif de PM2). N'y mets pas un mot de passe réutilisé ailleurs.
• Recommandé en production : garder host sur 127.0.0.1 et accéder via un tunnel SSH (ssh -L 9615:localhost:9615 user@serveur).

Endpoint JSON

Ajouter ?json à l'URL racine renvoie l'état de tous les process en JSON (utile pour scripts ou supervision externe). Les logs live ne sont pas inclus.

curl "http://<serveur>:9615/?json"
# avec authentification active :
curl -u admin:MotDePasse "http://<serveur>:9615/?json"

Réponse :

{
  "ok": true,
  "module": "pm2-dashboard-vision",
  "generated_at": "2026-07-16T18:08:07.575Z",
  "online": 12,
  "total": 24,
  "processes": [
    {
      "name": "api-server",
      "pm_id": 19,
      "status": "online",
      "cpu": 0,
      "memory": 164626432,
      "uptime": 1750000000000,
      "restarts": 0,
      "pid": 1772817,
      "exec_mode": "fork_mode",
      "node_version": "16.13.2",
      "is_module": false,
      "metrics": { "Event Loop Latency": "2.10ms", "HTTP P95 Latency": "1492ms" }
    }
  ]
}

L'API REST reste également disponible :

| Route | Rôle | Description | |-------|------|-------------| | GET /api/processes | tous | Liste des process (comme /?json) | | POST /api/action | admin | { action, id } — restart/stop/start/reload/delete | | POST /api/flush | admin | { id } — vide les logs PM2 du process | | GET /api/describe/:id | tous | Détail d'un process (script, cwd, versions, chemins de logs…) | | GET /api/logs/:id?type=out\|err&lines=N | tous | Tail des logs (texte brut) | | GET /api/audit | admin | Journal d'audit des actions |

Interface

• Cartes temps réel avec mini-graphes CPU/RAM (tendance sur ~1 min) en plus des jauges instantanées.
• Clic sur une carte → vue détail du process (script, répertoire, mode, versions, restarts, chemins de logs) + téléchargement des logs out/err et, pour l'admin, vider les logs PM2.
• Panneau logs en direct avec filtre par service, Télécharger (export .txt de ce qui est affiché) et Vider.
• Bouton Journal (admin) → journal d'audit des actions.

Métriques de latence

Chaque service affiche une section dépliable « Métriques » : Event Loop Latency, HTTP Mean / P95 Latency, Heap Usage, Active requests, etc.

Important : ces métriques ne sont disponibles que pour les services qui les publient eux-mêmes. PM2 ne les génère pas automatiquement — le service doit être instrumenté avec @pm2/io. Les services non instrumentés n'affichent que CPU et RAM.

Pour activer ces métriques dans un de tes services :

npm install @pm2/io

Puis en haut de son fichier d'entrée (ex. server.js) :

require('@pm2/io').init({ http: true });

Le http: true active automatiquement le suivi de la latence HTTP et de l'event loop. Après un pm2 restart <service>, les métriques apparaissent dans le dashboard.

Mise à jour

À chaque nouvelle version publiée :

pm2 install pm2-dashboard-vision

pm2 install sur un module déjà présent récupère la dernière version et le redémarre.

Stack

• @pm2/io — cycle de vie du module + metrics natives PM2
• express + ejs — serveur & templating
• socket.io — process & logs en temps réel
• API programmatique pm2 — list, launchBus, actions, axm_monitor

Licence

MIT