Wdrażanie NextPDF Connect

W skrócie

Transporty REST i gRPC działają w pulach workerów RoadRunner. Pakiet zawiera trzy profile RoadRunner: tylko HTTP, tylko gRPC oraz profil łączony. Transport MCP działa jako zwykły podproces i nie wymaga nadzorcy.

Instalacja

composer require nextpdf/server
./vendor/bin/rr get-binary

Przegląd koncepcyjny

RoadRunner jest nadzorcą procesów. Zarządza pulą workerów, restartuje workery przy presji pamięciowej i kieruje każde żądanie do dostępnego workera. Pakiet PHP udostępnia punkt wejścia workera: bin/nextpdf-server dla HTTP oraz bin/nextpdf-grpc dla gRPC. RoadRunner obejmuje ten punkt wejścia pulą workerów. Każdy worker obsługuje jedno żądanie naraz.

Transport MCP działa inaczej. bin/nextpdf-mcp jest pojedynczym procesem PHP. Komunikuje się w JSON-RPC przez stdio, a klient uruchamia go bezpośrednio.

Powierzchnia API

Profile RoadRunner

Profil	Transporty	Polecenie
`.rr.yaml`	tylko REST	`rr serve -c .rr.yaml`
`.rr.grpc.yaml`	tylko gRPC	`rr serve -c .rr.grpc.yaml`
`.rr.full.yaml`	REST + gRPC	`rr serve -c .rr.full.yaml`

Profil HTTP wiąże nasłuchiwacz REST z adresem 0.0.0.0:8080. Udostępnia punkt końcowy stanu na :2114 oraz metryki na :2112. Ustala rozmiar puli workerów na podstawie NEXTPDF_WORKER_COUNT, którego wartość domyślna wynosi cztery. W dostarczonych profilach nadzorca ogranicza każdy worker do 256 MB.

Profil łączony dodaje pulę workerów gRPC na tcp://0.0.0.0:9090. Ustala rozmiar tej puli na podstawie NEXTPDF_GRPC_WORKER_COUNT, którego wartość domyślna wynosi dwa. Konfiguruje również wzajemny TLS dla gRPC.

Przykład kodu — szybki start

export NEXTPDF_API_KEYS_FILE=/run/secrets/api-keys
./vendor/bin/rr serve -c .rr.full.yaml

Przykład kodu — produkcja

Uruchom kontener produkcyjny z profilem łączonym, kluczami opartymi na pliku i współdzielonymi magazynami opartymi na Redis:

services:
  nextpdf-connect:
    image: ghcr.io/nextpdf-labs/server:latest
    command: ["rr", "serve", "-c", "/app/.rr.full.yaml"]
    ports:
      - "8080:8080"   # REST
      - "9090:9090"   # gRPC
    environment:
      - NEXTPDF_API_KEYS_FILE=/run/secrets/api-keys
      - NEXTPDF_WORKER_COUNT=8
      - NEXTPDF_GRPC_WORKER_COUNT=4
      - NEXTPDF_REDIS_HOST=redis
    secrets:
      - api-keys
    depends_on:
      redis:
        condition: service_healthy
    restart: unless-stopped
  redis:
    image: redis:8

Przypadki brzegowe i pułapki

Magazyny w pamięci nie są współdzielone między workerami. Bez Redis każdy worker utrzymuje własne magazyny limitów żądań, idempotentności i dokumentów. W puli wielu workerów magazyny w pamięci powodują niespójne ograniczanie żądań i mogą gubić dokumenty między workerami. W każdej puli z więcej niż jednym workerem ustaw NEXTPDF_REDIS_HOST i zainstaluj ext-redis. Serwer automatycznie przełącza się z powrotem na magazyny w pamięci, jeśli połączenie z Redis zawiedzie. Sprawdzaj kondycję Redis; nie przyjmuj jej za pewnik.
Magazyn zadań używa SQLite w trybie WAL. Zadania asynchroniczne są zapisywane w jednym pliku SQLite współdzielonym przez wszystkie workery HTTP i gRPC. Umieść ten plik na woluminie, na którym wszystkie workery mogą zapisywać. Gdy worker się zamyka, w miarę możliwości oznacza swoje wciąż działające zadania jako nieudane, dzięki czemu nie zostają osierocone.
bin/nextpdf-prune jest punktem wejścia do konserwacji. Jest dostarczany w repozytorium, a nie w vendor/bin/. Uruchamiaj go bezpośrednio do czyszczenia magazynów. Nie jest transportem serwera.
Wersja PHP w obrazie może nie mieć ext-redis. Dostarczony plik Dockerfile buduje ext-redis w miarę możliwości. Budowanie jest kontynuowane bez rozszerzenia, jeśli dla bazowego PHP nie istnieje zgodne wydanie. Upewnij się, że rozszerzenie jest obecne w działającym obrazie, zanim zaczniesz polegać na magazynach opartych na Redis.

Wydajność

Ustaw NEXTPDF_WORKER_COUNT stosownie do dostępnego CPU i pamięci. Każdy worker jest procesem PHP z górnym limitem pamięci narzuconym przez nadzorcę. Dla obciążeń intensywnie renderujących zacznij od jednego workera na rdzeń, a następnie dostrajaj na podstawie danych z punktu końcowego metryk. Rozmiar puli gRPC dobieraj niezależnie. Zwykle jest mniejsza niż pula HTTP, ponieważ klientów gRPC jest zazwyczaj mniej i pozostają aktywni dłużej.

Uwagi dotyczące bezpieczeństwa

Wzajemny TLS dla gRPC

Profil łączony konfiguruje transport gRPC dla wzajemnego Transport Layer Security (TLS): serwer przedstawia certyfikat, a następnie wymaga certyfikatu klienta i go weryfikuje. Dostarczaj klucz serwera, certyfikat serwera i CA klienta jako sekrety wdrożeniowe, a nie elementy zaszyte w obrazie. Generuj je i rotuj poza pasmem; nie uruchamiaj transportu gRPC z nasłuchiwaczem w postaci zwykłego tekstu w niezaufanej sieci.

Terminacja TLS dla REST

Profil REST wiąże nasłuchiwacz HTTP w postaci zwykłego tekstu. Terminuj TLS przed nim za pomocą reverse proxy, modułu równoważenia obciążenia lub siatki usług, a nasłuchiwacz wiąż wyłącznie z siecią wewnętrzną. Przekazuj tożsamość klienta przez nagłówek Authorization bez zmian; serwer przeprowadza własną walidację klucza. Sam nasłuchiwacz nie zapewnia bezpiecznego transportu; zapewnia go konfiguracja wdrożeniowa.

Sekrety

Montuj klucze API za pomocą NEXTPDF_API_KEYS_FILE wskazującego na plik z sekretem, zamiast używać wbudowanej zmiennej NEXTPDF_API_KEYS. Magazyn oparty na pliku przeładowuje się na gorąco po zmianie, więc rotacja nie wymaga ponownego uruchomienia. Nigdy nie zaszywaj kluczy ani prywatnego materiału TLS w obrazie. Zobacz /connect/security-and-operations/.

Zgodność

Mechanizmy wdrażania nie zawierają żadnych normatywnych deklaracji dotyczących protokołu. Cytaty dotyczące uwierzytelniania i bezpieczeństwa transportu są przypięte w /connect/security-and-operations/.

Kontekst komercyjny

Zainstaluj nextpdf/premium w obrazie, aby zarejestrować dodatkowe narzędzia Pro i Enterprise wewnątrz tych samych workerów. Nie wymaga to żadnego osobnego procesu ani portu. Granicę pakowania ustalasz w czasie budowania obrazu.

Zobacz także

/connect/configuration/ — liczba workerów, Redis i limity poziomów
/connect/security-and-operations/ — TLS, wzajemny TLS, sekrety, model zagrożeń
/transports/rest/ · /transports/grpc/ — szczegóły działania dla poszczególnych transportów
/connect/production-usage/ — sondy kondycji, skalowanie i obserwowalność
/connect/troubleshooting/ — diagnozowanie awarii workerów, magazynów i uwierzytelniania