Monitoring operations

Le monitoring serveur surveille la sante du materiel ; le monitoring reseau surveille le trafic. Le monitoring operations, lui, surveille le quotidien de l'application : les erreurs que rencontrent les utilisateurs, la securite des dependances logicielles, le bon deroulement des taches automatiques, et l'historique de ce qui a ete deploye en production. C'est la vue "jour apres jour" de l'exploitation de BeePass.

Logs d'erreurs API

Quand un utilisateur rencontre une erreur 500 (erreur interne du serveur), il voit un message generique. Mais en coulisses, BeePass enregistre automatiquement tous les details de l'erreur --- la route API concernee, le message d'erreur, la trace d'execution --- pour permettre un diagnostic rapide. Sans ce systeme, il faudrait fouiller manuellement dans les logs Docker, ce qui est chronophage et peu fiable.

Tous les appels API qui retournent un code HTTP 500 sont automatiquement enregistres dans la table api_error_logs via le helper errorResponse(). Ce mecanisme est fire-and-forget (tirer et oublier) : l'enregistrement en base ne bloque pas la reponse au client.

Colonnes du tableau

Colonne	Description
Date	Horodatage de l'erreur
Route	Chemin de l'API concernee (ex : `/api/admin/users`, `/api/queens/f0`)
Methode	Verbe HTTP : `GET`, `POST`, `PUT`, `DELETE`
Message d'erreur	Description de l'erreur capturee
Utilisateur	Identifiant anonymise de l'utilisateur concerne
IP	Adresse IP du client
Stack trace	Trace d'execution detaillee (panneau deroulant) --- montre la suite d'appels de fonctions qui a conduit a l'erreur

Filtres et recherche

Pour retrouver rapidement une erreur parmi potentiellement des centaines, plusieurs filtres sont disponibles :

Filtre	Description
Route	Filtrer par chemin d'API specifique (utile pour isoler les erreurs d'un module)
Methode HTTP	Filtrer par verbe (`GET`, `POST`, `PUT`, `DELETE`)
Plage de dates	Selectionner une periode de debut et de fin
Recherche textuelle	Recherche libre dans le message d'erreur

Cartes de statistiques

Trois cartes en haut de page donnent une vision rapide de la situation :

Carte	Description
Erreurs aujourd'hui	Nombre d'erreurs API enregistrees dans les dernieres 24 heures
Routes distinctes	Nombre de routes API differentes ayant genere des erreurs (aide a savoir si le probleme est localise ou generalise)
Total (30 jours)	Nombre cumule d'erreurs sur les 30 derniers jours

Retention des donnees

Les logs d'erreurs API sont conserves pendant 30 jours. Au-dela, ils sont automatiquement purges par le cron job "Nettoyage erreurs API". Cette retention est un compromis entre la capacite de diagnostic (pouvoir remonter dans le temps) et l'espace disque.

Monitoring des erreurs

L'erreur API est enregistree via errorResponse() qui remplace le pattern console.error + return 500. Cela centralise le logging dans un seul endroit et evite les oublis. Chaque erreur est inseree en base de maniere non-bloquante --- l'utilisateur recoit sa reponse sans attendre que le log soit ecrit.

Erreurs Peppermint

Les erreurs liees au centre de support Peppermint (serveur inaccessible en dev) retournent un code 503 via la classe PeppermintUnavailableError et ne sont pas enregistrees dans api_error_logs. Ce comportement evite de polluer les logs et les notifications en environnement de developpement, ou Peppermint n'est pas lance. Les 11 points d'interception dans le code renvoient un 503 propre sans logger.

Route API

Route	Methode	Description
`/api/admin/error-logs`	GET	Liste paginee avec filtres (route, methode, dates, recherche)
`/api/admin/error-logs`	DELETE	Purge manuelle des logs

Taches planifiees (Cron Jobs)

Un serveur ne se gere pas uniquement en reagissant aux problemes : il faut aussi s'assurer que les taches automatiques (sauvegardes, nettoyage, mises a jour) s'executent correctement et dans les temps. La carte "Taches planifiees" joue ce role de sentinelle : elle verifie que chaque tache a bien tourne recemment et signale celles qui sont en retard.

Page : /backoffice/monitoring --- carte "Taches planifiees" (cote droit, grid 2 colonnes)

Jobs monitores

Chaque tache est verifiee selon une logique propre. Par exemple, pour le backup, on verifie l'age du dernier fichier .dump ; pour le nettoyage des erreurs, on compte les entrees obsoletes :

Tache	Planification	Source de la date	Logique de statut
Backup PostgreSQL	Quotidien 03:00 UTC	Fichier `.dump` le plus recent dans `/data/backups`	OK si < 26h, Warning si < 48h, Critical sinon
Snapshot Hetzner	Dimanche 04:00 UTC	Pas de donnee locale disponible	Toujours "Inconnu" (le snapshot est gere cote Hetzner Cloud)
Verification mises a jour	Manuel	`checked_at` dans `/data/upgradable.json`	OK si < 7 jours, Warning sinon
Nettoyage erreurs API	Retention 30 jours	COUNT `api_error_logs` avec date > 30j	OK si 0 vieux logs, Warning sinon
Generation changelog	Au deploiement	mtime du fichier `/data/changelog.json`	OK si < 7 jours, Warning sinon

Badges de statut

Badge	Couleur	Signification
OK	Vert	La tache s'est executee dans les temps --- tout va bien
En retard	Ambre	La tache a depasse le delai attendu --- a surveiller
Critique	Rouge	La tache est tres en retard ou a echoue --- action necessaire
Inconnu	Gris	Pas de donnee disponible pour determiner le statut (ex : snapshot Hetzner)

Audit de securite automatique

En complement des cron jobs systeme, un audit de securite complet est planifie automatiquement. L'objectif est de detecter les nouvelles vulnerabilites chaque jour, sans intervention humaine :

Declencheur	Horaire	Description
Cron quotidien	03:30 UTC	Execution des 19 outils de scan du Centre de securite
Post-deploiement	Apres chaque `deploy.sh`	Audit declenche automatiquement pour verifier que la nouvelle version n'a pas introduit de vulnerabilite

Le crontab serveur :

30 3 * * * /opt/beepass/scripts/cron-security.sh >> /var/log/beepass-cron.log 2>&1

L'endpoint /api/cron/security-audit est protege par un Bearer token (CRON_SECRET) verifie via timingSafeEqual (une methode de comparaison qui resiste aux attaques par timing --- elle prend toujours le meme temps pour comparer, qu'il y ait 0 ou 10 caracteres corrects).

Route API

Route	Methode	Description
`/api/admin/jobs`	GET	5 taches agregees multi-sources (backup, snapshot, upgrades, error cleanup, changelog)

Rafraichissement

Polling automatique : toutes les 5 minutes
Focus refetch : quand l'onglet reprend le focus

Audit des dependances

Un projet Node.js comme BeePass depend de centaines de packages (bibliotheques tierces). Chacun de ces packages peut contenir des failles de securite decouvertes apres sa publication. L'audit des dependances scanne ces packages pour detecter les vulnerabilites connues et recommander des mises a jour --- un peu comme un rappel de produit dans l'industrie automobile.

Tableau des vulnerabilites

Colonne	Description
Severite	Niveau de criticite : `critical` (faille exploitable immediatement), `high` (risque eleve), `medium`, `low`
CVE	Identifiant CVE (Common Vulnerabilities and Exposures --- le numero unique de la faille dans la base mondiale) avec lien vers la base National Vulnerability Database
Package	Nom du package NPM affecte
Version installee	Version actuellement utilisee dans le projet
Version corrigee	Version minimale contenant le correctif
Remediation	Etapes recommandees pour corriger la vulnerabilite

Les vulnerabilites sont triees par severite decroissante : les critical et high apparaissent en premier car elles necessitent une action rapide.

Contraintes architecturales

Le panneau liste egalement les contraintes de compatibilite entre dependances. Parfois, mettre a jour un package pour corriger une faille casse la compatibilite avec un autre package du projet --- c'est le dilemme classique des dependances imbriquees.

Actions

Action	Description
Rafraichir l'audit	Relance `npm audit` et met a jour les resultats

Resolution des vulnerabilites

Avant d'appliquer un npm audit fix, verifiez les contraintes architecturales listees. Une mise a jour automatique peut casser des dependances peer (des packages qui doivent etre dans une version specifique pour fonctionner ensemble). Privilegiez les mises a jour manuelles ciblees avec npm install package@version.

Route API

Route	Methode	Description
`/api/admin/dependencies`	GET	Resultat de `npm audit --json` avec parsing et classification

Changelog et deploiements

Chaque deploiement en production modifie le code qui tourne sur le serveur. Pour garder une tracabilite complete --- savoir ce qui a change, quand et pourquoi --- le panneau changelog affiche l'historique des commits Git deployes en production, organises par type et filtrables. C'est l'equivalent d'un journal de bord de l'application.

Classification des commits

Les commits sont automatiquement categorises par leur prefixe conventionnel (une convention d'ecriture ou le type de changement est indique au debut du message) :

Type	Prefixe	Description
Feature	`feat:`	Nouvelle fonctionnalite
Fix	`fix:`	Correction de bug
Performance	`perf:`	Amelioration des performances
Refactoring	`refactor:`	Restructuration du code sans changement fonctionnel
Documentation	`docs:`	Mise a jour de la documentation
Chore	`chore:`	Taches de maintenance (CI, configs, dependances)
Style	`style:`	Changements cosmetiques (formatage, nommage)
Test	`test:`	Ajout ou modification de tests
Autre	---	Commits ne correspondant a aucun prefixe conventionnel

Filtres et recherche

Filtre	Description
Type de commit	Filtrer par categorie (`feat`, `fix`, `docs`, etc.) --- utile pour voir "toutes les nouvelles fonctionnalites depuis un mois"
Recherche	Recherche libre dans le message de commit
Pagination	Navigation par pages pour les historiques longs

Cartes de statistiques

Carte	Description
Total commits	Nombre total de commits deployes
Features	Nombre de commits de type `feat`
Fixes	Nombre de commits de type `fix`

Generation du changelog

Le changelog est genere automatiquement par le script generate-changelog.mjs lors de chaque deploiement. Voici la sequence complete d'un deploiement, du code source au serveur en production :

1. git pull                   --> Recuperation du code source
   v
2. generate-changelog.mjs    --> Extraction et classification des commits
   v
3. docker compose build      --> Construction des images Docker
   v
4. docker compose up -d      --> Demarrage des nouveaux containers
   v
5. security-audit (post-deploy) --> Audit de securite automatique (background)
   v
6. docker system prune -af   --> Nettoyage images/cache inutilises (libere l'espace disque)

Commandes de deploiement

# Deploiement automatise (depuis la machine locale)
./scripts/deploy.sh          # web (changelog + build + restart + prune + security audit)
./scripts/deploy.sh worker   # worker (git SHA + build + restart + prune)
./scripts/deploy.sh docs     # docs (build + restart + prune)
./scripts/deploy.sh all      # les 3 d'un coup

# Deploiement manuel (depuis le serveur)
cd /opt/beepass && git pull
docker run --rm -v /opt/beepass:/app -w /app node:20-alpine sh -c \
  'apk add --no-cache git >/dev/null 2>&1 && node scripts/generate-changelog.mjs'
docker compose build --no-cache beepass-web
docker compose up -d beepass-web

Deploiement

Le script deploy.sh execute automatiquement toute la sequence. Il declenche egalement un audit de securite post-deploiement via curl /api/cron/security-audit?trigger=post_deploy (non-bloquant, en arriere-plan). Le rapport est visible dans /backoffice/security-reports avec triggered_by = 'post_deploy'.

Route API

Route	Methode	Description
`/api/admin/changelog`	GET	Liste des commits avec classification, filtres, pagination

Mises a jour serveur (Server Upgrades)

Le serveur Ubuntu a lui aussi des mises a jour de securite et de stabilite. Comme les dependances npm, les packages systeme (apt) peuvent contenir des failles corrigees par de nouvelles versions. La carte Server Upgrades permet de verifier et d'appliquer ces mises a jour directement depuis le backoffice, sans se connecter en SSH.

Fonctionnalites

Liste des packages : nom, version actuelle, version disponible
Verification manuelle : bouton pour relancer la verification (apt list --upgradable)
Application : bouton pour appliquer les mises a jour (apt upgrade -y)
Fichier source : /data/upgradable.json (genere par la commande de verification)

Route API

Route	Methode	Description
`/api/admin/server-upgrades`	GET	Liste des packages upgradable
`/api/admin/server-upgrades`	POST	Lancer verification ou appliquer mises a jour

Toutes les commandes admin utiles

Pour les cas ou l'interface ne suffit pas, voici les commandes les plus utiles a lancer en SSH sur le serveur :

# Monitoring
docker compose ps                                # Etat des services (equivalent du tableau Docker)
docker compose logs -f beepass-web               # Logs temps reel du frontend
docker compose logs --tail 50 beepass-worker     # Les 50 dernieres lignes du worker
docker ps --format 'table {{.Names}}\t{{.Status}}'  # Sante de tous les containers en un coup d'oeil

# Backups
docker exec beepass-backup /backup.sh            # Backup manuel (equivalent du bouton "Lancer un backup")
docker exec beepass-backup ls -lh /data/backups/ # Voir la liste des backups sur le disque

# Worker
curl http://127.0.0.1:8000/health                # Verifier que le worker est vivant
curl http://127.0.0.1:8000/health/db             # Verifier que le worker peut se connecter a la DB
curl -X POST http://127.0.0.1:8000/db/reset-pool # Reinitialiser le pool de connexions DB (utile apres un probleme de connexion)

# Prometheus / Grafana
curl -s http://localhost:9090/-/healthy           # Prometheus est-il en bonne sante ?
curl -s http://localhost:9100/metrics | head -50  # Echantillon des metriques systeme
curl -s http://localhost:9187/metrics | head -50  # Echantillon des metriques PostgreSQL

# Securite
bash scripts/cron-security.sh                    # Lancer un audit de securite manuellement

# Nettoyage
docker system prune -af                          # Nettoyer les images et caches Docker inutilises

Workflow recommande

Verification quotidienne

Cette routine de 30 secondes permet de detecter la plupart des problemes avant qu'ils n'impactent les utilisateurs :

Ouvrir /backoffice --- verifier le widget Server Health (jauges vertes)
Ouvrir la cloche --- verifier qu'aucune notification synthetique rouge n'apparait
Si alerte : cliquer le lien dans la notification pour acceder a la page concernee

Apres un deploiement

Les deploiements sont les moments les plus risques --- un bug peut etre introduit par un changement de code. Voici les verifications a effectuer :

Ouvrir /backoffice/docker --- verifier que tous les containers sont Running + Healthy
Verifier que les Restarts sont a 0 (sinon investiguer les logs)
Ouvrir /backoffice/monitoring --- verifier le statut des Cron Jobs (tous verts)
Verifier /backoffice/security-reports --- le rapport post-deploy doit apparaitre

En cas de probleme serveur

Quand quelque chose ne va pas, voici la demarche de diagnostic recommandee :

/backoffice/docker --- identifier le container problematique (unhealthy, exited, restarts > 0)
Expand les logs du container pour diagnostic
Si necessaire, redemarrer le container depuis l'interface (sauf beepass-web et traefik qui sont critiques)
Verifier dans /backoffice/error-logs si des erreurs API sont liees (souvent, une erreur API est le symptome d'un probleme de container)

Voir aussi : Monitoring serveur | Monitoring reseau | Centre de securite

Logs d'erreurs API​

Colonnes du tableau​

Filtres et recherche​

Cartes de statistiques​

Retention des donnees​

Route API​

Taches planifiees (Cron Jobs)​

Jobs monitores​

Badges de statut​

Audit de securite automatique​

Route API​

Rafraichissement​

Audit des dependances​

Tableau des vulnerabilites​

Contraintes architecturales​

Actions​

Route API​

Changelog et deploiements​

Classification des commits​

Filtres et recherche​

Cartes de statistiques​

Generation du changelog​

Commandes de deploiement​

Route API​

Mises a jour serveur (Server Upgrades)​

Fonctionnalites​

Route API​

Toutes les commandes admin utiles​

Workflow recommande​

Verification quotidienne​

Apres un deploiement​

En cas de probleme serveur​

Logs d'erreurs API

Colonnes du tableau

Filtres et recherche

Cartes de statistiques

Retention des donnees

Route API

Taches planifiees (Cron Jobs)

Jobs monitores

Badges de statut

Audit de securite automatique

Route API

Rafraichissement

Audit des dependances

Tableau des vulnerabilites

Contraintes architecturales

Actions

Route API

Changelog et deploiements

Classification des commits

Filtres et recherche

Cartes de statistiques

Generation du changelog

Commandes de deploiement

Route API

Mises a jour serveur (Server Upgrades)

Fonctionnalites

Route API

Toutes les commandes admin utiles

Workflow recommande

Verification quotidienne

Apres un deploiement

En cas de probleme serveur