Otimizar PHP-FPM Pool em VPS Linux: pm.max_children e Fim do 502

PHP-FPM com pool mal dimensionado é a causa número um de 502 Bad Gateway em VPS rodando Nginx + PHP. O sintoma aparece sob carga moderada — 50, 100 requests simultâneos — e desaparece quando o tráfego cai, levando o diagnóstico pra direções erradas (Nginx, banco, rede). Na realidade, o pool está exausto: todos os workers PHP-FPM ocupados, o Nginx tenta enviar o request via FastCGI, recebe negação ou timeout, e devolve 502 pro cliente.

Este tutorial é pra você developer ou sysadmin com VPS Linux rodando Nginx + PHP-FPM em qualquer aplicação PHP (Laravel, WordPress, Symfony, Magento) que está vendo 502 esporádicos em produção ou simplesmente quer dimensionar o pool com base em medição, não em valores copiados de blog. Vamos cobrir como medir a memória real dos workers, calcular pm.max_children pela fórmula correta, ajustar os parâmetros auxiliares (pm.start_servers, pm.min_spare_servers, pm.max_spare_servers, pm.max_requests) e validar a configuração com o Nginx servindo carga real.

Tempo estimado de execução: 25 minutos, incluindo um teste de carga controlado pra validar antes/depois.

Pré-requisitos

Você precisa de VPS Linux com privilégios root ou sudo, PHP-FPM instalado e funcional, e Nginx já roteando requests pro socket Unix do PHP-FPM. Os exemplos usam Ubuntu 24.04 LTS com PHP 8.3, mas os princípios se aplicam a qualquer versão do PHP-FPM (7.4 em diante) e a Debian, AlmaLinux ou Rocky Linux com ajustes mínimos nos caminhos de arquivo.

Medir a memória real dos workers

Antes de tocar em qualquer parâmetro, você precisa saber quanto cada worker PHP-FPM consome de memória residente (RSS) com sua aplicação específica. Esse número varia drasticamente entre stacks — um worker Laravel com Eloquent pesado pode consumir 80–120 MB, um WordPress simples fica em 40–60 MB, e uma API Symfony otimizada pode rodar com 30 MB. Chutar 60 MB porque “é o padrão” é a forma mais comum de subdimensionar o pool.

ab -n 1000 -c 20 https://seu-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

A fórmula é simples e existe pra ser respeitada: pm.max_children = (RAM disponível pra PHP) ÷ (RSS médio por worker). O ponto não-óbvio é o “disponível pra PHP” — não é a RAM total da VPS. Você precisa subtrair o que MySQL, Redis, Nginx, kernel e buffers consomem em pico.

free -m

2560 MB ÷ 80 MB = 32 workers

Ajustar o pool no www.conf

Com pm.max_children calculado, abra /etc/php/8.3/fpm/pool.d/www.conf e ajuste os parâmetros relacionados. Eles não são independentes — valores mal alinhados causam tanto churn que o ganho do max_children correto desaparece em 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

Expor o status no Nginx pra monitorar

O pm.status_path só funciona se o Nginx rotear o request pro PHP-FPM. Sem isso você dimensiona às cegas e descobre o problema só quando o 502 volta 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

Verificação

Gere carga novamente e observe duas métricas críticas no status. A primeira é listen queue: se for maior que zero de forma consistente, o pool está saturando e requests estão enfileirando — você precisa aumentar max_children ou investigar lentidão na aplicação. A segunda é max children reached: se esse contador subir, você bateu o teto pelo menos uma vez desde o último reload.

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

Saída saudável sob 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

Se max children reached ficou em 0 durante o teste de carga, o dimensionamento está correto. Se subiu, rode o ps novamente sob carga, recalcule a RSS média (workers podem estar consumindo mais do que você mediu inicialmente) e ajuste.

Resolução de problemas

502 continua aparecendo após o ajuste

Verifique /var/log/php8.3-fpm.log buscando a string server reached max_children setting. Se aparecer, seu cálculo subestimou a memória ou a carga real é maior que o teste. Aumente max_children em 20% e refaça o ciclo de medição. Se a mensagem não aparece mas o 502 persiste, o problema não é pool — investigue fastcgi_read_timeout no Nginx (padrão 60s pode ser baixo pra endpoints pesados) e queries lentas no banco.

Workers consumindo muito mais RAM que o esperado

Memory leaks em aplicação PHP acumulam ao longo de centenas de requests. Reduza pm.max_requests de 500 pra 200 — isso recicla workers mais agressivamente e mata o leak antes dele crescer. Se o leak é muito rápido (worker dobra de tamanho em 50 requests), o problema é código — profile com xdebug.profiler_enable em staging pra encontrar a causa.

Próximos passos

Com o pool dimensionado, alguns próximos passos lógicos pra fortalecer a stack: configurar OPcache com opcache.memory_consumption adequado pra evitar recompilação a cada hit, ajustar fastcgi_read_timeout no Nginx pra endpoints conhecidos como lentos, exportar métricas do pool pra um sistema de observabilidade (Grafana, Datadog), e implementar health checks no Nginx via fastcgi_next_upstream pra failover gracioso.

Se você está colocando isso em produção e quer começar com uma base estável, uma VPS Hostini já vem com PHP-FPM 8.3 pré-instalado, Nginx tuned, e SSD NVMe — o que reduz drasticamente o tempo de I/O por request e impacta diretamente o pm.max_children que sua aplicação precisa.