Hướng dẫn Cloudflare cho nhà phát triển

Tổng quan

Gói Cloudflare chuyển việc kết xuất PDF sang ranh giới Worker. Hãy xem kết xuất qua Worker, dự phòng cục bộ, bảo vệ API và kho lưu trữ R2 là các năng lực riêng biệt, mỗi năng lực có cách xử lý lỗi riêng.

Hãy dùng hướng dẫn này khi bạn xây dựng dịch vụ kết xuất tại biên, điểm cuối kết xuất được bảo vệ, quy trình lưu trữ hoặc đường dẫn dự phòng cục bộ với nextpdf/cloudflare.

Ranh giới kiến trúc

Lớp	Thuộc về	Trách nhiệm	Không đặt ở đây
Điểm cuối ứng dụng	Ứng dụng	Xác thực bên gọi, chuẩn hóa yêu cầu kết xuất và thực thi chính sách nghiệp vụ.	Token của Worker được lưu trong mã nguồn.
Bảo vệ API	`nextpdf/cloudflare` và ứng dụng	Kiểm tra khóa API, kích thước payload và các quyết định giới hạn tần suất trong tiến trình.	Thanh toán, quyền sử dụng của bên thuê hoặc thực thi hạn mức bền vững.
Trình kết xuất Cloudflare	`nextpdf/cloudflare`	Xác thực HTML và URL của Worker, gửi payload kết xuất và phân tích phản hồi.	Kết xuất mẫu hoặc truy vấn miền nghiệp vụ.
Worker	Triển khai ứng dụng	Chạy Browser Rendering và trả về byte PDF hoặc kết quả có cấu trúc.	Chính sách lưu trữ phía PHP.
Dự phòng cục bộ	Triển khai ứng dụng	Kết xuất khi Worker không khả dụng.	Dự phòng âm thầm làm che khuất các sự cố vận hành.
Kho lưu trữ R2	`nextpdf/cloudflare`	Tải lên tệp PDF, tạo khóa đối tượng và tạo URL có chữ ký.	Metadata nghiệp vụ nhạy cảm khi chưa được xem xét.

Vòng đời thời gian chạy

Giai đoạn	Hành vi	Hành động của nhà phát triển
Tạo cấu hình	Nạp URL của Worker, token API, giới hạn thời gian chờ, giới hạn kích thước, dự phòng và pin.	Giữ các giá trị bí mật trong cấu hình triển khai.
Bảo vệ yêu cầu	Tùy chọn `ApiProtection` xác thực khóa, kích thước và giới hạn tần suất.	Chạy bước này trước phần kết xuất tốn kém.
Lệnh gọi trình kết xuất	`CloudflareHtmlRenderer` xác thực HTML và URL của Worker, rồi gửi JavaScript Object Notation (JSON).	Xử lý riêng tình trạng Worker không khả dụng và lỗi kết xuất.
Phân tích phản hồi	`CloudflareResponseParser::parse()` chấp nhận đầu ra PDF nhị phân hoặc đầu ra JSON có cấu trúc.	Từ chối đầu ra không hợp lệ hoặc không phải PDF.
Dự phòng cục bộ	Một trình kết xuất cục bộ tùy chọn sẽ xử lý khi Worker gặp lỗi.	Chỉ chèn factory trình kết xuất cục bộ khi máy chủ hỗ trợ việc đó.
Kho lưu trữ R2	`R2ArchiveManager` lưu byte PDF và tạo URL có chữ ký.	Chỉ giữ metadata không nhạy cảm, trừ khi bạn cố ý lưu metadata đó.

Cấu trúc ứng dụng được đề xuất

Đường dẫn	Mục đích
`app/Pdf/Cloudflare/*`	Lớp bao bọc ứng dụng cho `CloudflareHtmlRenderer`.
`app/Pdf/Workers/*`	Các đối tượng truyền dữ liệu (DTO) cho yêu cầu Worker và chính sách riêng cho từng điểm cuối.
`app/Pdf/Archive/*`	Điều phối kho lưu trữ R2 và các quyết định lưu giữ.
`app/Pdf/Fallback/*`	`LocalRendererFactoryInterface` triển khai cho dự phòng được phép.
`tests/Pdf/Cloudflare/*`	Các kiểm thử cho Worker ngừng hoạt động, token không hợp lệ, payload và kho lưu trữ.

Hãy giữ token API của PHP tách biệt với token của Worker. PHP xác thực với Worker. Worker nên xác thực các yêu cầu đến trước khi bắt đầu công việc trình duyệt.

<?php

use NextPDF\Cloudflare\ApiProtection;
use NextPDF\Cloudflare\ApiProtectionConfig;
use NextPDF\Cloudflare\ApiKeyValidator;

$protection = new ApiProtection(
    new ApiProtectionConfig(maxRequestsPerMinute: 30),
    new ApiKeyValidator([$expectedApiKey]),
);

$result = $protection->checkRequest(
    clientId: $clientId,
    payloadSize: strlen($html),
    apiKey: $presentedApiKey,
);

if (!$result->allowed) {
    return new JsonResponse(['error' => $result->denialReason], 429, $result->toHeaders());
}

Mẫu trình kết xuất

Hãy xây dựng trình kết xuất bằng các phụ thuộc PSR từ framework của bạn, bao gồm PSR-18 và PSR-17. Giữ dự phòng cục bộ thật rõ ràng để người vận hành biết khi nào hệ thống ngừng dùng Worker.

<?php

use NextPDF\Cloudflare\CloudflareHtmlRenderer;
use NextPDF\Cloudflare\CloudflareRendererConfig;

$renderer = new CloudflareHtmlRenderer(
    config: CloudflareRendererConfig::fromArray([
        'worker_url' => getenv('NEXTPDF_CLOUDFLARE_WORKER_URL'),
        'api_token' => getenv('NEXTPDF_CLOUDFLARE_API_TOKEN'),
        'render_timeout' => 30,
        'max_html_size' => 1_000_000,
        'fallback_to_local' => false,
    ]),
    httpClient: $httpClient,
    requestFactory: $requestFactory,
    streamFactory: $streamFactory,
);

$rendered = $renderer->render($html, widthPt: 595.28);

Mẫu kho lưu trữ R2

Chỉ lưu trữ sau khi kết xuất thành công và chính sách đã chấp thuận kết quả. Hãy xem URL công khai và URL có chữ ký là hai quyết định riêng biệt.

<?php

use NextPDF\Cloudflare\R2ArchiveManager;

$upload = $archive->upload(
    pdfData: $rendered->pdfData,
    filename: 'invoice-1234.pdf',
    metadata: [
        'document_type' => 'invoice',
    ],
);

if ($upload->isValid()) {
    $temporaryUrl = $archive->generateSignedUrl($upload->key, 600);
}

Không đặt tên khách hàng, địa chỉ email, tổng giá trị hóa đơn hoặc các định danh được quản lý vào metadata của đối tượng, trừ khi chính sách lưu giữ và truy cập của bạn cho phép rõ ràng.

Điểm mở rộng

Điểm mở rộng	Dùng cho	Ràng buộc
`LocalRendererFactoryInterface`	Dự phòng cục bộ thông qua Artisan hoặc một trình kết xuất khác.	Phải trả về một đối tượng triển khai `LocalRendererInterface`.
`ApiProtectionConfig`	Chính sách khóa API, kích thước payload và giới hạn tần suất.	Các giới hạn trong bộ nhớ áp dụng theo từng tiến trình.
`ApiKeyValidator`	Xác thực khóa an toàn về thời gian và các công cụ hỗ trợ xoay vòng khóa.	Lưu bí mật bên ngoài mã nguồn.
`R2ArchiveConfig`	Bucket, thông tin xác thực, tiền tố đường dẫn, điểm cuối và giới hạn kích thước.	Thông tin xác thực không bao giờ được ghi vào nhật ký.
`PinnedCurlTransport`	Thực thi pin IP và SPKI.	Yêu cầu môi trường thời gian chạy có hỗ trợ cURL và một response factory.
`CloudflareResponseParser`	Phân tích phản hồi của Worker.	Từ chối đầu ra PDF không hợp lệ hoặc các phản hồi lỗi.

Quy trình phát triển

Xây dựng đường dẫn kết xuất cục bộ trước.
Thêm kết xuất qua Worker bằng một fixture HTML nhỏ mang tính đại diện.
Bật bảo vệ yêu cầu trước khi công khai các điểm cuối.
Chỉ thêm tải lên R2 sau khi luồng kết xuất và phản hồi đã ổn định.
Kiểm thử các đường dẫn khi Worker ngừng hoạt động, token không hợp lệ, payload quá lớn, vượt giới hạn tần suất và lỗi R2.
Thêm nhật ký phân biệt giữa kết xuất qua Worker, kết xuất dự phòng, tải lên kho lưu trữ và tạo URL có chữ ký.

Xử lý lỗi

Lỗi	Nơi cần xử lý	Phản hồi được đề xuất
Khóa API bị thiếu hoặc không hợp lệ	Lớp bảo vệ API.	Từ chối yêu cầu trước khi công việc kết xuất bắt đầu.
Payload quá lớn	Xác thực ở lớp bảo vệ API hoặc trình kết xuất.	Trả về lỗi xác thực mà không gọi Worker.
URL của Worker không an toàn	Chính sách bảo mật của trình kết xuất.	Làm cho cấu hình hoặc yêu cầu thất bại trước khi có hoạt động input/output (I/O) mạng.
Worker không khả dụng	Ranh giới trình kết xuất.	Chỉ dùng dự phòng tường minh khi được phép; nếu không, hãy để lỗi hiển thị rõ.
Lỗi tải lên R2	Ranh giới kho lưu trữ.	Trả về phản hồi PDF nếu kho lưu trữ là tùy chọn; để lỗi phát sinh nếu chính sách yêu cầu phải lưu trữ.
Lỗi xoay vòng pin	Triển khai và vận hành.	Xoay vòng kèm pin dự phòng và một kế hoạch khôi phục.

Các giá trị mặc định an toàn

Mối quan tâm	Mặc định	Khi nào nên ghi đè
Dự phòng	Được bật theo mặc định của cấu hình.	Tắt khi việc kết xuất cục bộ sẽ vi phạm tính cô lập của triển khai.
Kích thước HTML tối đa	`5,000,000` byte.	Hạ thấp cho các điểm cuối công khai.
Thời gian sống (TTL) của URL có chữ ký	`3600` giây.	Rút ngắn cho các tệp PDF nhạy cảm.
Tập hợp pin	Trống.	Chỉ thêm pin khi đã có kế hoạch xoay vòng và pin dự phòng.
Yêu cầu khóa API	Được bật theo mặc định của cấu hình bảo vệ.	Chỉ tắt cho các lệnh gọi nội bộ riêng tư đã được xác thực trước.

Danh sách kiểm thử

Các kiểm thử trình kết xuất bao quát HTML hợp lệ, HTML quá lớn, URL của Worker không hợp lệ và phản hồi lỗi từ Worker.
Các kiểm thử bảo vệ API bao quát khóa bị thiếu, khóa không hợp lệ, payload quá lớn và vượt giới hạn tần suất.
Các kiểm thử R2 bao quát tải lên thành công, tải lên quá lớn, trạng thái HTTP thất bại, bucket không hợp lệ và việc tạo URL có chữ ký.
Các kiểm thử dự phòng xác minh rằng đường dẫn trình kết xuất cục bộ là tường minh và có thể quan sát được.
Các kiểm thử vận chuyển bao quát IP được ghim, pin khóa công khai, thời gian chờ và việc tắt chuyển hướng theo chính sách.
Các kiểm thử khả năng quan sát khẳng định có các sự kiện nhật ký riêng biệt cho kết xuất, dự phòng, lưu trữ và việc tạo URL có chữ ký.