Deep Dive: PHP-FPM e OPcache – worker, limiti e una cache del bytecode troppo piccola

Ogni richiesta WordPress e Nextcloud è un worker PHP. Quanti sono, quanto a lungo possono girare e cosa tengono in memoria decide velocità e stabilità – con numeri misurati da tutti e tre i server e i default che li limitavano in silenzio.

Illustrazione per la serie Deep Dive

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

Deep Dive della serie attorno all’Ansible Tour. Il tour spiega i ruoli, i deep dive la tecnologia sottostante: come funziona, perché qui viene usata in questo modo, e cosa è andato storto lungo la strada.

WordPress e Nextcloud sono applicazioni PHP, e in entrambi i pod ogni richiesta dinamica finisce in un worker PHP-FPM (parte 3, parte 4). Quanti worker esistono, quanto a lungo può girare uno di loro e quanto codice compilato condividono decide quanto sono veloci i siti e cosa succede sotto carico. Questo post spiega la meccanica, le impostazioni scelte qui, le misure che ci stanno dietro – e due default che limitavano Nextcloud senza che nessuno se ne accorgesse.

Indice

🧭 Come funzionano PHP-FPM e OPcache

Master, pool, worker

PHP-FPM (“FastCGI Process Manager”) è un processo master che avvia e supervisiona i processi worker. Ogni worker gestisce esattamente una richiesta alla volta, dall’inizio alla fine. nginx, nello stesso pod, serve da sé i file statici e passa ogni richiesta .php via FastCGI alla porta 9000. Un pool è un gruppo di worker con impostazioni proprie; entrambe le applicazioni usano l’unico pool www delle immagini ufficiali.

Quanti worker

  • pm = static: un numero fisso di worker, sempre in esecuzione.
  • pm = dynamic: vengono tenuti pronti tra min_spare_servers e max_spare_servers worker inattivi; quelli nuovi vengono avviati fino a max_children.
  • pm = ondemand: i worker partono solo quando arriva una richiesta e si fermano dopo un timeout di inattività.

pm.max_children è il vero limite di concorrenza: la richiesta numero max_children + 1 aspetta nella listen queue finché un worker è libero. pm.max_requests ricicla un worker dopo quel numero di richieste, il che limita la lenta crescita di memoria dovuta a estensioni che perdono memoria.

Due tipi di limiti di tempo

max_execution_time è il limite di PHP stesso e su Linux conta solo il tempo CPU dello script – una richiesta che aspetta il database o un lock non lo consuma. request_terminate_timeout è il limite di FPM sul tempo reale: quando scade, il master uccide il worker. Solo il secondo libera un worker che si è bloccato.

OPcache: compilare una volta

PHP compila ogni script in bytecode prima di eseguirlo. OPcache tiene quel bytecode in memoria condivisa, che tutti i worker di un pool usano insieme, così un file viene compilato una volta per pod invece che una volta per richiesta. Tre impostazioni ne determinano la dimensione: memory_consumption (il segmento), interned_strings_buffer (stringhe identiche salvate una volta sola) e max_accelerated_files (il numero di slot nella sua tabella hash). Quest’ultimo viene arrotondato internamente al numero successivo di un elenco fisso di numeri primi – 10.000 diventa 16.229, 20.000 diventa 32.531. Quando gli slot o la memoria sono pieni, gli altri file semplicemente non vengono messi in cache e vengono compilati a ogni richiesta.

validate_timestamps decide se OPcache controlla le date di modifica dei file (ogni revalidate_freq secondi). Spento è più veloce, ma allora un file modificato resta bytecode vecchio finché FPM non si riavvia.

APCu: una cache per l’applicazione

APCu è un secondo segmento di memoria condivisa che l’applicazione stessa riempie di dati – Nextcloud ci salva come cache locale le ricerche di app e configurazione. Come OPcache è per pod, non condivisa tra pod; tutto ciò che deve essere coerente tra processi e pod va in Redis.

🛡️ Perché è qui

  • È quello che forniscono le immagini ufficiali. wordpress:fpm e nextcloud:fpm contengono entrambe PHP-FPM; nginx davanti è il setup documentato.
  • Concorrenza prevedibile. Un limite superiore fisso di worker che si adatta al limite di memoria del container è meglio di un server che accetta tutto e poi viene ucciso dall’OOM killer.
  • Controllo fine. Dimensione del pool, timeout, pagina di stato e slow log si possono impostare per applicazione, indipendentemente dal web server.

🔧 Cosa fa questo repository

BlogNextcloud A (più grande)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 del container1,5 GiB, 2 core6 GiB, 3 core5 GiB, 2 core
OPcache128 MB, 10.000 file, timestamp controllati ogni 60 s256 MB, 20.000 file, timestamp spentiuguale
APCu–128 MB128 MB

Le impostazioni del pool vivono in una ConfigMap montata come z-monitoring.conf in php-fpm.d/ – la “z” fa sì che venga letta per ultima e vinca sul www.conf dell’immagine. I valori di Nextcloud vengono da variabili dell’host con default nel template, così un piccolo host di test e i due server di produzione condividono un unico template.

Il default che limitava Nextcloud a cinque

Nella prima versione dello stack Nextcloud il pool non aveva impostazioni proprie. Il container quindi girava con il pm.max_children = 5 di serie di FPM – indipendentemente dal suo limite di memoria di 4 GiB. Client di sincronizzazione desktop, app mobili e le callback WOPI di Collabora occupano tutti dei worker; la sesta richiesta PHP simultanea finiva in coda. È stato corretto a luglio 2026 con un pool di 12, poi 20; a ottobre Prometheus mostrava picchi di 17 worker attivi sul server più grande, quindi il limite originale di cinque era molto reale. Il giro di tuning del 16 ottobre 2026 ha portato i pool a 30 e 20. La regola di dimensionamento: memoria per worker per max_children, più OPcache e APCu, deve restare ben sotto il limite del container.

Il succo: un default che nessuno ha impostato è comunque una decisione – di solito una che non si adatta al tuo carico.

La cache del bytecode troppo piccola

L’immagine di Nextcloud imposta max_accelerated_files = 10000, internamente 16.229 slot. Nextcloud con le sue app ha 15.486 file PHP sul server più grande e 17.811 su quello più piccolo. Sul server più piccolo, più di 1.500 file non entravano mai nella cache e venivano ricompilati a ogni richiesta che li usava. Dal 16 ottobre entrambi i server girano con 20.000 (32.531 slot) e 256 MB. Il blog, con 4.452 file PHP, è lontanissimo dal suo limite. Perché il server più piccolo ha più file: lì sono attive più app. “Più piccolo” si riferisce a utenti e carico; il limite conta i file di codice, indipendentemente da quante persone li usino.

Il succo: se la cache del bytecode è abbastanza grande dipende dal numero di file PHP, non dal numero di utenti.

Timestamp spenti – e quanto costa

Su Nextcloud validate_timestamps = 0: nessuna stat() per file e richiesta. Il prezzo è che un file modificato non viene notato finché il pod non si riavvia. Gli aggiornamenti dell’immagine riavviano comunque il pod, ma occ upgrade e occ app:update sovrascrivono i file PHP sul posto. Il playbook di aggiornamento quindi dopo di essi rifà un secondo rollout del pod Nextcloud. Scrivendo questo articolo è emerso che all’aggiornamento opzionale delle app nel playbook principale mancava quel secondo riavvio – le app aggiornate avrebbero continuato a girare con il loro vecchio codice. Corretto. Il blog tiene i timestamp attivi con un intervallo di 60 secondi, perché WordPress aggiorna i plugin sul posto dalla propria pagina di amministrazione.

Il succo: validate_timestamps=0 risparmia lavoro a ogni richiesta, ma richiede un riavvio del pod dopo ogni aggiornamento del codice.

Limiti rigidi e slow log

  • Anche request_terminate_timeout prima del 16 ottobre non era impostato: una richiesta bloccata su un lock o su uno storage esterno teneva il suo worker finché il pod non si riavviava. 3.600 s su Nextcloud, perché il download in streaming di una cartella può legittimamente durare molti minuti; 300 s sul blog.
  • Lo slow log va sullo stderr del container e quindi nel log del pod. Uno stack trace richiederebbe ptrace, che un container senza capability non ha; con profondità 0 registra solo la riga “executing too slowly”. FPM prova comunque ad agganciarsi e registra un innocuo failed to ptrace per ogni richiesta lenta – accettato, perché SYS_PTRACE indebolirebbe il container.
  • La pagina di stato non è esposta tramite nginx; un sidecar php-fpm_exporter nello stesso pod la legge via FastCGI e serve i numeri a Prometheus (dashboard Grafana 25545).

📊 Misurato

Ultimi 7 giorniBlogNextcloud ANextcloud B
Richieste PHP al giorno~21.700~23.600~16.200
Picco di worker attivi8 su 1213 su 309 su 20
max_children raggiunto000
Richieste lente (> 5 s)000
Memoria per worker (RSS / quota propria PSS)~78 / ~16 MB108–157 / 14–49 MB71–116 / 8–27 MB
Picco di memoria del container538 MiB su 1 GiB763 MiB su 6 GiB277 MiB su 5 GiB
Periodi CPU limitati (throttled)2,1 %2,2 %0,2 %

Tre letture. Primo, l’RSS di un worker ne sopravvaluta il costo: conta in ogni worker le pagine condivise di OPcache e APCu. Il PSS divide le pagine condivise tra i processi che le usano ed è il numero onesto – 16 MB per worker del blog, non 78. Secondo, i pool di Nextcloud ora sono generosi: il picco ne ha usata meno della metà, e i limiti dei container sono molto sopra i picchi. Terzo, il blog ha avuto un valore anomalo: un singolo minuto il 16 ottobre con 8 worker attivi e 30 richieste in attesa nella coda – una raffica di circa 40 richieste simultanee. Di quel giorno non è sopravvissuto alcun log (la raccolta dei log è iniziata tre giorni dopo), quindi la causa è sconosciuta. È stato un minuto in una settimana, e da allora la coda è rimasta a zero.

Una correzione mia. Il 26 ottobre ho diviso la memoria del container del blog per il numero di worker in esecuzione, ho ottenuto 90–130 MB per worker e ho concluso che 1 GiB non avrebbe retto un pool pieno di 12. Era l’errore dell’RSS di sopra in un’altra forma: la memoria del container include il segmento condiviso di OPcache, la page cache dei file PHP e il processo master. Distribuita su pochi worker sembra molto per worker, e moltiplicata per 12 la parte condivisa viene contata dodici volte. Misurato col PSS un worker richiede 20–26 MB; 12 worker più il segmento OPcache da 128 MB fanno circa 0,5 GB. Il limite è stato comunque alzato a 1,5 GiB – non per il pool, ma perché un singolo upload con elaborazione delle immagini può usare fino a memory_limit = 512M in una richiesta.

Il succo: la memoria per worker si misura col PSS. La memoria del container divisa per il numero di processi conta più volte la parte condivisa.

Cosa succede quando tutti i worker sono occupati

All’inizio non si rompe niente. nginx passa ogni richiesta PHP a FPM; se nessun worker è libero, la connessione aspetta nella listen queue del socket di FPM, e la pagina è semplicemente più lenta. Un errore arriva solo dopo: se non arriva risposta entro fastcgi_read_timeout (300 s), nginx restituisce 504; se la coda stessa è piena (backlog 511), le nuove connessioni vengono rifiutate e nginx restituisce 502. Per questo gli alert qui sotto avvisano molto prima: all'80 % di worker occupati e non appena max_children viene raggiunto anche una sola volta.

Una riunione in cui venti persone aprono lo stesso foglio di calcolo non ha bisogno di venti worker PHP. PHP gestisce apertura e salvataggio (le richieste WOPI); la modifica in sé passa attraverso una connessione WebSocket direttamente al container di Collabora. In una riunione del genere il carico finisce su CPU e memoria di Collabora – sul server più grande dal 26 ottobre può usare fino a 6 core – mentre il pool PHP resta quasi inattivo.

  • Dimensionare i worker. Misura il PSS sotto carico, moltiplicalo per il max_children previsto, aggiungi OPcache e APCu, confronta con il limite del container. Poi tieni d’occhio “max_children reached” e la listen queue in Grafana; se restano entrambi a zero, il pool è grande abbastanza.
  • Reset di OPcache. opcache_reset() da riga di comando azzera la cache della CLI, non quella di FPM. Per FPM il reset affidabile è un riavvio – su Kubernetes, un rollout.
  • Un sito bloccato. Le metriche per processo dell’exporter mostrano da quanto tempo ogni worker è occupato; insieme allo slow log di solito è più veloce che cercare nei log di accesso.

🆘 Cheat sheet: sintomo → comando

La versione breve di questo articolo per il momento in cui qualcosa non va. Da eseguire sull’host come root; <…> sono segnaposto.

SintomoComando
Tutti i worker occupati, richieste in attesak3s 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
Quali richieste sono lente?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 memoria richiede davvero un worker?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
Dopo un aggiornamento gira ancora il codice vecchiok3s kubectl -n nextcloud rollout restart deployment/nextcloud # OPcache: validate_timestamps=0
Lo stesso sul blogk3s kubectl -n wordpress logs deploy/wordpress -c wordpress-fpm --tail=30
k3s kubectl -n wordpress rollout restart deployment/wordpress

🔭 Cosa viene dopo

  • PHP 8.5 per il blog – fatto il 26 ottobre 2026 (immagine wordpress:7.1.3-php8.5-fpm); prima tutti i plugin e il tema sono stati passati al linter con PHP 8.5: solo avvisi di deprecazione, nessun errore.
  • JIT è spento. Per applicazioni web limitate dall’I/O come queste porta poco; sarebbe un esperimento con misure prima e dopo, non un default.
  • Un alert sulla listen queue – fatto il 21 ottobre 2026: manda una mail quando le richieste aspettano un worker libero per cinque minuti, cosa mai successa nei 14 giorni misurati.
  • Due preavvisi – aggiunti il 26 ottobre 2026: una mail quando più dell'80 % dei worker è occupato per cinque minuti, e una non appena max_children viene raggiunto. L’alert sulla coda arriva solo dopo questi.

🎯 Le lezioni

  • Controlla i default prima di fare tuning: entrambi i grandi guadagni stavano lì.
  • max_children deriva dalla memoria per worker (PSS) e dal limite del container, non dalla CPU.
  • Una coda piena prima rende le pagine lente; gli errori arrivano solo dopo il timeout.
  • Senza controllo dei timestamp ogni aggiornamento del codice richiede un riavvio.
  • I preavvisi all'80 % di worker occupati segnalano prima che gli utenti notino qualcosa.

⚖️ Alternative – e perché PHP-FPM

OpzionePunto di forzaPerché non qui
Apache con mod_phpSetup più semplice, un solo tipo di processoPHP vive in ogni processo del web server, compresi quelli che servono file statici; nessun controllo separato del pool.
FrankenPHP / RoadRunnerWorker di lunga durata, l’applicazione resta in memoriaRichiede un’applicazione costruita per questo; WordPress e Nextcloud si aspettano uno stato nuovo per ogni richiesta.
SwoolePHP asincronoNon compatibile con queste applicazioni.
PHP-FPM + nginxQuello che forniscono le immagini, controllo granulare, ben conosciutoScelto.

Niente in questo post è esotico. I due veri guadagni – venticinque worker in più e una cache adatta al codice – sono venuti dal guardare quali fossero davvero i default, non da un tuning ingegnoso. I default sono l’ipotesi di qualcun altro sul tuo carico di lavoro; con PHP-FPM, due di loro erano sbagliati per Nextcloud di un fattore quattro.

Alcuni testi e immagini di questo sito sono creati con l’aiuto dell’IA o generati dall’IA. Dettagli