Operativa real de mantenimiento de una aplicación Laravel desplegada en un servidor Linux: gestionar los workers de colas con Supervisor, ver qué jobs están pendientes, seguir los logs en producción, ajustar permisos y refrescar la cache de configuración.

Sustituye las rutas y nombres por los de tu proyecto: /var/www/app/current (raíz del release), app-workers (programa de Supervisor) y reports (nombre de cola) son placeholders.

1. Colas de Laravel

# Ver las conexiones de cola registradas
php artisan tinker
>>> array_keys(config('queue.connections'));

# Ver jobs pendientes en el driver database (vía tinker)
>>> DB::table('jobs')->where('queue','reports')->get();

# Lanzar un job de prueba para validar el worker
>>> dispatch(new \App\Domain\Report\Jobs\ReportExportJob);

-- Jobs pendientes aún sin intentar (driver database)
SELECT * FROM jobs WHERE queue = 'reports' AND attempts = 0;

# Si usas el driver Redis: longitud de la cola
redis-cli
> LLEN queues:reports

2. Workers con Supervisor

Supervisor mantiene vivos los procesos queue:work. El ciclo habitual tras tocar la config es reread → update → restart.

# Editar la definición del programa
sudo nano /etc/supervisor/conf.d/app.conf

# Recargar configuración y aplicar cambios
sudo supervisorctl reread
sudo supervisorctl update

# Estado de los workers de un programa
sudo supervisorctl status app-workers:*

# Reiniciar todos los workers del programa (p. ej. tras un deploy)
sudo supervisorctl restart app-workers:*

Tras cada despliegue, reinicia los workers: siguen ejecutando el código cargado en memoria al arrancar, así que sin reinicio seguirían usando la versión anterior.

3. Seguir logs en producción

Ruta típica de logs: /var/www/app/current/storage/logs.

# Seguir en tiempo real
tail -f /var/www/app/current/storage/logs/worker.log
tail -f /var/www/app/current/storage/logs/laravel.log

# less con "follow": Ctrl-C para parar y /patrón para buscar
less +F /var/www/app/current/storage/logs/worker.log

# Últimas N líneas
tail -n 100 /var/www/app/current/storage/logs/worker.log

# Filtrar el seguimiento por un job concreto (--line-buffered con grep tras tail -f)
tail -f /var/www/app/current/storage/logs/worker.log \
  | grep --line-buffered 'ReportExportJob'

# Solo estados RUNNING o DONE
tail -f /var/www/app/current/storage/logs/worker.log \
  | grep --line-buffered -E 'ReportExportJob.*(RUNNING|DONE)'

# Buscar errores en todos los logs
grep -R "ERROR" -n /var/www/app/current/storage/logs

# Contar ocurrencias / filtrar por fecha
grep -c "ReportExportJob" /var/www/app/current/storage/logs/worker.log
grep "2026-06-17" /var/www/app/current/storage/logs/worker.log

4. Tamaño, limpieza y rotación de logs

# Tamaño total y listado ordenado por tamaño
du -sh /var/www/app/current/storage/logs
ls -lh /var/www/app/current/storage/logs | sort -k5 -h

# Vaciar un log sin borrar el fichero (mantiene el inodo y los permisos)
truncate -s 0 /var/www/app/current/storage/logs/worker.log

# Ver la configuración de logrotate
cat /etc/logrotate.d/laravel-logs

# Ver varios logs a la vez
multitail \
  /var/www/app/current/storage/logs/worker.log \
  /var/www/app/current/storage/logs/laravel.log

# Navegador de logs con resaltado y filtros
lnav /var/www/app/current/storage/logs/*.log

5. Permisos de storage y bootstrap/cache

El fallo más común tras un deploy: el servidor web no puede escribir en storage o bootstrap/cache.

# Comprobar propietario y permisos
ls -ld /var/www/app/current/storage
ls -ld /var/www/app/current/storage/logs

# Ajustar propietario al usuario del servidor web y permisos correctos
sudo chown -R www-data:www-data \
  /var/www/app/current/storage/ \
  /var/www/app/current/bootstrap/cache

find /var/www/app/current/storage/ /var/www/app/current/bootstrap/cache -type d -exec chmod 775 {} \;
find /var/www/app/current/storage/ /var/www/app/current/bootstrap/cache -type f -exec chmod 664 {} \;

6. Cache de configuración y artisan

# Refrescar la cache de configuración (tras cambiar .env o config/*)
php artisan config:clear
php artisan config:cache

# Cache de rutas y vistas
php artisan route:cache
php artisan view:cache

Tras config:cache, Laravel deja de leer .env en runtime y usa la cache. Si cambias variables de entorno y no ves el efecto, regenera la cache (config:clear + config:cache).

7. Inventariar jobs y colas en el código

Útil para auditar qué colas existen y cómo están configuradas antes de tocar Supervisor.

# Listar todos los ficheros de Job
find app/Domain -type f -path '*/Jobs/*.php'

# Colas declaradas y timeouts por job
grep -R "public \$queue"   -n app/Domain/*/Jobs
grep -R "public \$timeout" -n app/Domain/*/Jobs

# Jobs encolables y asignaciones dinámicas de cola
grep -R "implements ShouldQueue" -n app/Domain/*/Jobs
grep -R "onQueue" -n app/Domain