Documentation complète

Documentation — WSA pour cPanel/WHM

Web Site Accelerator (WSA) — manuel d'utilisation complet.
Couvre l'interface WHM (administrateur), l'interface cPanel
(utilisateur final), la ligne de commande, l'activation par
package, et les intégrations WordPress / classe PHP.

Pour l'installation initiale, voir
installation-fr.md.

1. Vue d'ensemble

WSA place Nginx en frontal de Apache : Nginx écoute sur les ports 80
et 443 et joue le rôle de proxy inverse + serveur de cache. Apache
continue d'exécuter PHP/Perl/CGI sur les ports 8080 et 8443 (proxy
ports). Trois zones de cache distinctes coexistent :

Zone	Contenu type	Taille par défaut
Dynamic	Pages PHP/HTML générées	4 Go
CSS / JS	Fichiers `.css`, `.js` (statiques)	2 Go
Static / Media	Images, fontes, téléchargements	2 Go

Chaque zone est dimensionnée et gérée indépendamment. WSA propose
également une couche de protection contre les bots (IA, scanners,
SEO, requêtes sans User-Agent), un rate limiting multi-niveaux, et
une intégration aux changements SSL cPanel pour reconstruire les
vhosts automatiquement.

Le module suit une architecture en trois pans :

/etc/wsa/ — coeur du module (PHP, librairies, configuration,
base SQLite, journaux, daemon wsad).
WHM (/usr/local/cpanel/whostmgr/docroot/cgi/wsa/) —
configuration globale par l'administrateur.
cPanel (/usr/local/cpanel/base/frontend/{paper_lantern,jupiter}/wsa/) —
configuration par compte, par l'utilisateur final.

2. Installation

L'installation est documentée séparément dans
installation-fr.md.

Résumé pour mémoire :

wget https://static.astralinternet.com/nginx/install/wsa-install && sh wsa-install stable

Suivi d'une vérification dans WHM (bandeau de statut, jauges de
cache, en-têtes X-Nginx-Cache-Status sur un site test).

3. Interface WHM (administrateur)

L'interface WHM est l'outil d'administration global du serveur. On y
accède via WHM → Plugins → WSA – Cache for cPanel server.

3.1 Page d'accueil

La page d'accueil rassemble cinq blocs, du haut vers le bas :

3.1.1 Bandeau de statut

Deux lignes :

État du module : enabled / disabled
État de Nginx : running / stopped

Codes couleur : vert (sain), rouge (problème).

3.1.2 Tuiles d'action (rangée du haut)

Deux tuiles colorées par niveau de risque :

Rebuild Nginx conf (ambre) — régénère tous les vhosts puis
effectue un hot reload (aucune connexion active perdue). À faire
après toute modification de configuration WHM ou cPanel.
Restart Nginx (rouge) — redémarrage complet du processus.
Coupe les connexions actives. Confirme via une boîte de
dialogue. À utiliser uniquement quand un reload ne suffit pas.

3.1.3 Rangée de cache

Clear Nginx cache (tuile bleue, à gauche) — vide les trois
zones de cache. Sans danger : la prochaine requête repeuplera le
cache.
Cache usage bars (à droite) — trois barres de progression pour
Dynamic, CSS / JS, Media.

3.1.4 Bot Protection (statistiques 24 h)

Panneau ajouté en WSA 1.5.0. Affiche :

Total blocked — nombre cumulé de requêtes bloquées via HTTP 444
sur les 24 dernières heures
Unique IPs — IPs distinctes bloquées
Top User-Agent — UA le plus offensif (avec compteur)

Une section dépliable « Top 10 User-Agents » expose le détail
complet. Les statistiques sont mises en cache 5 minutes
(/etc/wsa/conf/bot_stats.json) pour ne pas pénaliser le chargement
de la page WHM. Le panneau disparaît automatiquement si le journal
Nginx (/var/log/nginx/access.log) est illisible.

3.1.5 Liste de configuration

Trois liens vers les pages de configuration détaillée :

Module Configuration — voir 3.2
Nginx Configuration — voir 3.3
Cache Configuration — voir 3.4

3.1.6 Zone de danger

Section visuellement séparée (bordure rouge) en bas de page. Contient
un seul bouton Disable module (ou Enable module si
actuellement désactivé). Cliquer dessus :

Arrête Nginx
Réassigne Apache aux ports 80 et 443
Tous les sites continuent de fonctionner mais sans cache

Une boîte de confirmation explicite empêche les clics accidentels.

3.2 Module Configuration

Réglages spécifiques au module WSA (et non à Nginx).

Option	Description
Auto Update	Active ou désactive la mise à jour automatique du module via cron.
Dynamic Cache Size	Taille maximale de la zone Dynamic sur disque. Choix prédéfinis (256 Mo, 512 Mo, 1 Go, 2 Go, 4 Go) ou valeur personnalisée.
CSS / JS Cache Size	Idem pour la zone CSS / JS.
Media Cache Size	Idem pour la zone Media (images / fontes / vidéos).
Release Tier	Branche de mise à jour : stable, current, edge, dev (si disponible).

Après modification, cliquer Save puis Rebuild Nginx conf
depuis la page d'accueil pour appliquer.

3.3 Nginx Configuration

Page la plus dense — elle expose toutes les directives Nginx que WSA
gère. Les options sont regroupées par section repliable :

General — worker_processes, worker_connections,
worker_rlimit_nofile, keepalive_timeout, client_max_body_size,
sendfile, tcp_nodelay, tcp_nopush, etc.
Rate Limiting — quatre mécanismes indépendants :
- Global request rate — débit global par IP réelle (par défaut
  désactivé ; activer avec une limite type 30 req/s + burst 100).
- Login URI rate — taux strict (5 req/min par défaut) sur les
  URIs d'authentification (/wp-login.php, /xmlrpc.php,
  /administrator/, /admin.php, /login).
- Concurrent connections / IP — anti-Slowloris (50 connexions
  simultanées par IP par défaut).
- Concurrent connections / vhost — équité entre sites (1000
  connexions par vhost par défaut).
- Whitelist — liste d'IPs / CIDR de confiance qui ne sont jamais
  comptés (CDN, monitoring, IPs internes).
Compression — gzip (activé par défaut), gzip_static,
bouton Build & install Brotli, case Enable Brotli,
niveaux de compression.
Bot Protection — listes de User-Agents bloqués par catégorie :
- AI Crawlers — GPTBot, ClaudeBot, PerplexityBot, Bytespider,
  Anthropic-AI, etc.
- Security Scanners — Nikto, sqlmap, Wfuzz, etc.
- SEO Spiders — AhrefsBot, SemrushBot, MJ12bot, etc.
- Empty User-Agent — bloque les requêtes sans aucun UA.
- Custom UA list — liste libre éditable par l'administrateur.
Caching behavior — proxy_cache_path levels, proxy_cache_key,
proxy_cache_use_stale, proxy_cache_lock, durées d'inactivité.
Other / Misc — directives diverses (open file cache, log
format, resolver DNS, etc.).

Chaque option affiche : libellé, brève description, valeur par
défaut, et le contrôle approprié (champ texte, On/Off, choix
multiples, ou liste de valeurs).

Sous le formulaire, un sous-formulaire séparé contient les boutons
Build & install Brotli / Uninstall Brotli (rendus en dehors
du <form> principal pour éviter une soumission accidentelle).

3.4 Cache Configuration

Réglages par défaut du cache, appliqués à tous les sites du
serveur. Un site peut surcharger ces valeurs via l'interface cPanel
(Mode Simple ou Avancé).

Page organisée par menu vertical à gauche :

ALL (par défaut) — toutes les sections affichées en même temps.
Dynamic Files — TTL serveur, TTL navigateur, cookies bypass,
URIs bypass.
CSS / JS Files — TTL serveur, TTL navigateur, URIs bypass.
Images / Fonts — TTL serveur, TTL navigateur, URIs bypass.

Chaque section reprend la même structure que les onglets
correspondants en mode cPanel Avancé (voir
section 6) — les directives sont
identiques, seul le scope change (global ici vs par-domaine en
cPanel).

Important : la section Bot Protection est volontairement
absente de cette page — elle vit dans Nginx Configuration pour
éviter la duplication d'interface.

4. Activation par package dans WHM

WSA est globalement enabled ou disabled sur le serveur, mais la
visibilité de l'interface cPanel est gérée individuellement par
le système de Feature Manager de cPanel — ce qui permet de
réserver l'accès au panneau WSA aux clients d'un package précis.

Le code WSA interroge en interne :

whmapi1 get_users_features_settings user=<user> feature=WSA-Website_Accelerator

Si le feature est désactivé pour le package d'un client, WSA
existe sur le serveur mais l'utilisateur ne voit ni l'icône cPanel
ni le panneau Mode Simple/Avancé.

4.1 Activer la fonctionnalité pour un package

WHM → Packages → Feature Manager.
Soit modifier une Feature List existante, soit en créer une
nouvelle (bouton Add a new feature list).
Cocher la case WSA-Website_Accelerator dans la liste.
Save.
WHM → Packages → Edit a Package, sélectionner le package à
modifier.
Choisir la Feature List préparée à l'étape précédente dans le
menu déroulant.
Save Changes.

Tous les comptes cPanel actuels et futurs assignés à ce package
verront le panneau WSA dès leur prochaine connexion à cPanel.

4.2 Désactiver pour un package

Suivre les mêmes étapes mais décocher WSA-Website_Accelerator
dans la Feature List. WSA continuera à proxifier et cacher leurs
sites — seule l'interface utilisateur est masquée.

4.3 Vérifier le statut d'un utilisateur

whmapi1 get_users_features_settings user=<utilisateur> feature=WSA-Website_Accelerator

Le champ feature_list_setting retourne 1 (activée) ou 0
(désactivée).

5. Interface cPanel — Mode Simple

Le Mode Simple est la vue par défaut quand un utilisateur cPanel
ouvre l'icône WSA. C'est un tableau à une colonne radio + une
colonne description, avec quatre choix mutuellement exclusifs.

Choix	Comportement
Default	Réglages globaux du serveur (définis par l'admin dans WHM → Cache Configuration).
Disable	Aucun cache — toutes les requêtes sont passées à Apache directement. Utile pour le debug.
Cache for 1 month	Durées de cache longues : adapté aux sites de contenu peu fréquemment mis à jour (sites vitrine).
Cache for 1 week	Compromis fréquence/performance — recommandé par défaut pour la plupart des sites WordPress / e-commerce de contenu.
Cache for 1 day	Cycle court — sites éditoriaux, blogs très actifs.
Store (e-commerce)	Préréglage e-commerce : cache CSS/JS/Media long, dynamique très court (1 min), URIs panier/checkout/login automatiquement bypass.

5.1 Indicateur de compression

Dans le coin supérieur droit du panneau cPanel, un point coloré
(« feu de circulation ») indique l'état des codecs de compression :

● Brotli/Gzip — les deux codecs actifs (cas optimal)
● Brotli — Brotli uniquement
● Gzip — gzip uniquement
(rien) — aucune compression

Cet indicateur est en lecture seule pour l'utilisateur ; le réglage
se fait dans WHM par l'administrateur.

5.2 Bouton Switch to Advance mode

En bas du panneau Simple, un bouton bascule l'utilisateur vers le
Mode Avancé. À utiliser quand le
client a besoin de régler les choses par domaine/sous-domaine, ou
d'ajuster les TTL individuellement.

5.3 Bouton Clear my cache

Vide uniquement les caches associés aux domaines de l'utilisateur
courant (pas le cache des autres comptes). Sans danger — la prochaine
requête repeuplera.

6. Interface cPanel — Mode Avancé

Le Mode Avancé permet une configuration par domaine et par
sous-domaine. Chaque entrée de la liste de domaines de l'utilisateur
est éditable séparément.

6.1 Sélection du domaine / sous-domaine

À l'arrivée en Mode Avancé, l'utilisateur voit la liste de tous ses
domaines et sous-domaines. Pour chacun, deux actions :

Edit — ouvre la fenêtre popup de configuration (5 onglets,
voir ci-dessous).
Use server default — supprime toute personnalisation et
réutilise les défauts globaux WHM.

Les sous-domaines héritent par défaut du domaine parent ; éditer un
sous-domaine crée une exception locale visible dans la liste.

6.2 Onglet Basic

Sélectionné par défaut à l'ouverture du popup. Quatre cases à cocher
(activer / désactiver) :

Option	Effet sur les en-têtes HTTP de réponse
Show "Powered By" header	Ajoute `X-Server-Powered-By: Nginx for WHM/cPanel by Astral Internet`.
Show Cache Status header	Ajoute `X-Nginx-Cache-Status: HIT/MISS/BYPASS/EXPIRED`. Très utile au debug.
Add XSS Protection header	Ajoute `X-XSS-Protection: 1; mode=block` (toujours, sur toutes les réponses).
Add Content-Type Options header	Ajoute `X-Content-Type-Options: nosniff` (anti-MIME-sniffing).

6.3 Onglet Bot Protection

Permet de surcharger les paramètres serveur par domaine. Chaque
catégorie est un sélecteur tri-état :

État	Effet
Server default	Hérite du réglage global WHM (recommandé).
Bloqué	Force le blocage pour ce domaine, même si désactivé globalement.
Autorisé	Force l'autorisation pour ce domaine, même si bloqué globalement.

Quatre catégories de bots :

AI Crawlers — GPTBot, ClaudeBot, PerplexityBot, Bytespider, etc.
Security Scanners — Nikto, sqlmap, Wfuzz, etc.
SEO Spiders — AhrefsBot, SemrushBot, MJ12bot, etc.
Empty User-Agent — requêtes sans en-tête User-Agent.

Cas d'usage : un client publie une API qui doit être consommée
par un agent IA — on bascule AI Crawlers sur Autorisé pour ce
domaine seulement, sans assouplir la politique globale du serveur.

6.4 Onglet Dynamic

Règles de cache pour le contenu dynamique (HTML généré, JSON, API).
Inclut un interrupteur principal Activate dynamic caching. Si
désactivé, aucune des sous-options ci-dessous ne s'applique.

Option	Description
Bypass Cache-Control header	Ignore les directives `Cache-Control` / `Expires` envoyées par l'application (utile contre les CMS qui forcent `no-cache`).
Server cache TTL	Durée pendant laquelle Nginx garde la réponse en cache (champ numérique + unité s/m/h/d/w/M).
Browser cache TTL	Valeur envoyée au navigateur via `Expires` / `Cache-Control`.
Cookie bypass list	Liste de noms de cookies (un par ligne, ajout via bouton +) ; toute requête contenant un de ces cookies court-circuite le cache. Exemple usage : `wordpress_logged_in`, `woocommerce_cart_hash`.
URI bypass list	Liste d'expressions régulières (un motif par ligne) ; les URIs qui matchent court-circuitent le cache. Exemple : `/wp-admin`, `/checkout`, `/cart`.

6.5 Onglet CSS / JS

Règles de cache pour les fichiers .css et .js. Mêmes contrôles
que l'onglet précédent, en plus simple :

Option	Description
Activate CSS/JS caching	Interrupteur principal de l'onglet.
Server cache TTL	TTL Nginx (typiquement plus long que dynamique : 1 mois).
Browser cache TTL	TTL navigateur.
URI bypass list	URIs à exclure (rare pour CSS/JS, utile pour les builds versionnés en dev).

6.6 Onglet Images & Fonts

Règles de cache pour images, fontes, fichiers téléchargeables.
Mêmes contrôles que CSS / JS. Les TTL par défaut sont les plus
longs (1 mois → 1 an typiquement) car ces fichiers changent
rarement et leur version est généralement encodée dans l'URL.

Option	Description
Activate media caching	Interrupteur principal.
Server cache TTL	TTL Nginx.
Browser cache TTL	TTL navigateur.
URI bypass list	URIs à exclure.

6.7 Sauvegarder

Bouton Save en bas du popup. Les modifications sont écrites dans
la base SQLite (/etc/wsa/conf/wsa.sqlite) puis le hook de rebuild
régénère la configuration Nginx du domaine concerné. Le résultat est
visible sous quelques secondes.

7. Ligne de commande

WSA expose un CLI complet pour automatiser ses opérations (Ansible,
cron, scripts de déploiement). L'utilitaire est installé à
/etc/wsa/wsa.

Important : dans certains environnements le bit d'exécution
peut être absent (durcissement, restorecon, etc.). La forme
recommandée est /etc/wsa/./wsa <flags> ou, en cas d'échec,
l'invocation explicite via PHP :
/usr/local/cpanel/3rdparty/bin/php /etc/wsa/wsa <flags>.

7.1 Aide et version

/etc/wsa/./wsa --help        # Affiche l'aide complète
/etc/wsa/./wsa --version     # Numéro de version installé
/etc/wsa/./wsa -h            # Forme courte de --help
/etc/wsa/./wsa -v            # Forme courte de --version

7.2 Gestion du cache

Commande	Effet
`--purgecache-all`	Vide intégralement les trois zones de cache.
`--purgecache-user=<user>`	Vide le cache d'un utilisateur cPanel.
`--purgecache-domain=<domain> --user=<user>`	Vide le cache d'un domaine spécifique. `--user` est obligatoire.
`--purgecache-url=<url>`	Vide une URL précise. URL doit commencer par `http://` ou `https://`.
`--update-disk-usage`	Recalcule les tailles de cache et met à jour les jauges WHM.

/etc/wsa/./wsa --purgecache-url=https://example.com/article/123
/etc/wsa/./wsa --purgecache-user=clienta --verbose

7.3 Gestion de la configuration Nginx

Commande	Effet
`--rebuild`	Régénère uniquement les vhosts modifiés (rapide).
`--rebuild-user=<user>`	Régénère un seul utilisateur cPanel.
`--rebuild-forced`	Régénère tout (lent — à utiliser après changement de Cache Configuration WHM).
`--reload-nginx`	Effectue un hot reload sans couper les connexions.
`--restart-nginx`	Redémarrage complet (coupe les connexions actives).
`--check-httpd-conf`	Vérifie si Apache a changé depuis le dernier rebuild.

7.4 Activation / désactivation du module

/etc/wsa/./wsa --enable      # Active WSA (Nginx prend les ports 80/443)
/etc/wsa/./wsa --disable     # Désactive WSA (Apache reprend 80/443)
/etc/wsa/./wsa --update      # Met à jour le module via la branche configurée
/etc/wsa/./wsa --check-wsad  # Vérifie + redémarre le daemon wsad si besoin

7.5 Modules Nginx additionnels (Brotli, etc.)

Tous ces flags acceptent un nom de module en argument
(ex. =brotli).

Commande	Effet	Code de sortie
`--nginx-list`	Liste les modules supportés.	0
`--nginx-status=<mod>`	Statut JSON (installé, statique, activé, version).	0 / 1
`--nginx-caninstall=<mod>`	Vérifie pré-requis.	0 si oui
`--nginx-isinstalled=<mod>`	Le module est-il installé ?	0 si oui
`--nginx-isstatic=<mod>`	Le module est-il compilé statiquement dans Nginx ?	0 si oui
`--nginx-isenabled=<mod>`	Le drapeau SQLite est-il actif ?	0 si oui
`--nginx-install=<mod>`	Compile et installe le module. Combiner avec `--force` pour recompiler.	0 si succès
`--nginx-uninstall=<mod>`	Retire les fichiers `.so`.	0 si succès
`--nginx-enable=<mod>`	Active les directives dans `nginx.conf`.	0 si succès
`--nginx-disable=<mod>`	Désactive les directives.	0 si succès

# Workflow Brotli complet
/etc/wsa/./wsa --nginx-caninstall=brotli && \
  /etc/wsa/./wsa --nginx-install=brotli --verbose && \
  /etc/wsa/./wsa --nginx-enable=brotli && \
  /etc/wsa/./wsa --rebuild-forced

7.6 Drapeaux globaux

Drapeau	Effet
`--verbose`	Affiche le détail de chaque étape (très utile en debug).
`--user=<user>`	Précise l'utilisateur cPanel ciblé (requis avec `--purgecache-domain`).
`--force`	Force la recompilation avec `--nginx-install` même si déjà à jour.

7.7 Codes de sortie standards

Code	Sens
0	Succès / oui / module installé / activé
1	Échec / non / module absent / désactivé
2+	Erreurs spécifiques (voir `/var/log/wsa/wsa.log`)

Conçu pour s'intégrer naturellement dans des scripts shell :

if /etc/wsa/./wsa --nginx-isinstalled=brotli; then
    echo "Brotli est déjà installé"
else
    /etc/wsa/./wsa --nginx-install=brotli --verbose
fi

8. Module WordPress (générique)

L'extension officielle « Cache Purge for Website Accelerator »
permet à WordPress de notifier WSA chaque fois qu'un contenu est
modifié, pour que la version cachée par Nginx soit immédiatement
remplacée par la nouvelle.

8.1 Installation

Dans WordPress : Extensions → Ajouter.
Rechercher « Cache Purge for Website Accelerator ».
Cliquer Installer maintenant puis Activer.

8.2 Configuration

L'extension fonctionne sans configuration : elle détecte WSA via les
en-têtes X-Server-Powered-By et émet un appel CLI vers
--purgecache-url= à chaque évènement WordPress de mise à jour de
contenu :

Publication ou mise à jour d'un article / page
Modification de menu
Modification de widget
Activation / désactivation d'extension
Changement de thème
Création / mise à jour de produit WooCommerce

8.3 Vérification

Modifier un article puis recharger la page côté visiteur. Dans les
en-têtes de réponse, X-Nginx-Cache-Status doit passer à MISS (la
version cachée a été purgée) puis HIT au rechargement suivant.

9. Classe PHP (générique)

Pour les développeurs qui veulent intégrer la purge de cache dans
un projet PHP non-WordPress (CMS sur mesure, framework Laravel/Symfony,
script de migration, etc.), Astral Internet fournit une classe PHP
libre de droits.

9.1 Téléchargement

La classe est distribuée sur le site web Astral Internet
(astralinternet.com/cache-pour-serveur-cpanel)
sous la section Extensions → Classe PHP.

9.2 Utilisation typique

require_once 'wsa_cache_purge.php';

$wsa = new WSA_Cache_Purge();

// Purger une URL après modification d'un article
$result = $wsa->purgeUrl('https://example.com/article/12345');

if ($result['success']) {
    error_log("Purgé : {$result['deleted']} fichier(s) sur {$result['tried']} variantes");
} else {
    error_log("Purge échouée : {$result['msg']}");
}

9.3 Méthodes principales

Méthode	Description
`purgeUrl(string $url): array`	Purge une URL précise. URL doit être absolue (`https://...`).
`purgeDomain(string $domain, string $user): bool`	Purge un domaine entier.
`purgeUser(string $user): bool`	Purge tous les domaines d'un utilisateur cPanel.
`purgeAll(): bool`	Purge totale (réservé root).

9.4 Variantes de clés cachées

Chaque appel purgeUrl() traite 8 variantes possibles :

2 schemes (http / https)
2 méthodes HTTP (GET / HEAD)
2 versions de mobile (desktop / mobile)

→ Un seul appel suffit donc à purger toutes les versions cachées
d'une même URL, sans que l'intégrateur ait à se soucier des
variantes.

9.5 Notes

La classe nécessite un appel via PHP-FPM ou CLI sous un compte qui
peut écrire dans /var/cache/nginx/wsa_* (typiquement nobody ou
l'utilisateur cPanel propriétaire du site).
Pour les usages multi-tenant, préférer --purgecache-url= via
shell_exec() plutôt que d'instancier la classe directement —
cela passe par le CLI WSA qui valide les permissions.

Document mis à jour pour WSA 1.5.8 — avril 2026.
Pour les questions non couvertes : support@astralinternet.com.