NextPDF Gotenberg 概览

快速概览

NextPDF Gotenberg 是 NextPDF 与外部 Gotenberg 服务之间的轻量桥接器。它会接收一份 NextPDF 无法原生渲染的 Office 文件，通过 HTTP 将该文件发送到 Gotenberg 实例，接收返回的 PDF，再把该 PDF 交给你的应用程序。随后，NextPDF 的其他功能会接手后续处理。

这个包小巧且职责明确。它不内嵌渲染器、不启动 LibreOffice，也不运行浏览器。每次转换都是向某个 Gotenberg 端点发出的单个 multipart HTTP 请求。该端点由你自行运营，并通过配置让桥接器指向它。

当你有 .docx、.xlsx、.pptx、.odt、.ods 或 .odp 源文件，并希望在 NextPDF 流程中将它们转换为 PDF 时，请使用这个桥接器。PDF 生成之后的一切处理——签名、PDF/A 转换、加水印、合并——都通过 NextPDF 本身或 nextpdf/premium 包来完成。

桥接器的依赖项

桥接器有一项并非 PHP 包的运行时依赖：一个正在运行的 Gotenberg 服务，且桥接器可以通过 HTTPS 连接到它。

桥接器不会安装、管理或监控 Gotenberg。Gotenberg 由你自行部署（上游项目会发布容器镜像），它的可用性、容量与网络暴露范围也都由你负责。
桥接器会与 Gotenberg 的 LibreOffice 转换路由通信。请求 URL 的组成形式为 <apiUrl>/forms/libreoffice/convert，其中 <apiUrl> 是你配置的基础 URL。这个路由决定了桥接器支持的格式集合。
健康检查会向 <apiUrl>/health 发出一个 HTTP HEAD 请求，并将任何低于 500 的状态码视为可用。

转换是在你自行运营的服务中进行的，因此桥接器的行为取决于你运行的 Gotenberg 版本。桥接器会发送固定的 multipart 请求结构，而路由路径（/forms/libreoffice/convert）与健康检查路径（/health）是它对 Gotenberg 端唯一假定的契约。部署基线请参阅 /integrations/gotenberg/install/，加固服务的方法请参阅 /integrations/gotenberg/security-and-operations/。

支持的文件格式

桥接器只转换其 OfficeFormat 类型中列举的格式。每种格式都按扩展名检测（不区分大小写，并允许开头带点号）。随后，每种格式都会以固定的 MIME 类型发送至 Gotenberg：

格式	扩展名	发送至 Gotenberg 的 MIME 类型
Word（OOXML）	`docx`	`application/vnd.openxmlformats-officedocument.wordprocessingml.document`
Excel（OOXML）	`xlsx`	`application/vnd.openxmlformats-officedocument.spreadsheetml.sheet`
PowerPoint（OOXML）	`pptx`	`application/vnd.openxmlformats-officedocument.presentationml.presentation`
OpenDocument Text	`odt`	`application/vnd.oasis.opendocument.text`
OpenDocument Spreadsheet	`ods`	`application/vnd.oasis.opendocument.spreadsheet`
OpenDocument Presentation	`odp`	`application/vnd.oasis.opendocument.presentation`

这份清单就是完整清单。不在此集合内的扩展名会在发出任何网络请求之前先触发 ValueError，因此桥接器绝不会尝试执行一项它无法描述的转换。桥接器并未宣称支持「任何 Office 文件」或「所有文件格式」。它支持上述六种格式，因为代码只识别这六种，测试套件也只验证这六种。

旧版二进制格式（.doc、.xls、.ppt）、RTF 格式（.rtf）、纯文本、CSV 以及图像格式，并不属于桥接器识别的集合。Gotenberg 自身的 LibreOffice 路由可能接受更广泛的输入范围。桥接器有意将自身限制在列举的集合内，这样格式检测、MIME 类型与结果元数据才能始终保持一致且可验证。

一次转换如何流转

一次转换是单一、线性的流程。在任何字节离开进程之前，它会在每个步骤进行验证：

检查配置。空白的 API URL 会立即导致转换异常。
验证 API URL：必须使用 HTTPS，且主机会被解析并筛查，确保它无法指向私有或保留地址。已解析的地址集合会被捕获下来，供稍后的地址固定使用。
读取输入（对于文件转换，会先将路径规范化以阻止路径遍历），并将其扩展名映射到一个 OfficeFormat。
会按配置的上限检查字节长度，并筛查文件名是否包含路径遍历序列、斜线、空字节与控制字符。
在发出请求前会立即重新检查地址集合，以消除验证与连接之间的时间差。
构造一个 multipart/form-data 主体，并通过 POST 发送至 LibreOffice 路由；如果配置了 bearer token，也会一并附上。
解析响应：状态码必须是 200，Content-Type 必须包含 application/pdf，且主体必须以 %PDF 标识开头。只有满足这些条件，才会返回结果。

步骤 1–7 中的任何失败都会引发类型化异常，而不是返回部分结果或未经检查的结果。具体的异常及其触发条件列在 /integrations/gotenberg/troubleshooting/。

你会取回什么

成功的转换会返回一个结果对象。该对象包含原始 PDF 字节、被转换的源格式，以及一个可选的渲染耗时测量值，并提供一项有效性检查（非空主体且以 %PDF 开头）以及一个字节大小访问器。这些字节是普通的 PDF 流，因此你可以将它们写入磁盘、流式传输给客户端，或送入一个 NextPDF 文件做进一步处理。

桥接器止步之处

桥接器负责转换与验证。它不会：

对输出进行签名、加密、线性化或 PDF/A 转换。这些属于后续处理范畴，由 NextPDF 核心或 nextpdf/premium 处理。
重试失败的请求、排队或缓存结果。这些属于应用程序层面的考虑。/integrations/gotenberg/production-usage/ 说明应在桥接器周围的哪些位置加入这些机制。
管理 Gotenberg 服务的生命周期。部署与运营相关内容见 /integrations/gotenberg/security-and-operations/。

版本与后续处理

OSS 核心可以按原样输出转换后的 PDF。如果你需要为转换后的文件签名、生成 PDF/A 归档配置文件或应用水印，nextpdf/premium 包会在其上加入这些功能。桥接器本身与版本无关：它只负责生成 PDF。你对那份 PDF 所做的事，决定了你是否需要商业版本。

Pro 版本仅提供 PAdES 基准级别 B-B。长期验证配置文件（B-T、B-LT、B-LTA）并不属于 Pro 版本，且本桥接器并未提供它们。请勿仅因本包存在，就推断其具备时间戳或 LTV 能力。

另请参阅

/integrations/gotenberg/install/ — 安装包并建立一个 Gotenberg 基线。
/integrations/gotenberg/configuration/ — 每个配置选项、其类型、默认值与作用。
/integrations/gotenberg/quickstart/ — 一个可执行的初次转换。
/integrations/gotenberg/production-usage/ — 将桥接器接入真实的应用程序。
/integrations/gotenberg/troubleshooting/ — 异常目录以及各项异常的含义。
/integrations/gotenberg/security-and-operations/ — 安全模型，以及如何安全运营所依赖的服务。
/integrations/gotenberg/boot-and-discovery/ — 宿主框架如何发现并接入桥接器。
/integrations/gotenberg/integration/ — 通过该服务驱动 NextPDF 渲染。