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.

🌐 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 tramin_spare_serversemax_spare_serversworker inattivi; quelli nuovi vengono avviati fino amax_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:fpmenextcloud:fpmcontengono 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
| Blog | Nextcloud A (più grande) | 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 del container | 1,5 GiB, 2 core | 6 GiB, 3 core | 5 GiB, 2 core |
| OPcache | 128 MB, 10.000 file, timestamp controllati ogni 60 s | 256 MB, 20.000 file, timestamp spenti | uguale |
| APCu | – | 128 MB | 128 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_timeoutprima 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 innocuofailed to ptraceper ogni richiesta lenta – accettato, perchéSYS_PTRACEindebolirebbe il container. - La pagina di stato non è esposta tramite nginx; un sidecar
php-fpm_exporternello stesso pod la legge via FastCGI e serve i numeri a Prometheus (dashboard Grafana 25545).
📊 Misurato
| Ultimi 7 giorni | Blog | Nextcloud A | Nextcloud B |
|---|---|---|---|
| Richieste PHP al giorno | ~21.700 | ~23.600 | ~16.200 |
| Picco di worker attivi | 8 su 12 | 13 su 30 | 9 su 20 |
max_children raggiunto | 0 | 0 | 0 |
| Richieste lente (> 5 s) | 0 | 0 | 0 |
| Memoria per worker (RSS / quota propria PSS) | ~78 / ~16 MB | 108–157 / 14–49 MB | 71–116 / 8–27 MB |
| Picco di memoria del container | 538 MiB su 1 GiB | 763 MiB su 6 GiB | 277 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_childrenprevisto, 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.
| Sintomo | Comando |
|---|---|
| Tutti i worker occupati, richieste in attesa | 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 |
| Quali richieste sono lente? | 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 memoria richiede davvero un worker? | for p in $(pgrep -f '^php-fpm: pool www'); doawk '/^Pss:/{s+=$2} END{printf "%d ", s/1024}' /proc/$p/smaps_rollup; done; echo |
| Dopo un aggiornamento gira ancora il codice vecchio | k3s kubectl -n nextcloud rollout restart deployment/nextcloud # OPcache: validate_timestamps=0 |
| Lo stesso sul blog | k3s kubectl -n wordpress logs deploy/wordpress -c wordpress-fpm --tail=30k3s 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_childrenviene 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_childrenderiva 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
| Opzione | Punto di forza | Perché non qui |
|---|---|---|
| Apache con mod_php | Setup più semplice, un solo tipo di processo | PHP vive in ogni processo del web server, compresi quelli che servono file statici; nessun controllo separato del pool. |
| FrankenPHP / RoadRunner | Worker di lunga durata, l’applicazione resta in memoria | Richiede un’applicazione costruita per questo; WordPress e Nextcloud si aspettano uno stato nuovo per ogni richiesta. |
| Swoole | PHP asincrono | Non compatibile con queste applicazioni. |
| PHP-FPM + nginx | Quello che forniscono le immagini, controllo granulare, ben conosciuto | Scelto. |
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.
