使用 Gotenberg API 進行 HTML 轉 PDF 轉換 - n8n 工作流程

需要可靠、自行託管解決方案來進行自動化文件生成的開發人員。
需要將內部、大量 PDF 轉換工具整合到現有 n8n 環境中的使用者。
尋找展示複雜二進位檔案處理和外部 API 串接之進階 n8n 範本的技術使用者。
所有使用 Docker 設定 n8n 環境，並想利用其他容器化服務的使用者。

從動態 HTML 內容生成高品質的 PDF 文件，是自動化中一項常見的挑戰。雖然市面上有許多線上服務，但它們常帶來隱私疑慮或擴展性問題。這個專門的 n8n 工作流程範本透過直接整合自行託管的 Gotenberg 服務來解決這個問題，該服務可與您的 n8n 實例安全地並行運行。

此自動化提供了一種安全且高度客製化的方法，用於建立專業報表、發票或複雜文件。該工作流程透過其初始的 n8n 觸發器接收 HTML 資料和期望的輸出檔名，在內部處理檔案準備，然後將請求發送到 Gotenberg，確保高效且保有隱私的 PDF 生成。掌握這個 n8n 自動化，即意味著您能完全掌控您的文件流程管線，這對於專業系統來說是一個關鍵功能。

當此 n8n 工作流程被手動執行，或被外部 Webhook 或觸發器呼叫時啟動，它會預期接收 HTML 內容和期望的檔案名稱。

1. 輸入觸發器 (Input Trigger)：工作流程從 Create PDF from HTML n8n 觸發器節點開始。此節點設定為預期接收兩個必要的輸入欄位：html（要轉換的內容）和 file_name（生成的 PDF 檔案名稱）。


2. 檔案準備 (File Preparation)：流程接著移動到 Create index.html n8n 節點，該節點使用內部的 convertToFile 函式。它會將接收到的 html 字串轉換成一個名為 index.html 的二進位檔案。這是正確打包 HTML 以供 Gotenberg API 使用的必要步驟。


3. 呼叫 Gotenberg API (Gotenberg API Call)：關鍵步驟發生在 Convert to PDF with Gotenberg n8n 節點（一個 HTTP Request n8n 節點）。此節點對 Gotenberg 服務（預設為 http://gotenberg:3000/forms/chromium/convert/html）執行一個 POST 請求。它使用 multipart-form-data 編碼方式傳送前一個步驟準備好的二進位檔案。


4. 中繼資料客製化 (Metadata Customization)：至關重要的是，此 n8n 節點還會在請求內文中傳遞客製化的中繼資料（例如作者、標題、建立日期和關鍵字）。它還使用一個動態表達式，連結回 n8n 觸發器中定義的初始輸入，來設定最終的輸出檔名。


5. 輸出 (Output)：Gotenberg 將生成的 PDF 文件以二進位輸出的形式回傳，隨後可以使用後續的 n8n 節點將其儲存、上傳到雲端儲存空間，或附加到電子郵件中。

若要成功部署這個 n8n 工作流程範本，請遵循以下步驟：

1. 匯入 n8n 工作流程：複製提供的 JSON 資料，並使用「新增」->「從 JSON 匯入」功能將其貼到您的 n8n 環境中。


2. 先決條件：設定 Gotenberg：此工作流程需要一個正在運行的 Gotenberg 服務。最簡單的方法是確保 n8n 和 Gotenberg 都在同一個 Docker 網路中運行。一個典型的 Docker 設定如下所示：

gotenberg:
        image: gotenberg/gotenberg:8
        restart: always

1. 設定 API 位址：在 Convert to PDF with Gotenberg n8n 節點中，檢查 URL。如果您的 Gotenberg 服務託管在標準 Docker 網路之外或使用不同連接埠，您必須將 url 參數從 http://gotenberg:3000/forms/chromium/convert/html 更新為您的特定端點。


2. 客製化中繼資料：檢查 Convert to PDF with Gotenberg n8n 節點中的「Body Parameters」（內文參數），以根據您的需求調整 PDF 中繼資料，例如「Author」（作者）和「Title」（標題）。


3. 測試：手動執行 Create PDF from HTML n8n 觸發器，以確保 PDF 已正確生成。

Create PDF from HTML (執行工作流程觸發器)
功能：作為工作流程的起點（n8n 觸發器），為執行提供範例資料。
關鍵設定：輸入資料定義了 html 內容和期望的輸出 file_name。

Create index.html (轉換成檔案)
功能：將輸入的 HTML 字串轉換成可儲存的二進位檔案（index.html）。Gotenberg 要求輸入必須以檔案形式傳送，使這個 n8n 節點對於準備工作至關重要。
關鍵設定：operation: toText、sourceProperty: html、fileName: index.html。

Convert to PDF with Gotenberg (HTTP 請求)
功能：將準備好的二進位 HTML 檔案傳送到自行託管的 Gotenberg 服務，以轉換成 PDF 文件。這是整個 n8n 工作流程的核心動作。
關鍵設定：
URL：http://gotenberg:3000/forms/chromium/convert/html（如果使用遠端服務，必須進行調整）。
內容類型 (Content Type)：multipart-form-data。
內文參數 (Body Parameters)：包含二進位資料輸入，以及大量的 JSON 格式 PDF 中繼資料以供客製化。
* 標頭 (Headers)：使用 Gotenberg-Output-Filename 標頭，並帶有動態表達式，以根據初始的 n8n 觸發器輸入來設定最終的 PDF 名稱。