NextPDF Connect w produkcji

W skrócie

Produkcyjne wdrożenie NextPDF Connect udostępnia kilka mechanizmów sterowania pracą: sondy kondycji i gotowości, synchroniczną i asynchroniczną ścieżkę renderowania, idempotencję, limity żądań na klienta i na adres IP oraz opcjonalne sesje stanowe. Ta strona pokazuje, jak korzystać z nich w przewidywalny sposób.

Instalacja

composer require nextpdf/server

Przegląd koncepcyjny

Transport REST (Representational State Transfer) jest potokiem oprogramowania pośredniczącego zgodnym z PHP Standards Recommendation (PSR)-15. Każde żądanie przechodzi przez oprogramowanie pośredniczące w tej kolejności: przypisanie identyfikatora żądania, limity rozmiaru treści, Cross-Origin Resource Sharing (CORS), uwierzytelnianie, autoryzacja uprawnień, ograniczanie liczby żądań, idempotencja i limit czasu. Następnie trafia do procedury obsługi. Transport gRPC korzysta z tych samych usług aplikacji za procesem roboczym gRPC RoadRunner.

Renderowanie ma dwie ścieżki. Synchroniczne POST /api/v1/render wykonuje operacje i zwraca w odpowiedzi plik Portable Document Format (PDF). Asynchroniczne zadanie używa POST /api/v1/jobs. Natychmiast zwraca identyfikator zadania, a wynik pobierasz później z GET /api/v1/jobs/{id}/result. Zadania są utrwalane we współdzielonym magazynie SQLite, więc dowolny proces roboczy może odpowiedzieć na żądanie statusu lub wyniku.

Powierzchnia API

Kondycja i gotowość

Punkt końcowy	Uwierzytelnianie	Znaczenie
`GET /healthz`	brak	Proces jest uruchomiony
`GET /readyz`	brak	Serwer jest gotowy do przyjmowania żądań

Skonfiguruj /healthz jako sondę aktywności, a /readyz jako sondę gotowości. Oba punkty końcowe nie wymagają uwierzytelniania, więc orkiestratory nie potrzebują poświadczeń.

Zadania asynchroniczne

Punkt końcowy	Metoda	Przeznaczenie
`/api/v1/jobs`	`POST`	Prześlij zadanie renderowania
`/api/v1/jobs/{id}`	`GET`	Status zadania
`/api/v1/jobs/{id}/result`	`GET`	Wynik zadania (plik PDF)
`/api/v1/jobs/{id}`	`DELETE`	Anuluj zadanie

Sesje (opcjonalne)

Gdy NEXTPDF_SESSIONS_ENABLED ma wartość true, a narzędzia są dostępne, punkty końcowe sesji udostępniają stanowy przepływ budowania. Tworzysz sesję, dodajesz strony, tekst, obrazy, tabele oraz HyperText Markup Language (HTML), ustawiasz czcionkę, a następnie renderujesz. Sesje mają limit na klienta oraz limit czasu bezczynności. Domyślnie są wyłączone.

Przykładowy kod — szybki start

Prześlij zadanie asynchroniczne i sprawdzaj wynik:

JOB=$(curl -sS -X POST http://localhost:8080/api/v1/jobs \
  -H "Authorization: Bearer $NEXTPDF_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"operations":[{"type":"add_text","text":"async render"}]}' \
  | python3 -c 'import sys,json;print(json.load(sys.stdin)["id"])')

curl -sS "http://localhost:8080/api/v1/jobs/$JOB/result" \
  -H "Authorization: Bearer $NEXTPDF_KEY" --output out.pdf

Przykładowy kod — produkcja

Aby można było bezpiecznie ponowić przesłanie, wyślij klucz idempotencji:

curl -sS -X POST http://localhost:8080/api/v1/jobs \
  -H "Authorization: Bearer $NEXTPDF_KEY" \
  -H 'Idempotency-Key: 7b1c2d3e-…' \
  -H 'Content-Type: application/json' \
  -d '{"operations":[{"type":"add_text","text":"safe retry"}]}'

Powtórzenie żądania z tym samym kluczem idempotencji zwraca pierwotny wynik zamiast tworzyć drugie zadanie. Dzięki temu przesłanie można bezpiecznie powtórzyć po awarii komunikacji. Odpowiada to właściwości, którą zapewnia metoda idempotentna: ponowne wysłanie tego samego żądania ma taki sam zamierzony skutek jak wysłanie go jeden raz (RFC 9110 §9.2.2). Takie żądanie można zatem automatycznie ponowić, jeśli połączenie zostanie zerwane, zanim klient odczyta odpowiedź (RFC 9110 §9.2.2).

Przypadki brzegowe i pułapki

Ograniczanie liczby żądań wymaga magazynu Redis, aby działało poprawnie we wszystkich procesach roboczych. Mechanizmy ograniczające na klienta i na adres IP korzystają ze skonfigurowanego magazynu. W przypadku magazynu w pamięci i więcej niż jednego procesu roboczego każdy proces roboczy zlicza żądania niezależnie, a efektywny limit jest mnożony przez liczbę procesów roboczych. W każdej puli z wieloma procesami roboczymi używaj magazynu Redis.
Żądanie odrzucone przez limit zwraca 429. Po przekroczeniu limitu serwer odpowiada kodem 429 Too Many Requests oraz nagłówkiem Retry-After, zgodnie z semantyką statusu ograniczania liczby żądań (RFC 6585 §4). Respektuj Retry-After; nie ponawiaj żądania natychmiast.
Wyniki zadań nie są przechowywane w nieskończoność. Magazyn zadań usuwa stare wpisy po upływie NEXTPDF_JOB_GC_MAX_AGE_SECONDS. Pobieraj wyniki, zanim wygasną.
Sesje zużywają pamięć. Sesja przechowuje dokument w trakcie tworzenia. Limit sesji na klienta oraz limit czasu bezczynności ograniczają ten koszt. Nie zwiększaj ich bez zwymiarowania pamięci na najgorszy przypadek.

Wydajność

Ścieżka synchroniczna zajmuje proces roboczy na czas całego renderowania. W przypadku dużych lub wolnych operacji renderowania korzystaj ze ścieżki zadań asynchronicznych. Zwalnia ona proces roboczy natychmiast, a klient odpytuje o wynik. Wymiaruj pulę procesów roboczych pod obserwowane opóźnienie renderowania i współbieżność. Monitoruj punkt końcowy metryk RoadRunner.

Uwagi dotyczące bezpieczeństwa

Każdy punkt końcowy z wyjątkiem sond kondycji i gotowości wymaga prawidłowego klucza interfejsu programowania aplikacji (API). Poziom klienta określa, które operacje i rozmiary ładunku są dozwolone. Klucze idempotencji dostarczają klienci. Traktuj każdy klucz jako nieinterpretowany i unikatowy dla jednej operacji logicznej. Zobacz /connect/security-and-operations/.

Zgodność

Twierdzenie	Źródło	`reference_id`
Idempotentne: powtórzone żądania = jeden skutek	RFC 9110 §9.2.2
Żądania idempotentne można ponawiać po awarii	RFC 9110 §9.2.2
`429` + `Retry-After` dla ograniczania liczby żądań	RFC 6585 §4

Kontekst komercyjny

Dla kluczy Pro i Enterprise obowiązują wyższe limity ładunku i czasu dla danego poziomu, gdy te narzędzia są zainstalowane. Domyślne wdrożenie korzysta z limitów poziomu core.

Zobacz też

/connect/deployment/ — pule procesów roboczych, Redis, profile RoadRunner
/transports/rest/ — pełny potok oprogramowania pośredniczącego i kontrakt OpenAPI
/connect/troubleshooting/ — diagnozowanie błędów 401/403/413/429/5xx oraz awarii magazynu
/connect/security-and-operations/ — uwierzytelnianie i zasady ograniczania liczby żądań