Processus persistants : workers de files d'attente, Horizon et commandes en fonctionnement continu

Certaines applications ont besoin d'un programme qui ne s'arrête jamais : un worker qui traite la file d'attente dès qu'une tâche arrive, Horizon, un consommateur de messages ou un bot. Une tâche cron démarre, fait son travail et s'arrête ; un processus persistant reste en fonctionnement et, s'il tombe, redémarre tout seul.

Ils sont disponibles sur les plans Avanza, Max et Elastic :

Plan	Processus persistants
Avanza	3
Max	5
Elastic	8

Les plans Inicia et Webmaster, ainsi que les comptes d'un hébergement multi-comptes, n'ont pas de processus persistants. Les files d'attente peuvent tout de même être traitées avec le scheduler ou une tâche cron, avec jusqu'à une minute d'attente : nous l'expliquons dans Installer Laravel et dans tâches cron.

Quel type choisir

Worker de files d'attente : exécute php artisan queue:work avec les files que vous indiquez. Pour les tâches Laravel en base de données ou dans Redis, sans Horizon.
Horizon : exécute php artisan horizon. Pour les files Redis gérées par Horizon, avec son tableau de bord et ses métriques.
Redis persistant : Valkey 8, compatible avec Redis, pour les files d'attente, les sessions et Horizon. Il s'active depuis le gestionnaire de paquets.
Commande personnalisée : une ligne de shell. Pour Symfony Messenger, des consommateurs de messages, des bots ou tout programme qui ne reçoit pas de connexions.

Avec Horizon, n'ajoutez pas en plus un worker de files d'attente pour les mêmes files : Horizon démarre et répartit ses propres workers. Horizon a besoin de files dans Redis, et c'est le rôle du Redis persistant : il occupe l'un des processus du plan.

Un processus persistant sert aux tâches en arrière-plan : files d'attente, Horizon, le Redis persistant, qui se connecte par socket, ou un script personnel. Il n'est pas prévu pour des serveurs qui reçoivent des connexions : nous ne prenons pas en charge les programmes qui écoutent sur un port, comme un serveur Node.js, une application Python, Laravel Reverb ou un autre serveur WebSockets. Pour les WebSockets avec Laravel, utilisez un service compatible avec Pusher, comme nous l'expliquons dans WebSockets avec Laravel ; si votre projet a besoin de son propre serveur, il vous faut un VPS.

Créer un processus

Dans l'espace client, ouvrez Hébergement, entrez dans votre service et allez dans Outils > Processus.
Dans le bloc Processus persistants, cliquez sur Ajouter un processus et choisissez le type.
Indiquez le dossier de l'application, relatif à votre home et sans /home/usuario. Si vous déployez avec Deploy+, c'est deploy/miapp/current, avec le nom de votre dépôt à la place de miapp ; si vous avez installé l'application à la main, c'est le dossier du projet, par exemple mi-proyecto. Pour une commande personnalisée, il est facultatif : sans dossier, elle démarre dans votre home.
Pour le worker de files d'attente et Horizon, choisissez la Version de PHP : 8.1 ou supérieure. Le processus utilise le binaire de cette version, par exemple /opt/alt/php84/usr/bin/php pour PHP 8.4, et non le php que vous trouvez dans le terminal, qui peut être une autre version. Choisissez la même que celle de votre site et activez dans cette version les extensions dont l'application a besoin depuis le sélecteur PHP.
Enregistrez. Le processus apparaît comme Démarrage et passe à En service en moins d'une minute.

Worker de files d'attente

Indiquez les files séparées par des virgules, par ordre de priorité : avec high,default, le worker vide d'abord high. Sans autre indication, il traite default avec la connexion de QUEUE_CONNECTION de votre .env. Voici les options par défaut :

php artisan queue:work --queue=default --sleep=3 --tries=3 --max-time=3600 --memory=256

--sleep=3 : quand la file est vide, il attend 3 secondes avant de regarder à nouveau.
--tries=3 : trois tentatives par tâche avant de la considérer comme échouée. Les tâches échouées restent dans failed_jobs ; vous les consultez avec php artisan queue:failed et les relancez avec php artisan queue:retry.
--max-time=3600 : au bout d'une heure, le worker s'arrête et redémarre en une seconde. Il libère ainsi la mémoire et prend le nouveau code même si personne ne le redémarre.
--memory=256 : s'il dépasse 256 Mo, il s'arrête une fois la tâche en cours terminée et redémarre.

Pour des files à fort volume, vous pouvez créer plusieurs workers sur les mêmes files, un par processus du plan. Commencez avec un seul et n'en ajoutez un autre que si les tâches s'accumulent.

Commande personnalisée

Écrivez une seule ligne, comme vous la taperiez dans le terminal, avec des chemins absolus pour PHP et pour tout ce qui n'est pas dans le dossier choisi. Par exemple, un consommateur Symfony Messenger :

/opt/alt/php84/usr/bin/php bin/console messenger:consume async --time-limit=3600 --memory-limit=256M

Une commande personnalisée peut lancer un script Python ou d'un autre langage disponible sur le compte pour une tâche en arrière-plan, mais nous n'assurons l'assistance officielle que pour les applications PHP : ce qui n'est pas en PHP reste sous votre responsabilité.

Le programme doit rester au premier plan. N'ajoutez ni &, ni nohup, ni d'options qui l'envoient en arrière-plan : le surveillant le verrait se terminer aussitôt, le relancerait et il finirait En échec avec plusieurs copies orphelines. Comme avec --max-time dans Laravel, il est préférable que le programme s'arrête de lui-même de temps en temps pour libérer la mémoire : il redémarre tout seul.

Comment il reste en fonctionnement

Un surveillant vérifie chaque minute les processus du compte et démarre ceux qui sont tombés. Vous le verrez dans vos tâches cron sous la forme d'une ligne qui se termine par # hostsuar-procesos : ne la modifiez pas et ne la supprimez pas, elle se gère depuis Processus.
Si le programme s'arrête, à cause de --max-time, de la mémoire ou après un php artisan queue:restart, il redémarre en une seconde. Il entre à nouveau dans le dossier à chaque démarrage : après un redémarrage, il prend donc la version publiée à ce moment-là.
S'il tombe 5 fois de suite juste après le démarrage, avant d'atteindre 30 secondes, il reste En échec et n'est plus relancé tant que vous ne le redémarrez pas depuis le panneau. Entre deux tentatives, il attend un peu plus à chaque fois, pour ne pas gaspiller le CPU du compte avec un programme qui ne peut pas démarrer.
Il s'exécute avec l'utilisateur de votre compte, dans ses ressources : le CPU, la mémoire et le nombre de processus du plan sont les mêmes que ceux de vos sites. Si le compte atteint sa limite de mémoire, le système peut couper le processus et le surveillant le redémarre. Consultez la consommation dans utilisation du CPU et des ressources.

États et actions

En service : le programme tourne depuis quelques secondes sans tomber.
Démarrage : il est demandé et n'apparaît pas encore comme actif, ou vient de démarrer ; le surveillant le démarre en moins d'une minute.
Nouvelle tentative : il tombe juste après le démarrage et le surveillant le relance. S'il tombe 5 fois de suite, il reste En échec. La raison figure dans son journal.
Arrêté : vous l'avez arrêté et il ne démarre pas tout seul.
En échec : il est tombé 5 fois de suite au démarrage et attend que vous le redémarriez.

Pour chaque processus, vous pouvez :

Redémarrer : l'arrête et le démarre immédiatement, y compris s'il était En échec.
Arrêter et Démarrer : arrêté, il n'est plus relancé, mais il reste dans la liste et conserve sa configuration.
Voir le journal : les dernières lignes écrites par le programme, avec une ligne arranca à chaque démarrage et une ligne terminó con el código N tras S s chaque fois qu'il s'arrête (code de sortie N après S secondes). Quand le journal dépasse 1 Mo, il est tronqué et conserve la partie la plus récente.
Modifier : à l'enregistrement, le processus redémarre avec les changements.
Supprimer : l'arrête et le retire du compte.

Avec Laravel, les erreurs des tâches restent aussi dans storage/logs/laravel.log, et les tâches échouées dans failed_jobs.

Si un processus reste « En échec »

Ouvrez son journal : la dernière ligne avant chaque terminó con el código explique presque toujours la cause. Les plus fréquentes :

« no existe la carpeta de trabajo » (le dossier de travail n'existe pas) : le dossier n'est pas correct. N'oubliez pas qu'il est relatif à votre home, sans /home/usuario.
Il manque une extension PHP, comme redis, ou pcntl et posix pour Horizon : activez-la dans la version de PHP du processus, qui peut être différente de celle de votre site.
L'application ne se connecte pas à Redis : le .env pointe vers un Redis qui n'est pas actif ou vers un autre socket.
Une commande personnalisée qui passe en arrière-plan ou qui s'arrête aussitôt parce qu'elle n'a rien à faire.
Une erreur au démarrage de l'application, par exemple après un déploiement avec une dépendance manquante.

Corrigez la cause et cliquez sur Redémarrer. Tant qu'il reste En échec, il ne consomme pas de ressources.

Déploiements et processus persistants

Un worker charge le code au démarrage et le garde en mémoire : il doit donc redémarrer pour utiliser une nouvelle version.

Avec Deploy+, vous n'avez rien à faire : dès que chaque déploiement se termine, et aussi lors d'un retour à une version précédente, il redémarre les processus persistants dont le dossier est le current de cette application ou un dossier à l'intérieur. Chaque worker termine la tâche en cours et redémarre en une seconde avec le nouveau code, et le journal du déploiement indique l'état de chacun. Ne mettez ni queue:restart ni horizon:terminate dans le script : il s'exécute avant l'activation de la version et le worker redémarrerait sur l'ancienne. Depuis la fiche du dépôt dans Deploy+, vous pouvez ajouter le worker de files d'attente de cette application avec le dossier déjà renseigné.
Si vous publiez autrement (Git à la main, FTP), cliquez sur Redémarrer sur le processus quand vous avez terminé, ou exécutez php artisan queue:restart, php artisan horizon:terminate ou php bin/console messenger:stop-workers une fois le nouveau code en place. Laravel prévient les workers via son cache : la commande et les workers doivent utiliser le même CACHE_STORE.

SSH tant qu'il y a des processus

Tant que le compte a des processus persistants, même arrêtés, l'accès SSH reste activé et ne peut pas être désactivé : le couper fermerait tous les processus du compte. Si vous voulez désactiver SSH, supprimez d'abord les processus persistants. Les processus n'ont pas besoin que vous ouvriez une session.

Changer de plan

Vers un plan avec moins de processus : les plus récents qui ne tiennent pas sont arrêtés, et la mémoire du Redis persistant est ajustée au maximum du nouveau plan.
Vers un plan sans processus persistants : ils sont tous arrêtés et restent dans la liste, pour que vous voyiez ce que vous aviez. Si vous revenez à Avanza, Max ou Elastic, vous pouvez les redémarrer.

Avant de changer de plan, préparez l'application à traiter ses files d'attente sans eux.