Dépannage
Cette page liste des symptômes courants, leur cause probable et l'action à mener. Elle se limite à des cas documentés dans le comportement de NGX Ops.
Installation et dashboard
| Symptôme |
Cause |
Action |
| La page CrowdSec reste vide ou « non disponible » |
Le conteneur NGX Ops ne joint pas CrowdSec |
Connecter le conteneur au réseau Docker de CrowdSec (voir CrowdSec) |
| Les statistiques du challenge sont vides |
Le dashboard ne joint pas le conteneur du challenge |
Les placer sur le même réseau Docker ; l'image du challenge doit être à jour |
| Le premier clone Git échoue |
Un dossier temporaire interrompu reste dans l'espace de travail Git |
NGX Ops nettoie les dossiers connus ; sinon il nomme ce qui reste, à supprimer manuellement |
| L'édition en ligne ou la restauration locale est refusée |
Git est configuré : le dépôt est la source de vérité |
Modifier le dépôt puis déployer ; git revert pour revenir en arrière |
Les réglages challenge_* ne sont pas pris en compte |
La configuration Nginx n'a pas été régénérée |
Utiliser Régénérer et recharger Nginx depuis la page Challenge HTTP |
| Les webhooks disparaissent après un redémarrage |
Ils ne sont conservés qu'en mémoire |
Les recréer, voir API REST et webhooks |
Sauvegardes
| Symptôme |
Cause |
Action |
| Des archives S3 disparaissent |
La rotation supprime les anciens .zip du préfixe |
Utiliser un préfixe dédié ; ajuster s3_keep |
Archive .ngxb illisible |
Mauvaise phrase de passe ou archive altérée |
Vérifier la variable de phrase (HUB_, S3_ ou BACKUP_) ; aucune récupération sans elle |
| Trois copies à chaque modification |
auto_local, auto_git et auto_s3 sont tous actifs |
Choisir une seule destination automatique |
Journalisation
| Symptôme |
Cause |
Action |
| Le log store refuse de démarrer |
Mode pseudonymized sans LOGSTORE_PSEUDO_KEY, ou LOGSTORE_REQUIRE_TIMESCALE=true sans TimescaleDB |
Fournir la clé (32 caractères minimum) ou une base TimescaleDB |
| Le shipper n'envoie plus |
Jeton write refusé, ou log store injoignable |
Voir GET /status du shipper ; les journaux d'accès sont rattrapés au retour, le tampon est plafonné |
| Des lignes d'accès manquent après une rotation |
Rotation par renommage vers un nom hors motif |
Utiliser copytruncate, ou un nom qui correspond au motif |
| Des décisions manquent |
Le shipper était arrêté : elles ne sont pas rejouées |
Comportement accepté ; garder le shipper démarré |
| Une statistique expire |
Période trop longue sur un gros volume (délai de 15 s) |
Réduire la période, voir Capacité du log store |
Hub
| Symptôme |
Cause |
Action |
| Instance « Hors ligne » |
3 échecs consécutifs de collecte |
Vérifier l'URL HTTPS, le certificat, HUB_TOKEN_SHA256 côté dashboard |
| Instance refusée sur un réseau privé |
Protection contre les requêtes vers l'interne |
Régler security.allow_private_networks ou allowed_cidrs |
| Jetons et MFA illisibles après une restauration |
HUB_SECRET_KEY perdue ou différente |
Restaurer la clé d'origine avec /data |
Mot de passe admin perdu |
— |
docker compose exec hub node bin/hub-admin.js set-password admin --must-change |
| L'archive ne s'ouvre pas dans le navigateur |
HTTPS (ou localhost) requis, ou mauvaise phrase |
Passer en HTTPS ; utiliser ngxb-decrypt.js en secours |
Agents distants
| Symptôme |
Cause |
Action |
| L'agent ne démarre pas |
--relay-*-advertise est un simple numéro de port |
Donner l'adresse complète, par exemple http://10.0.5.9:8080 |
| Erreur 502 en mode relay vers un service HTTPS |
Certificat auto-signé refusé par l'agent |
Activer RELAY_BACKEND_INSECURE_SKIP_VERIFY=true |
| Le jeton n'est plus affiché |
Il ne l'est qu'une fois |
Régénérer le jeton depuis la page Hôtes distants |
| WebSocket ou SSE ne passe pas |
Mode tunnel : non pris en charge |
Passer le vhost en mode relay |
Pour comprendre l'état d'un hôte virtuel, la page Diagnostic teste ses backends et affiche sa configuration. L'état de chaque composant est visible via Santé et Redis.