تهيئة NextPDF Connect

لمحة سريعة

يوفّر ⁨NextPDF Connect⁩ واجهتَي تهيئة. يقرأ خادم ⁨Model Context Protocol⁩ (⁨MCP⁩) ملف ⁨YAML⁩ ومتغيرات NEXTPDF_MCP_*. ويقرأ خادما ⁨REST⁩ و⁨gRPC⁩ متغيرات البيئة NEXTPDF_*. تصبح التهيئة غير قابلة للتغيير بعد إقلاع الخادم.

التثبيت

composer require nextpdf/server

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

يحلّ خادم ⁨MCP⁩ التهيئة وفق ترتيب أولوية ثابت. تكون الغلبة للمصدر الأعلى أولوية:

متغيرات البيئة (NEXTPDF_MCP_*).
قسم nextpdf_mcp في ملف تهيئة ⁨YAML.⁩
القيم الافتراضية المضمَّنة.

مرِّر ملف ⁨YAML⁩ باستخدام --config=PATH. إذا أغفلته، يستخدم الخادم القيم الافتراضية ومتغيرات البيئة فقط. كائن McpConfig الناتج هو كائن قيمة readonly. لا يمكن لأي إعداد أن يتغير بعد الإقلاع.

يقرأ خادما ⁨REST⁩ و⁨gRPC⁩ كائن HttpConfig من البيئة عند الإقلاع. ويدعمان NEXTPDF_BIND، وNEXTPDF_WORKER_COUNT، وNEXTPDF_SESSIONS_ENABLED، وNEXTPDF_CORS_ENABLED باعتبارها تجاوزات من البيئة. أمّا الحدود القصوى المتبقية فتستخدم قيمًا افتراضية آمنة.

واجهة ⁨API⁩

تهيئة ⁨MCP⁩ (`nextpdf-mcp`)

ملف ⁨YAML⁩، قسم nextpdf_mcp:

nextpdf_mcp:
  enabled_tools: []          # empty/absent = all available tools allowed
  temp_directory: /tmp/nextpdf-mcp
  max_documents: 50
  document_ttl: 1800
  max_file_size_bytes: 104857600
  allow_file_output: true
  compress: true
  risk_level_overrides:
    fill_form: 3             # raise fill_form to ApprovalRequired (see below)

تجاوزات البيئة الخاصة بخادم ⁨MCP⁩:

المتغير	مفتاح التهيئة	الافتراضي
`NEXTPDF_MCP_ENABLED_TOOLS`	`enabled_tools`	كل الأدوات مسموح بها
`NEXTPDF_MCP_TEMP_DIR`	`temp_directory`	المجلد المؤقت للنظام + `/nextpdf-mcp`
`NEXTPDF_MCP_MAX_FILE_SIZE`	`max_file_size_bytes`	`104857600` (100 ⁨MB⁩)
`NEXTPDF_MCP_MAX_DOCUMENTS`	`max_documents`	`50`
`NEXTPDF_MCP_DOCUMENT_TTL`	`document_ttl`	`1800` ثانية
`NEXTPDF_MCP_TOOL_PARSE_PDF_ENABLED`	(يضبط بوابة `parse_pdf`)	غير مضبوط (مُعطَّل)
`NEXTPDF_AST_TOOLS_ENABLED`	(يضبط بوابة أدوات ⁨AST⁩)	مُفعَّل
`NEXTPDF_MUTATION_TOOLS_ENABLED`	(يضبط بوابة أدوات التحوير في ⁨AST⁩)	غير مضبوط (مُعطَّل)

تهيئة ⁨REST⁩ و⁨gRPC⁩

المتغير	الافتراضي	الأثر
`NEXTPDF_BIND`	`0.0.0.0:8080`	عنوان الاستماع في ⁨REST⁩
`NEXTPDF_WORKER_COUNT`	`4`	عدد عمّال ⁨PHP⁩ في ⁨RoadRunner⁩
`NEXTPDF_SESSIONS_ENABLED`	`false`	تفعيل نقاط نهاية الجلسات ذات الحالة
`NEXTPDF_CORS_ENABLED`	`false`	تفعيل ترويسات استجابة ⁨CORS⁩
`NEXTPDF_API_KEYS`	غير مضبوط	تعريفات مفاتيح ⁨API⁩ مضمَّنة
`NEXTPDF_API_KEYS_FILE`	غير مضبوط	مسار إلى ملف مفاتيح ⁨API⁩
`NEXTPDF_JOB_STORE_PATH`	المجلد المؤقت للنظام	مسار مخزن مهام ⁨SQLite⁩
`NEXTPDF_REDIS_HOST`	غير مضبوط	يُفعِّل المخازن المعتمدة على ⁨Redis⁩ عند ضبطه

يستخدم خادم ⁨REST⁩ ⁨Redis⁩ عند ضبط NEXTPDF_REDIS_HOST وتحميل ext-redis:

المتغير	الافتراضي
`NEXTPDF_REDIS_PORT`	`6379`
`NEXTPDF_REDIS_PASSWORD`	فارغ
`NEXTPDF_REDIS_DATABASE`	`0`
`NEXTPDF_REDIS_PREFIX`	`nextpdf:`
`NEXTPDF_REDIS_CONNECT_TIMEOUT`	`2.0` ثانية
`NEXTPDF_REDIS_READ_TIMEOUT`	`2.0` ثانية

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

شغِّل خادم ⁨MCP⁩ بملف تهيئة صريح:

./vendor/bin/nextpdf-mcp --config=/etc/nextpdf/nextpdf-mcp.yaml

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

اقصر فهرس ⁨MCP⁩ على قائمة سماح صريحة، وارفع مستوى مخاطر إحدى الأدوات:

nextpdf_mcp:
  enabled_tools:
    - create_pdf
    - add_text
    - output_pdf
    - diagnostic.doctor
  temp_directory: /var/lib/nextpdf/tmp
  max_file_size_bytes: 26214400
  risk_level_overrides:
    add_text: 2          # upgrade add_text from caution to review

عندما لا تكون enabled_tools فارغة، تقبل سياسة الأمان أسماء الأدوات المدرجة فقط. ويسقط السجل كل أداة أخرى بصمت. أمّا القائمة الفارغة أو الغائبة فتقبل كل الأدوات المتاحة.

الحالات الطرفية والمزالق

لا يمكن خفض مستوى الأداتين الحرجتين. تتطلب الأداتان output_pdf وsign_pdf الموافقة بحكم التصميم: إذا خفّض مدخل risk_level_overrides مستوى أي منهما إلى ما دون ApprovalRequired، يطلق الخادم استثناء InvalidArgumentException وقت التحميل ويرفض الإقلاع. يمكنك رفع مستوى مخاطر أي أداة أخرى أو خفضه، لذا راجع أي خفض مقابل نموذج التهديد لديك. راجع /⁨connect/hitl-risk-tiers/.⁩
enabled_tools يرشّح، ولا يضيف. إنّ إدراج اسم أداة ⁨Pro⁩ بينما يكون nextpdf/premium غائبًا لا يجعلها تظهر. تُقارَن قائمة السماح بالأدوات التي اكتشفها السجل فعليًا.
تكون للبيئة أولوية على ⁨YAML⁩ في خادم ⁨MCP.⁩ يتجاوز متغير NEXTPDF_MCP_* المفتاح نفسه في ملف ⁨YAML.⁩ ولا يقرأ خادما ⁨REST⁩ و⁨gRPC⁩ ملف ⁨YAML⁩ الخاص بـ ⁨MCP⁩ إطلاقًا.
parse_pdf اختياري التفعيل. لا يسجّل الخادم أداة parse_pdf إلا عندما تكون قيمة NEXTPDF_MCP_TOOL_PARSE_PDF_ENABLED هي true أو 1. وهي غائبة افتراضيًا، حتى في الفهرس الأساسي.

الأداء

تُحلل التهيئة مرة واحدة عند الإقلاع. يحد إعدادا max_documents وdocument_ttl حجم مخزن المستندات في الذاكرة. يقلل خفضهما ذروة استهلاك الذاكرة، لكنه يقصر مدة الاحتفاظ بالمستندات. يمثّل عدد العمال والحدود القصوى للحمولة حسب الفئة إعدادات ضبط للنشر، وتتناولها /⁨connect/deployment/.⁩

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

تعامل مع enabled_tools بوصفه ضابط رفض افتراضي لعمليات النشر الأقل امتيازًا: أدرج الأدوات التي يحتاجها تكامل محدد فقط.
لا تخزن مفاتيح ⁨API⁩ في ملف ⁨YAML⁩ إطلاقًا. استخدم NEXTPDF_API_KEYS_FILE مع ملف مركّب بوصفه سرًا في ⁨Docker⁩ أو ⁨Kubernetes.⁩ يفضّل الخادم مخزن ملفات يدعم إعادة التحميل السريعة، فتدور المفاتيح دون إعادة تشغيل. راجع /⁨connect/security-and-operations/.⁩
إنّ temp_directory هو المجلد الأساسي المفروض على إخراج الملفات. يحوّل الخادم مسارات الإخراج إلى صيغتها القانونية ويرفض أي مسار يحل خارجه.

المطابقة

تصف هذه الصفحة آليات التهيئة. أمّا استشهادات امتثال المصادقة وأمان النقل فمثبتة في /⁨connect/security-and-operations/.⁩

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

تنطبق الحدود القصوى للحمولة والمهلة حسب الفئة (corePayloadLimit، وproPayloadLimit، وenterprisePayloadLimit، والمهلات المقابلة) على نقل ⁨REST⁩ وفقًا لفئة مفتاح ⁨API⁩ المصادَق عليه. ولا تسري إلا حين تكون أدوات ⁨Pro⁩ أو ⁨Enterprise⁩ مثبتة ويكون المفتاح مخولًا لها.

انظر أيضًا

/⁨connect/install/⁩ — التثبيت والحزم الاختيارية
/⁨connect/boot-and-discovery/⁩ — كيف تدخل التهيئة في تسلسل الإقلاع
/⁨connect/hitl-risk-tiers/⁩ — نموذج المخاطر وتجاوزات الترقية فقط
/⁨connect/security-and-operations/⁩ — تهيئة مفاتيح ⁨API⁩ وأمان النقل
/⁨connect/deployment/⁩ — عدد العمّال و⁨Redis⁩ والحدود القصوى للفئات في الإنتاج