Deep Dive: PHP-FPM e OPcache – workers, limites e um cache de bytecode pequeno demais

Cada requisição do WordPress e do Nextcloud é um worker PHP. Quantos existem, quanto tempo podem rodar e o que guardam na memória decide velocidade e estabilidade – com números medidos nos três servidores e os padrões que os limitavam em silêncio.

Ilustração da série Deep Dive

🌐 Também em: English · Deutsch · Français · Español · Italiano · Nederlands · Polski

Deep Dive da série em torno do Ansible Tour. O tour explica as roles; os deep dives, a tecnologia por baixo: como funciona, por que é usada assim aqui e o que deu errado pelo caminho.

WordPress e Nextcloud são aplicações PHP, e nos dois pods toda requisição dinâmica acaba em um worker do PHP-FPM (parte 3, parte 4). Quantos workers existem, quanto tempo um pode rodar e quanto código compilado eles compartilham decide a velocidade dos sites e o que acontece sob carga. Este post explica a mecânica, as configurações escolhidas aqui, as medições por trás delas – e dois padrões que limitavam o Nextcloud sem que ninguém percebesse.

Índice

🧭 Como PHP-FPM e OPcache funcionam

Master, pool, workers

O PHP-FPM (“FastCGI Process Manager”) é um processo master que inicia e supervisiona processos worker. Cada worker atende exatamente uma requisição por vez, do início ao fim. O nginx, no mesmo pod, serve os arquivos estáticos sozinho e repassa toda requisição .php via FastCGI para a porta 9000. Um pool é um grupo de workers com configurações próprias; as duas aplicações usam o único pool www das imagens oficiais.

Quantos workers

  • pm = static: um número fixo de workers, sempre rodando.
  • pm = dynamic: entre min_spare_servers e max_spare_servers workers ociosos ficam de prontidão; novos são iniciados até max_children.
  • pm = ondemand: workers só iniciam quando chega uma requisição e param após um timeout de ociosidade.

pm.max_children é o verdadeiro limite de concorrência: a requisição número max_children + 1 espera na listen queue até um worker ficar livre. pm.max_requests recicla um worker depois de tantas requisições, o que limita o crescimento lento de memória de extensões com vazamento.

Dois tipos de limite de tempo

max_execution_time é o limite do próprio PHP e, no Linux, conta só o tempo de CPU do script – uma requisição esperando pelo banco de dados ou por um lock não o consome. request_terminate_timeout é o limite do FPM sobre o tempo de relógio: quando expira, o master mata o worker. Só o segundo libera um worker travado.

OPcache: compilar uma vez

O PHP compila cada script em bytecode antes de executá-lo. O OPcache guarda esse bytecode em memória compartilhada, usada em conjunto por todos os workers de um pool, de modo que um arquivo é compilado uma vez por pod em vez de uma vez por requisição. Três configurações definem seu tamanho: memory_consumption (o segmento), interned_strings_buffer (strings idênticas guardadas uma só vez) e max_accelerated_files (o número de slots da sua tabela hash). Este último é arredondado internamente para o próximo número de uma lista fixa de primos – 10.000 vira 16.229, 20.000 vira 32.531. Quando os slots ou a memória estão cheios, os arquivos seguintes simplesmente não entram no cache e são compilados a cada requisição.

validate_timestamps decide se o OPcache verifica as datas de modificação dos arquivos (a cada revalidate_freq segundos). Desligado é mais rápido, mas aí um arquivo alterado continua como bytecode antigo até o FPM reiniciar.

APCu: um cache para a aplicação

O APCu é um segundo segmento de memória compartilhada que a própria aplicação preenche com dados – o Nextcloud guarda ali consultas de apps e de configuração como seu cache local. Como o OPcache, ele é por pod, não compartilhado entre pods; tudo o que precisa ser consistente entre processos e pods pertence ao Redis.

🛡️ Por que está aqui

  • É o que as imagens oficiais trazem. wordpress:fpm e nextcloud:fpm contêm PHP-FPM; nginx na frente é a configuração documentada.
  • Concorrência previsível. Um limite superior fixo de workers que cabe no limite de memória do container é melhor do que um servidor que aceita tudo e depois é morto pelo OOM killer.
  • Controle fino. Tamanho do pool, timeouts, página de status e slow log podem ser definidos por aplicação, independentemente do servidor web.

🔧 O que este repositório faz

BlogNextcloud A (maior)Nextcloud B
PHP8.58.58.5
pmdynamicdynamicdynamic
max_children123020
start / min spare / max spare4 / 2 / 88 / 4 / 166 / 3 / 12
max_requests500500500
request_terminate_timeout300 s3.600 s3.600 s
Limite do container1,5 GiB, 2 cores6 GiB, 3 cores5 GiB, 2 cores
OPcache128 MB, 10.000 arquivos, timestamps verificados a cada 60 s256 MB, 20.000 arquivos, timestamps desligadosigual
APCu–128 MB128 MB

As configurações do pool ficam em um ConfigMap montado como z-monitoring.conf em php-fpm.d/ – o “z” garante que ele seja lido por último e prevaleça sobre o www.conf da imagem. Os valores do Nextcloud vêm de variáveis de host com padrões no template, então um pequeno host de teste e os dois servidores de produção compartilham um único template.

O padrão que limitava o Nextcloud a cinco

Na primeira versão da stack do Nextcloud, o pool não tinha configurações próprias. O container rodava, portanto, com o pm.max_children = 5 padrão do FPM – independentemente do seu limite de memória de 4 GiB. Clientes de sincronização desktop, apps móveis e os callbacks WOPI do Collabora ocupam workers; a sexta requisição PHP simultânea entrava na fila. Isso foi corrigido em julho de 2026 com um pool de 12, depois 20; em outubro o Prometheus mostrava picos de 17 workers ativos no servidor maior, então o limite original de cinco era bem real. A rodada de tuning de 16 de outubro de 2026 elevou os pools para 30 e 20. A regra de dimensionamento: memória por worker vezes max_children, mais OPcache e APCu, precisa ficar bem abaixo do limite do container.

A lição: Um padrão que ninguém definiu continua sendo uma decisão – geralmente uma que não combina com a sua carga.

O cache de bytecode pequeno demais

A imagem do Nextcloud define max_accelerated_files = 10000, internamente 16.229 slots. O Nextcloud com seus apps tem 15.486 arquivos PHP no servidor maior e 17.811 no menor. No servidor menor, mais de 1.500 arquivos nunca couberam no cache e eram compilados de novo a cada requisição que os usava. Desde 16 de outubro os dois servidores rodam com 20.000 (32.531 slots) e 256 MB. O blog, com 4.452 arquivos PHP, está longe do seu limite. Por que o servidor menor tem mais arquivos: lá há mais apps habilitados. “Menor” se refere a usuários e carga; o limite conta arquivos de código, não importa quantas pessoas os usem.

A lição: Se o cache de bytecode é grande o suficiente depende do número de arquivos PHP, não do número de usuários.

Timestamps desligados – e o que isso custa

No Nextcloud, validate_timestamps = 0: nenhum stat() por arquivo e requisição. O preço é que um arquivo alterado só é percebido quando o pod reinicia. Atualizações de imagem reiniciam o pod de qualquer jeito, mas occ upgrade e occ app:update sobrescrevem arquivos PHP no lugar. Por isso o playbook de update reinicia o pod do Nextcloud uma segunda vez depois deles. Para este artigo, descobri que a atualização opcional de apps no playbook principal não tinha esse segundo restart – apps atualizados teriam continuado rodando como código antigo. Corrigido. O blog mantém os timestamps ligados com intervalo de 60 segundos, porque o WordPress atualiza plugins no lugar pela sua própria página de administração.

A lição: validate_timestamps=0 economiza trabalho em toda requisição, mas exige um restart do pod após cada atualização de código.

Limites rígidos e o slow log

  • request_terminate_timeout também não estava definido antes de 16 de outubro: uma requisição travada em um lock ou em um armazenamento externo segurava seu worker até o pod reiniciar. 3.600 s no Nextcloud, porque um download de pasta via streaming pode legitimamente levar muitos minutos; 300 s no blog.
  • O slow log vai para o stderr do container e, portanto, para o log do pod. Um stack trace precisaria de ptrace, que um container sem capabilities não tem; profundidade 0 registra apenas a linha “executing too slowly”. O FPM ainda tenta se anexar e registra um inofensivo failed to ptrace por requisição lenta – aceito, porque SYS_PTRACE enfraqueceria o container.
  • A página de status não é exposta pelo nginx; um sidecar php-fpm_exporter no mesmo pod a lê via FastCGI e entrega os números ao Prometheus (dashboard do Grafana 25545).

📊 Medido

Últimos 7 diasBlogNextcloud ANextcloud B
Requisições PHP por dia~21.700~23.600~16.200
Pico de workers ativos8 de 1213 de 309 de 20
max_children atingido000
Requisições lentas (> 5 s)000
Memória por worker (RSS / parte própria PSS)~78 / ~16 MB108–157 / 14–49 MB71–116 / 8–27 MB
Pico de memória do container538 MiB de 1 GiB763 MiB de 6 GiB277 MiB de 5 GiB
Períodos de CPU com throttling2,1 %2,2 %0,2 %

Três leituras. Primeiro, o RSS de um worker superestima seu custo: ele conta as páginas compartilhadas de OPcache e APCu em cada worker. O PSS divide as páginas compartilhadas entre os processos que as usam e é o número honesto – 16 MB por worker do blog, não 78. Segundo, os pools do Nextcloud agora são generosos: o pico usou menos da metade, e os limites dos containers estão muito acima dos picos. Terceiro, o blog teve um ponto fora da curva: um único minuto em 16 de outubro com 8 workers ativos e 30 requisições esperando na fila – uma rajada de cerca de 40 requisições simultâneas. Nenhum log daquele dia sobreviveu (a coleta de logs começou três dias depois), então a causa é desconhecida. Foi um minuto em uma semana, e desde então a fila ficou em zero.

Uma correção minha. Em 26 de outubro dividi a memória do container do blog pelo número de workers em execução, obtive 90–130 MB por worker e concluí que 1 GiB não comportaria um pool completo de 12. Era o erro do RSS acima em outra forma: a memória do container inclui o segmento compartilhado do OPcache, o page cache dos arquivos PHP e o processo master. Distribuído entre poucos workers parece muito por worker, e multiplicado por 12 a parte compartilhada é contada doze vezes. Medido pelo PSS, um worker precisa de 20–26 MB; 12 workers mais o segmento de 128 MB do OPcache dão cerca de 0,5 GB. O limite foi elevado para 1,5 GiB mesmo assim – não pelo pool, mas porque um único upload com processamento de imagem pode usar até memory_limit = 512M em uma requisição.

A lição: Memória por worker se mede com PSS. Memória do container dividida pelo número de processos conta a parte compartilhada várias vezes.

O que acontece quando todos os workers estão ocupados

De início, nada quebra. O nginx repassa toda requisição PHP ao FPM; se nenhum worker está livre, a conexão espera na listen queue do socket do FPM, e a página fica simplesmente mais lenta. Um erro só vem depois: se nenhuma resposta chega dentro de fastcgi_read_timeout (300 s), o nginx devolve 504; se a própria fila está cheia (backlog 511), novas conexões são recusadas e o nginx devolve 502. Por isso os alertas abaixo avisam muito antes: com 80 % dos workers ocupados e assim que max_children é atingido uma vez.

Uma reunião em que vinte pessoas abrem a mesma planilha não precisa de vinte workers PHP. O PHP cuida de abrir e salvar (as requisições WOPI); a edição em si roda por uma conexão WebSocket direto para o container do Collabora. Numa reunião assim, a carga cai sobre CPU e memória do Collabora – no servidor maior ele pode usar até 6 cores desde 26 de outubro – enquanto o pool PHP fica quase ocioso.

  • Dimensionar workers. Meça o PSS sob carga, multiplique pelo max_children planejado, some OPcache e APCu, compare com o limite do container. Depois observe “max_children reached” e a listen queue no Grafana; se ambos ficarem em zero, o pool é grande o suficiente.
  • Reset do OPcache. opcache_reset() na linha de comando reseta o cache do próprio CLI, não o do FPM. Para o FPM, o reset confiável é um restart – no Kubernetes, um rollout.
  • Um site travado. As métricas por processo do exporter mostram há quanto tempo cada worker está ocupado; junto com o slow log, isso costuma ser mais rápido do que vasculhar access logs.

🆘 Cola: sintoma → comando

A versão curta deste artigo para o momento em que algo está errado. Execute no host como root; <…> são placeholders.

SintomaComando
Todos os workers ocupados, requisições esperandok3s kubectl -n nextcloud exec deploy/nextcloud -c nginx -- \
curl -s http://127.0.0.1:9253/metrics | grep -E '^phpfpm_(active|idle|listen_queue|max_children)'
“server reached pm.max_children”k3s kubectl -n nextcloud logs deploy/nextcloud -c nextcloud-fpm | grep max_children
Quais requisições estão lentas?k3s kubectl -n nextcloud logs deploy/nextcloud -c nextcloud-fpm | grep -i 'executing too slow'
502 Bad Gatewayk3s kubectl -n nextcloud logs deploy/nextcloud -c nginx --tail=30
k3s kubectl -n nextcloud logs deploy/nextcloud -c nextcloud-fpm --tail=30
Quanta memória um worker realmente precisa?for p in $(pgrep -f '^php-fpm: pool www'); do
awk '/^Pss:/{s+=$2} END{printf "%d ", s/1024}' /proc/$p/smaps_rollup; done; echo
Código antigo ainda rodando após um updatek3s kubectl -n nextcloud rollout restart deployment/nextcloud # OPcache: validate_timestamps=0
O mesmo no blogk3s kubectl -n wordpress logs deploy/wordpress -c wordpress-fpm --tail=30
k3s kubectl -n wordpress rollout restart deployment/wordpress

🔭 O que vem a seguir

  • PHP 8.5 para o blog – feito em 26 de outubro de 2026 (imagem wordpress:7.1.3-php8.5-fpm); todos os plugins e o tema passaram antes por lint com PHP 8.5: só avisos de deprecation, nenhum erro.
  • JIT está desligado. Para aplicações web limitadas por I/O como estas, traz pouco; seria um experimento com medições antes e depois, não um padrão.
  • Um alerta na listen queue – feito em 21 de outubro de 2026: manda e-mail quando requisições esperam por um worker livre durante cinco minutos, o que nunca aconteceu nos 14 dias medidos.
  • Dois avisos antecipados – adicionados em 26 de outubro de 2026: um e-mail quando mais de 80 % dos workers estão ocupados por cinco minutos, e outro assim que max_children é atingido. O alerta da fila só vem depois deles.

🎯 As lições

  • Verifique os padrões antes de fazer tuning: os dois grandes ganhos estavam lá.
  • max_children resulta da memória por worker (PSS) e do limite do container, não da CPU.
  • Uma fila cheia primeiro deixa as páginas lentas; erros só vêm depois do timeout.
  • Sem verificação de timestamps, toda atualização de código precisa de um restart.
  • Avisos antecipados com 80 % dos workers ocupados alertam antes que os usuários percebam algo.

⚖️ Alternativas – e por que PHP-FPM

OpçãoPonto fortePor que não aqui
Apache com mod_phpConfiguração mais simples, um só tipo de processoO PHP vive em cada processo do servidor web, inclusive nos que servem arquivos estáticos; sem controle de pool separado.
FrankenPHP / RoadRunnerWorkers de longa duração, a aplicação fica na memóriaPrecisa de uma aplicação feita para isso; WordPress e Nextcloud esperam um estado novo por requisição.
SwoolePHP assíncronoNão compatível com estas aplicações.
PHP-FPM + nginxO que as imagens trazem, controle fino, bem conhecidoEscolhido.

Nada neste post é exótico. Os dois ganhos reais – vinte e cinco workers a mais e um cache que comporta o código – vieram de olhar quais eram de fato os padrões, não de tuning esperto. Padrões são o palpite de outra pessoa sobre a sua carga; no PHP-FPM, dois deles estavam errados para o Nextcloud por um fator de quatro.

Alguns textos e imagens deste site foram criados com a ajuda de IA ou gerados por IA. Detalhes