Operazioni in produzione

In sintesi

Questa pagina è la checklist per portare NextPDF in produzione e mantenerlo operativo. Fa da indice al manuale: ogni voce rimanda alla pagina che ne tratta i dettagli, così da verificare qui e approfondire là. Percorrere la Checklist pre-deploy prima del primo rilascio. Rivedere la Cadenza degli aggiornamenti e i Punti di ingresso per il triage degli incidenti come parte delle operazioni ordinarie (day-two).

Checklist pre-deploy

Confermare il runtime: NextPDF richiede PHP >=8.4 <9.0. Composer rifiuta qualsiasi versione al di fuori di questa finestra. Vedere Installazione.
Verificare le sei estensioni richieste con php -m: ext-mbstring, ext-zlib, ext-intl, ext-gd, ext-curl ed ext-openssl. La pagina di installazione spiega cosa fa ciascuna.
Eseguire vendor/bin/nextpdf doctor per un controllo dell’ambiente in un solo passaggio (versione di PHP, estensioni e disponibilità dei font in un unico report).
Decidere il percorso di rendering prima di dimensionare l’hardware. La pipeline in-process (writeHtml()) non richiede alcun servizio aggiuntivo. Artisan, Gotenberg e Cloudflare aggiungono ciascuno un browser o un servizio di rete da gestire. Usare Scegliere il percorso per decidere.
Se si è scelto un bridge del renderer, leggere la relativa pagina di sicurezza e operatività prima del go-live. Vedere Rafforzare la superficie del renderer.
Inserire nel bundle, al momento della build, i font che si renderizzano — e solo quelli. Vedere Fornire i font in produzione.

Dimensionamento delle risorse

Dimensionare in base al documento più grande che si genera, non a quello medio. getPdfData() costruisce in memoria l’intero documento in formato Portable Document Format (PDF) e lo restituisce come un’unica stringa.

Impostare la memoria del worker o della funzione seguendo le indicazioni di dimensionamento serverless: un documento di poche pagine sta comodamente in 512–1024 MB; i documenti ricchi di immagini o con molte pagine richiedono di più.
Impostare i timeout al di sopra del tempo di build nel caso peggiore, con un margine. Spostare i job sovradimensionati su una coda asincrona che scrive su object storage — la stessa sezione sul dimensionamento mostra il pattern.
Dotare i worker a lunga durata di opcache con la validazione dei timestamp disattivata. La sezione opcache della ricetta Docker riporta i valori ini di produzione.
Quando, dopo il lancio, la memoria o il throughput iniziano ad andare alla deriva, partire dalla tabella decisionale sintomo-leva.

Regole di sicurezza dei worker

Un Document è monouso. Costruirlo, scriverlo una sola volta e lasciarlo uscire dallo scope; creare un’istanza nuova per ogni richiesta o per ogni job di coda. Condividere soltanto i registri con durata pari al processo — FontRegistry e ImageRegistry — creandoli una sola volta all’avvio del worker. Questo rispecchia il modello per-richiesta e per-job di PHP-FPM, dei worker di coda e degli application server a lunga esecuzione.

Ricetta con la sequenza di avvio e il reset per ciclo: Rendering batch sicuro nei worker.
Il contratto in una sola risposta: È sicuro nei worker e nei thread?

Rafforzare la superficie del renderer

Trattare l’HTML come non attendibile, specialmente qualsiasi contenuto influenzato dall’utente. Scegliere il percorso definisce il confine: per impostazione predefinita, la pipeline integrata non esegue script e non recupera risorse remote, mentre ogni bridge esegue il rendering tramite un browser o un servizio di rete. Prima di esporre un bridge al traffico di produzione, esaminarne la pagina di sicurezza e operatività:

Sicurezza e operatività di Artisan — la superficie del renderer Chrome.
Sicurezza e operatività di Gotenberg — la superficie del servizio Gotenberg.
Sicurezza e operatività di Cloudflare — la superficie di deployment edge.
Si esegue il motore come servizio? Aggiungere Sicurezza e operatività di Connect.

Osservabilità

NextPDF non pubblica alcun target di service-level objective (SLO); ricavare i propri dalle metriche di durata del rendering e di memoria che si misurano più sotto.

Strumentare il percorso di rendering prima del primo incidente, non dopo.

Motore in-process: Osservare con OpenTelemetry.
Deployment con NextPDF Connect: Ricetta OpenTelemetry per Connect.
Per ogni rendering, registrare: tempo effettivo (wall time), picco di memoria, numero di pagine, dimensione dell’output e l’esito con la relativa categoria di eccezione tratta dal riferimento degli errori.
Impostare gli alert sui trend, non solo sui fallimenti: tempi di build in aumento, picchi di memoria crescenti e conteggi di timeout o di esaurimento della memoria sono i segnali principali nelle voci su memoria e prestazioni.

Cadenza degli aggiornamenti

Leggere una volta la policy di supporto delle versioni, quindi attenervisi per i rilasci. Definisce il contratto di versionamento semantico, le etichette di stabilità, il ciclo di vita di deprecazione e il vocabolario del ciclo di vita (active, lts, maintenance, frozen, eol) che questo manuale utilizza.
Effettuare il commit di composer.lock affinché ogni worker distribuito risolva la stessa versione del motore — la pagina di installazione enuncia questa disciplina.
Esaminare il changelog prima di ogni incremento di versione.

Punti di ingresso per il triage degli incidenti

Per un incidente relativo a un bridge del renderer (un crash di Chrome, un’interruzione di Gotenberg, un fallimento del rendering edge), partire dalla sezione sulle modalità di guasto di quel bridge in Rafforzare la superficie del renderer.

Partire dal sintomo, non dal nome della classe, nella knowledge base di risoluzione dei problemi.
Mappare un’eccezione catturata alla sua categoria e al suo contratto di contesto nel riferimento degli errori.

Vedere anche

Gestire NextPDF in produzione — il saggio Insider_ sul perché il motore si comporta così sotto carico.
Containerizzare un’applicazione NextPDF — l’immagine Docker di produzione, dall’inizio alla fine.
Eseguire il deployment su serverless — le specificità di Lambda, Cloud Run e App Runner.
Rendering sicuro nei worker su Connect — le stesse regole di durata applicate al server.