Optimizar Pool PHP-FPM en VPS Linux: pm.max_children y el Fin del 502

Un pool PHP-FPM mal dimensionado es la causa número uno de 502 Bad Gateway en VPS con Nginx + PHP. El síntoma aparece bajo carga moderada — 50, 100 requests simultáneos — y desaparece cuando el tráfico baja, llevando el diagnóstico en direcciones equivocadas (Nginx, base de datos, red). En realidad, el pool está agotado: todos los workers PHP-FPM ocupados, Nginx intenta enviar el request vía FastCGI, recibe rechazo o timeout, y devuelve 502 al cliente.

Este tutorial es para ti, developer o sysadmin con VPS Linux corriendo Nginx + PHP-FPM en cualquier aplicación PHP (Laravel, WordPress, Symfony, Magento) que está viendo 502 esporádicos en producción o simplemente quiere dimensionar el pool a partir de mediciones reales, no de valores copiados de un blog. Vamos a cubrir cómo medir la memoria real de los workers, calcular pm.max_children con la fórmula correcta, ajustar los parámetros auxiliares (pm.start_servers, pm.min_spare_servers, pm.max_spare_servers, pm.max_requests) y validar la configuración con Nginx sirviendo carga real.

Tiempo estimado de ejecución: 25 minutos, incluyendo una prueba de carga controlada para validar antes/después.

Requisitos previos

Necesitas una VPS Linux con privilegios root o sudo, PHP-FPM instalado y funcional, y Nginx ya enrutando requests al socket Unix de PHP-FPM. Los ejemplos usan Ubuntu 24.04 LTS con PHP 8.3, pero los principios se aplican a cualquier versión de PHP-FPM (7.4 en adelante) y a Debian, AlmaLinux o Rocky Linux con ajustes mínimos en las rutas de archivo.

Medir la memoria real de los workers

Antes de tocar cualquier parámetro, necesitas saber cuánto consume cada worker PHP-FPM de memoria residente (RSS) con tu aplicación específica. Ese número varía drásticamente entre stacks — un worker Laravel con Eloquent pesado puede consumir 80–120 MB, un WordPress sencillo se queda en 40–60 MB, y una API Symfony optimizada puede correr con 30 MB. Adivinar 60 MB porque “es el valor por defecto” es la forma más común de infradimensionar el pool.

ab -n 1000 -c 20 https://tu-dominio.com/endpoint-pesado

ps -ylC php-fpm8.3 --sort:rss

ps --no-headers -o rss -C php-fpm8.3 | awk '{sum+=$1; count++} END {print "Media:", sum/count/1024, "MB"}'

Calcular pm.max_children

La fórmula es simple y existe para ser respetada: pm.max_children = (RAM disponible para PHP) ÷ (RSS medio por worker). El punto no obvio es el “disponible para PHP” — no es la RAM total de la VPS. Tienes que restar lo que MySQL, Redis, Nginx, kernel y buffers consumen en pico.

free -m

2560 MB ÷ 80 MB = 32 workers

Ajustar el pool en www.conf

Con pm.max_children calculado, abre /etc/php/8.3/fpm/pool.d/www.conf y ajusta los parámetros relacionados. No son independientes — valores mal alineados causan tanto churn que la ganancia del max_children correcto desaparece en overhead de spawn.

sudo nano /etc/php/8.3/fpm/pool.d/www.conf

pm = dynamic
pm.max_children = 26
pm.start_servers = 7
pm.min_spare_servers = 4
pm.max_spare_servers = 10
pm.max_requests = 500

pm.status_path = /fpm-status

sudo php-fpm8.3 -t

sudo systemctl reload php8.3-fpm

Exponer el status en Nginx para monitorizar

pm.status_path solo funciona si Nginx enruta el request hacia PHP-FPM. Sin eso dimensionas a ciegas y descubres el problema solo cuando el 502 vuelve a aparecer.

location ~ ^/(fpm-status|fpm-ping)$ {
    allow 127.0.0.1;
    allow 10.0.0.0/8;
    deny all;
    fastcgi_pass unix:/run/php/php8.3-fpm.sock;
    include fastcgi_params;
    fastcgi_param SCRIPT_FILENAME $fastcgi_script_name;
}

sudo nginx -t && sudo systemctl reload nginx

Verificación

Genera carga de nuevo y observa dos métricas críticas en el status. La primera es listen queue: si es mayor que cero de forma consistente, el pool se está saturando y los requests se están encolando — necesitas aumentar max_children o investigar lentitud en la aplicación. La segunda es max children reached: si ese contador sube, has tocado techo al menos una vez desde el último reload.

curl -s http://127.0.0.1/fpm-status

Salida saludable bajo carga:

pool:                 www
process manager:      dynamic
accepted conn:        4823
listen queue:         0
max listen queue:     2
idle processes:       6
active processes:     11
total processes:      17
max active processes: 19
max children reached: 0

Si max children reached se quedó en 0 durante la prueba de carga, el dimensionamiento es correcto. Si subió, ejecuta ps de nuevo bajo carga, recalcula la RSS media (los workers pueden estar consumiendo más de lo que mediste inicialmente) y ajusta.

Resolución de problemas

El 502 sigue apareciendo tras el ajuste

Revisa /var/log/php8.3-fpm.log buscando la cadena server reached max_children setting. Si aparece, tu cálculo subestimó la memoria o la carga real es mayor que la prueba. Aumenta max_children en un 20% y repite el ciclo de medición. Si el mensaje no aparece pero el 502 persiste, el problema no es el pool — investiga fastcgi_read_timeout en Nginx (el valor por defecto de 60s puede ser bajo para endpoints pesados) y queries lentas en la base de datos.

Workers consumiendo mucha más RAM de la esperada

Los memory leaks en aplicaciones PHP se acumulan a lo largo de cientos de requests. Reduce pm.max_requests de 500 a 200 — eso recicla workers más agresivamente y mata el leak antes de que crezca. Si el leak es muy rápido (el worker duplica su tamaño en 50 requests), el problema es el código — profilea con xdebug.profiler_enable en staging para encontrar la causa.

Próximos pasos

Con el pool dimensionado, algunos próximos pasos lógicos para fortalecer la stack: configurar OPcache con un opcache.memory_consumption adecuado para evitar recompilación en cada hit, ajustar fastcgi_read_timeout en Nginx para endpoints conocidos como lentos, exportar métricas del pool a un sistema de observabilidad (Grafana, Datadog), e implementar health checks en Nginx vía fastcgi_next_upstream para failover elegante.

Si estás llevando esto a producción y quieres empezar con una base estable, una VPS Hostini ya viene con PHP-FPM 8.3 preinstalado, Nginx tuneado y SSD NVMe — lo que reduce drásticamente el tiempo de I/O por request e impacta directamente el pm.max_children que tu aplicación necesita.