Cấu hình cầu nối Cloudflare của NextPDF

Tổng quan nhanh

Gói này được điều khiển bởi ba đối tượng cấu hình bất biến. Mọi giá trị mặc định trong trang này đều được đọc từ chữ ký hàm khởi tạo tương ứng trong src/Cloudflare/. Các giá trị đó không được lấy từ đặc tả hay ước tính. Khi trang này nêu một giá trị tối đa, giá trị đó là giới hạn mà gói này áp dụng. Đây không phải là tuyên bố về năng lực của nền tảng Cloudflare.

`CloudflareRendererConfig`

Cấu hình cho bộ kết xuất. final readonly. Hãy khởi tạo trực tiếp hoặc thông qua CloudflareRendererConfig::fromArray().

Trường	Kiểu	Mặc định	Ý nghĩa
`workerUrl`	`string`	— (bắt buộc)	URL của điểm cuối Worker. Phải là HTTPS.
`apiToken`	`string`	— (bắt buộc)	Bearer token. Được đánh dấu `#[SensitiveParameter]`.
`renderTimeout`	`int`	`30`	Thời gian chờ truyền tải, tính bằng giây, do lớp truyền tải cURL đã ghim áp dụng.
`defaultCss`	`string`	`''`	CSS được chèn vào payload trước HTML của bạn.
`maxHtmlSize`	`int`	`5000000`	Kích thước HTML đầu vào tối đa, tính bằng byte, được áp dụng trước khi gửi yêu cầu.
`r2FontBucket`	`?string`	`null`	Tên bucket R2 cho các gói phông chữ tùy chỉnh.
`fallbackToLocal`	`bool`	`true`	Có chuyển về bộ kết xuất cục bộ khi không truy cập được Worker hay không.
`pinnedPublicKeys`	`list<string>`	`[]`	Dấu vân tay SPKI SHA-256 theo định dạng `sha256/<base64>`.
`backupPublicKeys`	`list<string>`	`[]`	Các pin SPKI dự phòng, được giữ riêng để có thể xác thực việc luân chuyển một cách độc lập.

isValid() chỉ trả về true khi workerUrl !== '' và apiToken !== ''. allPublicKeyPins() trả về hợp đã loại trùng của pinnedPublicKeys và backupPublicKeys. Lớp TLS chấp nhận chứng chỉ có giá trị băm SPKI xuất hiện trong bất kỳ phần tử nào của hợp đó. Điều này khớp với RFC 7469 §2.6, trong đó một kết nối đã ghim được xác thực khi tập hợp dấu vân tay SPKI được trình ra giao với tập đã ghim. RFC 7469 §2.5 mô tả pin dự phòng là cơ chế khôi phục chính khi xác thực pin thất bại ngoài ý muốn. Hãy giữ ít nhất một pin dự phòng để việc luân chuyển chứng chỉ không làm hỏng điểm cuối — xem /integrations/cloudflare/security-and-operations/.

`fromArray()` bản đồ khóa

CloudflareRendererConfig::fromArray() đọc các khóa snake_case và áp dụng cùng các giá trị mặc định khi một khóa vắng mặt hoặc sai kiểu:

Khóa mảng	Ánh xạ tới
`worker_url`	`workerUrl`
`api_token`	`apiToken`
`render_timeout`	`renderTimeout` (mặc định `30`)
`default_css`	`defaultCss`
`max_html_size`	`maxHtmlSize` (mặc định `5000000`)
`r2_font_bucket`	`r2FontBucket`
`fallback_to_local`	`fallbackToLocal` (mặc định `true`)
`pinned_public_keys`	`pinnedPublicKeys` (các phần tử không phải chuỗi bị loại bỏ)
`backup_public_keys`	`backupPublicKeys` (các phần tử không phải chuỗi bị loại bỏ)

<?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='],
]);

Các giới hạn kích thước đầu vào mà gói áp dụng

Các giới hạn này được CloudflareSecurityPolicy::validate() áp dụng trước khi bất kỳ yêu cầu nào rời khỏi tiến trình. Các con số được đọc từ mã nguồn:

Giới hạn	Giá trị	Ở đâu
HTML đầu vào tối đa	`maxHtmlSize` (mặc định `5000000` byte)	`CloudflareSecurityPolicy::validate()`
Kích thước tối đa của data-URI base64 sau khi giải mã	`13631488` byte (≈13 MB)	`CloudflareSecurityPolicy::MAX_DATA_URI_BYTES`

Vượt quá một trong hai giới hạn sẽ ném ra RuntimeException kèm thông báo nêu rõ kích thước vi phạm và giới hạn tương ứng. Ngưỡng trần base64 là biện pháp bảo vệ chống bom giải nén. Chính sách này ước tính kích thước sau giải mã từ độ dài base64 và từ chối ở mức ngưỡng trần hoặc cao hơn. Thẻ <meta http-equiv="refresh"> cũng bị từ chối, không phân biệt chữ hoa chữ thường, vì nó có thể kích hoạt chuyển hướng từ bên trong trang đã kết xuất.

Gói chỉ nêu những giới hạn mà chính nó áp dụng. Gói không đưa ra tuyên bố nào về các ngưỡng trần yêu cầu, CPU hay bộ nhớ của riêng Worker. Hãy tham khảo tài liệu chính thức của Cloudflare và phần triển khai Worker của bạn để biết những thông tin đó.

`ApiProtectionConfig`

Cấu hình cho lớp bảo vệ yêu cầu tùy chọn mà Worker — hoặc một cổng PHP đặt trước Worker — áp dụng cho các yêu cầu kết xuất đi vào. final readonly.

Trường	Kiểu	Mặc định	Ý nghĩa
`maxRequestsPerMinute`	`int`	`60`	Ngưỡng trần số yêu cầu trên mỗi máy khách mỗi phút.
`maxRequestsPerHour`	`int`	`1000`	Ngưỡng trần số yêu cầu trên mỗi máy khách mỗi giờ.
`maxPayloadSizeBytes`	`int`	`10485760`	Payload đến tối đa (≈10 MB).
`allowedOrigins`	`list<string>`	`[]`	Danh sách cho phép CORS. Để trống nghĩa là không thể hiện hạn chế nguồn gốc nào ở đây.
`requireApiKey`	`bool`	`true`	Có bắt buộc khóa API hay không.
`apiKeyHeader`	`string`	`'X-Api-Key'`	Header mang khóa API.
`rateLimitWindowSeconds`	`int`	`60`	Độ dài cửa sổ mỗi phút, tính bằng giây.

fromArray() đọc max_requests_per_minute, max_requests_per_hour, max_payload_size_bytes, allowed_origins, require_api_key, api_key_header, và rate_limit_window_seconds. isValid() yêu cầu tất cả trường số phải dương và apiKeyHeader phải khác rỗng.

`R2ArchiveConfig`

Cấu hình dùng để lưu trữ các PDF đã kết xuất vào Cloudflare R2 thông qua API tương thích S3. final readonly.

Trường	Kiểu	Mặc định	Ý nghĩa
`bucketName`	`string`	— (bắt buộc)	Bucket R2. Được kiểm tra theo quy tắc đặt tên S3.
`accountId`	`string`	— (bắt buộc)	ID tài khoản Cloudflare, dùng để dựng điểm cuối mặc định.
`accessKeyId`	`string`	— (bắt buộc)	ID khóa truy cập R2. `#[SensitiveParameter]`.
`secretAccessKey`	`string`	— (bắt buộc)	Khóa truy cập bí mật R2. `#[SensitiveParameter]`.
`endpoint`	`string`	`''`	Điểm cuối S3 tùy chỉnh. Nếu để trống, giá trị mặc định sẽ được dựng từ `accountId`.
`pathPrefix`	`string`	`'pdfs/'`	Tiền tố khóa cho các đối tượng được tải lên.
`maxFileSizeBytes`	`int`	`104857600`	Kích thước tải lên tối đa (≈100 MB), được áp dụng trước khi tải lên.

Hàm khởi tạo từ chối bucketName khác rỗng nếu không khớp với quy tắc tương thích S3. Quy tắc đó là: 3–63 ký tự, gồm chữ và số viết thường cùng dấu gạch nối, bắt đầu và kết thúc bằng một ký tự chữ hoặc số. Vi phạm quy tắc này sẽ ném ra InvalidArgumentException. isValid() yêu cầu bucketName, accountId, accessKeyId, và secretAccessKey phải khác rỗng. Khi endpoint để trống, getEndpoint() trả về https://<accountId>.r2.cloudflarestorage.com.

Xử lý bí mật

apiToken, accessKeyId, và secretAccessKey mang thuộc tính #[SensitiveParameter], nên PHP che chúng khỏi stack trace. Hãy cung cấp chúng từ biến môi trường hoặc trình quản lý bí mật. Đừng bao giờ commit chúng. Các đối tượng cấu hình là bất biến, nên một khi giá trị đã được đặt, giá trị đó không thể bị thay đổi sau khi khởi tạo.

Xem thêm

/integrations/cloudflare/quickstart/ — áp dụng cấu hình này cho lần kết xuất đầu tiên.
/integrations/cloudflare/production-usage/ — kết hợp dự phòng, lưu trữ R2 và bảo vệ API.
/integrations/cloudflare/security-and-operations/ — ghim, phòng thủ SSRF và luân chuyển bí mật.

Cấu hình cầu nối Cloudflare của NextPDF

Tổng quan nhanh

CloudflareRendererConfig

fromArray() bản đồ khóa