Deep Dive: PHP-FPM en OPcache – workers, limieten en een bytecode-cache die te klein was

Elk WordPress- en Nextcloud-request is een PHP-worker. Hoeveel er zijn, hoe lang ze mogen draaien en wat ze in het geheugen houden bepaalt snelheid en stabiliteit – met gemeten cijfers van alle drie de servers en de defaults die ze ongemerkt begrensden.

Illustratie voor de Deep Dive-serie

🌐 Ook in: English · Deutsch · Français · Español · Italiano · Português · Polski

Deep Dive in de serie rond de Ansible Tour. De tour legt de rollen uit, de deep dives de techniek eronder: hoe het werkt, waarom het hier zo wordt gebruikt en wat er onderweg misging.

WordPress en Nextcloud zijn PHP-applicaties, en in beide pods komt elk dynamisch request uit bij een PHP-FPM-worker (deel 3, deel 4). Hoeveel workers er zijn, hoe lang er één mag draaien en hoeveel gecompileerde code ze delen, bepaalt hoe snel de sites zijn en wat er onder belasting gebeurt. Deze post legt de mechaniek uit, de hier gekozen instellingen, de metingen erachter – en twee defaults die Nextcloud begrensden zonder dat iemand het merkte.

Inhoud

🧭 Hoe PHP-FPM en OPcache werken

Master, pool, workers

PHP-FPM (“FastCGI Process Manager”) is een masterproces dat workerprocessen start en bewaakt. Elke worker behandelt precies één request tegelijk, van begin tot eind. nginx, in dezelfde pod, levert statische bestanden zelf en geeft elk .php-request via FastCGI door aan poort 9000. Een pool is een groep workers met eigen instellingen; beide applicaties gebruiken de enkele pool www uit de officiële images.

Hoeveel workers

  • pm = static: een vast aantal workers, altijd actief.
  • pm = dynamic: tussen min_spare_servers en max_spare_servers idle workers staan klaar; nieuwe worden gestart tot max_children.
  • pm = ondemand: workers starten pas als er een request binnenkomt en stoppen na een idle-timeout.

pm.max_children is de echte concurrency-limiet: request nummer max_children + 1 wacht in de listen queue tot er een worker vrij is. pm.max_requests recyclet een worker na zoveel requests, wat langzame geheugengroei door lekkende extensies begrenst.

Twee soorten tijdslimieten

max_execution_time is PHP’s eigen limiet en telt op Linux alleen de CPU-tijd van het script – een request dat op de database of een lock wacht, verbruikt die niet. request_terminate_timeout is de limiet van FPM op wandkloktijd: als die verloopt, killt de master de worker. Alleen de tweede maakt een hangende worker vrij.

OPcache: één keer compileren

PHP compileert elk script naar bytecode voordat het wordt uitgevoerd. OPcache houdt die bytecode in gedeeld geheugen, dat alle workers van een pool samen gebruiken, zodat een bestand één keer per pod wordt gecompileerd in plaats van één keer per request. Drie instellingen bepalen de grootte: memory_consumption (het segment), interned_strings_buffer (identieke strings één keer opgeslagen) en max_accelerated_files (het aantal slots in de hashtabel). Die laatste wordt intern naar boven afgerond op het volgende getal uit een vaste lijst priemgetallen – 10.000 wordt 16.229, 20.000 wordt 32.531. Als de slots of het geheugen vol zijn, worden verdere bestanden gewoon niet gecachet en bij elk request opnieuw gecompileerd.

validate_timestamps bepaalt of OPcache de wijzigingstijden van bestanden controleert (elke revalidate_freq seconden). Uit is sneller, maar dan blijft een gewijzigd bestand oude bytecode tot FPM herstart.

APCu: een cache voor de applicatie

APCu is een tweede gedeeld geheugensegment dat de applicatie zelf met data vult – Nextcloud slaat daar app- en configuratie-lookups op als lokale cache. Net als OPcache is het per pod, niet gedeeld tussen pods; alles wat consistent moet zijn over processen en pods heen, hoort in Redis.

🛡️ Waarom het hier is

  • Het is wat de officiële images meeleveren. wordpress:fpm en nextcloud:fpm bevatten allebei PHP-FPM; nginx ervoor is de gedocumenteerde setup.
  • Voorspelbare concurrency. Een vaste bovengrens aan workers die in de geheugenlimiet van de container past, is beter dan een server die alles accepteert en dan door de OOM-killer wordt neergeschoten.
  • Fijne controle. Poolgrootte, timeouts, de statuspagina en de slow log zijn per applicatie in te stellen, onafhankelijk van de webserver.

🔧 Wat deze repository doet

BlogNextcloud A (groter)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
Containerlimiet1,5 GiB, 2 cores6 GiB, 3 cores5 GiB, 2 cores
OPcache128 MB, 10.000 bestanden, timestamps elke 60 s gecontroleerd256 MB, 20.000 bestanden, timestamps uitidem
APCu–128 MB128 MB

De poolinstellingen staan in een ConfigMap die als z-monitoring.conf in php-fpm.d/ wordt gemount – de “z” zorgt ervoor dat hij als laatste wordt gelezen en wint van de www.conf uit het image. De Nextcloud-waarden komen uit hostvariabelen met defaults in de template, zodat een kleine testhost en de twee productieservers één template delen.

De default die Nextcloud op vijf begrensde

In de eerste versie van de Nextcloud-stack had de pool geen eigen instellingen. De container draaide dus met FPM’s standaard pm.max_children = 5 – ongeacht zijn geheugenlimiet van 4 GiB. Desktop-syncclients, mobiele apps en de WOPI-callbacks van Collabora bezetten allemaal workers; het zesde gelijktijdige PHP-request kwam in de wachtrij. Dat werd in juli 2026 opgelost met een pool van 12, later 20; in oktober toonde Prometheus pieken van 17 actieve workers op de grotere server, dus de oorspronkelijke grens van vijf was heel reëel. De tuningronde van 16 oktober 2026 verhoogde de pools naar 30 en 20. De vuistregel: geheugen per worker maal max_children, plus OPcache en APCu, moet ruim onder de containerlimiet blijven.

De les: Een default die niemand heeft ingesteld, is nog steeds een beslissing – meestal een die niet bij je eigen belasting past.

De bytecode-cache die te klein was

Het Nextcloud-image zet max_accelerated_files = 10000, intern 16.229 slots. Nextcloud met zijn apps heeft 15.486 PHP-bestanden op de grotere server en 17.811 op de kleinere. Op de kleinere server pasten meer dan 1.500 bestanden nooit in de cache en werden ze opnieuw gecompileerd bij elk request dat ze gebruikte. Sinds 16 oktober draaien beide servers met 20.000 (32.531 slots) en 256 MB. De blog, met 4.452 PHP-bestanden, zit ver van zijn limiet. Waarom de kleinere server meer bestanden heeft: daar zijn meer apps ingeschakeld. “Kleiner” gaat over gebruikers en belasting; de limiet telt codebestanden, hoeveel mensen ze ook gebruiken.

De les: Of de bytecode-cache groot genoeg is, hangt af van het aantal PHP-bestanden, niet van het aantal gebruikers.

Timestamps uit – en wat dat kost

Op Nextcloud staat validate_timestamps = 0: geen stat() per bestand en request. De prijs is dat een gewijzigd bestand pas wordt opgemerkt als de pod herstart. Image-updates herstarten de pod sowieso, maar occ upgrade en occ app:update overschrijven PHP-bestanden ter plekke. Het update-playbook rolt de Nextcloud-pod daarom daarna een tweede keer. Voor dit artikel bleek dat de opt-in app-update in het hoofdplaybook die tweede herstart miste – bijgewerkte apps zouden als hun oude code zijn blijven draaien. Opgelost. De blog houdt timestamps aan met een interval van 60 seconden, omdat WordPress plugins ter plekke bijwerkt vanuit zijn eigen beheerpagina.

De les: validate_timestamps=0 bespaart werk bij elk request, maar vereist een pod-herstart na elke code-update.

Harde limieten en de slow log

  • request_terminate_timeout was vóór 16 oktober ook niet ingesteld: een request dat hing op een lock of een externe opslag hield zijn worker vast tot de pod herstartte. 3.600 s op Nextcloud, omdat een gestreamde mapdownload legitiem vele minuten kan duren; 300 s op de blog.
  • De slow log gaat naar de stderr van de container en dus naar de podlog. Een stacktrace zou ptrace nodig hebben, en dat heeft een container zonder capabilities niet; diepte 0 logt alleen de regel “executing too slowly”. FPM probeert toch te attachen en logt per traag request één onschuldige failed to ptrace – geaccepteerd, omdat SYS_PTRACE de container zou verzwakken.
  • De statuspagina wordt helemaal niet via nginx ontsloten; een php-fpm_exporter-sidecar in dezelfde pod leest hem via FastCGI en levert de cijfers aan Prometheus (Grafana-dashboard 25545).

📊 Gemeten

Laatste 7 dagenBlogNextcloud ANextcloud B
PHP-requests per dag~21.700~23.600~16.200
Piek actieve workers8 van 1213 van 309 van 20
max_children bereikt000
Trage requests (> 5 s)000
Workergeheugen (RSS / eigen deel PSS)~78 / ~16 MB108–157 / 14–49 MB71–116 / 8–27 MB
Piek containergeheugen538 MiB van 1 GiB763 MiB van 6 GiB277 MiB van 5 GiB
CPU-perioden gethrottled2,1 %2,2 %0,2 %

Drie observaties. Ten eerste overschat de RSS van een worker zijn kosten: hij telt de gedeelde OPcache- en APCu-pagina’s in elke worker mee. PSS verdeelt gedeelde pagina’s over de processen die ze gebruiken en is het eerlijke getal – 16 MB per blogworker, niet 78. Ten tweede zijn de Nextcloud-pools nu ruim: de piek gebruikte minder dan de helft, en de containerlimieten liggen ver boven de pieken. Ten derde had de blog één uitschieter: één enkele minuut op 16 oktober met 8 actieve workers en 30 wachtende requests in de queue – een burst van ruwweg 40 gelijktijdige requests. Er is geen log van die dag bewaard gebleven (logverzameling begon drie dagen later), dus de oorzaak is onbekend. Het was één minuut in een week, en sindsdien is de queue op nul gebleven.

Eén correctie van mezelf. Op 26 oktober deelde ik het geheugen van de blogcontainer door het aantal draaiende workers, kwam uit op 90–130 MB per worker en concludeerde dat 1 GiB geen volle pool van 12 zou houden. Dat was de RSS-fout van hierboven in een andere vorm: het containergeheugen omvat het gedeelde OPcache-segment, de page cache van de PHP-bestanden en het masterproces. Verdeeld over een paar workers lijkt dat veel per worker, en vermenigvuldigd met 12 wordt het gedeelde deel twaalf keer geteld. Gemeten met PSS heeft een worker 20–26 MB nodig; 12 workers plus het OPcache-segment van 128 MB komen op ongeveer 0,5 GB. De limiet werd toch verhoogd naar 1,5 GiB – niet voor de pool, maar omdat één upload met beeldverwerking tot memory_limit = 512M in één request kan gebruiken.

De les: Geheugen per worker meet je met PSS. Containergeheugen gedeeld door het aantal processen telt het gedeelde deel meerdere keren.

Wat er gebeurt als alle workers bezet zijn

Eerst gaat er niets stuk. nginx geeft elk PHP-request door aan FPM; als er geen worker vrij is, wacht de verbinding in de listen queue van de FPM-socket, en de pagina is gewoon trager. Een fout komt pas later: als er binnen fastcgi_read_timeout (300 s) geen antwoord komt, geeft nginx 504; als de queue zelf vol is (backlog 511), worden nieuwe verbindingen geweigerd en geeft nginx 502. Daarom waarschuwen de alerts hieronder veel eerder: bij 80 % bezette workers en zodra max_children één keer wordt bereikt.

Een vergadering waarin twintig mensen dezelfde spreadsheet openen, heeft geen twintig PHP-workers nodig. PHP regelt openen en opslaan (de WOPI-requests); het bewerken zelf loopt over een WebSocket-verbinding rechtstreeks naar de Collabora-container. In zo’n vergadering komt de belasting op CPU en geheugen van Collabora terecht – op de grotere server mag dat sinds 26 oktober tot 6 cores gebruiken – terwijl de PHP-pool bijna idle blijft.

  • Workers dimensioneren. Meet PSS onder belasting, vermenigvuldig met de geplande max_children, tel OPcache en APCu op, vergelijk met de containerlimiet. Houd daarna “max_children reached” en de listen queue in Grafana in de gaten; als beide op nul blijven, is de pool groot genoeg.
  • OPcache-reset. opcache_reset() op de commandline reset de eigen cache van de CLI, niet die van FPM. Voor FPM is de betrouwbare reset een herstart – op Kubernetes een rollout.
  • Een hangende site. De per-procesmetrics van de exporter tonen hoe lang elke worker al bezig is; samen met de slow log is dat meestal sneller dan door access logs zoeken.

🆘 Spiekbriefje: symptoom → commando

De korte versie van dit artikel voor het moment dat er iets mis is. Uitvoeren op de host als root; <…> zijn placeholders.

SymptoomCommando
Alle workers bezet, requests wachtenk3s 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
Welke requests zijn traag?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
Hoeveel geheugen heeft een worker echt nodig?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
Oude code draait nog na een updatek3s kubectl -n nextcloud rollout restart deployment/nextcloud # OPcache: validate_timestamps=0
Hetzelfde op de blogk3s kubectl -n wordpress logs deploy/wordpress -c wordpress-fpm --tail=30
k3s kubectl -n wordpress rollout restart deployment/wordpress

🔭 Wat er nog komt

  • PHP 8.5 voor de blog – gedaan op 26 oktober 2026 (image wordpress:7.1.3-php8.5-fpm); alle plugins en het thema zijn eerst met PHP 8.5 gelint: alleen deprecation notices, geen fouten.
  • JIT staat uit. Voor I/O-gebonden webapplicaties zoals deze levert het weinig op; het zou een experiment met metingen vooraf en achteraf zijn, geen default.
  • Een alert op de listen queue – gedaan op 21 oktober 2026: het mailt als requests vijf minuten op een vrije worker wachten, wat in de 14 gemeten dagen nooit is gebeurd.
  • Twee vroege waarschuwingen – toegevoegd op 26 oktober 2026: een mail als meer dan 80 % van de workers vijf minuten bezet is, en een zodra max_children überhaupt wordt bereikt. Het queue-alert komt pas daarna.

🎯 De lessen

  • Zoek de defaults op voordat je gaat tunen: beide grote winsten zaten daar.
  • max_children volgt uit geheugen per worker (PSS) en de containerlimiet, niet uit de CPU.
  • Een volle queue maakt pagina’s eerst traag; fouten komen pas na de timeout.
  • Zonder timestampcontrole heeft elke code-update een herstart nodig.
  • Vroege waarschuwingen bij 80 % bezette workers melden zich voordat gebruikers iets merken.

⚖️ Alternatieven – en waarom PHP-FPM

OptieSterkteWaarom niet hier
Apache met mod_phpEenvoudigste setup, één procestypePHP leeft in elk webserverproces, ook in de processen die statische bestanden leveren; geen aparte poolcontrole.
FrankenPHP / RoadRunnerLanglopende workers, de applicatie blijft in het geheugenVereist een applicatie die daarvoor gebouwd is; WordPress en Nextcloud verwachten per request een verse state.
SwooleAsynchrone PHPNiet compatibel met deze applicaties.
PHP-FPM + nginxWat de images meeleveren, fijne controle, goed begrepenGekozen.

Niets in deze post is exotisch. De twee echte winsten – vijfentwintig workers meer en een cache waar de code in past – kwamen van kijken wat de defaults eigenlijk waren, niet van slim tunen. Defaults zijn de gok van iemand anders over jouw workload; bij PHP-FPM zaten er twee voor Nextcloud een factor vier naast.

Sommige teksten en afbeeldingen op deze site zijn met hulp van AI gemaakt of door AI gegenereerd. Details