Rozwiązywanie problemów

W skrócie

Most zgłasza trzy typy wyjątków. Przechwycony wyjątek wskazuje, co zawiodło oraz czy należy ponowić próbę, czy skorzystać z rozwiązania zapasowego. Każdy fragment komunikatu poniżej pochodzi z kodu źródłowego.

Hierarchia wyjątków

Wyjątek	Rozszerza	Znaczenie
CloudflareNotAvailableException	NextPDF\Exception\NextPdfException	Most nie może połączyć się z brzegiem sieci albo konfiguracja jest niekompletna, a użyteczne rozwiązanie zapasowe nie jest dostępne.
CloudflareRenderException	NextPDF\Exception\NextPdfException	Worker odpowiedział, ale renderowanie zakończyło się niepowodzeniem (błąd protokołu Hypertext Transfer Protocol (HTTP) lub nieprawidłowo sformułowane ciało odpowiedzi). Nigdy nie uruchamia rozwiązania zapasowego.
InvalidSpkiPinException	InvalidArgumentException	Skonfigurowany ciąg pinu Subject Public Key Info (SPKI) ma nieprawidłowy format.

CloudflareSecurityPolicy zgłasza także bezpośrednio RuntimeException w przypadku naruszeń zasad dotyczących danych wejściowych i adresu Uniform Resource Locator (URL). Zgłasza ten wyjątek przed wysłaniem jakiegokolwiek żądania.

Awarie konfiguracji i danych wejściowych

Fragment komunikatu	Zgłaszany przez	Przyczyna	Rozwiązanie
incomplete (missing worker_url or api_token)	renderer (ścieżką rozwiązania zapasowego)	Pole workerUrl lub apiToken jest puste	Ustaw oba pola, a następnie zweryfikuj konfigurację za pomocą isValid().
HTML input exceeds maximum size	CloudflareSecurityPolicy::validate()	Dane wejściowe Hypertext Markup Language (HTML) są dłuższe niż maxHtmlSize	Zmniejsz dane wejściowe albo świadomie zwiększ maxHtmlSize.
Base64 data URI exceeds safety limit	CloudflareSecurityPolicy::validate()	Szacowany rozmiar Uniform Resource Identifier (URI) typu data:;base64, przekracza 13631488 bajtów	Przenieś zasób poza treść; nie osadzaj dużych plików binarnych w treści.
meta-refresh redirect which could cause SSRF	CloudflareSecurityPolicy::validate()	Znacznik <meta http-equiv="refresh"> mógłby umożliwić atak server-side request forgery (SSRF)	Usuń ten znacznik; użyj przekierowania po stronie serwera, poza renderowanym kodem HTML.
Invalid Worker URL	validateWorkerUrl()	Adresu URL nie można sparsować albo brakuje w nim scheme/host	Podaj pełny, bezwzględny adres URL używający protokołu Hypertext Transfer Protocol Secure (HTTPS).
Worker URL must use HTTPS	validateWorkerUrl()	Schemat nie jest HTTPS	Użyj https://.
private or reserved IP addresses	validateWorkerUrl()	Literał adresu Internet Protocol (IP) należy do zakresu Request for Comments (RFC) 1918 / pętli zwrotnej / RFC 3927	Skieruj ruch do publicznego punktu końcowego.
hostname resolves to a private or reserved IP	validateWorkerUrl()	Rekord A/AAAA systemu Domain Name System (DNS) rozwiązuje się do adresu prywatnego lub zarezerwowanego	Napraw DNS; sprawdź możliwość ataku rebinding.
DNS answer changed since validation	assertPinsStillValid()	Host został rozwiązany do nowego adresu IP między kontrolą a wysłaniem	Rozwiąż ponownie; potraktuj to jako możliwą próbę ataku rebinding.

Awarie po stronie Workera

To awarie typu CloudflareRenderException. Worker odpowiedział, ale samo renderowanie zakończyło się niepowodzeniem. Nigdy nie uruchamiają lokalnego rozwiązania zapasowego, ponieważ brzeg sieci był osiągalny.

Fragment komunikatu	Przyczyna
Cloudflare Worker returned HTTP <code>: <detail>	Status inny niż 200. Szczegóły pochodzą z pola error w formacie JavaScript Object Notation (JSON) lub z pierwszych 200 bajtów ciała odpowiedzi.
Worker returned empty or invalid PDF data	Odpowiedź binarna nie zaczyna się od %PDF.
Worker error: <message>	Odpowiedź JSON zawierająca pole error.
JSON response missing "pdf" field	Odpowiedź JSON bez pola pdf.
Invalid base64-encoded PDF in JSON response	Po zdekodowaniu z base64 pole pdf nie daje bajtów zaczynających się od %PDF.
Invalid JSON response from Worker	Ciało odpowiedzi ma Content-Type: application/json, ale po dekodowaniu nie jest tablicą.
Unexpected Content-Type from Worker: <type>	Odpowiedź 200, w której Content-Type nie jest ani application/pdf, ani application/json.

Po przechwyceniu jednej z tych awarii sprawdź dzienniki Workera. Problem leży po stronie Workera, a nie w tym moście.

Awarie osiągalności i rozwiązania zapasowego

To awarie typu CloudflareNotAvailableException. Most nie mógł skorzystać z brzegu sieci, a żadne rozwiązanie zapasowe nie wytworzyło pliku Portable Document Format (PDF).

Fragment komunikatu	Przyczyna	Rozwiązanie
Cloudflare Worker unavailable: <reason>	Błąd transportu przy wyłączonym rozwiązaniu zapasowym	Włącz fallbackToLocal i podłącz fabrykę albo napraw łączność.
Artisan is installed but no LocalRendererFactoryInterface was provided	nextpdf/artisan jest obecny, ale nie przekazano fabryki	Przekaż LocalRendererFactoryInterface do konstruktora.
local Chrome fallback (nextpdf/artisan) is not installed	Rozwiązanie zapasowe jest włączone, nie skonfigurowano fabryki, a Artisan nie jest zainstalowany	Uruchom composer require nextpdf/artisan, a następnie podłącz fabrykę.

Gdy dostarczysz rejestrator zgodny z PHP Standards Recommendation (PSR)-3 i uruchomi się ścieżka rozwiązania zapasowego, most zapisze wpis warning (Cloudflare render failed, attempting fallback), a następnie wpis info (Falling back to local renderer).

Awarie transportu / przypinania

Objaw	Przyczyna	Rozwiązanie
InvalidSpkiPinException: Invalid SPKI pin format	Pin nie ma postaci sha256/<base64> (ani sha256//<base64>)	Popraw ciąg pinu.
cURL transport error (<n>): <msg>	Awaria na poziomie cURL (Transport Layer Security (TLS), DNS, przekroczenie limitu czasu)	Sprawdź numer błędu cURL; jeśli piny są ustawione, upewnij się, że dostarczany SPKI jest nadal przypięty.
Renderowania zawodzą natychmiast po rotacji certyfikatu	SPKI nowego certyfikatu nie znajduje się w zestawie pinów	Dodaj nowy SPKI jako pin zapasowy przed rotacją.
Transport z przypinaniem nie jest używany mimo skonfigurowanych pinów	Nie dostarczono fabryki PSR-17 ResponseFactory	Przekaż ResponseFactory; transport z przypinaniem tego wymaga.

Zachowanie metody isAvailable()

isAvailable() nigdy nie zgłasza wyjątku. Zwraca false, gdy konfiguracja jest nieprawidłowa albo gdy sonda HEAD nie powiedzie się lub zgłosi wyjątek. Zwraca true tylko wtedy, gdy sonda odpowie statusem poniżej 500. Wynik true jest wyłącznie wskazówką: kolejne żądanie POST może mimo to zawieść z powodu dowolnego z powyższych błędów po stronie Workera. Nie traktuj pomyślnej sondy jako gwarancji.

Niespodzianki związane z limitami szybkości

ApiProtection przechowuje limity w pamięci, osobno dla każdego procesu. Liczniki nie przetrwają ponownego uruchomienia i nie są współdzielone między workerami ani węzłami. Jeśli jeden węzeł dopuszcza klienta, a inny mu odmawia, jest to oczekiwane. Umieść współdzielony magazyn przed mechanizmem limitującym, aby uzyskać limit obowiązujący w całym klastrze.

Zobacz też

• /integrations/cloudflare/security-and-operations/ — operacyjny podręcznik oraz mechanizmy kontroli stojące za tymi komunikatami.
• /integrations/cloudflare/quickstart/ — kanoniczny wzorzec try/catch.
• /integrations/cloudflare/production-usage/ — szczegóły podłączania rozwiązania zapasowego.