NextPDF Connect bereitstellen

Auf einen Blick

Der REST- und der gRPC-Transport laufen in RoadRunner-Worker-Pools. Das Paket liefert drei RoadRunner-Profile: nur HTTP, nur gRPC und ein kombiniertes Profil. Der MCP-Transport läuft als einfacher Subprozess und benötigt keinen Supervisor.

Installation

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

Konzeptioneller Überblick

RoadRunner ist der Prozess-Supervisor. Er verwaltet den Worker-Pool, startet Worker bei Speicherdruck neu und leitet jede Anfrage an einen freien Worker weiter. Das PHP-Paket stellt den Worker-Einstiegspunkt bereit: bin/nextpdf-server für HTTP und bin/nextpdf-grpc für gRPC. RoadRunner betreibt den Pool rund um diesen Einstiegspunkt. Jeder Worker bearbeitet zu jedem Zeitpunkt nur eine Anfrage.

Der MCP-Transport arbeitet anders. bin/nextpdf-mcp ist ein einzelner PHP-Prozess. Er kommuniziert per JSON-RPC über stdio; der Client startet ihn direkt.

API-Oberfläche

RoadRunner-Profile

Profil	Transporte	Befehl
`.rr.yaml`	nur REST	`rr serve -c .rr.yaml`
`.rr.grpc.yaml`	nur gRPC	`rr serve -c .rr.grpc.yaml`
`.rr.full.yaml`	REST + gRPC	`rr serve -c .rr.full.yaml`

Das HTTP-Profil bindet den REST-Listener an 0.0.0.0:8080. Es stellt einen Statusendpunkt unter :2114 und Metriken unter :2112 bereit. Die Größe des Worker-Pools richtet sich nach NEXTPDF_WORKER_COUNT, dessen Standardwert vier ist. Der Supervisor begrenzt den Speicher pro Worker in den ausgelieferten Profilen auf 256 MB.

Das kombinierte Profil ergänzt einen gRPC-Worker-Pool unter tcp://0.0.0.0:9090; seine Größe richtet sich nach NEXTPDF_GRPC_WORKER_COUNT, dessen Standardwert zwei ist. Außerdem konfiguriert es gegenseitiges gRPC-TLS.

Codebeispiel — Schnellstart

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

Codebeispiel — Produktion

Betreiben Sie einen Produktionscontainer mit dem kombinierten Profil, dateibasierten Schlüsseln und gemeinsamen Redis-gestützten Stores:

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

Grenzfälle und Stolperfallen

In-Memory-Stores gelten nicht über mehrere Worker hinweg. Ohne Redis hält jeder Worker seine eigenen Rate-Limit-, Idempotenz- und Dokument-Stores. Ein Pool mit mehreren Workern und In-Memory-Stores führt zu inkonsistentem Rate-Limiting; Dokumente gehen zwischen Workern verloren. Setzen Sie für jeden Pool, der größer als ein Worker ist, NEXTPDF_REDIS_HOST und installieren Sie ext-redis. Der Server fällt automatisch auf In-Memory zurück, wenn die Redis-Verbindung fehlschlägt. Prüfen Sie die Redis-Verfügbarkeit, statt sie vorauszusetzen.
Der Job-Store ist SQLite im WAL-Modus. Asynchrone Jobs werden in einer einzigen SQLite-Datei gespeichert, die alle HTTP- und gRPC-Worker gemeinsam nutzen. Legen Sie diese Datei auf ein Volume, auf das alle Worker schreiben können. Wenn ein Worker herunterfährt, markiert er seine noch laufenden Jobs, soweit möglich, als fehlgeschlagen, damit diese Jobs nicht verwaist zurückbleiben.
bin/nextpdf-prune ist ein Wartungseinstiegspunkt. Er wird im Repository ausgeliefert, nicht in vendor/bin/. Rufen Sie ihn für Store-Aufräumaufgaben direkt auf. Er ist kein Server-Transport.
Die PHP-Version des Images enthält möglicherweise kein ext-redis. Das ausgelieferte Dockerfile versucht, ext-redis zu bauen. Es fährt ohne die Erweiterung fort, wenn für das Basis-PHP kein kompatibles Release existiert. Vergewissern Sie sich, dass die Erweiterung im laufenden Image vorhanden ist, bevor Sie sich auf Redis-gestützte Stores verlassen.

Performance

Bemessen Sie NEXTPDF_WORKER_COUNT nach verfügbarer CPU-Kapazität und verfügbarem Speicher. Jeder Worker ist ein PHP-Prozess, der durch die Speicherobergrenze des Supervisors begrenzt ist. Beginnen Sie bei renderlastigen Workloads mit einem Worker pro Kern und passen Sie den Wert dann anhand des Metrikendpunkts an. Bemessen Sie den gRPC-Pool unabhängig davon. Er ist in der Regel kleiner als der HTTP-Pool, weil es meist weniger gRPC-Clients gibt und diese langlebiger sind.

Sicherheitshinweise

Gegenseitiges gRPC-TLS

Das kombinierte Profil konfiguriert den gRPC-Transport für gegenseitiges TLS: Der Server präsentiert ein Zertifikat und fordert ein Client-Zertifikat an, das er verifiziert. Der Server-Schlüssel, das Server-Zertifikat und die Client-CA werden als Deployment-Secrets bereitgestellt und nicht ins Image eingebrannt. Erzeugen und rotieren Sie diese out-of-band; betreiben Sie den gRPC-Transport nicht mit einem Klartext-Listener in einem nicht vertrauenswürdigen Netzwerk.

REST-TLS-Terminierung

Das REST-Profil bindet einen Klartext-HTTP-Listener. Terminieren Sie TLS vorgelagert — über einen Reverse Proxy, Load Balancer oder ein Service Mesh — und binden Sie den Listener nur an das interne Netzwerk. Leiten Sie die Client-Identität unverändert über den Authorization-Header weiter; der Server führt seine eigene Schlüsselvalidierung durch. Der Listener allein bietet keinen sicheren Transport; erst diese Deployment-Konfiguration stellt ihn bereit.

Secrets

Binden Sie API-Schlüssel über die Umgebungsvariable NEXTPDF_API_KEYS_FILE ein, die auf eine Secret-Datei zeigt, statt über die Inline-Variable NEXTPDF_API_KEYS; der dateibasierte Store lädt bei Änderungen automatisch neu, sodass die Rotation keinen Neustart erfordert. Brennen Sie niemals Schlüssel oder privates TLS-Material ins Image ein. Siehe /connect/security-and-operations/.

Konformität

Die Deployment-Mechanik enthält keine normativen Protokollaussagen. Belege zu Authentifizierung und Transportsicherheit finden Sie unter /connect/security-and-operations/.

Kommerzieller Kontext

Installieren Sie nextpdf/premium in das Image, um die zusätzlichen Pro- und Enterprise-Tools in denselben Workern zu registrieren. Dafür sind weder ein separater Prozess noch ein separater Port erforderlich. Die Paketierungsgrenze wird beim Image-Build festgelegt.

Siehe auch

/connect/configuration/ — Worker-Anzahl, Redis und Stufen-Obergrenzen
/connect/security-and-operations/ — TLS, gegenseitiges TLS, Secrets, Bedrohungsmodell
/transports/rest/ · /transports/grpc/ — Laufzeitdetails pro Transport
/connect/production-usage/ — Health Probes, Skalierung und Observability
/connect/troubleshooting/ — Diagnose von Worker-, Store- und Auth-Fehlern