Tổng quan về cầu kết xuất tại biên (edge-rendering bridge) cho Cloudflare của NextPDF

Nhìn nhanh

nextpdf/cloudflare là một cầu kết xuất tại biên. Ứng dụng PHP của bạn giữ Hypertext Markup Language (HTML), còn một Cloudflare Worker giữ trình duyệt không giao diện (headless browser). Cầu gửi HTML đến Worker qua Hypertext Transfer Protocol Secure (HTTPS) và nhận về các byte Portable Document Format (PDF) đã kết xuất. Không trình duyệt không giao diện nào chạy bên trong tiến trình PHP của bạn, và cầu không yêu cầu một tệp nhị phân Chromium cục bộ trên đường dẫn do nó quản lý.

Gói này thuộc hệ sinh thái NextPDF và phụ thuộc vào nextpdf/core^3.0. Đây là mã giao thức truyền (wire-protocol): nó tạo một yêu cầu JavaScript Object Notation (JSON), xác thực đầu vào và đích đến, gửi yêu cầu qua một PHP Standards Recommendation 18 (PSR-18) client, rồi phân tích phản hồi thành một đối tượng kết quả có kiểu. Phần triển khai Worker nằm ngoài gói này. Cầu này giao tiếp với Worker do bạn triển khai.

Ranh giới tin cậy

Đặc điểm cốt lõi của cầu này là HTML vượt qua một ranh giới mạng và đi tới một engine trình duyệt mà bạn không kiểm soát trực tiếp. Mọi biện pháp kiểm soát bảo mật trong gói này đều tồn tại vì ranh giới đó.

HTML được xác thực trước khi nó rời khỏi tiến trình PHP (CloudflareSecurityPolicy::validate()).
Uniform Resource Locator (URL) đích được xác thực trước khi yêu cầu được gửi đi (CloudflareSecurityPolicy::validateWorkerUrl()), rồi được xác thực lại tại thời điểm gửi yêu cầu để khép lại cửa sổ time-of-check/time-of-use (assertPinsStillValid()).
Lớp truyền có thể ghim (pin) tập Internet Protocol (IP) đã phân giải và khóa công khai của chứng chỉ máy chủ (Transport\PinnedCurlTransport).

Nếu bạn đang đánh giá cầu này cho môi trường production, hãy đọc /integrations/cloudflare/security-and-operations/ trước /integrations/cloudflare/quickstart/. Mô hình bảo mật không phải là phần bổ sung; nó giải thích vì sao gói này có thiết kế như hiện tại.

Nó làm gì

Khả năng	Được hỗ trợ bởi
Kết xuất HTML thành PDF qua một Cloudflare Worker	`CloudflareHtmlRenderer::render()`
Thăm dò khả năng tiếp cận (Hypertext Transfer Protocol (HTTP) `HEAD`)	`CloudflareHtmlRenderer::isAvailable()`
Lớp truyền trung lập với nhà cung cấp	Tiêm phụ thuộc (injection) `ClientInterface` theo PSR-18
Củng cố đầu vào (kích thước, bom base64, meta-refresh)	`CloudflareSecurityPolicy::validate()`
Phòng vệ trước server-side request forgery (SSRF) / DNS-rebinding (gắn lại Domain Name System (DNS))	`CloudflareSecurityPolicy::validateWorkerUrl()` + `assertPinsStillValid()`
Ghim khóa công khai Transport Layer Security (TLS), ghim DNS tại lớp cURL	`Transport\PinnedCurlTransport`
Dự phòng bằng Chrome cục bộ khi không tiếp cận được Worker	`Contract\LocalRendererFactoryInterface`
Phân tích phản hồi dạng nhị phân và JSON (base64)	`CloudflareResponseParser`
Đo từ xa tại biên (thời gian kết xuất, vị trí biên, chiều cao nội dung)	`CloudflareRenderResult`
Phông chữ tùy chỉnh từ một R2 bucket	`CloudflareRenderPayload` (`r2FontBucket`, `fontFiles`)
Lớp bảo vệ Application Programming Interface (API) (xác thực bằng khóa, kích thước payload, giới hạn tốc độ)	`ApiProtection`
Lưu trữ PDF vào R2 qua API tương thích S3	`R2ArchiveManager`

Mỗi hàng ánh xạ tới một lớp trong namespace NextPDF\Cloudflare. Mỗi hàng được kiểm chứng dựa trên hành vi của lớp đó và các bài kiểm thử tương ứng, không dựa trên một tài liệu đặc tả.

Nó không làm gì

Nó không chạy trình duyệt. Worker mới làm việc đó.
Nó không triển khai hoặc cấu hình Worker của bạn. Bạn là người sở hữu artifact đó.
Nó không ký PDF. Việc ký thuộc về nextpdf/core hoặc các phiên bản thương mại. Khi cần ký, hãy kết xuất trước, rồi ký các byte trả về bằng engine. NextPDF Pro cung cấp khả năng ký PAdES B-B. Các hồ sơ xác thực dài hạn (long-term-validation) là một khả năng của Enterprise.
Nó không khẳng định bất kỳ năng lực hay giới hạn nào của nền tảng Cloudflare. Những giới hạn duy nhất về kích thước và thời gian mà tài liệu này nêu ra là các giới hạn do chính gói này thực thi thông qua cấu hình của nó (xem /integrations/cloudflare/configuration/).

Hai chính sách bảo mật

Cầu đi kèm hai chính sách riêng biệt và bổ trợ cho nhau. Gộp lẫn hai chính sách này là lỗi rà soát phổ biến nhất. Sau đây là từng chính sách.

Chính sách bảo mật HTML (HtmlSecurityPolicyInterface, mặc định là NextPDF\Html\DefaultHtmlSecurityPolicy, do nextpdf/core cung cấp): lọc nội dung ở lớp phân tích cú pháp, áp dụng trước khi nội dung đến Worker. Lấy chính sách này bằng getHtmlSecurityPolicy().
Chính sách bảo mật Cloudflare (CloudflareSecurityPolicy, tĩnh): xử lý các mối quan tâm ở lớp truyền: kích thước đầu vào, phát hiện bom giải nén base64, chặn meta-refresh, bắt buộc HTTPS, và phòng vệ SSRF / DNS-rebinding cho URL của Worker.

Docblock của chính bộ kết xuất đã nêu rõ sự tách biệt này. Trang này nhắc lại điều đó vì người rà soát ở môi trường production cần thấy cả hai tên trên cùng một màn hình.

Mô hình kết xuất tại biên

Một lần gọi render() duy nhất tuân theo trình tự quan sát được dưới đây. Trình tự này được đọc trực tiếp từ CloudflareHtmlRenderer::render().

Kiểm tra tính đầy đủ của cấu hình (workerUrl và apiToken không rỗng). Nếu kiểm tra thất bại, cầu hoặc dự phòng sang một bộ kết xuất cục bộ, hoặc ném ra CloudflareNotAvailableException.
Xác thực HTML dựa trên kích thước tối đa đã cấu hình, giới hạn trần URI base64, và quy tắc cấm meta-refresh.
Xác thực URL của Worker, bước này phân giải host và trả về tập IP đã được thẩm định.
Dựng payload (CloudflareRenderPayload).
Một lần kiểm tra lại tại thời điểm sử dụng (time-of-use) xác nhận rằng phản hồi DNS của host không thay đổi kể từ bước 3.
HTTP POST được gửi qua lớp truyền cURL đã ghim khi tồn tại một tập IP hoặc một tập ghim Subject Public Key Info (SPKI) và đã có một ResponseFactory theo PSR-17 được cung cấp; nếu không, yêu cầu được gửi qua PSR-18 client đã được tiêm vào.
Phản hồi được phân tích thành một CloudflareRenderResult.

Bất kỳ throwable nào khác ngoài CloudflareRenderException đều kích hoạt đường dự phòng. CloudflareRenderException (một lỗi HTTP hoặc một phản hồi sai định dạng từ Worker) được ném lại nguyên trạng. Đây là lỗi phía Worker, không phải lỗi về khả năng tiếp cận, nên cầu không dùng dự phòng.

Xem thêm

/integrations/cloudflare/install/ — cài đặt gói và một PSR-18 client.
/integrations/cloudflare/configuration/ — mọi trường cấu hình, cùng các giá trị mặc định đã được kiểm chứng từ mã nguồn.
/integrations/cloudflare/quickstart/ — lần kết xuất chạy được đầu tiên của bạn.
/integrations/cloudflare/production-usage/ — dự phòng, đo từ xa, lưu trữ R2, bảo vệ API.
/integrations/cloudflare/security-and-operations/ — chi tiết vận hành cho ranh giới tin cậy.
/integrations/cloudflare/troubleshooting/ — các kiểu lỗi được ánh xạ sang exception.
/integrations/cloudflare/boot-and-discovery/ — cách cầu cắm vào một framework chủ.
/integrations/cloudflare/integration/ — vận hành NextPDF thông qua các dịch vụ Cloudflare.