配置 NextPDF Cloudflare 桥接

概览

三个不可变的配置对象管控整个包。本页列出的每个默认值，均来自 src/Cloudflare/ 中对应的构造函数签名，而非规格或估算值。本页标示的任何最大值，都是本包强制执行的上限，并非对 Cloudflare 平台容量的说明。

`CloudflareRendererConfig`

渲染器配置。final readonly。可直接构造，也可通过 CloudflareRendererConfig::fromArray() 构造。

字段	类型	默认值	含义
`workerUrl`	`string`	—（必填）	Worker 端点 URL。必须使用 HTTPS。
`apiToken`	`string`	—（必填）	Bearer token。已标记为 `#[SensitiveParameter]`。
`renderTimeout`	`int`	`30`	传输超时时间（秒），由固定的 cURL 传输层应用。
`defaultCss`	`string`	`''`	在你的 HTML 之前注入到负载中的 CSS。
`maxHtmlSize`	`int`	`5000000`	最大 HTML 输入大小（以字节计），在发送请求前强制检查。
`r2FontBucket`	`?string`	`null`	自定义字体包所用的 R2 存储桶名称。
`fallbackToLocal`	`bool`	`true`	Worker 无法连接时，是否回退到本地渲染器。
`pinnedPublicKeys`	`list<string>`	`[]`	SHA-256 SPKI 指纹，格式为 `sha256/<base64>`。
`backupPublicKeys`	`list<string>`	`[]`	备用 SPKI pin，特意单独保存，以便独立验证轮换。

isValid() 仅在 workerUrl !== '' 且 apiToken !== '' 时返回 true。allPublicKeyPins() 返回 pinnedPublicKeys 与 backupPublicKeys 去重后的并集。TLS 层会接受 SPKI 哈希值与该并集中任一成员匹配的证书。这符合 RFC 7469 §2.6：当呈现的 SPKI 指纹集合与已钉扎集合存在交集时，即验证为已钉扎连接。RFC 7469 §2.5 将备用 pin 描述为应对意外 pin 验证失败的主要恢复机制。至少保留一个备用 pin，可确保证书轮换不会中断端点——请见 /integrations/cloudflare/security-and-operations/。

`fromArray()` 键对应表

CloudflareRendererConfig::fromArray() 读取 snake_case 键；如果某个键缺失或类型错误，则应用相同的默认值：

数组键	对应到
`worker_url`	`workerUrl`
`api_token`	`apiToken`
`render_timeout`	`renderTimeout`（默认 `30`）
`default_css`	`defaultCss`
`max_html_size`	`maxHtmlSize`（默认 `5000000`）
`r2_font_bucket`	`r2FontBucket`
`fallback_to_local`	`fallbackToLocal`（默认 `true`）
`pinned_public_keys`	`pinnedPublicKeys`（非字符串成员会被丢弃）
`backup_public_keys`	`backupPublicKeys`（非字符串成员会被丢弃）

<?php

declare(strict_types=1);

use NextPDF\Cloudflare\CloudflareRendererConfig;

$config = CloudflareRendererConfig::fromArray([
    'worker_url'     => 'https://pdf-renderer.example.workers.dev/render',
    'api_token'      => getenv('CF_PDF_TOKEN') ?: '',
    'render_timeout' => 60,
    'r2_font_bucket' => 'pdf-fonts',
    'pinned_public_keys' => ['sha256/YLh1dUR9y6Kja30RrAn7JKnbQG/uEtLMkBgFF2Fuihg='],
    'backup_public_keys' => ['sha256/Vjs8r4z+80wjNcr1YKepWQboSIRi63WsWXhIMN+eWys='],
]);

本包强制执行的输入大小上限

这些上限由 CloudflareSecurityPolicy::validate() 在任何请求离开程序前强制检查。这些数值来自源码：

上限	数值	位置
最大 HTML 输入	`maxHtmlSize`（默认 `5000000` 字节）	`CloudflareSecurityPolicy::validate()`
解码后的 base64 data-URI 最大大小	`13631488` 字节（约 13 MB）	`CloudflareSecurityPolicy::MAX_DATA_URI_BYTES`

超出任一上限都会引发 RuntimeException，消息会指明违规大小与上限。base64 上限是用于防范解压缩炸弹的护栏。此策略会根据 base64 长度估算解码后的大小，并在达到或超过上限时拒绝。<meta http-equiv="refresh"> 标签也会被拒绝（不区分大小写），因为它可能从渲染页面内部触发重定向。

本包只说明它自身强制执行的上限。它并未对 Worker 本身的请求、CPU 或内存上限做出任何声明。请查阅 Cloudflare 官方文档和你的 Worker 实现，以了解那些上限。

`ApiProtectionConfig`

可选的请求防护层配置，由 Worker——或位于其前方的 PHP 网关——应用于传入的渲染请求。final readonly。

字段	类型	默认值	含义
`maxRequestsPerMinute`	`int`	`60`	每个客户端每分钟的请求上限。
`maxRequestsPerHour`	`int`	`1000`	每个客户端每小时的请求上限。
`maxPayloadSizeBytes`	`int`	`10485760`	最大传入负载（约 10 MB）。
`allowedOrigins`	`list<string>`	`[]`	CORS 允许列表。留空表示此处不表达任何来源限制。
`requireApiKey`	`bool`	`true`	是否要求 API 密钥。
`apiKeyHeader`	`string`	`'X-Api-Key'`	携带 API 密钥的请求头。
`rateLimitWindowSeconds`	`int`	`60`	每分钟时间窗长度（以秒计）。

fromArray() 读取 max_requests_per_minute、max_requests_per_hour、max_payload_size_bytes、allowed_origins、require_api_key、api_key_header 与 rate_limit_window_seconds。isValid() 要求每个数值字段均为正数，且 apiKeyHeader 不可为空。

`R2ArchiveConfig`

通过 S3 兼容 API 将渲染后的 PDF 封存至 Cloudflare R2 的配置。final readonly。

字段	类型	默认值	含义
`bucketName`	`string`	—（必填）	R2 存储桶。会按 S3 命名规则验证。
`accountId`	`string`	—（必填）	Cloudflare 账户 ID，用于构造默认端点。
`accessKeyId`	`string`	—（必填）	R2 access key ID。`#[SensitiveParameter]`。
`secretAccessKey`	`string`	—（必填）	R2 secret access key。`#[SensitiveParameter]`。
`endpoint`	`string`	`''`	自定义 S3 端点。留空时会从 `accountId` 构造默认端点。
`pathPrefix`	`string`	`'pdfs/'`	上传对象的键前缀。
`maxFileSizeBytes`	`int`	`104857600`	最大上传大小（约 100 MB），在上传前强制检查。

构造函数会拒绝不符合 S3 兼容规则的非空 bucketName。该规则为：3 至 63 个字符，小写字母数字与连字符，且以字母数字开头并结尾。违反规则会引发 InvalidArgumentException。isValid() 要求 bucketName、accountId、accessKeyId 与 secretAccessKey 均不可为空。当 endpoint 为空时，getEndpoint() 返回 https://<accountId>.r2.cloudflarestorage.com。

密钥处理

apiToken、accessKeyId 与 secretAccessKey 带有 #[SensitiveParameter] 属性，因此 PHP 会在堆栈跟踪中遮蔽它们。请通过环境变量或密钥管理器提供它们。切勿将它们提交到版本控制。配置对象不可变，因此一旦配置完成，就无法在构造后更改。

另请参阅

/integrations/cloudflare/quickstart/ — 在首次渲染中应用此配置。
/integrations/cloudflare/production-usage/ — 将回退、R2 封存与 API 防护串联在一起。
/integrations/cloudflare/security-and-operations/ — 钉扎、SSRF 防御与密钥轮换。

配置 NextPDF Cloudflare 桥接

概览

CloudflareRendererConfig

fromArray() 键对应表