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 COPY und CMD-Einträge durch die spezifischen Einträge 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 chmod 777 /tmp/-Zeile ist erforderlich, da IronPDF während der Initialisierung das Engine-Binärprogramm 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-ironpdf-Maven-Artefakt 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 ironpdf-engine-linux-x64-Artefakt muss genau mit der Version des Kern-ironpdf-Artefakts übereinstimmen.

Wie füge ich das Maven Shade Plugin hinzu?

Bei der Bereitstellung auf Google Cloud Functions als Uber-JAR (Fat JAR) sorgt maven-shade-plugin dafür, dass Dienstloader-Dateien aus allen 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 <build><plugins>-Abschnitt Ihrer pom.xml hinzu:

//: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 das entscheidende Element. Es kombiniert META-INF/services/-Einträge aus jedem Abhängigkeits-JAR zu einer einzigen zusammengefügten Datei. gRPC nutzt das Java-ServiceLoader-Mechanismus, daher sind zusammengeführte Servicedateien erforderlich, 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 Einbeziehung von grpc-netty-shaded für den Produktionseinsatz aus. Der grpc-okhttp-Transport ist eine leichtere Alternative, die nützlich ist, wenn die Bildgröße minimiert werden soll. Fügen Sie perfmark-api nur hinzu, wenn Sie Warnungen über fehlende Tracking-Annotationen in der Klassenpfad 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 Limits in der Google Cloud-Konsole oder über die gcloud-CLI bei der Bereitstellung der Funktion:

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 ihr Binärprogramm zu einem Arbeitsverzeichnis beim Start. In 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 {}-Initialisatorblocks garantiert, dass das Arbeitsverzeichnis konfiguriert ist, bevor eine Klasse in Ihrer Funktion versucht, die IronPDF-Engine zu laden. Wenn Sie es in einer Instanzmethode oder einem Anforderungs-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 Abhängigkeiten der Chrome-Systeme installiert, schließen Sie das ironpdf-engine-linux-x64-Maven-Artefakt ein, konfigurieren Sie das Arbeitsverzeichnis auf /tmp/, setzen Sie die Zeitüberschreitung auf mindestens 330 Sekunden und den Speicher auf mindestens 2.048 MB, und fügen Sie die maven-shade-plugin hinzu, um Dienstloader-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.