Eksploatacja produkcyjna

W skrócie

Ta strona jest listą kontrolną wdrożenia NextPDF na produkcję i utrzymania go tam. Stanowi przewodnik po podręczniku: każda pozycja odsyła do strony, która zawiera szczegóły — tutaj weryfikujesz, a tam czytasz. Przed pierwszym wydaniem przejdź przez Listę kontrolną przed wdrożeniem. W ramach codziennej eksploatacji wracaj do sekcji Rytm aktualizacji oraz Punkty startowe segregacji incydentów.

Lista kontrolna przed wdrożeniem

Potwierdź środowisko uruchomieniowe: NextPDF wymaga PHP >=8.4 <9.0. Composer odrzuca wszystko spoza tego zakresu. Zobacz Instalację.
Zweryfikuj sześć wymaganych rozszerzeń poleceniem php -m: ext-mbstring, ext-zlib, ext-intl, ext-gd, ext-curl oraz ext-openssl. Strona instalacji wyjaśnia, do czego służy każde z nich.
Uruchom vendor/bin/nextpdf doctor, aby jednorazowo sprawdzić środowisko (wersja PHP, rozszerzenia i dostępność czcionek w jednym raporcie).
Wybierz ścieżkę renderowania, zanim dobierzesz sprzęt. Potok wewnątrzprocesowy (writeHtml()) nie wymaga żadnej dodatkowej usługi. Artisan, Gotenberg i Cloudflare — każde z nich — dodaje przeglądarkę lub usługę sieciową, którą trzeba obsługiwać. Do podjęcia decyzji użyj strony Wybierz swoją ścieżkę.
Jeśli wybrano most renderera, przed uruchomieniem produkcyjnym przeczytaj jego stronę o bezpieczeństwie i eksploatacji. Zobacz Utwardzanie powierzchni renderera.
Dołącz na etapie budowania tylko te czcionki, których używasz do renderowania. Zobacz Udostępnianie czcionek na produkcji.

Dobór zasobów

Dobieraj zasoby pod największy generowany dokument, a nie pod średni. getPdfData() buduje w pamięci cały dokument Portable Document Format (PDF) i zwraca go jako jeden ciąg znaków.

Ustaw pamięć procesu roboczego lub funkcji zgodnie z wytycznymi doboru zasobów serverless: kilkustronicowy dokument mieści się swobodnie w 512–1024 MB; dokumenty z dużą liczbą obrazów lub stron potrzebują więcej.
Ustaw limity czasu powyżej najgorszego czasu budowania, z zapasem. Przenoś zbyt duże zadania do asynchronicznej kolejki, która zapisuje do magazynu obiektów — ten sam rozdział o doborze zasobów pokazuje ten wzorzec.
Długo działającym procesom roboczym udostępnij opcache z wyłączoną walidacją znaczników czasu. Sekcja o opcache w przepisie dla Dockera zawiera produkcyjne wartości ini.
Gdy po uruchomieniu zużycie pamięci lub przepustowość zacznie dryfować, zacznij od tabeli decyzyjnej objaw–dźwignia.

Zasady bezpieczeństwa procesów roboczych

Obiekt Document jest jednorazowy. Zbuduj go, zapisz jeden raz i pozwól mu opuścić zakres; twórz nową instancję na każde żądanie lub każde zadanie kolejki. Współdziel wyłącznie rejestry o cyklu życia procesu — FontRegistry i ImageRegistry — tworząc je jeden raz podczas uruchamiania procesu roboczego. Odpowiada to modelowi „na żądanie, na zadanie” stosowanemu w PHP-FPM, procesach roboczych kolejek i długo działających serwerach aplikacji.

Przepis z sekwencją uruchamiania i resetem między cyklami: Bezpieczne renderowanie wsadowe w procesie roboczym.
Kontrakt w jednej odpowiedzi: Czy jest bezpieczny dla procesów roboczych i wątków?

Utwardzanie powierzchni renderera

Traktuj HTML jako niezaufany, zwłaszcza wszystko, na co ma wpływ użytkownik. Wybierz swoją ścieżkę określa granicę: domyślnie wbudowany potok nie uruchamia żadnych skryptów ani nie pobiera zasobów zdalnych, podczas gdy każdy most renderuje przez przeglądarkę lub usługę sieciową. Zanim wystawisz most na ruch produkcyjny, przejdź przez jego stronę o bezpieczeństwie i eksploatacji:

Bezpieczeństwo i eksploatacja Artisan — powierzchnia renderera Chrome.
Bezpieczeństwo i eksploatacja Gotenberg — powierzchnia usługi Gotenberg.
Bezpieczeństwo i eksploatacja Cloudflare — powierzchnia wdrożenia brzegowego.
Uruchamiasz silnik jako usługę? Dodaj Bezpieczeństwo i eksploatacja Connect.

Obserwowalność

NextPDF nie publikuje docelowych wartości celów poziomu usług (SLO); wyznacz własne na podstawie mierzonych poniżej metryk czasu renderowania i pamięci.

Oprzyrząduj ścieżkę renderowania przed pierwszym incydentem, a nie po nim.

Silnik wewnątrzprocesowy: Obserwacja za pomocą OpenTelemetry.
Wdrożenia NextPDF Connect: Przepis OpenTelemetry dla Connect.
Dla każdego renderowania zapisuj: czas rzeczywisty, szczytowe zużycie pamięci, liczbę stron, rozmiar wyniku oraz rezultat wraz z kategorią wyjątku z dokumentacji błędów.
Alarmuj na podstawie trendów, a nie tylko awarii: rosnące czasy budowania, rosnące szczytowe zużycie pamięci oraz liczby przekroczeń limitu czasu lub wyczerpania pamięci to wiodące sygnały we wpisach o pamięci i wydajności.

Rytm aktualizacji

Przeczytaj raz zasady wsparcia wersji, a następnie trzymaj się ich przy wydaniach. Definiują one kontrakt wersjonowania semantycznego, etykiety stabilności, cykl życia wycofywania oraz słownictwo cyklu życia (active, lts, maintenance, frozen, eol), którego używa ten podręcznik.
Zatwierdzaj plik composer.lock, aby każdy wdrożony proces roboczy rozwiązywał tę samą wersję silnika — strona instalacji opisuje tę dyscyplinę.
Przejrzyj dziennik zmian przed każdą zmianą wersji.

Punkty startowe segregacji incydentów

W przypadku incydentu z mostem renderera (awaria Chrome, niedostępność Gotenberg, błąd renderowania brzegowego) zacznij od sekcji o trybach awarii danego mostu w Utwardzanie powierzchni renderera.

Zaczynaj od objawu, a nie od nazwy klasy, w bazie wiedzy o rozwiązywaniu problemów.
Przypisz przechwycony wyjątek do kategorii i kontraktu kontekstu w dokumentacji błędów.

Zobacz również

Eksploatacja NextPDF na produkcji — esej Insider_ o tym, dlaczego silnik zachowuje się w ten sposób pod obciążeniem.
Konteneryzacja aplikacji NextPDF — produkcyjny obraz Docker od początku do końca.
Wdrożenie w środowisku serverless — szczegóły dotyczące Lambda, Cloud Run i App Runner.
Bezpieczne renderowanie w procesie roboczym na Connect — te same zasady cyklu życia zastosowane do serwera.