Jak uruchomić IronPDF for Java w Google Cloud

Dlaczego domyślne obrazy Cloud Function nie działają?

Domyślne obrazy wykonawcze Google Cloud Functions są celowo minimalne — zawierają tylko pakiety potrzebne do wykonania kodu funkcji napisanego w popularnych językach. Oparty na Chromium silnik renderujący IronPDF opiera się na szerszym zestawie systemowych bibliotek Linuksa (czcionki, biblioteki grafiki, narzędzia do sandboxingu), które są nieobecne w standardowych obrazach.

Google publikuje pełną listę dostępnych pakietów systemowych dla każdej wykonawki na dokumencie referencyjnym pakiety systemowe Google Cloud Functions. Zależności Chromium nie są włączone w żadnej z standardowych wykonawczych 2. generacji. Próba załadowania silnika IronPDF w domyślnym obrazie skutkuje błędem ładowania natywnej biblioteki przy starcie.

Rozwiązaniem jest zbudowanie niestandardowego obrazu Docker, który jawnie instaluje te pakiety przed dodaniem pliku binarnego funkcji. To podejście jest w pełni wspierane przez Google Cloud Functions i jest tą samą strategią zalecaną dla każdej funkcji, która wymaga natywnych plików binarnych. Odnieś się do przewodnika wdrożenia IronPDF dla Linuksa dla pełnej listy pakietów do uwzględnienia.

Jak zbudować niestandardowy Dockerfile dla Google Cloud?

Niestandardowy Dockerfile daje pełną kontrolę nad środowiskiem wykonawczym. Rozpocznij od oficjalnego obrazu bazowego Java Google Cloud Functions, a następnie zainstaluj systemowe biblioteki wymagane przez Chromium.

Poniższy Dockerfile demonstruje zalecany schemat. Zastąp wpisy COPY i CMD szczegółami dotyczącymi Twojego projektu funkcji:

//: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"]

Linia chmod 777 /tmp/ jest konieczna, ponieważ IronPDF musi zapisać i uruchomić plik binarny silnika podczas inicjalizacji. Bez uprawnienia do wykonywania w katalogu roboczym, silnik nie uruchomi się.

Jak skonfigurować pom.xml dla wdrożenia Google Cloud?

Standardowy artefakt Maven ironpdf zawiera pliki binarne silnika dla wielu platform. Dla Google Cloud Functions (które działają na Linux x86-64), dodaj specyficzny dla platformy artefakt silnika, aby utrzymać obraz wdrożeniowy chudy i zapewnić, że poprawny plik binarny jest zawsze dostępny:

//: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>

Zawsze aktualizuj numer wersji do najnowszego wydania IronPDF dla Java. Artefakt ironpdf-engine-linux-x64 musi dokładnie odpowiadać wersji podstawowego artefaktu ironpdf.

Jak dodać wtyczkę Maven Shade?

Podczas wdrażania w Google Cloud Functions jako plik uber-JAR (fat JAR) maven-shade-plugin zapewnia prawidłowe scalanie plików ładujących usługi ze wszystkich zależności przechodnich. Bez tego, niektóre rejestracje serwisów gRPC mogą zostać cicho pominięte, powodując, że silnik nie zainicjuje się.

Dodaj następującą konfigurację wtyczki do sekcji <build><plugins> w pliku pom.xml:

//: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>

Kluczowym elementem jest ServicesResourceTransformer. Łączy wpisy META-INF/services/ ze wszystkich plików JAR zależności w jeden połączony plik. gRPC wykorzystuje mechanizm ServiceLoader języka Java, więc połączone pliki usług są wymagane, aby wybór transportu (HTTP/2 vs. zwykły tekst) działał w czasie wykonywania.

Jak dodać opcjonalne zależności gRPC?

W niektórych konfiguracjach wdrożeń — w szczególności przy użyciu osłoniętego JAR z niektórymi wersjami frameworka Google Cloud Functions — konieczne są wyraźne zależności transportu gRPC. Dodaj je, jeśli funkcja nie uruchamia się z błędem transportu gRPC lub kanału:

//: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>

W większości przypadków do produkcji wystarczy uwzględnienie grpc-netty-shaded. Transport grpc-okhttp jest lżejszą alternatywą, przydatną gdy priorytetem jest zminimalizowanie rozmiaru obrazu. Dodaj perfmark-api tylko wtedy, gdy pojawią się ostrzeżenia dotyczące ścieżki klasy (classpath) związane z brakującymi adnotacjami śledzenia.

Jak ustawić limity zasobów dla Google Cloud Functions?

IronPDF uruchamia podproces Chromium wewnątrz kontenera Cloud Function podczas pierwszego wywołania. Uruchomienie i początkowe renderowanie Chromium są pamięciochłonne, a funkcja musi być żywa wystarczają dostatecznie długo, aby silnik się zainicjował. Domyślne limity zasobów dla Cloud Functions są zbyt niskie do niezawodnego działania.

Skonfiguruj następujące limity w Google Cloud Console lub za pomocą interfejsu CLI gcloud podczas wdrażania funkcji:

Te wartości są punktami startowymi. Wysokowydajne lub skomplikowane generowanie PDF może wymagać wyższych przydziałów pamięci. Monitoruj metryki użycia pamięci Cloud Function w Google Cloud Console i zwiększ limity, jeśli zauważysz błędy z brakiem pamięci.

Jak skonfigurować katalog roboczy i uprawnienia do plików?

Silnik IronPDF podczas uruchamiania wyodrębnia swój plik binarny do katalogu roboczego. W Google Cloud Functions jedyną ścieżką, na której można zapisywać i uruchamiać pliki, jest /tmp/. Ustaw katalog roboczy wyraźnie przed wywołaniem jakiegokolwiek API IronPDF i upewnij się, że Dockerfile przyznaje niezbędne uprawnienia na tej ścieżce.

Dodaj to wywołanie konfiguracji na początku punktu wejścia funkcji, przed jakimikolwiek operacjami PDF:

//:path=/static-assets/pdf/content-code-examples/tutorials/google-cloud/configure-working-directory.java
import com.ironsoftware.ironpdf.Ustawienies;
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.
        Ustawienies.setIronPdfEngineWorkingDirectory(Paths.get("/tmp/"));
    }
}

//:path=/static-assets/pdf/content-code-examples/tutorials/google-cloud/configure-working-directory.java
import com.ironsoftware.ironpdf.Ustawienies;
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.
        Ustawienies.setIronPdfEngineWorkingDirectory(Paths.get("/tmp/"));
    }
}

Następnie dodaj odpowiednią komendę uprawnień do swojego Dockerfile:

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

Użycie bloku inicjalizującego static {} gwarantuje, że katalog roboczy zostanie skonfigurowany, zanim jakakolwiek klasa w funkcji spróbuje załadować silnik IronPDF. Jeśli ustawisz to w metodzie instancji lub obsłudze żądania, istnieje ryzyko, że inny wątek zainicjuje silnik, zanim ścieżka zostanie skonfigurowana.

Jakie są kolejne kroki?

Ten przewodnik obejmuje pełną konfigurację dla uruchamiania IronPDF for Java wewnątrz Google Cloud Function z użyciem niestandardowego kontenera Docker. Kluczowe punkty to: użycie niestandardowego pliku Dockerfile, który instaluje zależności systemowe Chrome, dołączenie artefaktu ironpdf-engine-linux-x64 Maven, skonfigurowanie katalogu roboczego na /tmp/, ustawienie limitu czasu na co najmniej 330 sekund i pamięci na co najmniej 2048 MB oraz dodanie maven-shade-plugin w celu scalania plików ładujących usługi.

Aby dowiedzieć się więcej o możliwościach IronPDF for Java, odwiedź dokumentację IronPDF for Java lub wypróbuj jeden z tych przewodników:

• IronPDF for Java na Linux — Zrozum pełną listę zależności Chrome dla wdrożeń na Linux
• IronPDF for Java na AWS Lambda — Podobny przewodnik wdrożenia oparty na Docker dla AWS
• Konwersja HTML na PDF w Java — Podstawowy przepływ renderowania dla logiki funkcji

Uzyskaj bezpłatną licencję próbną, aby przetestować IronPDF for Java w swoim środowisku Google Cloud. Klucz licencyjny jest wymagany do wdrożeń produkcyjnych. Kup licencję, gdy jesteś gotowy do produkcji.