إقلاع NextPDF Gotenberg وآلية اكتشافه

لمحة سريعة

لا يملك الجسر أي آلية اكتشاف تلقائي. أنشئه بوصفه خدمة عادية بحقن صريح عبر الباني: كائن قيمة للإعداد، ومتعاونو بروتوكول نقل النص التشعبي (⁨HTTP⁩) المحدَّدون وفق توصية ⁨PHP⁩ المعيارية (⁨PSR⁩). لا تتضمن هذه الحزمة أي مزوِّد خدمة أو حزمة (⁨bundle⁩) أو امتداد حاوية، ولا تقرأ أي متغير بيئة بنفسها. المقصود بـ”الاكتشاف” هنا هو كيفية تزويد إطار العمل المضيف الجسر بهؤلاء المتعاونين. تقع هذه المسؤولية على عاتق إطار العمل، لا على هذه الحزمة.

كيف يُكتشف الجسر

لا يُكتشف تلقائيًّا؛ فأنت من ينشئه. يتطلب GotenbergBridge أربع وسائط ويقبل ثلاثًا اختيارية:

• مطلوبة: GotenbergConfig، وعميل ⁨PSR-18⁩، ومصنع طلبات ⁨PSR-17⁩، ومصنع تدفقات ⁨PSR-17.⁩
• اختيارية: مسجِّل ⁨PSR-3⁩، وسياسة أمان للغة ترميز النص التشعبي (⁨HTML⁩) (تكون افتراضيًّا السياسة الافتراضية في نواة ⁨NextPDF⁩)، ومصنع استجابات ⁨PSR-17.⁩

يفعِّل مصنع الاستجابات النقل المثبَّت عبر ⁨cURL.⁩ إذا وفَّرته، وكان لدى الجسر ما يثبِّته (عناوين محلولة أو تثبيتات ⁨SubjectPublicKeyInfo⁩ (⁨SPKI⁩) مُعدَّة)، فإنه يستخدم نقل التثبيت. وإذا أغفلته، فسيُستخدم عميل ⁨PSR-18⁩ المحقون دائمًا. يرد عقد الوسائط الكامل في /⁨integrations/gotenberg/configuration/.⁩

تسلسل الإقلاع

لا توجد خطوة تسجيل. دورة الحياة هي:

1. يحل المضيف عميل ⁨PSR-18⁩ ومصانع ⁨PSR-17.⁩ حاوية المضيف هي التي تنفّذ ذلك، لا الحزمة.
2. يبني التطبيق GotenbergConfig من مصدر إعداده. تقبل GotenbergConfig::fromArray() مصفوفة بنمط ⁨snake_case⁩، وتستبدل القيم الافتراضية بقيم التجاوز الممرَّرة. تحقَّق من صحة المصدر في مسار الإقلاع لديك، بحيث يفشل غياب قيمة محدِّد موقع المورد الموحَّد (⁨URL⁩) عند الإقلاع، لا عند كل تحويل.
3. ينشئ التطبيق GotenbergBridge بالإعداد والمتعاونين.
4. يُجري أول استدعاء تحويل التحقق من صحة الـ ⁨URL⁩، وفحص تزوير الطلب من جانب الخادم (⁨SSRF⁩)، وفحص اسم الملف، ثم يرسل الطلب. لا يحدث أي عمل وقت الإنشاء؛ يبقى الجسر خاملًا حتى تستدعيه.

روابط الحاوية

لا تتضمن هذه الحزمة أي روابط حاوية. لجعل الجسر قابلًا للحقن، سجِّله في حاوية تطبيقك المضيف كما يلي:

• اربط GotenbergConfig من مصدر إعدادك.
• اربط عميل ⁨PSR-18⁩ ومصانع ⁨PSR-17⁩ بالتنفيذات التي تختارها.
• اربط GotenbergBridge بوصفه خدمة تتلقى تلك التبعيات.

يندرج التوصيل التلقائي الأصلي لإطار العمل، ونشر الإعداد، وتسجيل مزوِّد الخدمة أو الحزمة (⁨bundle⁩) ضمن حزم تكامل إطار العمل المخصَّصة، لا هنا. هذه الحزمة مستقلة عن إطار العمل بحكم تصميمها. فهي تعتمد على واجهات ⁨PSR⁩ فقط، لذا تعمل تحت أي حاوية.

ترتيب حل الإعداد

لا تقرأ الحزمة أي إعداد من تلقاء نفسها. ترتيب الحل هو ما ينفِّذه تطبيقك قبل استدعاء GotenbergConfig::fromArray() أو الباني. من الترتيبات الشائعة: متغيرات البيئة، ثم ملف إعداد منشور، ثم القيم الافتراضية في الشيفرة. هذا الترتيب هو عقد تطبيقك، لا عقد هذه الحزمة. ما تحدِّده الحزمة فعلًا هو القيمة الافتراضية لكل حقل تتركه المصفوفة الممرَّرة إلى fromArray(): عنوان ⁨URL⁩ فارغ لواجهة برمجة التطبيقات (⁨API⁩)، ومهلة 30 ثانية، وحد حجم 50 ⁨MiB⁩، ومفتاح ⁨API⁩ فارغ، وقوائم تثبيت فارغة.

التشخيصات

تؤكد إشارتان مدمجتان صحة التوصيل:

• تتحقق isAvailable() من صحة الـ ⁨URL⁩ دون حركة شبكة، ثم ترسل طلب HEAD إلى <apiUrl>/health وتُبلِغ عن التوافر عندما تكون الحالة أدنى من 500. تعيد false بدلًا من رمي استثناء عند أي فشل. استدعِها من فحص الجاهزية.
• يؤكد تحويل اختباري لمستند صغير معروف الصحة المسار الكامل من طرف إلى طرف. يشمل ذلك الطلب متعدد الأجزاء إلى <apiUrl>/forms/libreoffice/convert والتحقق من صحة الاستجابة.

انظر أيضًا

• /⁨integrations/gotenberg/integration/⁩ — شغِّل خط معالجة ⁨NextPDF⁩ عبر الخدمة.
• /⁨integrations/gotenberg/install/⁩ — ثبِّت الحزمة والخدمة.
• /⁨integrations/gotenberg/configuration/⁩ — راجع عقد الباني والإعداد الكامل.
• /⁨integrations/gotenberg/overview/⁩ — راجع تدفق التحويل ونموذج التبعيات.