NextPDF Gotenberg w środowisku produkcyjnym

W skrócie

Mostek wykonuje jedno synchroniczne wywołanie przez protokół Hypertext Transfer Protocol (HTTP) i weryfikuje wynik. Nie ponawia, nie kolejkuje, nie buforuje ani nie ogranicza tempa żądań. Zaimplementuj te zachowania w aplikacji, która korzysta z mostka. Ta strona pokazuje, które elementy powinny znaleźć się po stronie aplikacji i jakie gwarancje daje mostek, aby resztę dało się zbudować poprawnie.

Każdą konwersję traktuj jak zdalne wywołanie usługi, którą obsługujesz, ale której nie kontrolujesz w obrębie procesu. W planach uwzględniaj jej opóźnienia oraz awarie.

Pozyskiwanie konfiguracji i sekretów

GotenbergConfig przechowuje adres Uniform Resource Locator (URL) interfejsu programistycznego aplikacji (API), a gdy uwierzytelnianie jest włączone – także token bearer. Pole tokenu jest oznaczone #[\SensitiveParameter], więc w śladach stosu jest maskowane. Nadal odpowiadasz za bezpieczne pozyskanie tego tokenu.

• Wczytaj token z menedżera sekretów lub z wartości środowiskowej wstrzykniętej przy starcie procesu. Nie umieszczaj go w repozytorium ani w pliku konfiguracyjnym dostarczanym wraz z obrazem.
• Twórz konfigurację raz na zakres żądania albo raz na proces roboczy, a nie dla każdej konwersji. Konfiguracja jest niezmienna, a jej utrzymanie ma niski koszt.
• GotenbergConfig::fromArray() celowo akceptuje błędne dane wejściowe i po cichu podstawia wartości domyślne. W środowisku produkcyjnym zweryfikuj tablicę źródłową, zanim wywołasz fromArray(). Brakujący adres URL ujawni się wtedy jako błąd konfiguracji podczas uruchamiania, a nie później jako wyjątek Invalid Gotenberg configuration: apiUrl is empty przy każdej konwersji.

Limity czasu

timeout (w sekundach, domyślnie 30) to sztywny limit czasu transferu stosowany przez transport przypięty do cURL. Konwersja dokumentów Office przez LibreOffice nie jest natychmiastowa; duże lub złożone dokumenty wymagają więcej czasu. Ustaw limit czasu na podstawie zmierzonego opóźnienia konwersji rzeczywistych dokumentów, z zapasem. Utrzymuj go poniżej każdego limitu czasu nadrzędnej bramy oraz poniżej max_execution_time środowiska uruchomieniowego PHP. Dzięki temu mostek przekroczy limit czasu jako pierwszy, zgłaszając typowany wyjątek zamiast dopuścić do zabicia procesu.

Jeśli używasz ścieżki klienta ze wstrzykniętym PHP Standard Recommendation 18 (PSR-18) (bez wstrzykniętego responseFactory lub z gołym adresem URL opartym na protokole internetowym (IP) bez przypięć), mostek nie zastosuje wartości timeout do tego klienta. Skonfiguruj limit czasu również na kliencie PSR-18, aby oba transporty były objęte ograniczeniem.

Ponawianie

Mostek wysyła dokładnie jedno żądanie dla każdego wywołania i nigdy go nie ponawia. Dodaj mechanizm ponawiania w kodzie wywołującym i zadbaj o jego bezpieczeństwo:

• Ponawiaj wyłącznie awarie na poziomie transportu (wyjątek GotenbergConvertException, którego przyczyną jest wyjątek klienta PSR-18) oraz idempotentne błędy serwera (HTTP 502, 503, 504). Nie ponawiaj bezkrytycznie każdego wyjątku GotenbergConvertException. Odpowiedź klasy 400 zwykle oznacza, że dane wejściowe są błędne, więc ponowienie tego samego żądania zakończy się tym samym niepowodzeniem.
• Stosuj ograniczone wycofywanie wykładnicze z losowym rozrzutem. Gdy obciążona usługa konwersji zwraca 503, bombardowanie jej żądaniami tylko pogłębia awarię.
• Ogranicz łączną liczbę prób oraz łączny czas rzeczywisty. Konwersja sama w sobie jest wolna, więc nieograniczone ponawianie zwielokrotnia opóźnienia w ogonie rozkładu.
• Ponowna walidacja odbywa się automatycznie: każde ponowione wywołanie ponownie uruchamia walidację adresu URL oraz ponowną kontrolę adresu, więc ponowienie nie może przypadkowo ominąć zabezpieczenia przed fałszowaniem żądań po stronie serwera (SSRF).

Współbieżność i przepustowość

Każda konwersja zajmuje jedno połączenie i jeden proces roboczy LibreOffice po stronie Gotenberg, dopóki żądanie się nie zakończy. Sam mostek jest bezstanowy i można go bezpiecznie używać równocześnie z wielu procesów roboczych. Usługa Gotenberg ma jednak skończoną przepustowość konwersji.

• Ogranicz liczbę równolegle trwających konwersji po swojej stronie (za pomocą kolejki, semafora lub puli procesów roboczych) do przepustowości, którą Gotenberg jest w stanie utrzymać. Właściwy rozmiar zależy od wdrożenia Gotenberg, a nie od tego pakietu; zobacz /integrations/gotenberg/security-and-operations/.
• Limit rozmiaru danych wejściowych (maxFileSize, domyślnie 50 MiB) to jedyne wbudowane ograniczenie zasobów w mostku. Mostek egzekwuje go w obrębie procesu przed wysłaniem żądania, więc zbyt duży plik nigdy nie zużywa przepustowości usługi. Obniż go do poziomu faktycznie wymaganego przez dokumenty; mniejszy limit jest tańszą ochroną przed odmową usługi niż limit zawyżony.
• W obrębie procesu nie ma buforowania. Jeśli wielokrotnie konwertujesz ten sam dokument, buforuj wynik w formacie Portable Document Format (PDF) w swojej aplikacji, kluczując go skrótem treści danych wejściowych.

Obserwowalność

Wstrzyknij rejestrator PHP Standard Recommendation 3 (PSR-3), aby uzyskać jeden wpis debug dla każdego żądania konwersji. Wpis zawiera adres URL żądania, nazwę pliku, wykryty format oraz długość treści żądania. Nie zawiera treści pliku ani tokenu bearer.

• Przełóż ten sygnał na metryki: zliczaj konwersje według formatu i wyniku oraz rejestruj czas rzeczywisty każdego wywołania convertFile() / convertString() jako histogram opóźnień. Sam mostek nie emituje metryk.
• Obiekt wyniku udostępnia pole renderTimeMs. Ma ono wartość 0.0, chyba że integracja zmierzy i ustawi tę wartość; mostek nie wypełnia tego pola na podstawie odpowiedzi Gotenberg. Jeśli potrzebujesz tej wartości, zmierz czas wywołania po swojej stronie.
• Rejestruj wyjątki wraz z ich typem. Typ wyjątku to główny sygnał wskazujący, co zawiodło; katalog znajdziesz w /integrations/gotenberg/troubleshooting/.
• Wywołuj sondę isAvailable() z punktu końcowego gotowości lub kondycji, a nie przy każdej konwersji. Wysyła ona żądanie HEAD do /health. Wywoływanie jej przed każdą konwersją podwaja tempo żądań kierowanych do usługi bez żadnej korzyści.

Kontrakt obsługi awarii

Mostek przekazuje awarie jako typowane wyjątki i nigdy nie zwraca częściowego ani niezweryfikowanego wyniku. Gwarantuje, co następuje:

• Status inny niż 200, nagłówek Content-Type bez application/pdf albo treść, która nie zaczyna się od %PDF, powodują zgłoszenie wyjątku GotenbergConvertException. Mostek zwraca obiekt wyniku tylko wtedy, gdy wszystkie trzy kontrole przejdą pomyślnie.
• Awaria klienta PSR-18 (w tym awaria sieci lub przekroczenie limitu czasu) jest opakowywana jako GotenbergConvertException, w którym pierwotny wyjątek jest przyczyną, a kod klienta – kodem wyjątku.
• Niepowodzenia walidacji (adres URL inny niż HTTPS, adres private/reserved, zbyt duże dane wejściowe, niebezpieczna nazwa pliku) zgłaszają RuntimeException, zanim dojdzie do jakiegokolwiek ruchu sieciowego.
• Nierozpoznane rozszerzenie pliku zgłasza ValueError, zanim dojdzie do jakiegokolwiek ruchu sieciowego.

Przechwytuj konkretne typy. Przykładowy program w examples/convert-office-to-pdf.php pokazuje pełną kolejność przechwytywania. /integrations/gotenberg/troubleshooting/ wyjaśnia poszczególne wyzwalacze.

Granica przetwarzania końcowego

Mostek tworzy plik PDF i kończy działanie. Typowy potok produkcyjny wygląda następująco:

1. Przekonwertuj dokument Office za pomocą tego mostka.
2. Wczytaj powstałe bajty do dokumentu NextPDF.
3. Zastosuj przetwarzanie końcowe: składanie stron, nakładanie znaków wodnych, konwersję do formatu Portable Document Format/Archive (PDF/A) oraz podpisy cyfrowe.

Krok 3 należy do NextPDF, a nie do mostka. nextpdf/premium zapewnia podpisywanie, profile PDF/A oraz nakładanie znaków wodnych. Traktuj konwersję i przetwarzanie końcowe jako odrębne etapy, aby móc diagnozować niepowodzenie konwersji niezależnie od niepowodzenia podpisywania.

Obsługa PDF Advanced Electronic Signatures (PAdES) w edycji Pro obejmuje wyłącznie poziom bazowy B-B. Nie obejmuje B-T, B-LT ani B-LTA, a te profile nie wynikają z samego przekonwertowania dokumentu przez ten mostek. Możliwość walidacji długoterminowej to odrębna kwestia edycji i wykracza poza zakres tego pakietu.

Zobacz też

• /integrations/gotenberg/configuration/ - reguły wyboru transportu oraz model przypięć.
• /integrations/gotenberg/security-and-operations/ - wdrażanie i utwardzanie zależności Gotenberg.
• /integrations/gotenberg/troubleshooting/ - katalog wyjątków.
• /integrations/gotenberg/integration/ - podłączanie przekonwertowanego pliku PDF do potoku NextPDF.