Opérations en production

En un coup d’œil

Cette page est la liste de vérification pour mettre NextPDF en production et l’y maintenir. Elle sélectionne l’essentiel du manuel : chaque élément renvoie à la page qui entre dans le détail, de sorte que tu vérifies ici et lis là-bas. Parcours la Liste de vérification avant le déploiement avant la première mise en production. Reviens sur la Cadence de mise à jour et les Points d’entrée pour le triage des incidents dans le cadre des opérations du jour 2.

Liste de vérification avant le déploiement

• Confirme l’environnement d’exécution : NextPDF requiert PHP >=8.4 <9.0. Composer refuse tout ce qui sort de cette fenêtre. Voir Installation.
• Vérifie les six extensions requises avec php -m : ext-mbstring, ext-zlib, ext-intl, ext-gd, ext-curl et ext-openssl. La page d’installation explique le rôle de chacune.
• Exécute vendor/bin/nextpdf doctor pour une vérification unique de l’environnement (version de PHP, extensions et disponibilité des polices en un seul rapport).
• Choisis ta voie de rendu avant de dimensionner le matériel. Le pipeline in-process (writeHtml()) ne nécessite aucun service supplémentaire. Artisan, Gotenberg et Cloudflare ajoutent chacun un navigateur ou un service réseau à exploiter. Utilise Choisis ta voie pour décider.
• Si tu as choisi un pont de rendu, lis sa page de sécurité et exploitation avant la mise en service. Voir Renforcer la surface du moteur de rendu.
• Regroupe au moment de la compilation les polices que tu utilises pour le rendu, et uniquement celles-ci. Voir Provisionner les polices pour le moteur natif en production.

Dimensionnement des ressources

Dimensionne pour le plus grand document que tu génères, pas pour la moyenne. getPdfData() construit en mémoire l’intégralité du document Portable Document Format (PDF) et le renvoie sous forme d’une seule chaîne.

• Définis la mémoire du worker ou de la fonction à partir des recommandations de dimensionnement pour serverless : un document de quelques pages tient à l’aise entre 512 et 1024 MB ; les documents riches en images ou comptant de nombreuses pages en demandent davantage.
• Fixe des délais d’expiration au-dessus du temps de construction du pire cas, avec de la marge. Déplace les tâches surdimensionnées vers une file d’attente asynchrone qui écrit dans un stockage d’objets — la même section de dimensionnement présente ce modèle.
• Donne aux workers de longue durée un opcache avec la validation des horodatages désactivée. La section opcache de la recette Docker rassemble les valeurs ini de production.
• Quand la mémoire ou le débit dérive après le lancement, commence par la table de décision du symptôme au levier.

Règles de sécurité des workers

Un Document est à usage unique. Construis-le, écris-le une seule fois et laisse-le sortir de la portée ; crée une instance neuve à chaque requête ou à chaque tâche de file d’attente. Ne partage que les registres à durée de vie du processus — FontRegistry et ImageRegistry — en les créant une seule fois au démarrage du worker. Cela correspond au modèle par requête et par tâche de PHP-FPM, des workers en file d’attente et des serveurs d’application de longue durée.

• Recette avec la séquence de démarrage et la réinitialisation à chaque cycle : Rendre des PDF en toute sécurité dans un worker longue durée.
• Le contrat en une seule réponse : Est-ce sûr pour les workers et les threads ?

Renforcer la surface du moteur de rendu

Traite le HTML comme non fiable, en particulier tout ce qui est influencé par l’utilisateur. Choisis ta voie définit la limite : par défaut, le pipeline intégré n’exécute aucun script et ne récupère aucune ressource distante, tandis que chaque pont effectue le rendu via un navigateur ou un service réseau. Avant d’exposer un pont au trafic de production, parcours sa page de sécurité et exploitation :

• Sécurité et exploitation d’Artisan — la surface du moteur de rendu Chrome.
• Sécurité et exploitation de Gotenberg — la surface du service Gotenberg.
• Sécurité et exploitation de Cloudflare — la surface de déploiement à l’edge.
• Tu fais tourner le moteur en tant que service ? Ajoute Sécurité et exploitation de Connect.

Observabilité

NextPDF ne publie aucun objectif de niveau de service (SLO) ; dérive les tiens à partir des métriques de durée de rendu et de mémoire que tu mesures ci-dessous.

Instrumente le chemin de rendu avant le premier incident, pas après.

• Moteur in-process : Observer le rendu avec OpenTelemetry.
• Déploiements NextPDF Connect : Recette OpenTelemetry pour Connect.
• Pour chaque rendu, enregistre : le temps d’horloge, le pic de mémoire, le nombre de pages, la taille de sortie et le résultat avec sa catégorie d’exception issue de la référence des erreurs.
• Alerte sur les tendances, pas seulement sur les échecs : l’augmentation des temps de construction, l’augmentation du pic de mémoire et le nombre de délais dépassés ou d’épuisements de mémoire sont les principaux signaux dans les entrées mémoire et performances.

Cadence de mise à jour

• Lis une fois la politique de prise en charge des versions, puis aligne tes versions dessus. Elle définit le contrat de versionnage sémantique, les libellés de stabilité, le cycle de vie de l’obsolescence et le vocabulaire de cycle de vie (active, lts, maintenance, frozen, eol) qu’utilise ce manuel.
• Valide composer.lock afin que chaque worker déployé résolve la même version du moteur — la page d’installation énonce cette discipline.
• Consulte le journal des modifications avant chaque montée de version.

Points d’entrée pour le triage des incidents

Pour un incident de pont de rendu (un plantage de Chrome, une panne de Gotenberg, un échec de rendu à l’edge), commence par la section des modes de défaillance de ce pont dans Renforcer la surface du moteur de rendu.

• Pars du symptôme, pas du nom de la classe, dans la base de connaissances de dépannage.
• Associe une exception interceptée à sa catégorie et à son contrat de contexte dans la référence des erreurs.

Voir aussi

• Exploiter NextPDF en production — l’essai Insider_ sur les raisons pour lesquelles le moteur se comporte ainsi sous charge.
• Conteneuriser une application NextPDF — l’image Docker de production, de bout en bout.
• Déployer en serverless — les spécificités de Lambda, Cloud Run et App Runner.
• Rendu sûr pour les workers sur Connect — les mêmes règles de durée de vie appliquées au serveur.