NextPDF Gotenberg – Überblick

Auf einen Blick

NextPDF Gotenberg ist eine leichtgewichtige Brücke zwischen NextPDF und einem externen Gotenberg-Dienst. Sie nimmt ein Office-Dokument entgegen, das NextPDF nicht nativ rendern kann, sendet dieses Dokument über HTTP an eine Gotenberg-Instanz, erhält eine PDF-Datei zurück und übergibt sie an Ihre Anwendung. Von dort übernimmt der weitere NextPDF-Funktionsumfang die Nachverarbeitung.

Das Paket ist klein und explizit. Es bettet keinen Renderer ein, startet kein LibreOffice und führt keinen Browser aus. Jede Umwandlung besteht aus einer einzelnen Multipart-HTTP-Anfrage an einen Gotenberg-Endpunkt. Sie betreiben diesen Endpunkt und richten die Brücke über die Konfiguration darauf aus.

Verwenden Sie diese Brücke, wenn Sie .docx-, .xlsx-, .pptx-, .odt-, .ods- oder .odp-Quelldateien haben und sie in einer NextPDF-Pipeline als PDF benötigen. Alles, was nach dem Erzeugen der PDF-Datei passiert – Signieren, PDF/A-Umwandlung, Wasserzeichen, Zusammenführen –, läuft über NextPDF selbst oder das Paket nextpdf/premium.

Wovon die Brücke abhängt

Die Brücke hat eine Laufzeitabhängigkeit, die kein PHP-Paket ist: einen laufenden Gotenberg-Dienst, den die Brücke über HTTPS erreichen kann.

Die Brücke installiert, verwaltet oder überwacht Gotenberg nicht. Sie stellen Gotenberg selbst bereit (das Upstream-Projekt veröffentlicht ein Container-Image) und sind für dessen Verfügbarkeit, Kapazität und Netzwerkexposition verantwortlich.
Die Brücke spricht mit Gotenbergs LibreOffice-Umwandlungsroute. Die Anfrage-URL wird als <apiUrl>/forms/libreoffice/convert aufgebaut, wobei <apiUrl> die von Ihnen konfigurierte Basis-URL ist. Diese Route legt fest, welche Formate die Brücke unterstützt.
Die Health-Prüfung richtet sich mit einer HTTP-HEAD-Anfrage an <apiUrl>/health und wertet jeden Status unter 500 als verfügbar.

Die Umwandlung findet in einem Dienst statt, den Sie betreiben. Daher hängt das Verhalten der Brücke von der Gotenberg-Version ab, die Sie ausführen. Die Brücke sendet ein festes Multipart-Anfrageformat, und der Routenpfad (/forms/libreoffice/convert) und der Health-Pfad (/health) sind der einzige Gotenberg-seitige Vertrag, den sie voraussetzt. Siehe /integrations/gotenberg/install/ für die Bereitstellungsgrundlagen und /integrations/gotenberg/security-and-operations/ für die Härtung des Dienstes.

Unterstützte Dokumentformate

Die Brücke wandelt genau die Formate um, die in ihrem OfficeFormat-Typ aufgeführt sind. Jedes Format wird anhand der Dateiendung erkannt (Groß-/Kleinschreibung wird ignoriert, und ein führender Punkt wird toleriert). Jedes Format wird dann mit einem festen MIME-Typ an Gotenberg gesendet:

Format	Endung	An Gotenberg gesendeter MIME-Typ
Word (OOXML)	`docx`	`application/vnd.openxmlformats-officedocument.wordprocessingml.document`
Excel (OOXML)	`xlsx`	`application/vnd.openxmlformats-officedocument.spreadsheetml.sheet`
PowerPoint (OOXML)	`pptx`	`application/vnd.openxmlformats-officedocument.presentationml.presentation`
OpenDocument Text	`odt`	`application/vnd.oasis.opendocument.text`
OpenDocument Spreadsheet	`ods`	`application/vnd.oasis.opendocument.spreadsheet`
OpenDocument Presentation	`odp`	`application/vnd.oasis.opendocument.presentation`

Diese Liste ist abschließend. Eine Endung außerhalb dieses Satzes löst einen ValueError aus, bevor überhaupt eine Netzwerkanfrage gestellt wird, sodass die Brücke nie eine Umwandlung versucht, die sie nicht beschreiben kann. Die Brücke beansprucht nicht, „jede Office-Datei” oder „alle Dokumentformate” zu unterstützen. Sie unterstützt die sechs oben aufgeführten Formate, weil nur diese sechs vom Code erkannt und von der Testsuite abgedeckt werden.

Veraltete Binärformate (.doc, .xls, .ppt), Rich Text (.rtf), reiner Text, CSV und Bildformate sind nicht Teil des von der Brücke erkannten Satzes. Gotenbergs eigene LibreOffice-Route akzeptiert möglicherweise ein breiteres Spektrum an Eingaben. Die Brücke beschränkt sich bewusst auf den aufgeführten Satz, damit Formaterkennung, MIME-Typ und Ergebnis-Metadaten stets konsistent und überprüfbar sind.

Wie eine Umwandlung abläuft

Eine Umwandlung ist ein einzelner linearer Ablauf. Sie validiert bei jedem Schritt, bevor auch nur ein Byte den Prozess verlässt:

Die Konfiguration wird geprüft. Eine leere API-URL schlägt sofort mit einer Umwandlungs-Exception fehl.
Die API-URL wird validiert: HTTPS ist erforderlich, und der Host wird aufgelöst und überprüft, sodass er nicht auf eine private oder reservierte Adresse zeigen kann. Der aufgelöste Adresssatz wird für späteres Pinning erfasst.
Die Eingabe wird gelesen (bei Dateiumwandlungen wird der Pfad zuerst kanonisiert, um Traversal zu blockieren), und ihre Endung wird auf ein OfficeFormat abgebildet.
Die Byte-Länge wird gegen das konfigurierte Maximum geprüft, und der Dateiname wird auf Traversal-Sequenzen, Schrägstriche, Null-Bytes und Steuerzeichen überprüft.
Der Adresssatz wird unmittelbar vor der Anfrage erneut geprüft, um das Zeitfenster zwischen Validierung und Verbindung zu schließen.
Ein multipart/form-data-Body wird aufgebaut und per POST an die LibreOffice-Route gesendet, mit einem Bearer-Token, falls eines konfiguriert ist.
Die Antwort wird ausgewertet: Der Status muss 200 sein, der Content-Type muss application/pdf enthalten, und der Body muss mit der %PDF-Signatur beginnen. Erst dann wird ein Ergebnis zurückgegeben.

Jeder Fehler in den Schritten 1–7 löst eine typisierte Exception aus, anstatt ein teilweises oder ungeprüftes Ergebnis zurückzugeben. Die genauen Exceptions und ihre Auslöser sind unter /integrations/gotenberg/troubleshooting/ katalogisiert.

Was Sie zurückbekommen

Eine erfolgreiche Umwandlung gibt ein Ergebnisobjekt zurück. Das Objekt enthält die rohen PDF-Bytes, das umgewandelte Quellformat und eine optionale Renderzeitmessung. Außerdem stellt es eine Gültigkeitsprüfung (ein nicht-leerer Body, der mit %PDF beginnt) sowie einen Accessor für die Bytegröße bereit. Die Bytes sind ein normaler PDF-Stream, sodass Sie sie auf die Festplatte schreiben, an einen Client streamen oder zur Weiterverarbeitung in ein NextPDF-Dokument einspeisen können.

Wo die Brücke aufhört

Die Brücke wandelt um und validiert. Sie erledigt Folgendes nicht:

Die Ausgabe signieren, verschlüsseln, linearisieren oder in PDF/A umwandeln. Das sind Nachverarbeitungsaufgaben, die von NextPDF-Core oder von nextpdf/premium übernommen werden.
Fehlgeschlagene Anfragen erneut versuchen, Arbeit in eine Warteschlange stellen oder Ergebnisse cachen. Das sind Aufgaben auf Anwendungsebene. /integrations/gotenberg/production-usage/ zeigt, wo Sie sie rund um die Brücke ergänzen.
Den Lebenszyklus des Gotenberg-Dienstes verwalten. Bereitstellung und Betrieb werden unter /integrations/gotenberg/security-and-operations/ behandelt.

Editionen und Nachverarbeitung

Der OSS-Core kann die umgewandelte PDF-Datei unverändert schreiben. Wenn Sie das umgewandelte Dokument signieren, ein PDF/A-Archivierungsprofil erzeugen oder ein Wasserzeichen anbringen müssen, ergänzt das Paket nextpdf/premium diese Fähigkeiten zusätzlich. Die Brücke selbst ist editionsneutral: Sie erzeugt eine PDF-Datei. Was Sie mit dieser PDF-Datei machen, bestimmt, ob Sie eine kommerzielle Edition benötigen.

Die in der Pro-Edition verfügbare PAdES-Baseline ist ausschließlich B-B. Long-Term-Validation-Profile (B-T, B-LT, B-LTA) sind nicht Teil der Pro-Edition und werden von dieser Brücke nicht bereitgestellt. Schließen Sie nicht aus dem Vorhandensein dieses Pakets auf eine Zeitstempel- oder LTV-Fähigkeit.

Siehe auch

/integrations/gotenberg/install/ – das Paket installieren und eine Gotenberg-Basis aufsetzen.
/integrations/gotenberg/configuration/ – jede Konfigurationsoption, ihr Typ, Standardwert und ihre Wirkung.
/integrations/gotenberg/quickstart/ – eine erste lauffähige Umwandlung.
/integrations/gotenberg/production-usage/ – die Brücke in eine Produktivanwendung einbinden.
/integrations/gotenberg/troubleshooting/ – der Exception-Katalog und die Bedeutung der einzelnen Exceptions.
/integrations/gotenberg/security-and-operations/ – das Sicherheitsmodell und wie der abhängige Dienst sicher betrieben wird.
/integrations/gotenberg/boot-and-discovery/ – wie Host-Frameworks die Brücke entdecken und verdrahten.
/integrations/gotenberg/integration/ – das NextPDF-Rendering über den Dienst steuern.