استكشاف الأخطاء وإصلاحها

لمحة سريعة

يثير الجسر ثلاثة أنواع من الاستثناءات. يبيّن لك الاستثناء الذي تلتقطه ما الذي فشل، وما إذا كان ينبغي إعادة المحاولة أو استخدام مسار احتياطي. كل جزء رسالة أدناه مأخوذ من الشيفرة المصدرية.

التسلسل الهرمي للاستثناءات

الاستثناء	يمتد من	المعنى
CloudflareNotAvailableException	NextPDF\Exception\NextPdfException	يتعذّر على الجسر الوصول إلى الحافة، أو تكون التهيئة غير مكتملة، ولا يتوفر مسار احتياطي صالح للاستخدام.
CloudflareRenderException	NextPDF\Exception\NextPdfException	استجاب الـ ⁨Worker⁩، لكن العرض فشل (خطأ في بروتوكول نقل النص الفائق (⁨HTTP⁩) أو بنية جسم مشوّهة). لا ينتقل إلى المسار الاحتياطي إطلاقًا.
InvalidSpkiPinException	InvalidArgumentException	سلسلة تثبيت معلومات المفتاح العام للموضوع (⁨SPKI⁩) المهيّأة ذات تنسيق غير صالح.

كما تثير CloudflareSecurityPolicy الاستثناء RuntimeException مباشرةً عند انتهاك سياسة الإدخال أو محدّد الموارد الموحّد (⁨URL⁩). ويحدث ذلك قبل إرسال أي طلب.

إخفاقات التهيئة والإدخال

جزء الرسالة	يُثيره	السبب	الإصلاح
incomplete (missing worker_url or api_token)	المُصيِّر (عبر المسار الاحتياطي)	إما workerUrl أو apiToken فارغ	عيّن كليهما، ثم تحقّق باستخدام isValid().
HTML input exceeds maximum size	CloudflareSecurityPolicy::validate()	إدخال لغة ترميز النص الفائق (⁨HTML⁩) يتجاوز maxHtmlSize	قلّل حجم الإدخال، أو ارفع maxHtmlSize عن قصد.
Base64 data URI exceeds safety limit	CloudflareSecurityPolicy::validate()	يُقدَّر أن معرّف موارد موحّد (⁨URI⁩) من نوع data:;base64, يتجاوز 13631488 بايت	انقل الأصل إلى مورد خارجي؛ ولا تُضمّن ملفات ثنائية كبيرة داخل المحتوى.
meta-refresh redirect which could cause SSRF	CloudflareSecurityPolicy::validate()	قد يؤدي وسم <meta http-equiv="refresh"> إلى تزوير طلب من جانب الخادم (⁨SSRF⁩)	احذف الوسم؛ واستخدم إعادة توجيه من جانب الخادم خارج محتوى ⁨HTML⁩ المُصيَّر.
Invalid Worker URL	validateWorkerUrl()	يتعذّر تحليل الـ ⁨URL⁩ أو يفتقر إلى ⁨scheme/host⁩	وفّر ⁨URL⁩ مطلقًا كاملًا يستخدم بروتوكول نقل النص الفائق الآمن (⁨HTTPS⁩).
Worker URL must use HTTPS	validateWorkerUrl()	المخطّط ليس ⁨HTTPS⁩	استخدم https://.
private or reserved IP addresses	validateWorkerUrl()	عنوان بروتوكول الإنترنت (⁨IP⁩) حرفي يقع ضمن نطاق طلب التعليقات (⁨RFC⁩) 1918 / حلقة استرجاع / ⁨RFC 3927⁩	وجّهه إلى نقطة نهاية عامة.
hostname resolves to a private or reserved IP	validateWorkerUrl()	سجل ⁨A/AAAA⁩ لنظام أسماء النطاقات (⁨DNS⁩) بعد التحليل خاص أو محجوز	أصلح الـ ⁨DNS⁩؛ وتحقّق من احتمال إعادة ربط النطاق.
DNS answer changed since validation	assertPinsStillValid()	حُلّل المضيف إلى عنوان ⁨IP⁩ جديد بين الفحص والإرسال	أعد التحليل؛ وتعامل معه على أنه محاولة محتملة لإعادة ربط النطاق.

إخفاقات من جانب الـ ⁨Worker⁩

هذه إخفاقات من نوع CloudflareRenderException. استجاب الـ ⁨Worker⁩، لكن عملية العرض نفسها فشلت. لا تؤدي هذه إطلاقًا إلى تشغيل المسار الاحتياطي المحلي لأن الحافة كانت قابلة للوصول.

جزء الرسالة	السبب
Cloudflare Worker returned HTTP <code>: <detail>	حالة غير 200. يأتي التفصيل من حقل error في تدوين كائن ⁨JavaScript⁩ (⁨JSON⁩)، أو من أول 200 بايت من جسم الاستجابة.
Worker returned empty or invalid PDF data	الاستجابة الثنائية لا تبدأ بـ %PDF.
Worker error: <message>	استجابة ⁨JSON⁩ تحمل حقل error.
JSON response missing "pdf" field	استجابة ⁨JSON⁩ بدون حقل pdf.
Invalid base64-encoded PDF in JSON response	لم يُفكَّ ترميز ⁨base64⁩ لحقل pdf إلى بايتات تبدأ بـ %PDF.
Invalid JSON response from Worker	يستخدم جسم الاستجابة Content-Type: application/json، لكنه لا يُفكَّ ترميزه إلى مصفوفة.
Unexpected Content-Type from Worker: <type>	استجابة 200 يكون نوع المحتوى فيها ليس application/pdf ولا application/json.

عند التقاط أحد هذه الاستثناءات، افحص سجلات الـ ⁨Worker.⁩ فالإخفاق من جانب الـ ⁨Worker⁩، وليس في هذا الجسر.

إخفاقات إمكانية الوصول والمسار الاحتياطي

هذه إخفاقات من نوع CloudflareNotAvailableException. تعذّر على الجسر استخدام الحافة، ولم يُنتج أي مسار احتياطي ملف تنسيق مستند محمول (⁨PDF⁩).

جزء الرسالة	السبب	الإصلاح
Cloudflare Worker unavailable: <reason>	خطأ في النقل مع تعطيل المسار الاحتياطي	فعّل fallbackToLocal واربط مصنعًا، أو أصلح الاتصال.
Artisan is installed but no LocalRendererFactoryInterface was provided	nextpdf/artisan موجود، لكن لم يُمرَّر أي مصنع	مرّر LocalRendererFactoryInterface إلى الدالة البانية.
local Chrome fallback (nextpdf/artisan) is not installed	المسار الاحتياطي مفعّل، ولا يوجد مصنع مهيّأ، و⁨Artisan⁩ غائب	شغّل composer require nextpdf/artisan، ثم اربط مصنعًا.

عند توفير مُسجِّل توصية معايير ⁨PHP⁩ (⁨PSR⁩)-3 وتشغيل المسار الاحتياطي، يسجّل الجسر رسالة warning (Cloudflare render failed, attempting fallback)، ثم رسالة info (Falling back to local renderer).

إخفاقات النقل / التثبيت

العَرَض	السبب	الإصلاح
InvalidSpkiPinException: Invalid SPKI pin format	أحد عناصر التثبيت ليس بصيغة sha256/<base64> (أو sha256//<base64>)	صحّح سلسلة التثبيت.
cURL transport error (<n>): <msg>	إخفاق على مستوى ⁨cURL⁩ (أمان طبقة النقل (⁨TLS⁩)، أو ⁨DNS⁩، أو انتهاء المهلة)	افحص رقم خطأ ⁨cURL⁩؛ وإذا كانت عناصر التثبيت مضبوطة، فتأكد من أن الـ ⁨SPKI⁩ المُقدَّم لا يزال مثبّتًا.
تفشل عمليات العرض فور تدوير الشهادة	الـ ⁨SPKI⁩ الخاص بالشهادة الجديدة ليس ضمن مجموعة التثبيت	أضف الـ ⁨SPKI⁩ الجديد كعنصر تثبيت احتياطي قبل التدوير.
لم يُستخدم النقل المثبّت رغم تهيئة عناصر التثبيت	لم يُوفَّر ResponseFactory من نوع ⁨PSR-17⁩	مرّر ResponseFactory؛ فالنقل المثبّت يتطلّبه.

سلوك isAvailable()

لا تثير isAvailable() أي استثناء إطلاقًا. وتُعيد false عندما تكون التهيئة غير صالحة، أو عندما يفشل فحص HEAD أو يثير استثناءً. ولا تُعيد true إلا عندما يستجيب الفحص بحالة أقل من 500. نتيجة true مجرد مؤشّر؛ فما زال بإمكان POST اللاحق أن يفشل بأي من أخطاء جانب الـ ⁨Worker⁩ المذكورة أعلاه. لا تتعامل مع نجاح الفحص على أنه ضمان.

مفاجآت تحديد المعدل

تحتفظ ApiProtection بالحدود في الذاكرة لكل عملية. لا تبقى العدّادات بعد إعادة التشغيل، ولا تكون مشتركة عبر العمليات أو العُقَد. إذا سمحت إحدى العُقَد لعميل ومنعته أخرى، فهذا سلوك متوقّع. ضع مخزنًا مشتركًا أمام المُحدِّد للحصول على حد على مستوى المجموعة بأكملها.

انظر أيضًا

• /⁨integrations/cloudflare/security-and-operations/⁩ — دليل التشغيل العملي والضوابط التي تستند إليها هذه الرسائل.
• /⁨integrations/cloudflare/quickstart/⁩ — نمط ⁨try/catch⁩ المعياري.
• /⁨integrations/cloudflare/production-usage/⁩ — تفاصيل توصيل المسار الاحتياطي.