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

لمحة سريعة

عند نشر ⁨NextPDF Connect⁩ في الإنتاج، تتوفر لك ضوابط تشغيلية متعددة: فحوص السلامة والجاهزية، ومسارات التصيير المتزامنة وغير المتزامنة، وعدم التكرار، وحدود معدل لكل عميل ولكل عنوان بروتوكول إنترنت (⁨IP⁩)، وجلسات اختيارية تحتفظ بالحالة. استخدم هذه الصفحة لضبطها بسلوك يمكن التنبؤ به.

التثبيت

composer require nextpdf/server

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

يعمل ناقل نقل الحالة التمثيلية (⁨REST⁩) كخط معالجة وسيطة (⁨middleware⁩) وفق توصية معايير ⁨PHP⁩ رقم (⁨PSR⁩)-15. يمرّ كل طلب عبر الوسيطات بالترتيب: تعيين معرّف الطلب، وحدود حجم المتن، ومشاركة الموارد عبر الأصول (⁨CORS⁩)، والمصادقة، وتفويض الإمكانات، وتحديد المعدل، وعدم التكرار، والمهلة. ثم يصل الطلب إلى المعالِج. ويعيد ناقل ⁨gRPC⁩ استخدام خدمات التطبيق نفسها خلف عامل ⁨gRPC⁩ الخاص بـ ⁨RoadRunner.⁩

للتصيير مساران. ينفّذ الطلب المتزامن POST /api/v1/render العمليات ويعيد ملف تنسيق المستندات المحمولة (⁨PDF⁩) في الاستجابة. وتستخدم المهمة غير المتزامنة POST /api/v1/jobs. يعيد هذا الطلب معرّف مهمة فورًا، وتجلب النتيجة لاحقًا من GET /api/v1/jobs/{id}/result. تبقى المهام محفوظة في مخزن ⁨SQLite⁩ مشترك، بحيث يمكن لأي عامل الرد على استعلام حالة أو نتيجة.

واجهة ⁨API⁩

السلامة والجاهزية

نقطة النهاية	المصادقة	المعنى
`GET /healthz`	لا شيء	العملية قيد التشغيل
`GET /readyz`	لا شيء	الخادم جاهز لقبول الطلبات

اربط /healthz بفحص نشاط (⁨liveness⁩) و/readyz بفحص جاهزية (⁨readiness⁩). لا تتطلب أي من نقطتي النهاية مصادقة، لذا لا تحتاج أدوات التنسيق (⁨orchestrators⁩) إلى بيانات اعتماد.

المهام غير المتزامنة

نقطة النهاية	الطريقة	الغرض
`/api/v1/jobs`	`POST`	إرسال مهمة تصيير
`/api/v1/jobs/{id}`	`GET`	حالة المهمة
`/api/v1/jobs/{id}/result`	`GET`	نتيجة المهمة (ملف ⁨PDF⁩)
`/api/v1/jobs/{id}`	`DELETE`	إلغاء مهمة

الجلسات (بالاشتراك الاختياري)

عندما تكون قيمة NEXTPDF_SESSIONS_ENABLED هي true والأدوات متاحة، توفّر نقاط نهاية الجلسة سير عمل للبناء يحتفظ بالحالة. أنشئ جلسة، وأضف صفحات ونصوصًا وصورًا وجداول ولغة ترميز النص التشعبي (⁨HTML⁩)، وحدّد الخط، ثم صيّر. للجلسات حدّ أقصى لكل عميل ومهلة خمول. وهي معطّلة افتراضيًا.

عيّنة شيفرة — بداية سريعة

أرسل مهمة غير متزامنة واستعلم دوريًا عن النتيجة:

JOB=$(curl -sS -X POST http://localhost:8080/api/v1/jobs \
  -H "Authorization: Bearer $NEXTPDF_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"operations":[{"type":"add_text","text":"async render"}]}' \
  | python3 -c 'import sys,json;print(json.load(sys.stdin)["id"])')

curl -sS "http://localhost:8080/api/v1/jobs/$JOB/result" \
  -H "Authorization: Bearer $NEXTPDF_KEY" --output out.pdf

عيّنة شيفرة — الإنتاج

اجعل الإرسال آمنًا عند إعادة المحاولة بإرسال مفتاح عدم تكرار (⁨idempotency key⁩):

curl -sS -X POST http://localhost:8080/api/v1/jobs \
  -H "Authorization: Bearer $NEXTPDF_KEY" \
  -H 'Idempotency-Key: 7b1c2d3e-…' \
  -H 'Content-Type: application/json' \
  -d '{"operations":[{"type":"add_text","text":"safe retry"}]}'

الطلب الذي يُعاد إرساله بمفتاح عدم التكرار نفسه يعيد النتيجة الأصلية بدلًا من إنشاء مهمة ثانية. وبذلك يصبح الإرسال قابلًا لإعادة المحاولة بأمان بعد فشل الاتصال. ويتوافق ذلك مع خاصية الطريقة عديمة التكرار: فإرسال الطلب نفسه مرة أخرى يحقق الأثر المقصود نفسه لإرساله مرة واحدة (⁨RFC 9110⁩ §9.2.2). لذلك يمكن إعادة محاولة الطلب تلقائيًا إذا انقطع الاتصال قبل أن يقرأ العميل الاستجابة (⁨RFC 9110⁩ §9.2.2).

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

يتطلب تحديد المعدل ⁨Redis⁩ ليعمل بدقة عبر العمّال. يستخدم محدِّدا المعدل، لكل عميل ولكل ⁨IP⁩، المخزن المُعدّ. عند استخدام المخزن في الذاكرة مع أكثر من عامل واحد، يحسب كل عامل الطلبات بشكل مستقل، فيتضاعف الحدّ الفعلي بعدد العمّال. استخدم مخزن ⁨Redis⁩ لأي تجمّع متعدد العمّال.
يعيد الطلب المقيَّد بالمعدل 429. عند تجاوز حدّ ما، يستجيب الخادم بـ 429 Too Many Requests مع ترويسة Retry-After، اتباعًا لدلالات حالة تحديد المعدل (⁨RFC 6585⁩ §4). التزم بـ Retry-After؛ لا تعد المحاولة فورًا.
نتائج المهام ليست دائمة. يجمع مخزن المهام المهملات بإزالة الإدخالات القديمة بعد NEXTPDF_JOB_GC_MAX_AGE_SECONDS. اجلب النتائج قبل أن تنتهي صلاحيتها.
الجلسات تستهلك الذاكرة. تحتفظ الجلسة بمستند قيد الإنشاء. يحدّ الحدّ الأقصى للجلسات لكل عميل ومهلة الخمول من هذه التكلفة. لا ترفعهما من دون حساب حجم الذاكرة وفق أسوأ الحالات.

الأداء

يحجز المسار المتزامن عاملًا طوال مدة التصيير الكاملة. لعمليات التصيير الكبيرة أو البطيئة، استخدم مسار المهام غير المتزامنة. فهو يحرّر العامل فورًا، ويستعلم العميل دوريًا عن النتيجة. حدّد حجم تجمّع العمّال وفق زمن استجابة التصيير والتزامن المرصودين. راقب نقطة نهاية مقاييس ⁨RoadRunner.⁩

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

تتطلّب كل نقطة نهاية، باستثناء فحوص السلامة، مفتاح واجهة برمجة التطبيقات (⁨API⁩) صالحًا. تتحكّم فئة العميل في العمليات وأحجام الحمولة المسموح بها. يوفّر العملاء مفاتيح عدم التكرار. تعامل مع كل مفتاح بوصفه قيمة مبهمة وفريدة لعملية منطقية واحدة. راجع /⁨connect/security-and-operations/.⁩

المطابقة

الادعاء	المصدر	`reference_id`
عديم التكرار: الطلبات المتكررة = أثر واحد	⁨RFC 9110⁩ §9.2.2
الطلبات عديمة التكرار قابلة لإعادة المحاولة بعد الفشل	⁨RFC 9110⁩ §9.2.2
`429` + `Retry-After` لتحديد المعدل	⁨RFC 6585⁩ §4

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

تحصل مفاتيح ⁨Pro⁩ و⁨Enterprise⁩ على حدود قصوى أعلى للحمولة والمهلة لكل فئة عند تثبيت تلك الأدوات. يستخدم النشر الافتراضي حدود فئة ⁨core⁩ القصوى.

انظر أيضًا

/⁨connect/deployment/⁩ — تجمّعات العمّال، و⁨Redis⁩، وملفّات تعريف ⁨RoadRunner⁩
/⁨transports/rest/⁩ — خط معالجة الوسيطة الكامل وعقد ⁨OpenAPI⁩
/⁨connect/troubleshooting/⁩ — تشخيص 401/403/413/429/5⁨xx⁩ وأعطال المخزن
/⁨connect/security-and-operations/⁩ — المصادقة ووضع تحديد المعدل