如何在AWS上設置IronPDF for Java

目錄

• 需要哪些先決條件？
• 為什麼必須使用Docker而不是Zip部署？
• 如何配置Maven依賴關係？
• 如何編寫Lambda處理程式？
• 如何配置SAM模板？
• 如何構建Dockerfile？
• 如何構建和部署Lambda函式？
• 接下來的步驟是什麼？

需要哪些先決條件？

在開始之前，請確認開發機器上安裝了以下工具。每個工具在構建和部署管道中發揮特定作用。

• IntelliJ IDEA — 本指南中使用的IDE。從jetbrains.com/idea下載。
• AWS Toolkit for JetBrains — 在IntelliJ中提供SAM專案精靈和Lambda運行配置。 設置說明在AWS Toolkit for JetBrains文件頁面上。
• AWS SAM CLI — 構建Docker映像並部署Lambda功能的命令行工具。 請按照SAM CLI安裝指南進行安裝。
• Docker Desktop — 因為Lambda功能被打包為容器映像，而不是Zip存檔，因此需要。下載Docker社群版。

在部署到AWS之前進行本地調用測試，也安裝：

• Java 8 JDK — 從Oracle JDK 8下載頁面獲得。
• Apache Maven — 按照Maven安裝指南。

工具準備就緒後，打開IntelliJ IDEA並通過File → New → Project建立新項目。 在項目精靈中，選擇AWS Lambda模板並選擇以下選項：

• Package Type: Image
• Runtime: java8 or java11
• SAM Template: Maven

為什麼必須使用Docker而不是Zip部署？

AWS Lambda支持兩種部署包型別：Zip存檔和容器映像。 Zip部署非常適合輕量級的Java功能，因為運行時環境由AWS完全管理。 然而，IronPDF運送了一個原生二進制文件——一個基於Chrome的PDF渲染引擎——必須在運行時提取並執行。Zip部署的Lambda執行環境限制了文件系統寫入到/tmp，而Zip包層限制了大型原生二進制文件的提取。

容器映像部署刪除了這些限制。 當您定義自己的Docker映像時，您可以控制基礎操作系統、安裝的系統包和目錄佈局。 IronPDF的渲染引擎可以在啟動時提取到/tmp，所需的系統庫可以預先安裝在映像中，且10 GB的容器大小限制足以容納完整引擎。

實際結果很簡單：在PackageType: Image並使用Docker-aware基礎映像進行構建。 SAM CLI會處理其餘的工作。

如何配置Maven依賴關係？

pom.xml文件需要標準Lambda SDK之外的三類附加依賴：IronPDF Java程式庫、IronPDF Linux x64渲染引擎以及IronPDF引擎內部使用的gRPC傳輸。

打開<dependencies>內新增以下依賴：

//:path=pom.xml
<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>
<dependency>
    <groupId>org.slf4j</groupId>
    <artifactId>slf4j-simple</artifactId>
    <version>2.0.3</version>
</dependency>
<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>

//:path=pom.xml
<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>
<dependency>
    <groupId>org.slf4j</groupId>
    <artifactId>slf4j-simple</artifactId>
    <version>2.0.3</version>
</dependency>
<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>

ironpdf-engine-linux-x64工件捆綁了64位Linux預編譯的基於Chromium的渲染引擎。 這就是使IronPDF能夠在Lambda容器中將HTML渲染為PDF的原因。 沒有它，渲染調用將因缺少二進制錯誤而失敗。 gRPC依賴（perfmark-api）是必需的，因為IronPDF通過本地gRPC通道與其渲染引擎通信。 slf4j-simple依賴提供了最小的日誌實現，使得IronPDF的內部日誌可以在CloudWatch中見。

始終對齊ironpdf-engine-linux-x64版本號——混合版本將導致啟動失敗。 查看IronPDF for Java在Maven Central上的最新版本字串。

如何編寫Lambda處理程式？

Lambda處理程式類接收一個APIGatewayProxyResponseEvent。 兩個IronPDF配置調用必須在第一次渲染操作之前出現：將工作目錄設置為/tmp並可選地啟用除錯日誌。

用以下內容替換App.java的內容：

//:path=App.java
import com.amazonaws.services.lambda.runtime.Context;
import com.amazonaws.services.lambda.runtime.events.APIGatewayProxyRequestEvent;
import com.amazonaws.services.lambda.runtime.events.APIGatewayProxyResponseEvent;
import com.ironsoftware.ironpdf.PdfDocument;
import com.ironsoftware.ironpdf.Settings;

import java.nio.file.Paths;
import java.util.HashMap;
import java.util.Map;

public class App {
    public APIGatewayProxyResponseEvent handleRequest(
            final APIGatewayProxyRequestEvent input,
            final Context context) {

        APIGatewayProxyResponseEvent response = new APIGatewayProxyResponseEvent();

        // IronPDF must write its engine binaries and temporary files to /tmp.
        // This is the only writable path available in the Lambda execution environment.
        Settings.setIronPdfEngineWorkingDirectory(Paths.get("/tmp/"));

        // Enable debug logging to CloudWatch during initial testing.
        Settings.setDebug(true);

        try {
            context.getLogger().log("Starting PDF render");

            // Render a PDF from a live URL. Replace with your own HTML or URL as needed.
            PdfDocument pdf = PdfDocument.renderUrlAsPdf("https://www.google.com");

            context.getLogger().log("PDF render complete");

            // Save the rendered PDF to /tmp. Files in /tmp persist for the lifetime
            // of the Lambda execution environment (warm instance).
            pdf.saveAs("/tmp/output.pdf");

            Map<String, String> headers = new HashMap<>();
            headers.put("Content-Type", "application/json");

            return response
                    .withStatusCode(200)
                    .withHeaders(headers)
                    .withBody("PDF generated successfully.");

        } catch (Exception e) {
            context.getLogger().log("PDF render failed: " + e.getMessage());
            return response
                    .withStatusCode(500)
                    .withBody("{\"error\": \"" + e.getMessage() + "\"}");
        }
    }
}

//:path=App.java
import com.amazonaws.services.lambda.runtime.Context;
import com.amazonaws.services.lambda.runtime.events.APIGatewayProxyRequestEvent;
import com.amazonaws.services.lambda.runtime.events.APIGatewayProxyResponseEvent;
import com.ironsoftware.ironpdf.PdfDocument;
import com.ironsoftware.ironpdf.Settings;

import java.nio.file.Paths;
import java.util.HashMap;
import java.util.Map;

public class App {
    public APIGatewayProxyResponseEvent handleRequest(
            final APIGatewayProxyRequestEvent input,
            final Context context) {

        APIGatewayProxyResponseEvent response = new APIGatewayProxyResponseEvent();

        // IronPDF must write its engine binaries and temporary files to /tmp.
        // This is the only writable path available in the Lambda execution environment.
        Settings.setIronPdfEngineWorkingDirectory(Paths.get("/tmp/"));

        // Enable debug logging to CloudWatch during initial testing.
        Settings.setDebug(true);

        try {
            context.getLogger().log("Starting PDF render");

            // Render a PDF from a live URL. Replace with your own HTML or URL as needed.
            PdfDocument pdf = PdfDocument.renderUrlAsPdf("https://www.google.com");

            context.getLogger().log("PDF render complete");

            // Save the rendered PDF to /tmp. Files in /tmp persist for the lifetime
            // of the Lambda execution environment (warm instance).
            pdf.saveAs("/tmp/output.pdf");

            Map<String, String> headers = new HashMap<>();
            headers.put("Content-Type", "application/json");

            return response
                    .withStatusCode(200)
                    .withHeaders(headers)
                    .withBody("PDF generated successfully.");

        } catch (Exception e) {
            context.getLogger().log("PDF render failed: " + e.getMessage());
            return response
                    .withStatusCode(500)
                    .withBody("{\"error\": \"" + e.getMessage() + "\"}");
        }
    }
}

對Settings.setIronPdfEngineWorkingDirectory(Paths.get("/tmp/"))的調用是強制性的。 AWS Lambda的執行環境將函式程式碼掛載在唯讀目錄中。 IronPDF引擎必須在啟動時提取支持文件並建立套接字——這些活動需要寫存取權限。 /tmp目錄是Lambda允許文件寫入的唯一位置，因此IronPDF必須在任何渲染開始之前指向那裡。 如果省略此設置，引擎將無法啟動，且每個渲染調用都將拋出異常。

/tmp文件系統中。 如果Lambda函式需要將PDF作為二進制響應返回或上傳到S3，則應使用pdf.getBinaryData()檢索字節，而不是寫入磁碟。 對於大規模工作負載，推薦的模式是上傳到Amazon S3並返回預簽名的URL。

如何配置SAM模板？

template.yaml文件控制著Lambda函式的資源分配。 三個設置直接影響IronPDF是否能成功運行：EphemeralStorage.Size。

將Globals部分更新如下：

//:path=template.yaml
Globals:
  Function:
    Timeout: 400
    MemorySize: 2048
    EphemeralStorage:
      Size: 1024

//:path=template.yaml
Globals:
  Function:
    Timeout: 400
    MemorySize: 2048
    EphemeralStorage:
      Size: 1024

Timeout設置為400秒。 在冷啟動時，IronPDF必須將渲染引擎提取到/tmp並啟動一個本地Chromium進程。 這次提取會在第一次調用時花費30–60秒。 超過330秒的超時將導致冷啟動調用因任務超時錯誤而失敗。 預熱調用要快得多——簡單的HTML到PDF轉換通常在5秒內完成。

MemorySize設置為2048 MB。 Chromium渲染器是記憶體密集型的。AWS Lambda的IronPDF最低可行記憶體為1024 MB，但2048 MB減少了因為複雜頁面導致記憶體不足失敗的風險，同時因為Lambda在記憶體中還按比例縮放CPU分配，產生顯著更快的渲染時間。

EphemeralStorage.Size設置為1024 MB。 預設的Lambda /tmp分配是512 MB。 IronPDF將渲染引擎二進位文件、字體快取和臨時渲染文件寫入/tmp。 這些資產在冷啟動時可能超過512 MB，這會導致引擎提取失敗。 設置臨時儲存至少為1024 MB可以防止這種失敗模式。

如何構建Dockerfile？

Dockerfile是此部署的核心。 它執行多步驟構建：第一步驟使用Maven構建映像編譯Java項目； 第二步驟基於Amazon Linux 2建立最終的Lambda運行時映像，安裝IronPDF的Chromium引擎所需的系統包，並複製已編譯的工件。

打開專案的Dockerfile並將其內容替換為以下內容：

//:path=Dockerfile
# Stage 1: Build the Maven project
FROM public.ecr.aws/sam/build-java8.al2:latest AS build-image
WORKDIR /task
COPY src/src/
COPY pom.xml ./
RUN mvn -q clean install
RUN mvn dependency:copy-dependencies -DincludeScope=compile

# Stage 2: Create the Lambda runtime image
FROM public.ecr.aws/lambda/java:8.al2

# Update the package index and install system libraries required by Chromium.
# These packages provide font rendering, graphics, audio, GTK3, and input
# method support — all needed by the headless browser inside IronPDF.
RUN yum update -y && \
    yum install -y \
        pango.x86_64 \
        libXcomposite.x86_64 \
        libXcursor.x86_64 \
        libXdamage.x86_64 \
        libXext.x86_64 \
        libXi.x86_64 \
        libXtst.x86_64 \
        cups-libs.x86_64 \
        libXScrnSaver.x86_64 \
        libXrandr.x86_64 \
        GConf2.x86_64 \
        alsa-lib.x86_64 \
        atk.x86_64 \
        gtk3.x86_64 \
        ipa-gothic-fonts \
        xorg-x11-fonts-100dpi \
        xorg-x11-fonts-75dpi \
        xorg-x11-utils \
        xorg-x11-fonts-cyrillic \
        xorg-x11-fonts-Type1 \
        xorg-x11-fonts-misc \
        glibc-devel.x86_64 \
        at-spi2-atk.x86_64 \
        mesa-libgbm.x86_64 \
        libxkbcommon \
        amazon-linux-extras && \
    amazon-linux-extras install epel -y && \
    yum install -y libgdiplus

# Ensure /tmp is writable by the Lambda execution user.
RUN chmod 777 /tmp/

# Copy the compiled classes and dependencies from the build stage.
COPY --from=build-image /task/target/classes /var/task/
COPY --from=build-image /task/target/dependency /var/task/lib

# Entry point: package.ClassName::methodName
CMD ["helloworld.App::handleRequest"]

兩個階段的基礎映像都使用java8。 .al2後綴表示Amazon Linux 2，IronPDF需要它。 舊的java8映像在原始的Amazon Linux 1上運行，使用的是不再接收更新且缺少IronPDF所依賴的幾個包的yum儲存庫。 在Java 8上部署IronPDF時，始終使用.al2映像。

yum install塊安裝Chromium需要渲染頁面的X11、GTK3、Pango和字體相關庫。 省略其中任何一個包可能產生不完整的PDF輸出或使渲染引擎因缺少共享庫錯誤而崩潰。 libgdiplus包是GDI+相容性所必需的，這在某些IronPDF繪圖操作中使用。

根據實際的包和類名，如果與CMD指令。

如何構建和部署Lambda函式？

配置好Dockerfile、App.java後，從專案根目錄運行以下兩個SAM CLI命令。

步驟1 — 构建容器映像：

//:path=build.sh
sam build -u

//:path=build.sh
sam build -u

-u標誌指示SAM使用Docker（"使用容器"模式）。 SAM執行多階段的Dockerfile，編譯Maven專案並生產最終的Lambda映像。 預計此步驟在第一次運行時需要數分鐘，因為Docker正在拉取基礎映像。

步驟2 — 部署到AWS：

//:path=deploy.sh
sam deploy --guided

//:path=deploy.sh
sam deploy --guided

--guided標誌啟動交互式提示，詢問堆疊名稱、AWS區域、工件的S3儲存桶及在部署前是否確認變更集。 回答提示，SAM將把容器映像推送到Amazon ECR並建立在template.yaml中定義的Lambda功能、API Gateway和IAM角色。

部署完成後，SAM CLI輸出API端點URL。 打開AWS Lambda Console查看部署的功能，運行測試調用並檢查CloudWatch日誌以查看IronPDF的除錯輸出。

在第一次調用（冷啟動）時，預計響應時間為60–120秒，因為Lambda執行環境啟動並將IronPDF提取到/tmp。 在相同的熱實例上的後續調用將在幾秒內返回。 如果對於生產工作負載來說冷啟動延遲是一個問題，請考慮使用Lambda Provisioned Concurrency來保持實例熱。

您還可以在部署前本地測試功能，方法是使用測試事件負載運行sam local invoke，前提是Docker正在開發機器上運行。

接下來的步驟是什麼？

Lambda功能現在已部署並渲染PDF。 以下指南講解成功部署IronPDF後最常見的下一步：

• IronPDF for Java — 入門 — 總覽完整的IronPDF Java API，包括HTML到PDF、URL到PDF和PDF加蓋。
• 如何在Java中從HTML生成PDF — 將HTML字串、文件和模板渲染為PDF。
• 如何在Java中將標題和頁尾應用到PDF — 將頁碼、徽標和文字標題新增到Lambda生成的PDF中。
• 如何在Java中新增水印到PDF — 在返回給呼叫者之前，將文字或圖像水印蓋印在PDF輸出中。
• IronPDF授權 — 用於生產Lambda部署的授權選項，包括部署數量授權。

開始IronPDF for Java免費試用，在評估期間，在您的Lambda功能中生成和編輯PDF而無任何限制。 當準備好部署到生產時，查看IronPDF授權選項以找到適合您的無伺服器負載的方案。