Procesos persistentes: workers de colas, Horizon y comandos en marcha continua

Algunas aplicaciones necesitan un programa que no termine nunca: un worker que procese la cola en cuanto llega un trabajo, Horizon, un consumidor de mensajes o un bot. Una tarea cron arranca, hace su trabajo y termina; un proceso persistente se queda en marcha y, si se cae, vuelve a arrancar solo.

Están disponibles en los planes Avanza, Max y Elástico:

Plan	Procesos persistentes
Avanza	3
Max	5
Elástico	8

En Inicia, Webmaster y en las cuentas de un multicuenta no hay procesos persistentes. Las colas se pueden procesar igualmente con el scheduler o con una tarea cron, con hasta un minuto de espera: lo explicamos en Instalar Laravel y en tareas cron.

Qué tipo elegir

Worker de colas: ejecuta php artisan queue:work con las colas que indiques. Para trabajos de Laravel en la base de datos o en Redis, sin Horizon.
Horizon: ejecuta php artisan horizon. Para colas en Redis gestionadas por Horizon, con su panel y sus métricas.
Redis persistente: Valkey 8, compatible con Redis, para colas, sesiones y Horizon. Se activa desde el Gestor de paquetes.
Comando propio: una línea de shell. Para Symfony Messenger, consumidores de mensajes, bots o cualquier programa que no reciba visitas.

Con Horizon no añadas además un worker de colas para las mismas colas: Horizon arranca y reparte sus propios workers. Horizon necesita colas en Redis, y para eso está el Redis persistente: ocupa uno de los procesos del plan.

Un proceso persistente no publica nada en internet. No sirve para una aplicación que espera visitas en un puerto propio, como un servidor Node.js, una aplicación Python o Laravel Reverb: el servidor web no le hace llegar esas conexiones. Para WebSockets, consulta WebSockets en Laravel.

Crear un proceso

En el área de clientes, abre Hosting, entra en tu servicio y ve a Herramientas > Procesos.
En el bloque Procesos persistentes, pulsa Añadir proceso y elige el tipo.
Indica la carpeta de la aplicación, relativa a tu home y sin /home/usuario. Si despliegas con Deploy+, es deploy/miapp/current, con el nombre de tu repositorio en lugar de miapp; si instalaste la aplicación a mano, la carpeta del proyecto, por ejemplo mi-proyecto. En un comando propio es opcional: sin carpeta, arranca en tu home.
En el worker de colas y en Horizon, elige la versión de PHP: de la 8.1 en adelante. El proceso usa el binario de esa versión, por ejemplo /opt/alt/php84/usr/bin/php para PHP 8.4, y no el php que encuentres en la terminal, que puede ser otra. Elige la misma que usa tu web y activa en esa versión las extensiones que necesite la aplicación desde el selector de PHP.
Guarda. El proceso aparece como Arrancando y pasa a En marcha en menos de un minuto.

Worker de colas

Indica las colas separadas por comas, en orden de prioridad: con high,default, el worker vacía primero high. Si no indicas otra cosa, procesa default con la conexión de QUEUE_CONNECTION de tu .env. Estas son las opciones por defecto:

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

--sleep=3: con la cola vacía, espera 3 segundos antes de volver a mirar.
--tries=3: tres intentos por trabajo antes de darlo por fallido. Los fallidos quedan en failed_jobs; los ves con php artisan queue:failed y los repites con php artisan queue:retry.
--max-time=3600: a la hora, el worker termina y vuelve a arrancar en un segundo. Así suelta memoria y recoge el código nuevo aunque nadie lo reinicie.
--memory=256: si pasa de 256 MB, termina al acabar el trabajo en curso y vuelve a arrancar.

Para colas con mucho volumen puedes crear varios workers sobre las mismas colas, uno por proceso del plan. Empieza con uno y añade otro solo si los trabajos se acumulan.

Comando propio

Escribe una sola línea, como la teclearías en la terminal, con rutas absolutas para PHP y para lo que no esté en la carpeta elegida. Por ejemplo, un consumidor de Symfony Messenger:

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

Un comando propio puede lanzar un script Python o de otro lenguaje disponible en la cuenta, pero solo damos soporte oficial a las aplicaciones PHP: lo que no sea PHP corre por tu cuenta.

El programa tiene que quedarse en primer plano. No añadas &, nohup ni opciones que lo manden a segundo plano: el vigilante lo vería terminar enseguida, lo lanzaría otra vez y acabaría En fallo con varias copias sueltas. Igual que con --max-time en Laravel, conviene que el programa termine cada cierto tiempo por su cuenta para soltar memoria: vuelve a arrancar solo.

Cómo se mantiene en marcha

Un vigilante comprueba cada minuto los procesos de la cuenta y arranca los que estén caídos. Lo verás en tus tareas cron como una línea que termina en # hostsuar-procesos: no la edites ni la borres, se gestiona desde Procesos.
Si el programa termina, por --max-time, por memoria o tras un php artisan queue:restart, vuelve a arrancar en un segundo. Entra de nuevo en la carpeta en cada arranque, así que tras un reinicio recoge la versión publicada en ese momento.
Si cae 5 veces seguidas nada más arrancar, antes de llegar a 30 segundos, se queda En fallo y no lo vuelve a intentar hasta que lo reinicies desde el panel. Entre un intento y el siguiente espera algo más cada vez, para no gastar la CPU de la cuenta en un programa que no puede arrancar.
Corre con el usuario de tu cuenta, dentro de sus recursos: la CPU, la memoria y el número de procesos del plan son los mismos que usan tus webs. Si la cuenta llega al límite de memoria, el sistema puede cortar el proceso y el vigilante lo vuelve a arrancar. Revisa el consumo en uso de CPU y recursos.

Estados y acciones

En marcha: el programa lleva unos segundos vivo sin caer.
Arrancando: está pedido y todavía no consta vivo, o acaba de arrancar; el vigilante lo arranca en menos de un minuto.
Reintentando: está cayendo nada más arrancar y el vigilante lo vuelve a lanzar. Si cae 5 veces seguidas, se queda En fallo. El porqué está en su registro.
Parado: lo has parado tú y no se arranca solo.
En fallo: ha caído 5 veces seguidas al arrancar y espera a que lo reinicies.

En cada proceso puedes:

Reiniciar: lo para y lo arranca en el momento, también si estaba En fallo.
Parar y Arrancar: parado no se vuelve a lanzar, pero sigue en la lista y conserva su configuración.
Ver el registro: las últimas líneas de lo que ha escrito el programa, con una línea arranca en cada arranque y otra terminó con el código N tras S s cada vez que termina. Cuando el registro pasa de 1 MB, se recorta y conserva la parte más reciente.
Editar: al guardar, el proceso se reinicia con los cambios.
Borrar: lo para y lo quita de la cuenta.

En Laravel, los errores de los trabajos también quedan en storage/logs/laravel.log, y los trabajos fallidos en failed_jobs.

Si un proceso se queda «En fallo»

Abre su registro: casi siempre la última línea antes de cada terminó con el código explica la causa. Las más habituales:

«no existe la carpeta de trabajo»: la carpeta no es correcta. Recuerda que es relativa a tu home, sin /home/usuario.
Falta una extensión de PHP, como redis, o pcntl y posix en Horizon: actívala en la versión de PHP del proceso, que puede no ser la de tu web.
La aplicación no conecta con Redis: el .env apunta a un Redis que no está activo o a otro socket.
Un comando propio que se va a segundo plano o que termina enseguida porque no tiene nada que hacer.
Un error al arrancar la aplicación, por ejemplo tras un despliegue con una dependencia que falta.

Corrige la causa y pulsa Reiniciar. Mientras siga En fallo, no consume recursos.

Despliegues y procesos persistentes

Un worker carga el código al arrancar y lo mantiene en memoria, así que tiene que reiniciarse para usar una versión nueva.

Con Deploy+ no tienes que hacer nada: en cuanto termina cada despliegue, y también al volver a una versión anterior, reinicia los procesos persistentes cuya carpeta es el current de esa aplicación o una carpeta de dentro. Cada worker termina el trabajo en curso y vuelve a arrancar en un segundo con el código nuevo, y el registro del despliegue dice cómo ha quedado cada uno. No pongas queue:restart ni horizon:terminate en el script: corre antes de activar la versión y el worker volvería a arrancar sobre la anterior. Desde la ficha del repositorio en Deploy+ puedes añadir el worker de colas de esa aplicación con la carpeta ya puesta.
Si publicas de otra forma (Git a mano, FTP), pulsa Reiniciar en el proceso cuando termines, o ejecuta php artisan queue:restart, php artisan horizon:terminate o php bin/console messenger:stop-workers cuando el código nuevo ya esté en su sitio. Laravel avisa a los workers a través de su caché: el comando y los workers deben usar el mismo CACHE_STORE.

SSH mientras haya procesos

Mientras la cuenta tenga procesos persistentes, aunque estén parados, el acceso SSH queda activado y no se puede desactivar: al apagarlo se cerrarían todos los procesos de la cuenta. Si quieres desactivar SSH, borra antes los procesos persistentes. Los procesos no necesitan que tú abras ninguna sesión.

Cambiar de plan

A un plan con menos procesos: se paran los más recientes que no quepan, y la memoria del Redis persistente se ajusta al máximo del plan nuevo.
A un plan sin procesos persistentes: se paran todos y siguen en la lista, para que veas qué tenías. Si vuelves a Avanza, Max o Elástico, puedes arrancarlos de nuevo.

Antes de cambiar de plan, prepara la aplicación para procesar sus colas sin ellos.