استخدام NextPDF Gotenberg في الإنتاج

نظرة سريعة

ينفّذ الجسر طلبًا متزامنًا واحدًا ذهابًا وإيابًا عبر بروتوكول نقل النص الفائق (⁨HTTP⁩)، ثم يتحقّق من النتيجة. وهو لا يعيد المحاولة، ولا يضع الطلبات في طابور، ولا يخزّن مؤقتًا، ولا يحدّ من المعدّل. ضع هذه السلوكيات في التطبيق المحيط بالجسر. توضّح هذه الصفحة ما الذي ينتمي إلى كل موضع، وما الذي يضمنه الجسر، حتى تتمكّن من بناء بقية النظام على نحو صحيح.

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

الحصول على الإعدادات والأسرار

يخزّن GotenbergConfig محدّد موقع المورد الموحّد (⁨URL⁩) لواجهة برمجة التطبيقات (⁨API⁩)، وعند تفعيل المصادقة يخزّن رمزًا حاملًا. حقل الرمز مُعلَّم بـ #[\SensitiveParameter]، لذلك تحجبه تتبّعات المكدّس. ومع ذلك، تظل مسؤولًا عن الحصول عليه على نحو آمن.

• اقرأ الرمز من مدير الأسرار لديك أو من قيمة بيئة محقونة عند بدء العملية. لا تُودِعه في نظام التحكم بالإصدارات، ولا تضعه في ملف إعدادات يُشحَن ضمن الصورة.
• ابنِ الإعدادات مرة واحدة لكل نطاق طلب أو مرة واحدة لكل عامل، لا لكل عملية تحويل. الإعدادات غير قابلة للتغيير، والاحتفاظ بها منخفض التكلفة.
• يقبل GotenbergConfig::fromArray() المدخلات المشوّهة عمدًا ويستبدل بها القيم الافتراضية بصمت. في الإنتاج، تحقّق من المصفوفة المصدر قبل استدعاء fromArray(). عندها يظهر عنوان ⁨URL⁩ المفقود كخطأ في الإعدادات أثناء الإقلاع، لا لاحقًا كاستثناء Invalid Gotenberg configuration: apiUrl is empty مع كل عملية تحويل.

المُهَل الزمنية

timeout (بالثواني، القيمة الافتراضية 30) هي مهلة النقل الصارمة التي يطبّقها النقل المثبَّت على ⁨cURL.⁩ تحويل مستندات ⁨Office⁩ عبر ⁨LibreOffice⁩ ليس فوريًا؛ فالمستندات الكبيرة أو المعقّدة تستغرق وقتًا أطول. اضبط المهلة بناءً على زمن التحويل المقيس لمستنداتك الفعلية، مع هامش إضافي. أبقِها أدنى من أي مهلة بوابة أعلى في السلسلة أو من max_execution_time في بيئة تشغيل ⁨PHP.⁩ يتيح ذلك للجسر أن تنتهي مهلته أولًا، فيُطلق استثناءً مُصنَّفًا بدلًا من أن تُقتل العملية.

إذا استخدمت مسار عميل توصية ⁨PHP⁩ المعيارية رقم 18 (⁨PSR-18⁩) المحقون (دون حقن responseFactory، أو عنوان ⁨URL⁩ مجرّد ببروتوكول الإنترنت (⁨IP⁩) دون تثبيتات)، فلن يطبّق الجسر قيمة timeout على ذلك العميل. اضبط المهلة على عميل ⁨PSR-18⁩ أيضًا، حتى يبقى كلا النقلين محدودًا.

إعادات المحاولة

يرسل الجسر طلبًا واحدًا بالضبط لكل استدعاء، ولا يعيد المحاولة أبدًا. أضف إعادات المحاولة في المُستدعِي، واجعلها آمنة:

• أعِد المحاولة فقط عند إخفاقات مستوى النقل (استثناء GotenbergConvertException يكون سببه استثناء عميل ⁨PSR-18⁩) وأخطاء الخادم العديمة الأثر الجانبي (⁨HTTP⁩ ‏502، 503، 504). لا تُعِد المحاولة لكل GotenbergConvertException دون تمييز. عادةً ما تعني استجابة من فئة 400 أن المدخل خاطئ، لذلك ستخفق إعادة المحاولة نفسها بالطريقة نفسها.
• استخدم تراجعًا أُسّيًا محدودًا مع تشويش زمني. عندما تُرجع خدمة تحويل واقعة تحت الحِمل 503، فإن إغراقها بالطلبات يزيد الانقطاع سوءًا.
• حُدّ إجمالي المحاولات وإجمالي الزمن الفعلي. التحويل بطيء أصلًا، لذلك فإن إعادات المحاولة غير المحدودة تضاعف زمن الاستجابة في الذيل.
• تُجرى إعادة التحقّق تلقائيًا: فكل استدعاء يُعاد تنفيذه يعيد تنفيذ التحقّق من عنوان ⁨URL⁩ وفحص العنوان، لذلك لا يمكن لإعادة المحاولة أن تتجاوز حارس تزوير الطلب من جانب الخادم (⁨SSRF⁩) عن طريق الخطأ.

التزامن والسعة

تشغل كل عملية تحويل اتصالًا واحدًا وعاملًا واحدًا من ⁨LibreOffice⁩ على جانب ⁨Gotenberg⁩ حتى ينتهي الطلب. والجسر نفسه عديم الحالة وآمن للاستخدام من عدة عمّال في الوقت نفسه. ومع ذلك، تبقى لخدمة ⁨Gotenberg⁩ سعة تحويل محدودة.

• حُدّ عدد عمليات التحويل الجارية من جانبك (بطابور أو إشارة مزامنة أو تجمّع عمّال) بما يوافق السعة التي يستطيع ⁨Gotenberg⁩ تحمّلها. يعتمد ضبط الحجم على نشر ⁨Gotenberg⁩ لديك، لا على هذه الحزمة؛ انظر /⁨integrations/gotenberg/security-and-operations/.⁩
• سقف حجم المدخل (maxFileSize، القيمة الافتراضية 50 ⁨MiB⁩) هو الحدّ الوحيد المدمج للموارد في الجسر. يفرضه الجسر داخل العملية قبل إرسال الطلب، لذلك لا يستهلك ملف مفرط الحجم أي سعة من الخدمة أبدًا. اخفضه ليطابق ما تحتاجه مستنداتك فعلًا؛ فالسقف الأصغر ضابط أرخص يمنع الخدمة من بلوغ السقف الأكبر.
• لا يوجد تخزين مؤقت داخل العملية. إذا حوّلت المستند نفسه مرارًا، فخزّن مؤقتًا ملف صيغة المستند المحمول (⁨PDF⁩) الناتج في تطبيقك، مُفهرسًا ببصمة محتوى للمدخل.

قابلية المراقبة

احقن مُسجّلًا متوافقًا مع توصية ⁨PHP⁩ المعيارية رقم 3 (⁨PSR-3⁩) للحصول على مدخلة debug واحدة لكل طلب تحويل. تحتوي المدخلة على عنوان ⁨URL⁩ للطلب، واسم الملف، والصيغة المكتشَفة، وطول محتوى الطلب. وهي لا تحتوي على محتويات الملف ولا على الرمز الحامل.

• حوّل تلك الإشارة إلى مقياس: عُدّ عمليات التحويل حسب الصيغة والنتيجة، وسجّل الزمن الفعلي حول كل استدعاء convertFile() / convertString() بوصفه مدرّجًا تكراريًا لزمن الاستجابة. لا يصدر الجسر مقاييس بنفسه.
• يكشف كائن النتيجة عن حقل renderTimeMs. وقيمته 0.0 ما لم يقِسها تكاملك ويضبطها؛ فالجسر لا يملؤها من استجابة ⁨Gotenberg.⁩ وقّت الاستدعاء بنفسك إذا كنت بحاجة إلى القيمة.
• سجّل الاستثناءات مع نوعها. نوع الاستثناء هو الإشارة الأساسية إلى ما أخفق؛ انظر /⁨integrations/gotenberg/troubleshooting/⁩ للاطّلاع على الفهرس.
• افحص isAvailable() من نقطة نهاية الجاهزية أو الصحة لديك، لا عند كل عملية تحويل. فهو يرسل HEAD إلى /health. وتشغيله قبل كل عملية تحويل يضاعف معدّل طلباتك على الخدمة دون فائدة.

عقد التعامل مع الإخفاقات

يُظهر الجسر الإخفاقات على هيئة استثناءات مُصنَّفة، ولا يُرجع أبدًا نتيجة جزئية أو غير متحقَّق منها. وهو يضمن ما يلي:

• أي حالة غير 200، أو Content-Type دون application/pdf، أو جسم لا يبدأ بـ %PDF يثير GotenbergConvertException. ولا يُرجع الجسر كائن نتيجة إلا عندما تجتاز الفحوص الثلاثة جميعها.
• يُغلَّف إخفاق عميل ⁨PSR-18⁩ (بما في ذلك إخفاق الشبكة أو انتهاء المهلة) ضمن GotenbergConvertException، مع الاستثناء الأصلي بوصفه سببه ورمز العميل بوصفه رمز الاستثناء.
• إخفاقات التحقّق (عنوان ⁨URL⁩ ليس ⁨HTTPS⁩، أو عنوان ⁨private/reserved⁩، أو مدخل مفرط الحجم، أو اسم ملف غير آمن) تثير RuntimeException قبل أي حركة مرور على الشبكة.
• امتداد ملف غير معروف يثير ValueError قبل أي حركة مرور على الشبكة.

التقط الأنواع المحدّدة. يبيّن البرنامج المثال في examples/convert-office-to-pdf.php ترتيب الالتقاط الشامل. يشرح /⁨integrations/gotenberg/troubleshooting/⁩ كل مُحفِّز.

حدّ المعالجة اللاحقة

ينتج الجسر ملف ⁨PDF⁩ ثم يتوقّف. ومن خطوط الإنتاج الشائعة ما يلي:

1. حوّل مستند ⁨Office⁩ بهذا الجسر.
2. حمّل البايتات الناتجة في مستند ⁨NextPDF.⁩
3. طبّق المعالجة اللاحقة: تجميع الصفحات، ووضع العلامة المائية، والتحويل إلى صيغة المستند المحمول/الأرشيفية (⁨PDF/A⁩)، والتواقيع الرقمية.

تعود الخطوة 3 إلى ⁨NextPDF⁩، لا إلى الجسر. يوفّر nextpdf/premium التوقيع، وملفّات تعريف ⁨PDF/A⁩، ووضع العلامة المائية. أبقِ التحويل والمعالجة اللاحقة مرحلتين منفصلتين، حتى تتمكّن من تشخيص إخفاق التحويل بمعزل عن إخفاق التوقيع.

دعم التواقيع الإلكترونية المتقدّمة للـ ⁨PDF⁩ (⁨PAdES⁩) في إصدار ⁨Pro⁩ هو الأساس ⁨B-B⁩ فقط. وهو لا يوفّر ⁨B-T⁩ ولا ⁨B-LT⁩ ولا ⁨B-LTA⁩، و لا تُستلزَم تلك الملفّات التعريفية بمجرّد تحويل مستند عبر هذا الجسر. قدرة التحقّق طويل الأمد شأن إصدار منفصل وهي خارج نطاق هذه الحزمة.

انظر أيضًا

• /⁨integrations/gotenberg/configuration/⁩ - قواعد اختيار النقل ونموذج التثبيت.
• /⁨integrations/gotenberg/security-and-operations/⁩ - نشر تبعية ⁨Gotenberg⁩ وتقويتها.
• /⁨integrations/gotenberg/troubleshooting/⁩ - فهرس الاستثناءات.
• /⁨integrations/gotenberg/integration/⁩ - ربط ملف ⁨PDF⁩ المحوَّل بخط معالجة ⁨NextPDF.⁩