Migration de nginx vers bext

Ce guide explique le remplacement de nginx par bext, du test de votre configuration à un basculement complet de la production.

Conseil

Commencez par bext nginx check (étape 1) avant de toucher quoi que ce soit. Il est en lecture seule et affichera toutes les directives non prises en charge avec des numéros de fichier et de ligne exacts.

Étape 1 : testez votre configuration#

Avant d'apporter des modifications, vérifiez que bext peut analyser votre configuration nginx :

bash

# Auto-detect and validate
bext nginx check

# Or specify a path
bext nginx check --nginx-config /etc/nginx/nginx.conf

bext rapportera :

Nombre d'hôtes virtuels détectés
Nombre de blocs en amont
Chemins de certificat SSL
Toutes les directives non prises en charge (avec des emplacements file:line)

Étape 2 : Exécuter côte à côte#

Démarrez bext sur un autre port pour tester avec votre nginx en cours d'exécution :

bash

# Run bext on port 8080, reading your nginx config
bext serve --nginx-config /etc/nginx/nginx.conf --port 8080

Testez les points de terminaison individuels :

bash

# Compare responses
curl -H "Host: example.com" http://localhost:80/api/health   # nginx
curl -H "Host: example.com" http://localhost:8080/api/health  # bext

Étape 3 : Utiliser le tableau de bord de contrôle en amont#

Pour un aperçu visuel de tout ce que bext a détecté :

bash

sudo bext nginx-takeover --port 9999

Ouvrez http://localhost:9999 dans votre navigateur. Le tableau de bord affiche :

Tous les hôtes virtuels avec leurs noms de serveur, ports et emplacements
Certificats SSL et leurs dates d'expiration
Backends en amont et stratégies d’équilibrage de charge
Avertissements de conversion pour toute directive non prise en charge
Huit vérifications en amont (configuration analysée, certificats SSL accessibles, ports disponibles, etc.)

Étape 4 : Choisissez votre chemin de migration#

Option A : commutation rapide (mode mascarade)#

Remplacez entièrement nginx par une seule commande :

bash

sudo bext nginx masquerade install

Ce:

Sauvegarde votre véritable binaire nginx sur /usr/sbin/nginx.real
Installe une cale bext à /usr/sbin/nginx
Crée un drop-in systemd qui exécute bext au lieu de nginx
Exécute systemctl daemon-reload

Après l'installation, systemctl restart nginx démarre bext — et tous les outils existants (certbot, logrotate, surveillance) continuent de fonctionner sans changement.

Pour annuler :

bash

sudo bext nginx masquerade uninstall

Option B : rachat atomique#

Utilisez le processus de reprise pour une migration contrôlée et réversible :

bash

sudo bext nginx-takeover

Le Processus de rachat arrête le nginx, lie le bext aux ports 80/443 et fournit un bouton de restauration en cas de problème.

Option C : Migration progressive#

Exécutez d'abord bext derrière nginx en tant que proxy inverse, puis migrez les services un par un :

nginx

# nginx proxying to bext for specific paths
location /api/ {
    proxy_pass http://127.0.0.1:3000;
}

Une fois que vous avez validé que bext gère correctement votre trafic, passez à l'option A ou B.

Référence rapide du mappage de configuration#

nginx	équivalent à bext
`nginx.conf`	Analysé automatiquement – aucune configuration bext nécessaire
`sites-available/`	Détecté via les directives `include`
`upstream {}`	Converti en pools en amont bext
`proxy_cache_path`	Mappé sur le cache hiérarchisé de bext
`ssl_certificate`	Chargé dans le résolveur SNI
`limit_req_zone`	Converti en limiteur de taux de compartiment de jetons
`auth_basic_user_file`	htpasswd chargé avec le support bcrypt
Rechargement `SIGHUP`	Pris en charge : configuration + certificats TLS rechargés à chaud
Réouverture du journal `SIGUSR1`	Pris en charge – compatible avec la rotation
`/run/nginx.pid`	Écrit et géré par bext

Modèles courants#

Redirection HTTPS#

nginx:

nginx

server {
    listen 80;
    server_name example.com;
    return 301 https://$host$request_uri;
}

bext gère cela de la même manière : la directive return est convertie et exécutée au niveau du serveur avant la correspondance d'emplacement.

PHP/ Laravel#

nginx:

nginx

location ~ \.php$ {
    fastcgi_pass unix:/run/php/php-fpm.sock;
    fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
    include fastcgi_params;
}

bext transmet les requêtes PHP via FastCGI à vos pools PHP-FPM existants. Pour ignorer FPM et exécuter PHP dans le runtime de travail intégré de bext, consultez le Intégration Laravel.

SPA avec API back-end#

nginx:

nginx

location /api/ {
    proxy_pass http://backend;
}

location / {
    try_files $uri $uri/ /index.html;
}

Le proxy et les try_files sont entièrement pris en charge, y compris le modèle de secours SPA.

WebSocket Proxy#

nginx:

nginx

location /ws/ {
    proxy_pass http://backend;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
}

bext détecte automatiquement les en-têtes de mise à niveau WebSocket et gère la mise à niveau de la connexion.

Sites WordPress / PHP-FPM#

bext détecte automatiquement les sites WordPress et achemine les requêtes PHP via FastCGI vers vos sockets PHP-FPM existants. Il n'y a pas de runtime PHP intégré à installer ou à configurer : bext agit comme un proxy FastCGI pour les pools PHP-FPM déjà exécutés sur votre serveur.

Comment fonctionne la détection#

Lorsque bext analyse votre configuration nginx, il identifie les sites WordPress en recherchant :

Un fichier wp-config.php à la racine du document
Un répertoire wp-content/ à la racine du document

Si l’un ou l’autre est trouvé, le site est marqué comme site WordPress et le routage est configuré en conséquence.

Détection de versions PHP#

bext extrait la version PHP du nom du socket FPM. Par exemple:

unix:/run/php/php8.4-fpm.sock → PHP 8.4
unix:/run/php/php8.1-fpm.sock → PHP 8.1

Ceci est utilisé pour la création de rapports dans bext nginx list et les métadonnées de synchronisation dans le cloud.

Service d'actifs statiques#

Les actifs statiques sous wp-content/ (CSS, JS, images, polices) sont servis directement par bext sans passer par PHP. Cela correspond au modèle nginx location ~* \.(css|js|png|jpg|...)$ typique et évite une surcharge PHP inutile.

Routage WordPress#

Tous les itinéraires WordPress standard fonctionnent correctement :

wp-admin/ — tableau de bord d'administration
wp-login.php — page de connexion
xmlrpc.php — API XML-RPC
Tous les fichiers PHP — acheminés via FastCGI vers PHP-FPM
try_files $uri /index.php — de jolis permaliens sont gérés ; les requêtes qui ne correspondent pas à un fichier statique passent à index.php avec l'URI d'origine

Aucune modification de votre installation WordPress ou de votre configuration PHP-FPM n'est nécessaire.

Après la migration#

Une fois que bext diffuse votre trafic :

SIGHUP recharge la configuration et les certificats TLS (l'intégration de certbot fonctionne inchangée)
SIGUSR1 rouvre les fichiers journaux (la rotation fonctionne inchangée)
Fichier PID à /run/nginx.pid (les outils de surveillance fonctionnent inchangés)
nginx -t teste la syntaxe de configuration (via la cale bext)
nginx -s reload envoie SIGHUP (via la cale bext)

Votre outil opérationnel existant doit fonctionner sans modification.

Synchronisation dans le cloud#

Après la migration, enregistrez tous vos sites dans le tableau de bord bext cloud avec une seule commande. Le tableau de bord cloud sur le cloud . bext.dev affiche tous les sites regroupés par client, avec leurs domaines, types de framework et statut SSL.

Authentification#

Tout d’abord, authentifiez-vous auprès du cloud :

bash

bext login

Cela stocke votre clé API localement. Vous pouvez également définir BEXT_CLOUD_API_KEY sur la machine CLI et sur le serveur cloud.

Synchronisation des sites#

bash

# 1. See all detected vhosts with stable IDs
bext nginx list

# 2. Compare local nginx config vs cloud state
bext nginx diff

# 3. Sync everything to the cloud
bext nginx sync-cloud

# 4. Or sync specific vhosts only
bext nginx sync-cloud --only a282,5427

# 5. Preview first with --dry-run
bext nginx sync-cloud --dry-run

Ce qui est synchronisé#

La synchronisation envoie les métadonnées suivantes pour chaque hôte virtuel :

Nom du projet — dérivé du domaine principal
Domaines — toutes les entrées server_name
Type de framework — statique, proxy/ hono, PHP/ laravel, PHP/ wordpress, etc.
Chemins racine — répertoires racine du document
Sockets PHP-FPM — chemins de socket et version PHP détectée
Expiration du certificat SSL — analysé à partir des fichiers de certificat

La synchronisation détecte le framework de chaque vhost et crée un projet avec tous ses domaines. Les projets existants sont ignorés — de nouveaux domaines sont toujours ajoutés.

Différence et nettoyage#

Utilisez bext nginx diff pour comparer la configuration locale et l'état du cloud. Chaque hôte virtuel est classé comme synchronisé, nouveau, dérive (incompatibilité de domaine) ou obsolète (dans le cloud mais pas dans nginx).

Pour nettoyer les projets qui n'ont plus de vhost correspondant dans nginx :

bash

bext nginx remove-cloud --only c02c

L'URL du cloud est par défaut http://localhost:3025 (remplacer par --cloud-url ou BEXT_CLOUD_URL ).

Restauration#

Si vous devez revenir au nginx d'origine, le processus dépend du chemin de migration que vous avez utilisé.

Restauration du mode mascarade#

Si vous avez utilisé le mode mascarade (Option A), désinstallez le shim et redémarrez nginx :

bash

# Restore the real nginx binary from /usr/sbin/nginx.real
sudo bext nginx masquerade uninstall

# Start the original nginx
sudo systemctl restart nginx

Cela supprime la cale bext de /usr/sbin/nginx, restaure le binaire d'origine, supprime le drop-in systemd et exécute systemctl daemon-reload.

Restauration du script de migration#

Si un script de rollback a été généré lors de la migration, vous pouvez l'utiliser directement :

bash

sudo ./rollback.sh

Le script effectue les mêmes étapes : restaure le binaire d'origine, supprime les remplacements systemd et redémarre nginx.

Restauration du mode de reprise#

Si vous avez utilisé le processus de prise de contrôle (option B), le tableau de bord de contrôle en amont comprend un bouton de restauration. Vous pouvez également arrêter bext et démarrer nginx :

bash

sudo systemctl stop bext
sudo systemctl start nginx

Vérification de la restauration#

Après la restauration, vérifiez que nginx est en cours d'exécution :

bash

nginx -v          # Should show the real nginx version
systemctl status nginx   # Should show active (running)
curl -I http://localhost # Should return nginx server header

En rapport#

Aperçu de la compatibilité nginx — ce que bext comprend d'une configuration nginx
Tableau de bord de contrôle en amont — inspection visuelle avant migration (étape 3 ci-dessus)
Mode mascarade - comment fonctionnent le binaire shim, le drop-in systemd et les signaux
Processus de rachat — basculement du trafic atomique avec restauration automatique
Couverture de la directive — liste complète des directives prises en charge
TLS et HTTPS — rechargement à chaud du certificat et intégration de certbot après la migration