Khắc phục sự cố
Tổng quan nhanh
Phần tiêu đề “Tổng quan nhanh”Cầu nối có thể phát sinh ba loại ngoại lệ. Ngoại lệ bạn bắt được cho biết phần nào đã thất bại và nên thử lại hay chuyển sang phương án dự phòng. Mỗi đoạn thông báo dưới đây đều được lấy từ mã nguồn.
Hệ thống phân cấp ngoại lệ
Phần tiêu đề “Hệ thống phân cấp ngoại lệ”| Ngoại lệ | Kế thừa từ | Ý nghĩa |
|---|---|---|
CloudflareNotAvailableException | NextPDF\Exception\NextPdfException | Cầu nối không thể tiếp cận edge, hoặc cấu hình chưa hoàn chỉnh, và không có phương án dự phòng khả dụng. |
CloudflareRenderException | NextPDF\Exception\NextPdfException | Worker đã phản hồi, nhưng quá trình kết xuất thất bại (lỗi Hypertext Transfer Protocol (HTTP) hoặc phần thân sai định dạng). Không bao giờ sử dụng phương án dự phòng. |
InvalidSpkiPinException | InvalidArgumentException | Chuỗi pin Subject Public Key Info (SPKI) đã cấu hình có định dạng không hợp lệ. |
CloudflareSecurityPolicy cũng phát sinh trực tiếp RuntimeException khi có vi phạm chính sách về đầu vào và Uniform Resource Locator (URL). Ngoại lệ được phát sinh trước khi gửi bất kỳ yêu cầu nào.
Lỗi cấu hình và đầu vào
Phần tiêu đề “Lỗi cấu hình và đầu vào”| Đoạn thông báo | Phát sinh bởi | Nguyên nhân | Cách khắc phục |
|---|---|---|---|
incomplete (missing worker_url or api_token) | Renderer (qua đường dẫn dự phòng) | Hoặc workerUrl hoặc apiToken bị rỗng | Đặt cả hai giá trị, rồi xác minh bằng isValid(). |
HTML input exceeds maximum size | CloudflareSecurityPolicy::validate() | Đầu vào Hypertext Markup Language (HTML) dài hơn maxHtmlSize | Rút gọn đầu vào hoặc chủ động tăng maxHtmlSize. |
Base64 data URI exceeds safety limit | CloudflareSecurityPolicy::validate() | Một Uniform Resource Identifier (URI) dạng data:;base64, được ước tính là vượt quá 13631488 byte | Đưa tài nguyên ra ngoài; đừng nhúng trực tiếp các tệp nhị phân lớn. |
meta-refresh redirect which could cause SSRF | CloudflareSecurityPolicy::validate() | Một thẻ <meta http-equiv="refresh"> có thể kích hoạt giả mạo yêu cầu phía máy chủ (SSRF) | Loại bỏ thẻ đó; dùng chuyển hướng phía máy chủ bên ngoài phần HTML được kết xuất. |
Invalid Worker URL | validateWorkerUrl() | URL không phân tích được hoặc thiếu scheme/host | Cung cấp một URL tuyệt đối đầy đủ dùng Hypertext Transfer Protocol Secure (HTTPS). |
Worker URL must use HTTPS | validateWorkerUrl() | Scheme không phải HTTPS | Dùng https://. |
private or reserved IP addresses | validateWorkerUrl() | Địa chỉ Internet Protocol (IP) dạng literal nằm trong dải Request for Comments (RFC) 1918 / loopback / RFC 3927 | Trỏ tới một điểm cuối công khai. |
hostname resolves to a private or reserved IP | validateWorkerUrl() | Một bản ghi A/AAAA Domain Name System (DNS) phân giải thành địa chỉ riêng tư hoặc dành riêng | Sửa DNS; điều tra khả năng tấn công rebinding. |
DNS answer changed since validation | assertPinsStillValid() | Host được phân giải sang một địa chỉ IP mới giữa thời điểm kiểm tra và thời điểm gửi | Phân giải lại; xem đây là một nỗ lực rebinding có thể xảy ra. |
Lỗi phía Worker
Phần tiêu đề “Lỗi phía Worker”Đây là các lỗi CloudflareRenderException. Worker đã phản hồi, nhưng bản thân quá trình kết xuất thất bại. Những lỗi này không bao giờ kích hoạt phương án dự phòng cục bộ vì edge vẫn tiếp cận được.
| Đoạn thông báo | Nguyên nhân |
|---|---|
Cloudflare Worker returned HTTP <code>: <detail> | Trạng thái khác 200. Chi tiết được lấy từ trường error trong JavaScript Object Notation (JSON) hoặc 200 byte đầu tiên của phần thân. |
Worker returned empty or invalid PDF data | Phản hồi nhị phân không bắt đầu bằng %PDF. |
Worker error: <message> | Phản hồi JSON có chứa trường error. |
JSON response missing "pdf" field | Phản hồi JSON không có trường pdf. |
Invalid base64-encoded PDF in JSON response | Khi giải mã base64, trường pdf không tạo ra các byte bắt đầu bằng %PDF. |
Invalid JSON response from Worker | Phần thân dùng Content-Type: application/json, nhưng không giải mã được thành mảng. |
Unexpected Content-Type from Worker: <type> | Một phản hồi 200 có Content-Type không phải application/pdf cũng không phải application/json. |
Khi bắt được một trong những lỗi này, hãy kiểm tra nhật ký Worker. Lỗi nằm ở phía Worker, không phải trong cầu nối này.
Lỗi về khả năng tiếp cận và phương án dự phòng
Phần tiêu đề “Lỗi về khả năng tiếp cận và phương án dự phòng”Đây là các lỗi CloudflareNotAvailableException. Cầu nối không thể dùng edge, và không có phương án dự phòng nào tạo được tệp Portable Document Format (PDF).
| Đoạn thông báo | Nguyên nhân | Cách khắc phục |
|---|---|---|
Cloudflare Worker unavailable: <reason> | Lỗi truyền tải khi phương án dự phòng đang bị tắt | Bật fallbackToLocal và kết nối một factory, hoặc khắc phục khả năng kết nối. |
Artisan is installed but no LocalRendererFactoryInterface was provided | nextpdf/artisan có mặt, nhưng không có factory nào được truyền vào | Truyền một LocalRendererFactoryInterface vào constructor. |
local Chrome fallback (nextpdf/artisan) is not installed | Phương án dự phòng đang bật, không có factory nào được cấu hình, và Artisan không có mặt | Chạy composer require nextpdf/artisan, rồi kết nối một factory. |
Khi bạn cung cấp một logger PHP Standards Recommendation (PSR)-3 và đường dẫn dự phòng chạy, cầu nối ghi một warning (Cloudflare render failed, attempting fallback), sau đó ghi một info (Falling back to local renderer).
Lỗi truyền tải / pinning
Phần tiêu đề “Lỗi truyền tải / pinning”| Triệu chứng | Nguyên nhân | Cách khắc phục |
|---|---|---|
InvalidSpkiPinException: Invalid SPKI pin format | Một pin không ở dạng sha256/<base64> (hoặc sha256//<base64>) | Sửa lại chuỗi pin. |
cURL transport error (<n>): <msg> | Lỗi ở mức cURL (Transport Layer Security (TLS), DNS, hết thời gian chờ) | Kiểm tra mã lỗi cURL; nếu pin đã được đặt, hãy xác nhận SPKI đang phục vụ vẫn còn được pin. |
| Kết xuất thất bại ngay sau khi xoay vòng chứng chỉ | SPKI của chứng chỉ mới không nằm trong tập pin | Thêm SPKI mới làm pin dự phòng trước khi xoay vòng. |
| Truyền tải có pin không được dùng dù đã cấu hình pin | Không có ResponseFactory PSR-17 nào được cung cấp | Truyền một ResponseFactory; truyền tải có pin yêu cầu phải có nó. |
isAvailable() hoạt động như thế nào
Phần tiêu đề “isAvailable() hoạt động như thế nào”isAvailable() không bao giờ ném ngoại lệ. Nó trả về false khi cấu hình không hợp lệ, hoặc khi phép thăm dò HEAD thất bại hay phát sinh ngoại lệ. Nó chỉ trả về true khi phép thăm dò phản hồi với trạng thái dưới 500. Kết quả true chỉ là một gợi ý: lệnh POST tiếp theo vẫn có thể thất bại với bất kỳ lỗi phía Worker nào ở trên. Đừng xem một phép thăm dò thành công là sự bảo đảm.
Bất ngờ về giới hạn tần suất
Phần tiêu đề “Bất ngờ về giới hạn tần suất”ApiProtection giữ các giới hạn trong bộ nhớ theo từng tiến trình. Số đếm không tồn tại sau khi khởi động lại, và không được chia sẻ giữa các worker hay node. Nếu một node cho phép một client còn node khác từ chối client đó, thì đó là điều bình thường. Đặt một kho chia sẻ phía trước bộ giới hạn để áp dụng giới hạn trên toàn cụm.
Xem thêm
Phần tiêu đề “Xem thêm”- /integrations/cloudflare/security-and-operations/ — sổ tay vận hành và các biện pháp kiểm soát phía sau những thông báo này.
- /integrations/cloudflare/quickstart/ — mẫu try/catch chuẩn.
- /integrations/cloudflare/production-usage/ — chi tiết kết nối phương án dự phòng.