NextPDF Gotenberg 配置

速览

配置分布在两个位置。第一个是不可变的 GotenbergConfig 值对象，用于描述该服务及其各项限制。第二个是 GotenbergBridge 构造函数，用于接入 PSR HTTP 协作组件。两者都通过显式构造函数注入。不使用全局状态，包内部也不会读取任何环境变量或隐藏的默认端点。

配置对象

GotenbergConfig 是一个 final readonly 值对象。你可以使用具名参数直接构造它，也可以通过 GotenbergConfig::fromArray() 从关联数组构建它。

字段

字段	类型	默认值	效果
apiUrl	string	''	Gotenberg 服务的基础 URL。必填：空值会使配置无效，并导致每次转换都快速失败。必须为 HTTPS。
timeout	int	30	强制传输超时，单位为秒。选用 cURL 固定传输时，由该传输应用此超时。
maxFileSize	int	52_428_800	最大输入大小，单位为字节（50 MiB）。超过此大小的输入会在发出任何请求前被拒绝。
apiKey	string	''	Bearer 令牌。非空时，会作为 Authorization: Bearer <token> 标头发送。标记为 #[\SensitiveParameter]，因此会在堆栈跟踪中被脱敏。
pinnedPublicKeys	list<string>	[]	主 TLS SPKI 固定值，格式为 sha256/<base64>。为空时禁用固定。
backupPublicKeys	list<string>	[]	备用 TLS SPKI 固定值，单独保存，以便独立验证轮换。

直接构造

<?php

declare(strict_types=1);

use NextPDF\Gotenberg\GotenbergConfig;

$config = new GotenbergConfig(
    apiUrl: 'https://gotenberg.example.com',
    timeout: 60,
    maxFileSize: 20 * 1024 * 1024,
    apiKey: $secretFromYourSecretStore,
);

从数组构造

fromArray() 接受 snake_case 键，并会忽略任何格式错误的内容，而不是抛出异常。非字符串的 api_url 会变为 ''。非整数的 timeout 会回退为 30。非整数的 max_file_size 会回退为 50 MiB 的默认值。非数组的固定值列表会变为 []。固定值数组中的非字符串条目会被丢弃。

<?php

declare(strict_types=1);

use NextPDF\Gotenberg\GotenbergConfig;

$config = GotenbergConfig::fromArray([
    'api_url' => 'https://gotenberg.example.com',
    'timeout' => 45,
    'max_file_size' => 20_000_000,
    'api_key' => $secretFromYourSecretStore,
    'pinned_public_keys' => ['sha256/YLh1dUR9y6Kja30RrAn7JKnbQG/uEtLMkBgFF2Fuihg='],
    'backup_public_keys' => ['sha256/Vjs8r4z+80wjNcr1YKepWQboSIRi63WsWXhIMN+eWys='],
]);

这种宽容解析是有意设计的。它让你可以直接传入框架配置数组，无需额外的预校验层，同时仍能产出类型良好的对象。它不会校验该 URL 是否可达，也不会校验固定值是否正确。这些检查会在转换时进行。

有效性

只有当 apiUrl 为非空字符串时，isValid() 才返回 true。它不执行网络检查或协议方案检查。HTTPS 与私有地址筛查会在转换时由安全策略内部完成。无效配置会导致 convertFile() 和 convertString() 抛出 GotenbergConvertException，消息为 Invalid Gotenberg configuration: apiUrl is empty。无效配置还会导致 isAvailable() 返回 false，并且不会发起任何网络调用。

桥接构造函数

GotenbergBridge 接收配置和 PSR 协作组件：

参数	类型	必填	效果
config	GotenbergConfig	是	上文所述的服务描述符和限制。
httpClient	Psr\Http\Client\ClientInterface	是	用于健康探测，并在回退传输中使用的 PSR-18 客户端。
requestFactory	Psr\Http\Message\RequestFactoryInterface	是	构建 PSR-7 请求。
streamFactory	Psr\Http\Message\StreamFactoryInterface	是	构建请求体流。
logger	Psr\Log\LoggerInterface|null	否（默认 null）	提供后，每个转换请求都会记录一条 debug 级别的日志条目。
htmlSecurityPolicy	HtmlSecurityPolicyInterface|null	否	默认使用核心的默认 HTML 安全策略。它是解析层策略，与传输层策略相辅相成。
responseFactory	Psr\Http\Message\ResponseFactoryInterface|null	否（默认 null）	激活 cURL 固定传输时必填。没有它，桥接会始终使用注入的 PSR-18 客户端。

<?php

declare(strict_types=1);

use NextPDF\Gotenberg\GotenbergBridge;

$bridge = new GotenbergBridge(
    config: $config,
    httpClient: $psrHttpClient,
    requestFactory: $psrRequestFactory,
    streamFactory: $psrStreamFactory,
    logger: $psrLogger,
    responseFactory: $psrResponseFactory,
);

传输选择

桥接有两种传输，并会为每个转换请求选择其中一种：

• cURL 固定传输 —— 当注入了 responseFactory，并且存在可固定内容（URL 解析出一个或多个 IP，或已配置 SPKI 固定值）时使用。该传输使用 CURLOPT_RESOLVE 绑定已解析的地址集。存在固定值时，它使用 CURLOPT_PINNEDPUBLICKEY 强制执行 SPKI 固定。它会验证对端和主机（CURLOPT_SSL_VERIFYPEER、CURLOPT_SSL_VERIFYHOST = 2）。它会应用已配置的超时，并禁用重定向跟随（CURLOPT_FOLLOWLOCATION = false、CURLOPT_MAXREDIRS = 0）。
• 注入的 PSR-18 客户端 —— 用于所有其他情形，包括 API URL 是裸公网 IP 字面量（没有可固定的 DNS）且未配置 SPKI 固定值，或未提供 responseFactory。

实际影响是：若要获得抗 DNS 重绑定的连接以及 TLS 固定，需要注入 responseFactory 并配置固定值。无论选择哪种传输，健康探测始终使用注入的 PSR-18 客户端。

TLS 公钥固定

固定遵循 SHA-256 SPKI 指纹模型。每个固定值都是形如 sha256/<base64-encoded-spki-hash> 的字符串。该传输也接受 cURL 原生的 sha256//<base64> 形式，并会把单斜杠形式转换为该原生形式。任何其他前缀都会引发 InvalidSpkiPinException。

allPublicKeyPins() 返回 pinnedPublicKeys 与 backupPublicKeys 去重后的并集。TLS 层会接受 SPKI 哈希匹配该合并集合中任一成员的证书。从运维角度看，你应至少配置一个备用固定值，这样在新密钥传播期间，计划内的证书或密钥轮换不会把桥接锁在服务之外。将备用列表与主列表分开保存，可以让你独立于当前固定值验证并轮换备用固定值。轮换流程参见 /integrations/gotenberg/security-and-operations/。

逐请求转换选项

多部分载荷类型（GotenbergConvertPayload）除文件外，还携带两个可选的 Gotenberg 转换选项：

• landscape（bool，默认 false）—— 作为 landscape 表单字段发送，值为 "true" 或 "false"。
• nativePageRanges（string，默认 ''）—— 仅在非空时作为 nativePageRanges 表单字段发送；接受 Gotenberg 的范围语法，例如 1-3 或 1,3,5-9。

公开的 convertFile() 与 convertString() 入口点会使用这两个字段的默认值构建载荷。这些字段属于载荷契约，并由测试套件验证。如果你需要横向输出或页面选择，可在自己的集成层中暴露它们。

另见

• /integrations/gotenberg/install/ —— 安装和 Gotenberg 基线。
• /integrations/gotenberg/quickstart/ —— 一个可运行的端到端示例。
• /integrations/gotenberg/production-usage/ —— 配置来源、密钥、超时与重试。
• /integrations/gotenberg/security-and-operations/ —— 完整的安全模型和固定值轮换。
• /integrations/gotenberg/troubleshooting/ —— 每个与配置相关的异常含义。