基于 Gotenberg API 的 HTML 转 PDF - n8n 工作流

需要可靠、可自托管的自动化文档生成方案的开发者。
需要私密、大批量 PDF 转换工具并希望集成到现有 n8n 环境中的用户。
寻求能展示复杂二进制文件处理和外部 API 集成的进阶 n8n 模板的技术用户。
使用 Docker 部署 n8n 并在其中希望利用其他容器化服务的用户。

从动态 HTML 内容生成高质量的 PDF 文档是自动化中一个常见的痛点。尽管有很多在线服务，但它们常常带来隐私担忧或扩展性问题。这个专用的 n8n 工作流模板通过直接集成到与 n8n 实例安全并存的自托管 Gotenberg 服务来解决这个问题。

这个自动化流程提供了一种安全且高度可定制的方法，用于创建专业报告、发票或复杂文档。该工作流通过初始的 n8n 触发器接收 HTML 数据和期望的输出文件名，在内部处理文件准备工作，然后向 Gotenberg 发送请求，确保高效且私密的 PDF 生成。掌握这个 n8n 自动化意味着你可以完全掌控你的文档处理流程，这对专业系统来说是一个关键特性。

该 n8n 工作流在手动运行或被外部 Webhook 或触发器调用时启动，需要接收 HTML 内容和所需的文件名。

1. 输入触发器： 工作流在 Create PDF from HTML（通过 HTML 创建 PDF）n8n 触发器节点处开始。该节点配置为接收两个必要的输入字段：html（待转换内容）和 file_name（生成的 PDF 文件名）。


2. 文件准备： 流程进入 Create index.html（创建 index.html）n8n 节点，该节点使用内部的 convertToFile 函数。它接收传入的 html 字符串并将其转换为名为 index.html 的二进制文件。这是为了正确打包 HTML 内容供 Gotenberg API 使用的必要步骤。


3. Gotenberg API 调用： 关键步骤发生在 Convert to PDF with Gotenberg（使用 Gotenberg 转换为 PDF）n8n 节点（一个 HTTP 请求节点）。该节点向 Gotenberg 服务执行 POST 请求（默认为 http://gotenberg:3000/forms/chromium/convert/html）。它使用 multipart-form-data 编码发送上一步准备好的二进制文件。


4. 元数据定制： 至关重要的是，此 n8n 节点还在请求体中传递了定制化的元数据（如作者、标题、创建日期和关键字）。它还使用一个表达式动态设置输出文件名，该表达式链接回 n8n 触发器中定义的初始输入。


5. 输出： Gotenberg 将生成的 PDF 文档作为二进制输出返回，随后可以使用后续的 n8n 节点将其保存、上传到云存储或作为附件添加到电子邮件中。

要成功部署此 n8n 工作流模板，请遵循以下步骤：

1. 导入 n8n 工作流： 复制提供的 JSON 数据，并在 n8n 环境中使用“新建” -> “从 JSON 导入”功能粘贴。


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”（请求体参数），以根据你的需求调整如 Author（作者）和 Title（标题）等 PDF 元数据。


3. 测试： 手动执行 Create PDF from HTML（通过 HTML 创建 PDF）n8n 触发器，以确保 PDF 生成正确。

Create PDF from HTML (执行工作流触发器)
功能：作为工作流的起点（n8n 触发器），为执行提供示例数据。
关键配置：输入数据定义了 html 内容和期望的输出 file_name（文件名）。

Create index.html (转换为文件)
功能：将输入的 HTML 字符串转换成可存储的二进制文件（index.html）。Gotenberg 要求输入以文件形式发送，因此该 n8n 节点是准备工作中的关键环节。
关键配置：operation: toText（操作：转文本），sourceProperty: html（源属性：html），fileName: index.html（文件名：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 文件名。