نشر NextPDF Connect

لمحة سريعة

تعمل وسيلتا النقل ⁨REST⁩ و⁨gRPC⁩ ضمن تجمعات عمال ⁨RoadRunner.⁩ وتتضمن الحزمة ثلاثة ملفات تعريف لـ ⁨RoadRunner⁩: ⁨HTTP⁩ فقط، و⁨gRPC⁩ فقط، وملف تعريف مدمج. أمّا وسيلة النقل ⁨MCP⁩ فتعمل كعملية فرعية عادية ولا تحتاج إلى مشرف.

التثبيت

composer require nextpdf/server
./vendor/bin/rr get-binary

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

يُعدّ ⁨RoadRunner⁩ مشرف العمليات. فهو يمتلك تجمع العمال، ويعيد تشغيل العمال عند ضغط الذاكرة، ويوجّه كل طلب إلى عامل متاح. توفّر حزمة ⁨PHP⁩ نقطة دخول العامل: bin/nextpdf-server لـ ⁨HTTP⁩، وbin/nextpdf-grpc لـ ⁨gRPC.⁩ ويغلّف ⁨RoadRunner⁩ نقطة الدخول هذه بتجمع. يعالج كل عامل طلبًا واحدًا في كل مرة.

تعمل وسيلة النقل ⁨MCP⁩ بطريقة مختلفة. bin/nextpdf-mcp هو عملية ⁨PHP⁩ واحدة. ويتواصل عبر ⁨JSON-RPC⁩ على ⁨stdio⁩، ويبدأه العميل مباشرةً.

واجهة ⁨API⁩

ملفات تعريف ⁨RoadRunner⁩

ملف التعريف	وسائل النقل	الأمر
`.rr.yaml`	⁨REST⁩ فقط	`rr serve -c .rr.yaml`
`.rr.grpc.yaml`	⁨gRPC⁩ فقط	`rr serve -c .rr.grpc.yaml`
`.rr.full.yaml`	⁨REST⁩ + ⁨gRPC⁩	`rr serve -c .rr.full.yaml`

يربط ملف تعريف ⁨HTTP⁩ مستمع ⁨REST⁩ بالعنوان 0.0.0.0:8080. ويعرض نقطة نهاية الحالة على :2114 والمقاييس على :2112. كما يحدّد حجم تجمع العمال من NEXTPDF_WORKER_COUNT، وقيمته الافتراضية أربعة. في ملفات التعريف المرفقة، يقيّد المشرف كل عامل بـ 256 ⁨MB.⁩

يضيف ملف التعريف المدمج تجمع عمال ⁨gRPC⁩ على tcp://0.0.0.0:9090. ويحدّد حجم ذلك التجمع من NEXTPDF_GRPC_WORKER_COUNT، وقيمته الافتراضية اثنان. كما يهيّئ طبقة ⁨TLS⁩ المتبادلة في ⁨gRPC.⁩

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

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

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

شغّل حاوية إنتاج باستخدام ملف التعريف المدمج، والمفاتيح المستندة إلى ملفات، والمخازن المشتركة المدعومة بـ ⁨Redis⁩:

services:
  nextpdf-connect:
    image: ghcr.io/nextpdf-labs/server:latest
    command: ["rr", "serve", "-c", "/app/.rr.full.yaml"]
    ports:
      - "8080:8080"   # REST
      - "9090:9090"   # gRPC
    environment:
      - NEXTPDF_API_KEYS_FILE=/run/secrets/api-keys
      - NEXTPDF_WORKER_COUNT=8
      - NEXTPDF_GRPC_WORKER_COUNT=4
      - NEXTPDF_REDIS_HOST=redis
    secrets:
      - api-keys
    depends_on:
      redis:
        condition: service_healthy
    restart: unless-stopped
  redis:
    image: redis:8

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

المخازن في الذاكرة لا تمتد عبر العمال. بدون ⁨Redis⁩، يحتفظ كل عامل بمخازنه الخاصة لحدّ المعدل والتكرار الآمن والمستندات. في تجمع متعدد العمال، تؤدي المخازن في الذاكرة إلى تطبيق غير متسق لحدّ المعدل وقد تفقد المستندات عبر العمال. لأي تجمع أكبر من عامل واحد، اضبط NEXTPDF_REDIS_HOST وثبّت ext-redis. يتراجع الخادم تلقائيًا إلى المخازن في الذاكرة إذا فشل اتصال ⁨Redis.⁩ تحقّق من سلامة ⁨Redis⁩؛ ولا تفترضها.
مخزن المهام هو ⁨SQLite⁩ في وضع ⁨WAL.⁩ تُحفظ المهام غير المتزامنة في ملف ⁨SQLite⁩ واحد يتشاركه جميع عمال ⁨HTTP⁩ و⁨gRPC.⁩ ضع ذلك الملف على وحدة تخزين يمكن لجميع العمال الكتابة إليها. عند إيقاف تشغيل عامل، يضع قدر المستطاع علامة فشل على مهامه التي لا تزال قيد التشغيل، حتى لا تُترك تلك المهام يتيمة.
bin/nextpdf-prune هو نقطة دخول للصيانة. وهو مرفق في المستودع، وليس في vendor/bin/. استدعِه مباشرةً لمهام تقليم المخازن. وهو ليس وسيلة نقل للخادم.
قد لا تحتوي نسخة ⁨PHP⁩ في الصورة على ext-redis. يحاول ملف ⁨Dockerfile⁩ المرفق بناء ext-redis عندما يكون ذلك ممكنًا. ويتابع دون الامتداد إذا لم يوجد إصدار متوافق مع ⁨PHP⁩ الأساسي. تأكّد من وجود الامتداد في الصورة قيد التشغيل قبل أن تعتمد على المخازن المدعومة بـ ⁨Redis.⁩

الأداء

اضبط NEXTPDF_WORKER_COUNT بما يتناسب مع وحدة المعالجة المركزية والذاكرة المتاحة. كل عامل هو عملية ⁨PHP⁩ محدودة بسقف الذاكرة الذي يضعه المشرف. مع الأحمال كثيفة العرض، ابدأ بعامل واحد لكل نواة، ثم اضبط بالاستناد إلى نقطة نهاية المقاييس. حدّد حجم تجمع ⁨gRPC⁩ بشكل مستقل. وهو عادةً أصغر من تجمع ⁨HTTP⁩، لأن عملاء ⁨gRPC⁩ أقل عددًا وأطول عمرًا في العادة.

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

طبقة ⁨TLS⁩ المتبادلة في ⁨gRPC⁩

يهيّئ ملف التعريف المدمج وسيلة النقل ⁨gRPC⁩ لأمان طبقة النقل المتبادل (⁨TLS⁩): يقدّم الخادم شهادة، ثم يطلب شهادة عميل ويتحقق منها. قدّم مفتاح الخادم وشهادة الخادم ومرجع التصديق للعميل بصفتها أسرار نشر، لا مواد مضمّنة داخل الصورة. أنشئها وناوبها خارج النطاق؛ ولا تشغّل وسيلة النقل ⁨gRPC⁩ بمستمع نصي صِرف على شبكة غير موثوقة.

إنهاء ⁨TLS⁩ لـ ⁨REST⁩

يربط ملف تعريف ⁨REST⁩ مستمع ⁨HTTP⁩ نصيًّا صِرفًا. أنهِ ⁨TLS⁩ أمامه باستخدام وكيل عكسي أو موازِن أحمال أو شبكة خدمات، واربط المستمع بالشبكة الداخلية فقط. مرّر هوية العميل عبر ترويسة Authorization دون تغيير؛ فالخادم يتحقق من المفاتيح بنفسه. لا يوفّر المستمع نقلًا آمنًا بمفرده؛ بل تهيئة النشر هذه هي التي توفّره.

الأسرار

حمّل مفاتيح ⁨API⁩ باستخدام NEXTPDF_API_KEYS_FILE للإشارة إلى ملف سري بدلًا من استخدام المتغير المضمّن NEXTPDF_API_KEYS. يُعيد المخزن المستند إلى الملفات التحميل فوريًّا عند التغيير، لذا لا تتطلب المناوبة إعادة تشغيل. لا تضمّن المفاتيح أو المواد الخاصة بـ ⁨TLS⁩ داخل الصورة أبدًا. راجع /⁨connect/security-and-operations/.⁩

المطابقة

لا تطرح آليات النشر أي ادعاءات معيارية بشأن البروتوكول. استشهادات المصادقة وأمان النقل مثبتة في /⁨connect/security-and-operations/.⁩

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

ثبّت nextpdf/premium في الصورة لتسجيل أدوات ⁨Pro⁩ و⁨Enterprise⁩ الإضافية داخل العمال أنفسهم. ولا تدخل في ذلك أي عملية أو منفذ منفصل. أنت تحدّد حدود التحزيم وقت بناء الصورة.

انظر أيضًا

/⁨connect/configuration/⁩ — عدد العمال و⁨Redis⁩ وحدود مستويات الخدمة
/⁨connect/security-and-operations/⁩ — ⁨TLS⁩ وطبقة ⁨TLS⁩ المتبادلة والأسرار ونموذج التهديد
/⁨transports/rest/⁩ · /⁨transports/grpc/⁩ — تفاصيل وقت التشغيل لكل وسيلة نقل
/⁨connect/production-usage/⁩ — فحوص السلامة والتوسّع وقابلية المراقبة
/⁨connect/troubleshooting/⁩ — تشخيص أعطال العمال والمخازن والمصادقة