如何在 Google Cloud 上運行 IronPDF for Java

為什麼預設的雲函式映像無法工作？

預設的 Google Cloud Function 運行時映像設計為最小化——其中僅包括執行用常見語言編寫的函式程式碼所需的包。 IronPDF 的基於 Chromium 的渲染引擎依賴於更廣泛的一組 Linux 系統庫（字體、圖形庫、沙箱工具），這些在標準映像中缺失。

Google 發布了每個運行時可用系統包的完整列表，位於 Google Cloud Functions 系統包參考。 Chromium 的依賴在任何標準的二代運行時中均不包含。 嘗試在預設映像中載入 IronPDF 引擎會導致啟動時本機庫載入失敗。

解決方案是構建一個自定義 Docker 映像，在新增函式二進制之前明確安裝這些包。 此方法完全支持 Google Cloud Functions，並且是任何需要本機二進制的函式推薦的策略。 請參閱 IronPDF Linux 部署指南 以瞭解應包括的完整包列表。

如何為 Google Cloud 構建自定義 Dockerfile？

自定義的 Dockerfile 提供對運行環境的完全控制。 從官方的 Google Cloud Functions Java 基礎映像開始，然後安裝 Chromium 需要的系統庫。

下面的 Dockerfile 示範了推薦的模式。 用您函式專案的具體內容替換 COPY 和 CMD 條目：

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

chmod 777 /tmp/ 行是必要的，因為 IronPDF 需要在初始化期間寫入並執行引擎二進制。 如果工作目錄沒有執行權限，引擎將無法啟動。

如何為 Google Cloud 部署配置 pom.xml？

標準 ironpdf Maven 工件包含多個平臺的引擎二進制。 對於 Google Cloud Functions（在 x86-64 Linux 上運行），新增平台特定的引擎工件以保持部署映像精簡 並確保正確的二進制文件始終可用：

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

始終將版本號更新為IronPDF for Java 的最新發布。 ironpdf-engine-linux-x64 工件必須與核心 ironpdf 工件的版本完全匹配。

如何新增 Maven Shade 插件？

當作為 uber-JAR（大 JAR）部署到 Google Cloud Functions 時，maven-shade-plugin 確保所有間接依賴項的服務裝載文件正確地合併。 沒有它，某些 gRPC 服務註冊可能會被默默地刪除，導致引擎初始化失敗。

在您的 pom.xml 的 <build><plugins> 部分新增以下插件配置：

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

ServicesResourceTransformer 是關鍵部分。 它將來自每個依賴項 JAR 的 META-INF/services/ 條目合併到一個文件中。gRPC 使用 Java 的 ServiceLoader 機制，因此合併的服務文件是傳輸選擇（HTTP/2 vs. 純文字）運行時需要的。

如何新增可選的 gRPC 依賴項？

在某些部署配置中 - 特別是在使用某些版本的 Google Cloud Functions 框架時當使用陰影 JAR 時 - 需要顯式的 gRPC 傳輸依賴項。 如果函式因 gRPC 傳輸或通道錯誤而無法啟動，請新增這些：

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

在大多數情況下，包括 grpc-netty-shaded 足以用於生產。 grpc-okhttp 傳輸是一個較輕的替代方案，當以最小化映像大小為優先事項時很有用。 只有在遇到關於遺失的跟踪註解的類路徑警告時才新增 perfmark-api。

如何為 Google Cloud Functions 設定資源限制？

IronPDF 在其第一次調用時在 Cloud Function 容器中啟動一個 Chromium 子進程。 Chromium 的啟動和初始渲染對記憶體的要求很高，函式必須保持活動以便引擎初始化。Cloud Functions 的預設資源限制對於可靠運行來說太低。

在部署函式時在 Google Cloud Console 或通過 gcloud CLI 中配置以下限制：

這些值是起始點。 大批量或複雜的 PDF 生成可能需要更高的記憶體分配。 監控 Google Cloud Console 中的雲函式記憶體使用度量，並在觀察到記憶體不足錯誤時增加限制。

如何配置工作目錄和文件權限？

IronPDF 引擎在啟動時將其二進制文件提取到工作目錄。在 Google Cloud Functions 上，唯一的可寫和可執行路徑是 /tmp/。 在調用任何 IronPDF API 之前明確設置工作目錄，並確保 Dockerfile 授予該路徑必要的權限。

在函式入口點的頂部新增此配置調用，在進行任何 PDF 操作之前：

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

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

然後將相應的權限命令新增到您的 Dockerfile：

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

using static {} 初始化器塊保證在函式中的任何類嘗試載入 IronPDF 引擎之前已配置工作目錄。如果在實例方法或請求處理器中設置它，可能會存在其他執行緒在路徑配置之前初始化引擎的風險。

接下來的步驟是什麼？

本指南涵蓋了使用自定義 Docker 容器在 Google Cloud Function 中運行 IronPDF for Java 的完整配置。 關鍵點是：使用安裝 Chrome 系統依賴的自定義 Dockerfile，包括 ironpdf-engine-linux-x64 Maven 工件，將工作目錄配置為 /tmp/，將超時設置至少 330 秒且記憶體至少設置 2,048 MB，並新增 maven-shade-plugin 以合併服務裝載文件。

要探索 IronPDF for Java 的更多功能，請存取 IronPDF for Java 文件 或嘗試這些指南之一：

• IronPDF for Java 在 Linux 上 - 了解 Linux 部署的 Chrome 依賴的完整列表
• IronPDF for Java 在 AWS Lambda 上 - 類似於 AWS 的基於 Docker 的部署指南
• Java 中的 HTML 到 PDF 轉換 - 您的函式邏輯的核心渲染工作流程

獲取免費試用授權 在您的 Google Cloud 環境中測試 IronPDF for Java。 生產部署需要授權金鑰。 購買授權 當您準備好上線時。