Erreur 503 sur Apache

Diagnostic : Identifier la cause

Étape 1 : Vérifier les logs Apache

# Logs d'erreur (le plus important)
$ tail -100 /var/log/apache2/error.log

# Sur CentOS/RHEL
$ tail -100 /var/log/httpd/error_log

# Filtrer les erreurs 503
$ grep "503" /var/log/apache2/access.log | tail -50

# Erreurs en temps réel
$ tail -f /var/log/apache2/error.log

Messages d’erreur courants

# PHP-FPM down
[proxy_fcgi:error] [pid 1234] (111)Connection refused: AH01079: 
failed to make connection to backend: /run/php/php8.2-fpm.sock
→ PHP-FPM n'écoute pas sur le socket

# Backend timeout
[proxy_fcgi:error] [pid 1234] AH01075: Error dispatching request to : 
(polling) backend connection timed out
→ PHP-FPM ne répond pas assez vite

# Tous les workers occupés
[mpm_event:error] [pid 1234] AH00485: scoreboard is full, not at MaxRequestWorkers
→ Plus de workers disponibles

# Limite de fichiers atteinte
[core:error] [pid 1234] (24)Too many open files: AH00024: 
Couldn't create accept lock
→ Limite système ulimit atteinte

# mod_php memory exhausted
[core:notice] [pid 1234] PHP Fatal error: Allowed memory size exhausted
→ Script PHP dépasse la limite mémoire

Étape 2 : Vérifier l’état d’Apache

# État du service
$ systemctl status apache2
# ou sur CentOS/RHEL
$ systemctl status httpd

# Processus Apache
$ ps aux | grep apache2 | head -10

# Connexions actives
$ ss -tlnp | grep apache2

# Workers actifs (si mod_status activé)
$ curl -s http://localhost/server-status?auto | grep -E "^(Busy|Idle)Workers"
BusyWorkers: 45
IdleWorkers: 5

Étape 3 : Vérifier les backends

# PHP-FPM
$ systemctl status php8.2-fpm
$ ps aux | grep php-fpm

# Socket existe ?
$ ls -la /run/php/php8.2-fpm.sock

# Test de connexion au socket
$ php -r "var_dump(stream_socket_client('unix:///run/php/php8.2-fpm.sock'));"

Problème 2 : Workers MPM épuisés

Tous les workers Apache sont occupés, les nouvelles requêtes sont refusées.

Diagnostic

# Voir les workers actifs
$ curl -s http://localhost/server-status?auto 2>/dev/null | grep Workers
BusyWorkers: 150
IdleWorkers: 0  # ← Aucun worker libre !

# Ou via les processus
$ ps aux | grep apache2 | wc -l
152

# Logs
$ grep "scoreboard is full" /var/log/apache2/error.log
[mpm_event:error] AH00485: scoreboard is full, not at MaxRequestWorkers

Solutions

Solution 1 : Augmenter les workers MPM Event

<IfModule mpm_event_module>
    # Processus serveur
    StartServers             4
    MinSpareThreads          75
    MaxSpareThreads          250
    
    # Threads par processus
    ThreadsPerChild          25
    
    # Maximum total de connexions simultanées
    # MaxRequestWorkers = ServerLimit * ThreadsPerChild
    MaxRequestWorkers        400
    ServerLimit              16
    
    # Connexions en file d'attente
    ListenBacklog            511
    
    # Recyclage des processus (évite memory leaks)
    MaxConnectionsPerChild   10000
</IfModule>

$ systemctl restart apache2

Solution 2 : Augmenter les workers MPM Prefork (si mod_php)

<IfModule mpm_prefork_module>
    StartServers             5
    MinSpareServers          5
    MaxSpareServers          10
    
    # Maximum de processus simultanés
    # Attention : chaque processus consomme ~50-100 Mo avec mod_php
    MaxRequestWorkers        150
    ServerLimit              150
    
    MaxConnectionsPerChild   3000
</IfModule>

Solution 3 : Passer à MPM Event + PHP-FPM

Si vous êtes encore en prefork + mod_php, la migration vers event + PHP-FPM améliore drastiquement les performances :

# Désactiver mod_php et prefork
$ a2dismod php8.2
$ a2dismod mpm_prefork

# Activer event et proxy_fcgi
$ a2enmod mpm_event
$ a2enmod proxy_fcgi

# Configurer PHP-FPM
$ a2enconf php8.2-fpm

$ systemctl restart apache2

Problème 4 : Configuration .htaccess

Le fichier .htaccess peut retourner explicitement une 503 ou créer des boucles.

Diagnostic

# Vérifier les .htaccess récemment modifiés
$ find /var/www -name ".htaccess" -mtime -1

# Chercher des règles 503
$ grep -r "503\\|maintenance" /var/www/*/.htaccess

Configuration maintenance via .htaccess

# ============================================
# MODE MAINTENANCE
# Décommenter pour activer
# ============================================

RewriteEngine On

# 1. Exclure votre IP
RewriteCond %{REMOTE_ADDR} !^123\\.456\\.789\\.012$
# Ajouter d'autres IPs si besoin
# RewriteCond %{REMOTE_ADDR} !^111\\.222\\.333\\.444$

# 2. Exclure les fichiers statiques (optionnel)
RewriteCond %{REQUEST_URI} !\\.(css|js|png|jpg|gif|svg|ico|woff2?)$ [NC]

# 3. Exclure la page maintenance elle-même
RewriteCond %{REQUEST_URI} !^/maintenance\\.html$

# 4. Rediriger vers 503
RewriteRule ^(.*)$ /maintenance.html [R=503,L]

# 5. Header Retry-After
<IfModule mod_headers.c>
    Header always set Retry-After "3600"
    Header always set Cache-Control "no-store, no-cache, must-revalidate"
</IfModule>

# 6. ErrorDocument personnalisé
ErrorDocument 503 /maintenance.html

Méthode alternative plus fiable

# Méthode avec ErrorDocument (plus fiable)

<IfModule mod_rewrite.c>
    RewriteEngine On
    
    # Créer une condition de maintenance
    RewriteCond %{DOCUMENT_ROOT}/maintenance.enable -f
    RewriteCond %{REMOTE_ADDR} !^123\\.456\\.789\\.012$
    RewriteCond %{REQUEST_URI} !^/maintenance\\.html$
    RewriteCond %{REQUEST_URI} !\\.(css|js|png|jpg|gif)$ [NC]
    RewriteRule ^ - [E=MAINTENANCE:1]
</IfModule>

<IfModule mod_headers.c>
    <If "%{ENV:MAINTENANCE} == '1'">
        Header always set Retry-After "3600"
    </If>
</IfModule>

# Si variable MAINTENANCE définie, retourner 503
<If "%{ENV:MAINTENANCE} == '1'">
    ErrorDocument 503 /maintenance.html
    # Forcer le 503
    RedirectMatch 503 ^/(?!maintenance\\.html)
</If>

Activation :

# Créer le fichier flag pour activer
$ touch /var/www/monsite/maintenance.enable

# Supprimer pour désactiver
$ rm /var/www/monsite/maintenance.enable

Problème 6 : Reverse Proxy (mod_proxy)

Si Apache sert de reverse proxy vers d’autres backends.

Configuration type

<VirtualHost *:443>
    ServerName monsite.com
    
    # Activer le proxy
    ProxyPreserveHost On
    ProxyRequests Off
    
    # Backend principal
    ProxyPass / http://127.0.0.1:3000/
    ProxyPassReverse / http://127.0.0.1:3000/
    
    # Timeouts
    ProxyTimeout 60
    
    # Health check passif
    ProxyPass / http://127.0.0.1:3000/ retry=5 timeout=60
</VirtualHost>

Diagnostic

$ grep "proxy:" /var/log/apache2/error.log | tail -20

[proxy:error] AH00959: ap_proxy_connect_backend disabling worker for (127.0.0.1)
# → Backend marqué comme down

[proxy_http:error] AH01114: HTTP: failed to make connection to backend: 127.0.0.1
# → Impossible de se connecter

Solutions

Solution 1 : Load balancing avec failover

<VirtualHost *:443>
    ServerName monsite.com
    
    # Pool de backends
    <Proxy "balancer://mycluster">
        BalancerMember http://192.168.1.10:3000 loadfactor=5
        BalancerMember http://192.168.1.11:3000 loadfactor=3
        BalancerMember http://192.168.1.12:3000 status=+H  # Hot standby
        
        ProxySet lbmethod=byrequests
        ProxySet failontimeout=on
        ProxySet timeout=30
    </Proxy>
    
    ProxyPass / balancer://mycluster/
    ProxyPassReverse / balancer://mycluster/
</VirtualHost>

Solution 2 : Page d’erreur personnalisée

<VirtualHost *:443>
    # Page 503 personnalisée
    ErrorDocument 503 /errors/maintenance.html
    
    # Alias pour servir les erreurs même si proxy down
    Alias /errors /var/www/errors
    <Directory /var/www/errors>
        Require all granted
    </Directory>
    
    # Headers SEO sur les erreurs
    <Location /errors/maintenance.html>
        Header always set Retry-After "3600"
    </Location>
    
    ProxyPass /errors !  # Ne pas proxifier les erreurs
    ProxyPass / http://backend:3000/
</VirtualHost>

Solution 3 : Réactiver un backend désactivé

# Si un backend est marqué comme "in error state"
# Il faut attendre le retry ou redémarrer Apache

$ systemctl reload apache2
# ou forcer avec
$ systemctl restart apache2

Commandes Apache essentielles

# === GESTION DU SERVICE ===

# Démarrer / Arrêter / Redémarrer
$ systemctl start apache2
$ systemctl stop apache2
$ systemctl restart apache2

# Recharger la config (graceful, sans couper les connexions)
$ systemctl reload apache2
# ou
$ apachectl graceful

# === TEST ET DIAGNOSTIC ===

# Tester la configuration
$ apachectl configtest
# ou
$ apache2ctl -t
Syntax OK

# Voir la configuration effective
$ apachectl -S

# Voir les modules chargés
$ apachectl -M

# Version et compilation
$ apachectl -V

# === MODULES ===

# Activer un module
$ a2enmod rewrite
$ a2enmod headers
$ a2enmod proxy_fcgi
$ a2enmod ssl

# Désactiver un module
$ a2dismod php8.2

# === SITES ===

# Activer un site
$ a2ensite monsite.conf

# Désactiver un site
$ a2dissite 000-default.conf

# === LOGS ===

# Erreurs en temps réel
$ tail -f /var/log/apache2/error.log

# Accès en temps réel
$ tail -f /var/log/apache2/access.log

# Filtrer les erreurs 5xx
$ grep " 50[0-9] " /var/log/apache2/access.log | tail -50

# === MONITORING ===

# Server status (si mod_status activé)
$ curl -s http://localhost/server-status?auto

# Processus Apache
$ ps aux | grep apache2

# Ports écoutés
$ ss -tlnp | grep apache2

# === PERFORMANCE ===

# Benchmark simple
$ ab -n 1000 -c 50 https://monsite.com/

Migration de mod_php vers PHP-FPM

Si vous êtes encore sur une configuration legacy avec mod_php :

Étape 1 : Installer PHP-FPM

$ apt install php8.2-fpm
$ systemctl enable php8.2-fpm
$ systemctl start php8.2-fpm

Étape 2 : Configurer Apache

# Désactiver mod_php
$ a2dismod php8.2

# Désactiver MPM prefork
$ a2dismod mpm_prefork

# Activer MPM event et proxy_fcgi
$ a2enmod mpm_event
$ a2enmod proxy
$ a2enmod proxy_fcgi

# Activer la configuration PHP-FPM
$ a2enconf php8.2-fpm

Étape 3 : Mettre à jour les vhosts

<VirtualHost *:80>
    # PHP géré automatiquement par mod_php
</VirtualHost>

<VirtualHost *:80>
    <FilesMatch \\.php$>
        SetHandler "proxy:unix:/run/php/php8.2-fpm.sock|fcgi://localhost"
    </FilesMatch>
</VirtualHost>

Étape 4 : Redémarrer

$ apache2ctl configtest
$ systemctl restart apache2

Avantages de la migration