NextPDF Gotenberg im Produktiveinsatz

Auf einen Blick

Die Brücke besteht aus einem einzelnen synchronen HTTP-Roundtrip, der durch Validierung abgesichert ist. Sie führt keine Wiederholungsversuche aus und stellt weder Queue noch Cache oder Rate-Limiting bereit. Diese Verantwortlichkeiten gehören in die Anwendung rund um die Brücke. Diese Seite zeigt, wo sie hingehören und was die Brücke garantiert, damit Sie den Rest korrekt aufbauen können.

Behandeln Sie jede Konvertierung als Remote-Aufruf an einen Dienst, den Sie betreiben, aber nicht im selben Prozess kontrollieren. Berücksichtigen Sie seine Latenz und mögliche Ausfälle.

Konfiguration und Secrets beziehen

GotenbergConfig enthält die API-URL und bei aktivierter Authentifizierung ein Bearer-Token. Das Token-Feld ist mit #[\SensitiveParameter] markiert, sodass es in Stack-Traces unkenntlich gemacht wird. Sie bleiben dennoch dafür verantwortlich, aus welcher Quelle es stammt.

• Beziehen Sie das Token beim Prozessstart aus Ihrem Secret-Manager oder aus einem eingespeisten Umgebungswert. Committen Sie es nicht und legen Sie es nicht in einer Konfigurationsdatei ab, die im Image ausgeliefert wird.
• Erzeugen Sie die Konfiguration einmal pro Request-Scope oder einmal pro Worker, nicht pro Konvertierung. Sie ist unveränderlich und ohne nennenswerten Aufwand vorzuhalten.
• GotenbergConfig::fromArray() toleriert absichtlich fehlerhafte Eingaben: Es setzt stillschweigend Standardwerte ein. Validieren Sie im Produktivbetrieb das Quell-Array selbst, bevor Sie fromArray() aufrufen. Eine fehlende URL wird dann in Ihrem Boot-Pfad als Konfigurationsfehler sichtbar und nicht später pro Konvertierung als Invalid Gotenberg configuration: apiUrl is empty-Ausnahme.

Timeouts

timeout (Sekunden, Standard 30) ist das harte Übertragungs-Timeout, das vom cURL-gebundenen Transport durchgesetzt wird. Die Office-Konvertierung über LibreOffice ist kein Sofortvorgang; große oder komplexe Dokumente dauern länger. Legen Sie das Timeout anhand der gemessenen Konvertierungslatenz Ihrer echten Dokumente fest, mit ausreichender Reserve. Halten Sie es unter dem Wert eines vorgelagerten Gateways oder der PHP-Einstellung max_execution_time. Auf diese Weise erreicht die Brücke zuerst ihr Timeout, und Sie erhalten eine typisierte Ausnahme anstelle eines abgebrochenen Prozesses.

Wenn Sie den Pfad mit eingespeistem PSR-18-Client nutzen (kein responseFactory eingespeist oder eine reine IP-URL ohne Pins), erzwingt die Brücke den Wert von timeout für diesen Client nicht. Konfigurieren Sie das Timeout auch am PSR-18-Client selbst, damit beide Transporte zeitlich begrenzt sind.

Wiederholungsversuche

Die Brücke sendet genau eine Anfrage pro Aufruf und wiederholt niemals. Fügen Sie die Wiederholungslogik im Aufrufer hinzu und gestalten Sie sie sicher:

• Wiederholen Sie nur bei einem Fehler auf Transportebene (eine GotenbergConvertException, deren Ursache eine PSR-18-Client-Ausnahme ist) und bei idempotenten Serverfehlern (HTTP 502, 503, 504). Wiederholen Sie nicht jede GotenbergConvertException unterschiedslos. Eine Antwort aus der 400-Klasse bedeutet in der Regel, dass die Eingabe falsch ist, und ein Wiederholungsversuch schlägt auf dieselbe Weise fehl.
• Verwenden Sie einen begrenzten exponentiellen Backoff mit Jitter. Ein Konvertierungsdienst unter Last gibt 503 zurück; ihn weiter zu überlasten verschlimmert den Ausfall.
• Begrenzen Sie die Gesamtzahl der Versuche und die Gesamtdauer. Die Konvertierung ist bereits langsam, daher vervielfachen unbegrenzte Wiederholungsversuche die Tail-Latenz.
• Die erneute Validierung erfolgt automatisch: Jeder wiederholte Aufruf führt die URL-Validierung und die erneute Adressprüfung erneut aus, sodass ein Wiederholungsversuch den SSRF-Schutz nicht versehentlich umgehen kann.

Nebenläufigkeit und Kapazität

Jede Konvertierung belegt auf Gotenberg-Seite für die Dauer der Anfrage eine Verbindung und einen LibreOffice-Worker. Die Brücke selbst ist zustandslos und kann sicher von vielen Workern gleichzeitig verwendet werden. Der Gotenberg-Dienst hat jedoch eine begrenzte Konvertierungskapazität.

• Begrenzen Sie die Anzahl der laufenden Konvertierungen anwendungsseitig (eine Queue, ein Semaphor oder ein Worker-Pool) auf die Kapazität, die Gotenberg dauerhaft tragen kann. Die Dimensionierung ist eine Eigenschaft Ihres Gotenberg-Deployments, nicht dieses Pakets — siehe /integrations/gotenberg/security-and-operations/.
• Die Obergrenze für die Eingabegröße (maxFileSize, Standard 50 MiB) ist die einzige integrierte Ressourcenbegrenzung der Brücke. Sie wird im Prozess durchgesetzt, bevor die Anfrage gesendet wird, sodass eine übergroße Datei niemals Dienstkapazität verbraucht. Senken Sie sie auf das, was Ihre Dokumente tatsächlich benötigen; eine kleinere Obergrenze ist ein kostengünstigerer Schutz gegen Denial-of-Service als eine größere.
• Es gibt kein In-Process-Caching. Wenn dasselbe Dokument wiederholt konvertiert wird, cachen Sie das resultierende PDF in Ihrer Anwendung, indexiert über einen Content-Hash der Eingabe.

Observability

Stellen Sie einen PSR-3-Logger bereit, um pro Konvertierungsanfrage einen debug-Eintrag zu erhalten. Der Eintrag enthält die Anfrage-URL, den Dateinamen, das erkannte Format und die Content-Length der Anfrage. Er enthält nicht den Dateiinhalt oder das Bearer-Token.

• Überführen Sie dieses Signal in Metriken: Zählen Sie Konvertierungen nach Format und Ergebnis und erfassen Sie die Wanduhrzeit um jeden convertFile()- / convertString()-Aufruf als Latenz-Histogramm. Die Brücke selbst gibt keine Metriken aus.
• Das Ergebnisobjekt stellt ein renderTimeMs-Feld bereit, das 0.0 ist, sofern Ihre Integration es nicht misst und setzt; die Brücke befüllt es nicht aus der Gotenberg-Antwort. Messen Sie den Aufruf selbst, wenn Sie diesen Wert benötigen.
• Protokollieren Sie Ausnahmen mit ihrem Typ. Der Ausnahmetyp ist das primäre Signal dafür, welcher Fehler aufgetreten ist; der Katalog befindet sich in /integrations/gotenberg/troubleshooting/.
• Rufen Sie isAvailable() von Ihrem Readiness- oder Health-Endpunkt aus auf, nicht bei jeder Konvertierung. Der Aufruf sendet ein HEAD an /health. Wenn Sie ihn vor jeder Konvertierung ausführen, verdoppeln Sie ohne Nutzen Ihre Anfragerate gegenüber dem Dienst.

Vertrag zur Fehlerbehandlung

Die Brücke macht Fehler als typisierte Ausnahmen sichtbar und gibt niemals ein partielles oder unvalidiertes Ergebnis zurück. Die relevanten Garantien lauten:

• Ein Status ungleich 200, ein Content-Type ohne application/pdf oder ein Body, der nicht mit %PDF beginnt, lösen jeweils eine GotenbergConvertException aus. Ein Ergebnisobjekt wird nur zurückgegeben, wenn alle drei Prüfungen bestehen.
• Ein PSR-18-Client-Fehler (einschließlich eines Netzwerkfehlers oder Timeouts) wird als GotenbergConvertException umhüllt, mit der ursprünglichen Ausnahme als Ursache und dem Clientcode als Ausnahmecode.
• Validierungsfehler (Nicht-HTTPS-URL, private/reserved-Adresse, übergroße Eingabe, unsicherer Dateiname) lösen RuntimeException aus, bevor Netzwerkverkehr stattfindet.
• Eine nicht erkannte Dateiendung löst ValueError aus, bevor Netzwerkverkehr stattfindet.

Fangen Sie die spezifischen Typen ab. Das Beispielprogramm in examples/convert-office-to-pdf.php zeigt die vollständige Catch-Reihenfolge. /integrations/gotenberg/troubleshooting/ erläutert jeden Auslöser.

Die Grenze der Nachbearbeitung

Die Brücke erzeugt ein PDF und beendet danach ihre Arbeit. Eine gängige Produktiv-Pipeline sieht so aus:

1. Konvertieren Sie das Office-Dokument mit dieser Brücke.
2. Laden Sie die resultierenden Bytes in ein NextPDF-Dokument.
3. Wenden Sie die Nachbearbeitung an — Seitenmontage, Wasserzeichen, PDF/A-Konvertierung, digitale Signaturen.

Schritt 3 liegt in der Verantwortung von NextPDF, nicht der Brücke. Signieren, PDF/A-Profile und Wasserzeichen werden von nextpdf/premium bereitgestellt. Halten Sie Konvertierung und Nachbearbeitung als getrennte Stufen, sodass ein Konvertierungsfehler und ein Signaturfehler unabhängig voneinander diagnostizierbar sind.

Die PAdES-Unterstützung der Pro-Edition umfasst ausschließlich die B-B-Baseline. Sie bietet weder B-T, B-LT noch B-LTA, und diese Profile ergeben sich nicht implizit aus dem Konvertieren eines Dokuments über diese Brücke. Die Long-Term-Validation- Fähigkeit ist ein separates Editionsanliegen und liegt außerhalb des Umfangs dieses Pakets.

Siehe auch

• /integrations/gotenberg/configuration/ — die Regeln zur Transportauswahl und das Pin-Modell.
• /integrations/gotenberg/security-and-operations/ — Deployment und Härtung der Gotenberg-Abhängigkeit.
• /integrations/gotenberg/troubleshooting/ — der Ausnahmekatalog.
• /integrations/gotenberg/integration/ — die Einbindung des konvertierten PDFs in eine NextPDF-Pipeline.