Wie IronPDF for Java in der Google Cloud ausgeführt wird

Warum funktionieren Standard-Cloud-Funktions-Images nicht?

Standard-Google-Cloud-Funktion-Laufzeitbilder sind minimal konzipiert – sie enthalten nur die Pakete, die benötigt werden, um Funktionscode auszuführen, der in gängigen Sprachen geschrieben ist. Die Chromium-basierte Rendering-Engine von IronPDF hängt von einem breiteren Satz an Linux-Systembibliotheken ab (Schriftarten, Grafikbibliotheken, Sandboxing-Tools), die in den Standard-Images nicht vorhanden sind.

Google veröffentlicht eine vollständige Liste der verfügbaren Systempakete für jede Laufzeit in der Google Cloud Functions Systempaket-Referenz. Chromiums Abhängigkeiten sind in keinem der Standard-Laufzeits der 2. Generation enthalten. Der Versuch, die IronPDF-Engine im Standard-Image zu laden, führt beim Start zu einem nativen Bibliotheksladefehler.

Die Lösung besteht darin, ein benutzerdefiniertes Docker-Image zu erstellen, das diese Pakete explizit installiert, bevor die Funktions-Binärdatei hinzugefügt wird. Dieser Ansatz wird von Google Cloud Functions vollständig unterstützt und ist die gleiche Strategie, die für jede Funktion empfohlen wird, die native Binärdateien erfordert. Siehe die IronPDF Linux Bereitstellungsanleitung für die vollständige Liste der einzuschließenden Pakete.

Wie erstelle ich ein benutzerdefiniertes Dockerfile für Google Cloud?

Ein benutzerdefiniertes Dockerfile bietet die vollständige Kontrolle über die Laufzeitumgebung. Starten Sie mit dem offiziellen Google Cloud Functions Java-Basisimage und installieren Sie dann die Systembibliotheken, die Chromium benötigt.

Das untenstehende Dockerfile zeigt das empfohlene Muster. Ersetzen Sie die Einträge COPY und CMD durch die spezifischen Angaben Ihres Funktionsprojekts:

//:path=Dockerfile
# Use the official Google Cloud Functions Java 17 base image
FROM gcr.io/google-appengine/java17:latest

# Install Chrome system dependencies required by IronPDF's rendering engine
RUN apt-get update && apt-get install -y \
    libglib2.0-0 \
    libnss3 \
    libatk1.0-0 \
    libatk-bridge2.0-0 \
    libcups2 \
    libdrm2 \
    libxkbcommon0 \
    libxcomposite1 \
    libxdamage1 \
    libxfixes3 \
    libxrandr2 \
    libgbm1 \
    libasound2 \
    libpango-1.0-0 \
    libpangocairo-1.0-0 \
    --no-install-recommends \
    && rm -rf /var/lib/apt/lists/*

# Grant execute permissions on /tmp so the IronPDF engine can extract there
RUN chmod 777 /tmp/

# Copy the compiled JAR and set the entry point
COPY target/your-function.jar /app/function.jar
CMD ["java", "-jar", "/app/function.jar"]

Die Zeile chmod 777 /tmp/ ist erforderlich, da IronPDF die Engine-Binärdatei während der Initialisierung schreiben und ausführen muss. Ohne Ausführungsberechtigungen im Arbeitsverzeichnis wird der Start der Engine fehlschlagen.

Wie konfiguriere ich pom.xml für die Google Cloud-Bereitstellung?

Das Standard-Maven-Artefakt ironpdf bündelt Engine-Binärdateien für mehrere Plattformen. Für Google Cloud Functions (die auf Linux x86-64 laufen), fügen Sie das plattformspezifische Engine-Artefakt hinzu, um das Bereitstellungsimage schlank zu halten und sicherzustellen, dass die richtige Binärdatei immer verfügbar ist:

//:path=pom.xml
<dependencies>

    <dependency>
        <groupId>com.ironsoftware</groupId>
        <artifactId>ironpdf</artifactId>
        <version>2024.9.1</version>
    </dependency>

    <dependency>
        <groupId>com.ironsoftware</groupId>
        <artifactId>ironpdf-engine-linux-x64</artifactId>
        <version>2024.9.1</version>
    </dependency>
</dependencies>

//:path=pom.xml
<dependencies>

    <dependency>
        <groupId>com.ironsoftware</groupId>
        <artifactId>ironpdf</artifactId>
        <version>2024.9.1</version>
    </dependency>

    <dependency>
        <groupId>com.ironsoftware</groupId>
        <artifactId>ironpdf-engine-linux-x64</artifactId>
        <version>2024.9.1</version>
    </dependency>
</dependencies>

Aktualisieren Sie immer die Versionsnummer auf die neueste IronPDF for Java-Version. Das Artefakt ironpdf-engine-linux-x64 muss genau mit der Version des Kernartefakts ironpdf übereinstimmen.

Wie füge ich das Maven Shade Plugin hinzu?

Bei der Bereitstellung in Google Cloud Functions als Uber-JAR (Fat JAR) stellt maven-shade-plugin sicher, dass die Service-Loader-Dateien aller transitiven Abhängigkeiten korrekt zusammengeführt werden. Ohne sie können einige gRPC-Serviceregistrierungen stillschweigend aufgegeben werden, was dazu führt, dass die Engine nicht initialisiert wird.

Fügen Sie die folgende Plugin-Konfiguration in den Abschnitt <build><plugins> Ihrer pom.xml ein:

//:path=pom.xml
<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-shade-plugin</artifactId>
    <version>3.2.4</version>
    <executions>
        <execution>
            <phase>package</phase>
            <goals>
                <goal>shade</goal>
            </goals>

            <configuration>
                <transformers>
                    <transformer implementation="org.apache.maven.plugins.shade.resource.ServicesResourceTransformer"/>
                </transformers>
            </configuration>
        </execution>
    </executions>
</plugin>

//:path=pom.xml
<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-shade-plugin</artifactId>
    <version>3.2.4</version>
    <executions>
        <execution>
            <phase>package</phase>
            <goals>
                <goal>shade</goal>
            </goals>

            <configuration>
                <transformers>
                    <transformer implementation="org.apache.maven.plugins.shade.resource.ServicesResourceTransformer"/>
                </transformers>
            </configuration>
        </execution>
    </executions>
</plugin>

Der ServicesResourceTransformer ist der entscheidende Teil. Sie kombiniert META-INF/services/-Einträge aus jeder Abhängigkeits-JAR-Datei zu einer einzigen zusammengeführten Datei. gRPC nutzt den ServiceLoader-Mechanismus von Java, sodass zusammengeführte Service-Dateien erforderlich sind, damit die Transportauswahl (HTTP/2 vs. Klartext) zur Laufzeit funktioniert.

Wie füge ich optionale gRPC-Abhängigkeiten hinzu?

In einigen Bereitstellungskonfigurationen — insbesondere bei der Verwendung eines geschatteten JARs mit bestimmten Versionen des Google Cloud Functions-Frameworks — sind explizite gRPC-Transportabhängigkeiten erforderlich. Fügen Sie diese hinzu, wenn die Funktion beim Start mit einem gRPC-Transport- oder Kanalfehler fehlschlägt:

//:path=pom.xml
<dependencies>

    <dependency>
        <groupId>io.perfmark</groupId>
        <artifactId>perfmark-api</artifactId>
        <version>0.26.0</version>
    </dependency>

    <dependency>
        <groupId>io.grpc</groupId>
        <artifactId>grpc-okhttp</artifactId>
        <version>1.50.2</version>
    </dependency>

    <dependency>
        <groupId>io.grpc</groupId>
        <artifactId>grpc-netty-shaded</artifactId>
        <version>1.50.2</version>
    </dependency>
</dependencies>

//:path=pom.xml
<dependencies>

    <dependency>
        <groupId>io.perfmark</groupId>
        <artifactId>perfmark-api</artifactId>
        <version>0.26.0</version>
    </dependency>

    <dependency>
        <groupId>io.grpc</groupId>
        <artifactId>grpc-okhttp</artifactId>
        <version>1.50.2</version>
    </dependency>

    <dependency>
        <groupId>io.grpc</groupId>
        <artifactId>grpc-netty-shaded</artifactId>
        <version>1.50.2</version>
    </dependency>
</dependencies>

In den meisten Fällen reicht die Einbindung von grpc-netty-shaded für die Produktion aus. Der grpc-okhttp-Transport ist eine schlankere Alternative, die sich eignet, wenn die Minimierung der Bildgröße Priorität hat. Fügen Sie perfmark-api nur hinzu, wenn Sie Classpath-Warnungen bezüglich fehlender Tracing-Annotationen erhalten.

Wie setze ich Ressourcengrenzen für Google Cloud Functions?

IronPDF startet einen Chromium-Subprozess innerhalb des Cloud-Funktionscontainers bei seiner ersten Aufruf. Der Start und das erste Rendering von Chromium sind speicherintensiv, und die Funktion muss lange genug am Leben bleiben, damit die Engine initialisiert werden kann. Die standardmäßigen Ressourcengrenzen für Cloud Functions sind für einen zuverlässigen Betrieb zu niedrig.

Konfigurieren Sie die folgenden Grenzwerte in der Google Cloud Console oder über die gcloud CLI, wenn Sie die Funktion bereitstellen:

Diese Werte sind Ausgangspunkte. Hochvolumige oder komplexe PDF-Erzeugung kann höhere Speicherzuweisungen erfordern. Überwachen Sie die Cloud-Funktions-Speichernutzungsmetriken in der Google Cloud Console und erhöhen Sie die Grenzen, wenn Sie Speicherüberlauf-Fehler beobachten.

Wie konfiguriere ich das Arbeitsverzeichnis und die Dateiberechtigungen?

Die IronPDF-Engine extrahiert ihre Binärdatei beim Start in ein Arbeitsverzeichnis. Auf Google Cloud Functions ist der einzige beschreibbare und ausführbare Pfad /tmp/. Legen Sie das Arbeitsverzeichnis explizit fest, bevor Sie eine IronPDF-API aufrufen, und stellen Sie sicher, dass das Dockerfile die notwendigen Berechtigungen für diesen Pfad erteilt.

Fügen Sie diesen Konfigurationsaufruf oben in Ihrem Funktions-Einstiegspunkt, vor allen PDF-Vorgängen hinzu:

//:path=/static-assets/pdf/content-code-examples/tutorials/google-cloud/configure-working-directory.java
import com.ironsoftware.ironpdf.Einstellungs;
import java.nio.file.Paths;

public class PdfFunction {
    static {
        // Must be called before any IronPDF operation.
        // /tmp/ is the only writable and executable directory in Cloud Functions.
        Einstellungs.setIronPdfEngineWorkingDirectory(Paths.get("/tmp/"));
    }
}

//:path=/static-assets/pdf/content-code-examples/tutorials/google-cloud/configure-working-directory.java
import com.ironsoftware.ironpdf.Einstellungs;
import java.nio.file.Paths;

public class PdfFunction {
    static {
        // Must be called before any IronPDF operation.
        // /tmp/ is the only writable and executable directory in Cloud Functions.
        Einstellungs.setIronPdfEngineWorkingDirectory(Paths.get("/tmp/"));
    }
}

Fügen Sie dann den entsprechenden Berechtigungsbefehl Ihrem Dockerfile hinzu:

//:path=Dockerfile
# Ensure the IronPDF engine can extract and run binaries from /tmp/
RUN chmod 777 /tmp/

Die Verwendung eines static {}-Initialisierungsblocks stellt sicher, dass das Arbeitsverzeichnis konfiguriert ist, bevor eine Klasse in Ihrer Funktion versucht, die IronPDF-Engine zu laden. Wenn Sie dies in einer Instanzmethode oder einem Request-Handler festlegen, besteht das Risiko, dass ein anderer Thread die Engine initialisiert, bevor der Pfad konfiguriert ist.

Was sind die nächsten Schritte?

Diese Anleitung deckt die vollständige Konfiguration für den Betrieb von IronPDF for Java innerhalb einer Google Cloud Function mit einem benutzerdefinierten Docker-Container ab. Die wichtigsten Punkte sind: Verwenden Sie eine benutzerdefinierte Dockerfile, die die Systemabhängigkeiten von Chrome installiert, fügen Sie das ironpdf-engine-linux-x64 Maven-Artefakt einbinden, das Arbeitsverzeichnis auf /tmp/ konfigurieren, das Zeitüberschreitung auf mindestens 330 Sekunden und den Speicher auf mindestens 2.048 MB einstellen sowie das maven-shade-plugin hinzufügen, um Service-Loader-Dateien zusammenzuführen.

Um mehr darüber zu erfahren, was IronPDF for Java tun kann, besuchen Sie die IronPDF for Java Dokumentation oder probieren Sie eine dieser Anleitungen aus:

• IronPDF for Java auf Linux — Verstehen Sie die vollständige Liste der Chrome-Abhängigkeiten für Linux-Bereitstellungen
• IronPDF for Java auf AWS Lambda — Ähnliche Docker-basierte Anleitung für AWS
• HTML-zu-PDF-Konvertierung in Java — Kernworkflow für Rendering in Ihrer Funktionslogik

Erhalten Sie eine kostenlose Testlizenz, um IronPDF for Java in Ihrer Google Cloud-Umgebung zu testen. Ein Lizenzschlüssel ist für Produktionsbereitstellungen erforderlich. Erwerben Sie eine Lizenz, wenn Sie bereit sind, live zu gehen.