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

لمحة سريعة

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

التثبيت

composer require nextpdf/server

نظرة عامة مفاهيمية

تسلسل إقلاع ⁨MCP⁩

يربط McpServer::create() خادم بروتوكول سياق النموذج (⁨MCP⁩) بترتيب ثابت. أولاً، يحمّل الإعدادات، ويبني سياسة الأمان منها، وينشئ سجل الأدوات، ويشغّل اكتشاف الطبقات. بعد ذلك، يبني مخزن المستندات في الذاكرة استناداً إلى مدة البقاء (⁨TTL⁩) والسعة المُعدَّتين، وينشئ ناقل ⁨stdio⁩، ويجمع معالِج بروتوكول ⁨JSON-RPC⁩ مع بوابة التأكيد ومسجّل التدقيق. ثم يدخل الخادم حلقة القراءة-المعالجة-الكتابة الخاصة به، ويستمر في العمل إلى أن يبلغ الإدخال القياسي نهاية الملف.

تسلسل إقلاع ⁨REST⁩

يقرأ HttpServer::create() القيمة HttpConfig من البيئة، ويطبّق تجاوزات واجهة سطر الأوامر (⁨CLI⁩). ثم يحلّ مخزن مفاتيح واجهة برمجة التطبيقات (⁨API⁩) وفق ترتيب الأفضلية التالي: مخزن الملفات ذو إعادة التحميل الساخن أولاً، ثم الملف الثابت، ثم البيئة. بعد ذلك، يحلّ مخزنَي تحديد المعدل والتكرار الآمن (⁨idempotency⁩). ويستخدمان ⁨Redis⁩ عندما يكون ⁨Redis⁩ مُعدّاً ويمكن الوصول إليه، ويعودان إلى التخزين في الذاكرة في غير ذلك. ومن هناك، يفتح الخادم مخزن المهام المشترك القائم على ⁨SQLite⁩، ويبني خدمات التطبيق، وينشئ جدول التوجيه. ولأن جدول التوجيه يُبنى من الطبقات المُكتشَفة، فإنه يعكس الحزم المثبَّتة. ثم يقود ⁨RoadRunner⁩ حلقة طلبات العامل.

تسلسل إقلاع ⁨gRPC⁩

يحلّ GrpcServer::create() مخزن المفاتيح نفسه، ويبني خدمات التطبيق نفسها، ويسجّل خدمة nextpdf.connect.v1 لدى عامل ⁨Spiral gRPC.⁩ عندما تكون تبعية المحرّك غير متوفّرة، يبدأ خادم ⁨gRPC⁩ مع ذلك، ويخدم استعلامات السلامة والقدرات. في هذه الحالة، لا ترفض العملية الإقلاع؛ بل تفشل استدعاءات الإجراءات البعيدة (⁨RPCs⁩) التي تحمل بيانات فشلاً نظيفاً.

اكتشاف الأدوات

الاكتشاف هو خطوة التسجيل الافتراضية في السجل. تُسجَّل الطبقة الأساسية أولاً. بعد ذلك، يُسجَّل مزوّدا ⁨Pro⁩ و⁨Enterprise⁩ إذا أمكن تحليل صفوفهما عبر class_exists(). ثم يُسجَّل مزوّدا شجرة التركيب المجرّدة (⁨AST⁩) والطفرات المُرفقان ضمن طبقة ⁨Pro⁩، رهناً ببوابات البيئة الخاصة بهما. يُرشَّح كل تسجيل عبر قائمة السماح الأمنية enabled_tools، وتعرض استجابة initialize الخاصة بـ ⁨MCP⁩ الأعداد الناتجة لكل طبقة. راجع /⁨connect/tool-catalog/.⁩

اكتشاف النواقل

لا يوجد إعداد تهيئة واحد “يفعّل النواقل.” فكل ناقل نقطة دخول مستقلة. لكل من ⁨REST⁩ و⁨gRPC⁩ ملف تعريف ⁨RoadRunner⁩ منفصل. يختار النشر النواقل بحسب ملف التعريف الذي يشغّله: .rr.yaml لـ ⁨REST⁩، و.rr.grpc.yaml لـ ⁨gRPC⁩، أو .rr.full.yaml لكليهما. تعمل النواقل كعمليات مستقلة. غياب عميل ⁨MCP⁩ لا يمنع خادم ⁨REST⁩ أبداً، وغياب عميل ⁨REST⁩ لا يمنع ⁨MCP⁩ أبداً. راجع /⁨connect/deployment/.⁩

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

يحلّ خادم ⁨MCP⁩ الإعدادات وفق ترتيب الأسبقية التالي: البيئة (NEXTPDF_MCP_*) لها الأولوية على قسم nextpdf_mcp في ملف ⁨YAML⁩، وهذا القسم له الأولوية على القيم الافتراضية المدمجة. يقرأ خادما ⁨REST⁩ و⁨gRPC⁩ القيمة HttpConfig من متغيرات البيئة NEXTPDF_* مع قيم افتراضية آمنة. وهما لا يقرآن ملف ⁨YAML⁩ الخاص بـ ⁨MCP.⁩ راجع /⁨connect/configuration/.⁩

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

لا توجد حاوية لحقن التبعيات ولا مزوّد خدمة للتسجيل. ينشئ كل مصنع create() مخطط الكائنات الخاص به بنفسه، على نحو صريح وحتمي. توجد نقطتا حقن — الناقل ومصنع العامل — وكلتاهما مخصصتان للاختبار، لا لربط التطبيق.

مثال برمجي — بداية سريعة

افحص ناتج الاكتشاف دون خدمة أي حركة مرور:

./vendor/bin/generate-skills --dry-run --list-tools

مثال برمجي — الإنتاج

شغّل النواقل المجمَّعة تحت مشرف واحد:

export NEXTPDF_API_KEYS_FILE=/run/secrets/api-keys
./vendor/bin/rr serve -c .rr.full.yaml

الحالات الحدّية والمزالق

• الطبقة المفقودة لا تُفشِل الإقلاع. يتجاوز اكتشاف الطبقات بصمت أي حزمة ⁨Pro⁩ أو ⁨Enterprise⁩ غائبة. يبدأ الخادم بالكتالوج الأساسي.

• تجاوز التخفيض يُفشِل الإقلاع. أي مُدخَل risk_level_overrides يُضعِف اشتراط approval_required يطلق استثناءً أثناء تحميل الإعدادات؛ ويرفض الخادم البدء. هذا متعمَّد.

• فشل ⁨Redis⁩ يؤدي إلى تدهور الأداء، لا إلى تعطّل. إذا كان ⁨Redis⁩ مُعدّاً لكن يتعذّر الوصول إليه عند الإقلاع، فإن خادم ⁨REST⁩ يعود إلى مخازن الذاكرة. تحقّق من سلامة ⁨Redis⁩ بدلاً من افتراض أن ⁨Redis⁩ قيد الاستخدام.

الأداء

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

ملاحظات أمنية

تُبنى سياسة الأمان قبل السجل، لذلك تقيّد قائمة السماح enabled_tools الاكتشاف منذ أول تسجيل. لا تُقرأ مفاتيح ⁨API⁩ أبداً من ملف ⁨YAML⁩ الخاص بـ ⁨MCP⁩؛ بل تحلّ النواقل الشبكية المفاتيح من ملف سرّي أو من البيئة. راجع /⁨connect/security-and-operations/.⁩

المطابقة

تصف هذه الصفحة آليات الإقلاع. ترد استشهادات البروتوكول والأمان المثبَّتة في /⁨transports/mcp/⁩ و/⁨transports/rest/⁩ و/⁨transports/grpc/⁩ و/⁨connect/security-and-operations/.⁩

السياق التجاري

اكتشاف الطبقات عند الإقلاع هو النقطة الوحيدة التي يضيف فيها nextpdf/premium أدوات ⁨Pro⁩ و⁨Enterprise⁩ الخاصة به إلى الكتالوج، عندما يكون nextpdf/premium مثبَّتاً إلى جانب الخادم.

انظر أيضاً

• /⁨connect/tool-catalog/⁩ — ما يسجّله الاكتشاف وسبب تباين العدد
• /⁨connect/configuration/⁩ — ترتيب الحلّ بالتفصيل
• /⁨connect/deployment/⁩ — اختيار النواقل عبر ملفات تعريف ⁨RoadRunner⁩
• /⁨transports/mcp/⁩ · /⁨transports/rest/⁩ · /⁨transports/grpc/⁩ — تفاصيل كل ناقل