Dépannage

Cette page couvre les problèmes courants que vous pouvez rencontrer lors de l'exécution de bext, ainsi que les commandes de diagnostic et les correctifs.

Commandes de diagnostic#

Commencez ici. Ces commandes vous donnent un instantané de l'état du système :

bash

# Pre-flight check: validates config, checks ports, TLS paths, permissions
bext-server check

# Show loaded configuration (merged from file + env + defaults)
bext-server config show

# Print the route table for the current app
bext-server routes

# Cache hit rates, sizes, and per-app breakdown
bext-server cache stats

# Running apps, render worker count, memory usage
bext-server ps

# Health check (DB, cache, isolates, plugins)
bext-server health

# Current metrics snapshot
bext-server metrics

Pour une sortie détaillée, ajoutez --log-level debug ou --log-level trace :

bash

bext-server --log-level debug run

Erreurs de certificat TLS#

Échec du défi ACME#

Symptôme : error: ACME HTTP-01 challenge failed for domain.com

Causes et correctifs :

Port 80 non accessible. ACME HTTP-01 nécessite du trafic entrant sur le port 80. Vérifiez les règles de pare-feu et confirmez que bext écoute sur le port 80 (il se lie automatiquement lorsque tls.auto_acme = true ).

bash

# Check if port 80 is open
ss -tlnp | grep :80

Le DNS ne pointe pas vers ce serveur. Le domaine doit être résolu en adresse IP publique du serveur. Vérifiez auprès de :

bash

dig +short domain.com
curl -I http://domain.com/.well-known/acme-challenge/test

Un autre processus sur le port 80. Si nginx ou Apache est déjà lié au port 80, arrêtez-le ou utilisez le mode de reprise nginx de bext.

Certificat non renouvelé#

Les certificats se renouvellent automatiquement 30 jours avant leur expiration. Si le renouvellement échoue, vérifiez les journaux :

bash

bext-server --log-level debug run 2>&1 | grep -i acme

Cause fréquente : la limite de taux du compte ACME a été atteinte. Attendez 1 heure et redémarrez.

Utiliser des certificats personnalisés#

Si auto-ACME ne convient pas, fournissez directement les fichiers de certificat :

toml

[tls]
auto_acme = false
cert_path = "/etc/ssl/certs/domain.pem"
key_path = "/etc/ssl/private/domain.key"

Assurez-vous que les fichiers sont lisibles par l'utilisateur du processus bext et que la chaîne de certificats est complète (feuille + intermédiaires).

Échecs du RSS#

Épuisement de la piscine V8#

Symptôme : Requêtes en file d'attente, pics de latence, les journaux affichent jsc pool: all workers busy, waiting...

Correction de : Augmentez le nombre de travailleurs de rendu :

toml

[render]
workers = 8    # default is 4, increase for high-traffic SSR

Surveillez avec les métriques render_pool_active et render_pool_idle. Si render_pool_idle tombe systématiquement à 0, ajoutez d’autres nœuds de calcul.

Délai d'expiration du rendu SSR#

Symptôme : error: SSR render timed out after 10000ms

Le rendu de vos composants React prend trop de temps côté serveur. Causes courantes :

Récupération de données à l'intérieur des composants pendant SSR (déplacement vers getServerSideProps ou actions du serveur)
Boucles infinies dans la logique de rendu
Très grands arbres de composants

Augmentez le délai d'attente en guise de palliatif, puis corrigez le problème sous-jacent :

toml

[render]
timeout_ms = 15000    # default is 10000

Le manque de mémoire (MOO) tue#

Symptôme : rend les travailleurs tués, les journaux affichent jsc worker OOM: exceeded 256MB limit

Chaque moteur de rendu a une limite de mémoire pour empêcher un seul rendu de consommer toute la RAM :

toml

[render]
worker_memory_limit_mb = 512    # default is 256

Si les rendus atteignent systématiquement cette limite, vérifiez votre code SSR pour détecter les fuites de mémoire (structures de données volumineuses, caches illimités dans la portée du module).

Problèmes de cache#

Contenu obsolète après le déploiement#

Symptôme : L'ancien contenu est toujours diffusé après le déploiement du nouveau code.

Le cache ISR et le cache de compression doivent être effacés :

bash

# Purge all caches for an app
bext-server cache purge --app my-app

# Or purge everything
bext-server cache purge --all

Si vous utilisez Redis L2, la commande de purge efface à la fois L1 et L2. Déploiements automatisés via bext deploy purge automatiquement les caches.

Bousculade du cache sous charge#

Symptôme : Pics élevés du processeur lorsque les entrées de cache expirent en cas de trafic intense.

La protection contre la bousculade de bext regroupe les requêtes simultanées pour la même URL non mise en cache. Vérifiez qu'il est actif :

bash

bext-server cache stats --json | jq '.stampede_coalesced'

Si la bousculade continue de se produire, assurez-vous que le mode obsolète pendant la revalidation (SWR) est configuré. SWR sert l'entrée obsolète tandis qu'une requête en arrière-plan la rafraîchit :

toml

[cache.isr]
default_swr_ms = 3_600_000    # serve stale for up to 1 hour while revalidating

Le cache ISR devient trop volumineux sur le disque#

Le cache ISR est en mémoire par défaut (limité par max_entries ). Si Redis L2 est activé, Redis peut croître. Définissez un TTL sur les entrées L2 :

toml

[cache.isr]
l2_ttl_ms = 300_000    # Redis entries expire after 5 minutes

Problèmes de plugins#

Délai d'expiration du plugin#

Symptôme : warn: plugin "my-plugin" timed out after 5000ms

Les plugins ont un délai d'exécution par défaut pour empêcher l'emballement du code :

toml

[plugins]
timeout_ms = 10000    # increase from default 5000

Pour les plugins WASM, vérifiez si le plugin effectue des E/S coûteuses. Pour les plugins QuickJS, recherchez les boucles infinies.

Crash / panique du plugin#

Symptôme : error: plugin "my-plugin" panicked: ...

Les plugins s'exécutent dans des bacs à sable isolés, donc un crash ne met pas le serveur hors service. Le plugin est désactivé pour les requêtes ultérieures jusqu'à ce qu'il soit rechargé.

Recharger les plugins sans redémarrer le serveur :

bash

kill -HUP $(cat /run/bext.pid)

Vérifiez les journaux du plugin au niveau debug pour voir la trace de panique.

Limites de mémoire du plugin#

Les plugins WASM ont des limites de mémoire configurables :

toml

[plugins.wasm]
max_memory_mb = 64    # per-plugin memory limit

Utilisation élevée du processeur#

Transformer le pipeline#

Si le processeur est élevé et que la métrique http_request_duration_seconds affiche de longues traînes, le pipeline de transformation (compilation TypeScript, transformations JSX) peut constituer le goulot d'étranglement. En production, les transformations doivent avoir lieu au moment de la construction, et non par requête :

bash

# Build once for production
bext-server build

# Then run the built output
bext-server run

Optimisation des images#

Le redimensionnement d'image à la volée est gourmand en CPU. Activez le cache d'images pour éviter le retraitement :

toml

[image]
cache = true
cache_dir = "/var/cache/bext/images"
max_width = 2048
quality = 80

Pré-générez des tailles communes lors de la création pour les images à fort trafic.

Espace disque#

Les fichiers journaux augmentent#

Activer la rotation des journaux :

toml

[logging]
rotate = true
rotate_max_size_mb = 100
rotate_max_files = 10
rotate_compress = true

Ou utilisez logrotate en externe :

code

/var/log/bext/*.log {
    daily
    rotate 14
    compress
    missingok
    notifempty
    postrotate
        kill -USR1 $(cat /run/bext.pid)
    endscript
}

Le signal USR1 indique à bext de rouvrir les fichiers journaux après la rotation.

Croissance du cache d’images#

Définissez une taille maximale pour le cache d'optimisation d'image :

toml

[image]
cache_max_size_mb = 2048    # evict LRU entries above 2GB

Obtenir de l'aide#

Si ces étapes ne résolvent pas votre problème :

Exécutez bext-server check --fail-on-warnings et incluez la sortie
Définissez le niveau de journalisation sur debug et capturez les lignes de journal pertinentes
Vérifiez le Problèmes GitHub pour les problèmes connus
Ouvrez un nouveau problème avec votre version de bext ( bext-server version ), votre système d'exploitation, votre fichier de configuration (expurger les secrets) et la sortie d'erreur complète

Conseil

bext-server check --fail-on-warnings est la première étape la plus rapide avant de déposer un problème. Il valide la configuration, vérifie la disponibilité des ports, les chemins TLS et les autorisations, et révèle souvent la mauvaise configuration exacte à l'origine du symptôme.

En rapport#

Codes d'erreur — codes E_ stables avec prose par code, exemples et étapes suivantes
Enregistrement — configuration du niveau de journalisation et comment réduire le bruit au niveau du module
Surveillance — Métriques Prometheus pour détecter l'épuisement du pool, les pics de taux d'erreur et la dégradation du cache
Invalidation et redémarrages — surfaces par site et par cache pour résoudre le contenu obsolète sans redémarrage complet
Guides : mise en cache — Mécanismes de garde ISR, périmés pendant la revalidation et de bousculade