Przewodnik deweloperski Cloudflare

W skrócie

Pakiet Cloudflare przenosi renderowanie PDF na granicę Workera. Traktuj renderowanie w Workerze, lokalny tryb awaryjny, ochronę API i archiwum R2 jako odrębne funkcje, z których każda ma własną obsługę awarii.

Korzystaj z tego przewodnika, gdy budujesz usługi renderowania na brzegu sieci, chronione punkty końcowe renderowania, procesy archiwizacji albo ścieżki lokalnego trybu awaryjnego z użyciem nextpdf/cloudflare.

Granica architektury

Warstwa	Właściciel	Odpowiedzialność	Czego tu nie umieszczać
Punkt końcowy aplikacji	Aplikacja	Autoryzuj wywołującego, normalizuj żądanie renderowania i egzekwuj politykę biznesową.	Tokenów Workera zapisanych w kodzie.
Ochrona API	nextpdf/cloudflare i aplikacja	Walidacja kluczy API, kontrola rozmiaru ładunku oraz decyzje o ograniczaniu liczby żądań w obrębie procesu.	Rozliczeń, uprawnień najemcy ani trwałego egzekwowania limitów.
renderer Cloudflare	nextpdf/cloudflare	Weryfikuj HTML i adres URL Workera, wysyłaj ładunek renderowania i analizuj odpowiedź.	Renderowania szablonów ani zapytań domenowych.
Worker	Wdrożenie aplikacji	Uruchamiaj Browser Rendering i zwracaj bajty PDF albo ustrukturyzowany wynik.	Polityki przechowywania po stronie PHP.
Lokalny tryb awaryjny	Wdrożenie aplikacji	Renderowanie, gdy Worker jest niedostępny.	Cichego trybu awaryjnego, który ukrywa awarie operacyjne.
Archiwum R2	nextpdf/cloudflare	Przesyłaj pliki PDF, buduj klucze obiektów i twórz podpisane adresy URL.	Wrażliwych metadanych biznesowych bez weryfikacji.

Cykl życia w czasie wykonywania

Etap	Zachowanie	Działanie dewelopera
Tworzenie konfiguracji	Wczytuje adres URL Workera, token API, limity czasu, limity rozmiaru, tryb awaryjny i przypięcia.	Przechowuj sekrety w konfiguracji wdrożenia.
Ochrona żądań	Opcjonalny ApiProtection weryfikuje klucz, rozmiar i limit żądań.	Uruchom go przed kosztownym renderowaniem.
Wywołanie renderera	CloudflareHtmlRenderer weryfikuje HTML i adres URL Workera, a następnie wysyła JSON.	Obsługuj osobno niedostępność Workera i błędy renderowania.
Analiza odpowiedzi	CloudflareResponseParser::parse() przyjmuje wynik binarny PDF albo ustrukturyzowany wynik JSON.	Odrzucaj wynik nieprawidłowy albo niebędący plikiem PDF.
Lokalny tryb awaryjny	Opcjonalny lokalny renderer obsługuje awarię Workera.	Wstrzykuj fabrykę lokalnego renderera tylko wtedy, gdy host ją obsługuje.
Archiwum R2	R2ArchiveManager przechowuje bajty PDF i tworzy podpisane adresy URL.	Przechowuj w metadanych tylko dane niewrażliwe, chyba że celowo zapisujesz tam dane wrażliwe.

Zalecana struktura aplikacji

Ścieżka	Przeznaczenie
app/Pdf/Cloudflare/*	Warstwa aplikacyjna opakowująca CloudflareHtmlRenderer.
app/Pdf/Workers/*	DTO dla żądań Workera oraz polityka specyficzna dla punktu końcowego.
app/Pdf/Archive/*	Orkiestracja archiwum R2 i decyzje dotyczące przechowywania.
app/Pdf/Fallback/*	LocalRendererFactoryInterface — implementacja dopuszczonego trybu awaryjnego.
tests/Pdf/Cloudflare/*	Testy niedostępności Workera, nieprawidłowego tokenu, ładunku oraz archiwum.

Oddzielaj token API po stronie PHP od tokenu Workera. PHP uwierzytelnia się wobec Workera. Worker powinien uwierzytelniać przychodzące żądania, zanim uruchomi pracę przeglądarki.

<?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());
}

Wzorzec renderera

Zbuduj renderer, korzystając z zależności PSR, w tym PSR-18 i PSR-17, dostarczanych przez framework. Zachowaj jawność lokalnego trybu awaryjnego, aby operatorzy widzieli, kiedy system przestaje korzystać z Workera.

<?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);

Wzorzec archiwum R2

Archiwizuj dopiero po pomyślnym renderowaniu i zatwierdzeniu wyniku przez politykę. Publiczne adresy URL i podpisane adresy URL traktuj jako odrębne decyzje.

<?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);
}

Nie umieszczaj nazwisk klientów, adresów e-mail, kwot faktur ani regulowanych identyfikatorów w metadanych obiektów, chyba że polityka przechowywania i dostępu wyraźnie na to pozwala.

Punkty rozszerzeń

Punkt rozszerzenia	Zastosowanie	Ograniczenie
LocalRendererFactoryInterface	Lokalny tryb awaryjny realizowany przez Artisan lub inny renderer.	Musi zwracać obiekt implementujący LocalRendererInterface.
ApiProtectionConfig	Polityka klucza API, rozmiaru ładunku i ograniczania liczby żądań.	Limity w pamięci obowiązują na proces.
ApiKeyValidator	Walidacja kluczy odporna na ataki czasowe oraz funkcje pomocnicze do rotacji kluczy.	Przechowuj sekrety poza kodem źródłowym.
R2ArchiveConfig	Bucket, poświadczenia, prefiks ścieżki, punkt końcowy i limity rozmiaru.	Poświadczenia nigdy nie mogą być zapisywane w logach.
PinnedCurlTransport	Egzekwowanie przypięć Internet Protocol (IP) oraz Subject Public Key Info (SPKI).	Wymaga środowiska uruchomieniowego obsługującego cURL oraz fabryki odpowiedzi.
CloudflareResponseParser	Analiza odpowiedzi Workera.	Odrzuca nieprawidłowy wynik PDF lub odpowiedzi z błędem.

Proces deweloperski

1. Najpierw zbuduj lokalną ścieżkę renderowania.
2. Dodaj renderowanie w Workerze na niewielkim, reprezentatywnym fragmencie HTML.
3. Włącz ochronę żądań przed udostępnieniem publicznych punktów końcowych.
4. Dodaj przesyłanie do R2 dopiero wtedy, gdy przepływy renderowania i odpowiedzi będą stabilne.
5. Przetestuj ścieżki niedostępności Workera, nieprawidłowego tokenu, zbyt dużego ładunku, limitu żądań oraz awarii R2.
6. Dodaj logowanie, które rozróżnia renderowanie w Workerze, renderowanie w trybie awaryjnym, przesyłanie do archiwum oraz tworzenie podpisanego adresu URL.

Obsługa awarii

Awaria	Gdzie obsłużyć	Zalecana reakcja
Brak lub nieprawidłowy klucz API	Warstwa ochrony API.	Odrzuć żądanie, zanim rozpocznie się renderowanie.
Zbyt duży ładunek	Ochrona API lub walidacja renderera.	Zwróć błąd walidacji bez wywoływania Workera.
Niebezpieczny adres URL Workera	Polityka bezpieczeństwa renderera.	Zgłoś błąd konfiguracji lub żądania przed sieciowymi operacjami I/O.
Worker niedostępny	Granica renderera.	Korzystaj z jawnego trybu awaryjnego tylko wtedy, gdy jest dozwolony; w przeciwnym razie zgłoś błąd w widoczny sposób.
Awaria przesyłania do R2	Granica archiwum.	Zwróć odpowiedź z plikiem PDF, jeśli archiwizacja jest opcjonalna; zgłoś błąd, jeśli archiwizacja jest wymagana przez politykę.
Awaria rotacji przypięć	Wdrożenie i operacje.	Wykonuj rotację z zapasowymi przypięciami i planem wycofania.

Bezpieczne wartości domyślne

Zagadnienie	Wartość domyślna	Kiedy nadpisać
Tryb awaryjny	Włączony domyślnie w konfiguracji.	Wyłącz, gdy lokalne renderowanie naruszałoby izolację wdrożenia.
Maksymalny rozmiar HTML	5,000,000 bajtów.	Zmniejsz dla publicznych punktów końcowych.
Czas życia (TTL) podpisanego adresu URL	3600 sekund.	Skróć dla wrażliwych plików PDF.
Zestawy przypięć	Pusty.	Dodawaj przypięcia tylko z planem rotacji i zapasowymi przypięciami.
Wymóg klucza API	Włączony domyślnie w konfiguracji ochrony.	Wyłącz tylko dla prywatnych, już uwierzytelnionych wywołań wewnętrznych.

Lista kontrolna testów

• Testy renderera obejmują prawidłowy HTML, zbyt duży HTML, nieprawidłowy adres URL Workera oraz odpowiedź Workera z błędem.
• Testy ochrony API obejmują brak klucza, nieprawidłowy klucz, zbyt duży ładunek oraz przekroczony limit żądań.
• Testy R2 obejmują pomyślne przesłanie, zbyt duże przesłanie, nieudany status HTTP, nieprawidłowy bucket oraz generowanie podpisanego adresu URL.
• Testy trybu awaryjnego weryfikują, że ścieżka lokalnego renderera jest jawna i obserwowalna.
• Testy transportu obejmują przypięte adresy IP, przypięcia klucza publicznego, limit czasu oraz przekierowania wyłączone zgodnie z polityką.
• Testy obserwowalności potwierdzają osobne zdarzenia w logach dla renderowania, trybu awaryjnego, archiwum oraz tworzenia podpisanego adresu URL.