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.

🌐 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: entremin_spare_serversemax_spare_serversworkers 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:fpmenextcloud:fpmcontê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
| Blog | Nextcloud A (maior) | Nextcloud B | |
|---|---|---|---|
| PHP | 8.5 | 8.5 | 8.5 |
pm | dynamic | dynamic | dynamic |
max_children | 12 | 30 | 20 |
| start / min spare / max spare | 4 / 2 / 8 | 8 / 4 / 16 | 6 / 3 / 12 |
max_requests | 500 | 500 | 500 |
request_terminate_timeout | 300 s | 3.600 s | 3.600 s |
| Limite do container | 1,5 GiB, 2 cores | 6 GiB, 3 cores | 5 GiB, 2 cores |
| OPcache | 128 MB, 10.000 arquivos, timestamps verificados a cada 60 s | 256 MB, 20.000 arquivos, timestamps desligados | igual |
| APCu | – | 128 MB | 128 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_timeouttambé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 inofensivofailed to ptracepor requisição lenta – aceito, porqueSYS_PTRACEenfraqueceria o container. - A página de status não é exposta pelo nginx; um sidecar
php-fpm_exporterno mesmo pod a lê via FastCGI e entrega os números ao Prometheus (dashboard do Grafana 25545).
📊 Medido
| Últimos 7 dias | Blog | Nextcloud A | Nextcloud B |
|---|---|---|---|
| Requisições PHP por dia | ~21.700 | ~23.600 | ~16.200 |
| Pico de workers ativos | 8 de 12 | 13 de 30 | 9 de 20 |
max_children atingido | 0 | 0 | 0 |
| Requisições lentas (> 5 s) | 0 | 0 | 0 |
| Memória por worker (RSS / parte própria PSS) | ~78 / ~16 MB | 108–157 / 14–49 MB | 71–116 / 8–27 MB |
| Pico de memória do container | 538 MiB de 1 GiB | 763 MiB de 6 GiB | 277 MiB de 5 GiB |
| Períodos de CPU com throttling | 2,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_childrenplanejado, 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.
| Sintoma | Comando |
|---|---|
| Todos os workers ocupados, requisições esperando | k3s 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 Gateway | k3s kubectl -n nextcloud logs deploy/nextcloud -c nginx --tail=30k3s 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'); doawk '/^Pss:/{s+=$2} END{printf "%d ", s/1024}' /proc/$p/smaps_rollup; done; echo |
| Código antigo ainda rodando após um update | k3s kubectl -n nextcloud rollout restart deployment/nextcloud # OPcache: validate_timestamps=0 |
| O mesmo no blog | k3s kubectl -n wordpress logs deploy/wordpress -c wordpress-fpm --tail=30k3s 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_childrenresulta 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ção | Ponto forte | Por que não aqui |
|---|---|---|
| Apache com mod_php | Configuração mais simples, um só tipo de processo | O PHP vive em cada processo do servidor web, inclusive nos que servem arquivos estáticos; sem controle de pool separado. |
| FrankenPHP / RoadRunner | Workers de longa duração, a aplicação fica na memória | Precisa de uma aplicação feita para isso; WordPress e Nextcloud esperam um estado novo por requisição. |
| Swoole | PHP assíncrono | Não compatível com estas aplicações. |
| PHP-FPM + nginx | O que as imagens trazem, controle fino, bem conhecido | Escolhido. |
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.
