SaaS

لمحة سريعة

يوفّر ⁨NextPDF Enterprise⁩ اللبنات الأساسية لنشر ⁨SaaS⁩ متعدّد المستأجِرين: سياق مستأجِر ثابت، ومفاتيح ⁨API⁩ ذات نطاق بمجموع اختباري وتحقّق آمن زمنيًا، وفحص حصّة سابق للطلب بسلوك 80%/100%، ومزامنة قياس قائمة على السحب إلى مزوّد فوترة خارجي. تصف هذه الصفحة السلوك القابل للملاحظة والعقد العام.

التوفّر والترخيص

تُشحَن هذه القدرة في ⁨NextPDF Enterprise⁩ (nextpdf/enterprise) وتُفعَّل بمظروف ترخيص من فئة ⁨Enterprise⁩. لا يُحمّل النشرُ الذي يفتقر إلى هذا الاستحقاق أصنافَ القدرة. قارن الإصدارات واحصل على ترخيص.

سطح تعدّدية المستأجِرين في ⁨SaaS⁩ قدرة أساسية في ⁨Enterprise⁩، تتوفّر بمجرّد تثبيت الحزمة؛ ولا يوجد علم منفصل لكل ميزة.

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

يُمثَّل المستأجِر بسياق مستأجِر ثابت: معرّف مستأجِر، والمصدر الذي حلّه (رمز، أو ⁨mutual-TLS⁩، أو مفتاح ⁨API⁩)، ومجموعة من النطاقات المُصرَّح بها. تُحلّ هوية المستأجِر دائمًا من السياق المُصادَق عليه — لا من ترويسة أو معامل استعلام يزوّدهما العميل أبدًا. يستخدم النشر أحادي المستأجِر سياقًا افتراضيًا ثابتًا بنطاقات كاملة.

تحمل مفاتيح ⁨API⁩ بادئة مقروءة تميّز الإنتاج عن الرمل التجريبي، وجسمًا عشوائيًا عالي العشوائية، ومجموعًا اختباريًا قصيرًا. المجموع الاختباري وسيلة راحة سريعة لرفض الأخطاء الطباعية، لا آليّة أمنية — فهو يتيح رفض مفتاح مُشوَّه قبل أي بحث في مخزن البيانات. تتحقّق المصادقة من المجموع الاختباري، وتُجزِّئ المفتاح بـ ⁨SHA-256⁩، وتبحث عن التجزئة في مستودع، وترفض المفاتيح غير المعروفة أو المُبطَلة أو المنتهية. لا تُسجَّل المفاتيح ولا تُخزَّن بنص صريح أبدًا، والقيمة المخزَّنة هي التجزئة. فرض النطاق صريح: يمكن اشتراط أن يحمل سياقٌ نطاقًا معطى.

يعمل فاحص الحصّة قبل أن يمضي الطلب. يقرأ استخدام المستأجِر في الفترة الحالية، ويحذّر عند الحدّ المرن (80%) من خلال ردّ نداء تنبيه يزوّده المستدعي، ويرفض عند الحدّ الصارم (100%) بحالة تجاوز الحصّة تحمل لحظة إعادة التعيين. إعادة تعيين الفترة هي حدّ الشهر التالي بالتوقيت ⁨UTC⁩.

يسحب مُحوِّل مزامنة القياس أحداث الاستخدام من مصدر الاستخدام الموثوق للنشر، ويحوّلها إلى شكل حدث العدّاد لدى مزوّد الفوترة بمفتاح حياديّة تكرار مستقرّ، ويرسلها. تُوجَّه الأحداث المُخفِقة إلى ردّ نداء الرسائل المهملة، ويتتبّع المُزامِن مؤشّرًا لكل مصدر بحيث تستأنف دورة المزامنة من حيث توقّفت السابقة. تكامل مزوّد الفوترة واجهة، لذا فإن المزوّد قابل للاستبدال.

لماذا يعمل بهذه الطريقة

القرار الحامل هو أن ⁨NextPDF⁩ يشحن أوّليّات فرض، لا منصّة مُستضافة. إن TenantContext، وApiKeyAuthenticator، وQuotaChecker، ومُحوِّل مزامنة القياس عقودٌ يوصّلها نشرُك إلى مخازنه الخاصة. تُحلّ هوية المستأجِر من السياق المُصادَق عليه فقط، فلا يمكن لعميل أبدًا أن يؤكّد مستأجِره الخاص عبر ترويسة. تعيش المفاتيح في مستودعك كتجزئات ⁨SHA-256⁩، ويقرأ فحص الحصّة مصدر استخدامك، ومزوّد الفوترة واجهة قابلة للاستبدال. لا يحفظ ⁨NextPDF⁩ شيئًا، فتبقى بيانات المستأجِر والمفاتيح والفوترة تحت سيطرتك. ولأن السطح يُحلّ عبر عقد ⁨Core⁩، تعمل الشيفرة المُستدعية نفسها على ⁨Core⁩ أو ⁨Pro⁩ أو ⁨Enterprise⁩ — ولا تعيد ترقية الإصدار كتابة شيفرة التكامل أبدًا.

خلفية التصميم: النواة المفتوحة، دون احتجاز.

سطح الـ ⁨API⁩ العام

composer require nextpdf/enterprise:^3

نقاط التكامل المدعومة هي سياق المستأجِر (hasScope، وhasAnyScope، وsingleTenant)، ومولّد مفتاح الـ ⁨API⁩ (generateLive، وgenerateTest، وvalidateChecksum، وhashKey، وisLiveKey، وisTestKey)، ومُصادِق مفتاح الـ ⁨API⁩ (authenticate، وrequireScope)، وواجهة مستودع مفتاح الـ ⁨API⁩، وفاحص الحصّة (check)، وكائن قيمة حصّة المستأجِر، وواجهة مُحوِّل مزامنة القياس. وفّر تنفيذات مستودع ومُحوِّل فوترة دائمة للإنتاج.

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

use NextPDF\Enterprise\SaaS\ApiKey\ApiKeyAuthenticator;
use NextPDF\Enterprise\SaaS\ApiKey\ApiKeyScope;

$tenant = $authenticator->authenticate($request->header('X-API-Key'));
$authenticator->requireScope($tenant, ApiKeyScope::Write);

// $tenant->tenantId is now safe to use as the billing/metering subject.

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

use NextPDF\Enterprise\SaaS\Quota\QuotaChecker;
use NextPDF\Enterprise\SaaS\Quota\QuotaExceededException;

$checker = new QuotaChecker($usageMeter, $logger, $alertCallback);

try {
    $status = $checker->check($tenant, $tenantQuota);
    if ($status['warning_percentage'] !== null) {
        $response = $response->withHeader('X-Quota-Warning', (string) $status['warning_percentage']);
    }
} catch (QuotaExceededException $e) {
    return $this->quotaExceeded($e->resetsAt); // 100% — reject with reset instant
}

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

• المجموع الاختباري ليس أمنًا. المجموع الاختباري الناجح يعني فقط أن المفتاح حسن التكوين؛ ولا تزال المصادقة تُجزِّئه وتبحث عنه وتفرض الإبطال والانتهاء.
• مقارنة آمنة زمنيًا. يستخدم التحقق من المفتاح مقارنة بزمن ثابت؛ لا تُعِد إدخال مقارنة سلاسل قصيرة الدارة في مُغلِّف.
• منشأ هوية المستأجِر. لا تبنِ سياق مستأجِر من ترويسة أو قيمة استعلام يزوّدهما العميل أبدًا؛ حُلّه من السياق المُصادَق عليه فقط.
• تحذير الحصّة مقابل الرفض. 80% يحذّر ويترك الطلب يمضي (مع نسبة تحذير)؛ و100% يرفض مع لحظة إعادة التعيين. وينبغي لردّ نداء التنبيه أن يزيل التكرار لكل فترة.
• مرونة المزامنة. يُعيد إخفاق سحب مزامنة القياس دورة بلا عمل ويحفظ المؤشّر؛ وتذهب الأحداث الفردية المُخفِقة إلى ردّ نداء الرسائل المهملة بدلًا من حجب الدورة.

الأداء

فحوصات سياق المستأجِر والتحقق من المجموع الاختباري في زمن ثابت. تكلفة المصادقة تجزئة واحدة إضافةً إلى بحث واحد في المستودع. وتكلفة فحص الحصّة قراءة استخدام واحدة إضافةً إلى حساب في زمن ثابت. مزامنة القياس عملية دُفعية تُشغَّل وفق جدول، خارج مسار الطلب.

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

تُخزَّن مفاتيح الـ ⁨API⁩ كتجزئات ⁨SHA-256⁩ فقط ولا تُسجَّل بنص صريح أبدًا؛ والتحقق آمن زمنيًا؛ وتُرفض المفاتيح المُبطَلة والمنتهية بنتائج متمايزة. يجب أن تأتي هوية المستأجِر من السياق المُصادَق عليه. تحمل الرموز الخدمية القصيرة العمر المسكوكة للاستدعاءات بين المكوّنات الادعاءات المُسجَّلة القياسية وانتهاءً قصيرًا. تصف هذه الصفحة السلوك فقط؛ وأجزاء التحقّق من الرمز الداخلية ليست جزءًا من العقد العام.

المطابقة

• تحمل الرموز الخدمية بين المكوّنات الادعاءات المُسجَّلة iss، وaud، وsub، وexp، وjti وتحترم قاعدة exp (لا بعد) وفق ⁨RFC 7519⁩ (⁨JWT⁩)، §4.1.4.
• تستخدم الرموز الخدمية ثلاثي التسلسل المُدمَج لـ ⁨JWS⁩ وفق ⁨RFC 7515⁩ (⁨JSON Web Signature⁩)، §3.1.
• تُخزَّن مفاتيح الـ ⁨API⁩ كملخّصات ⁨SHA-256⁩ (⁨FIPS 180-4 SHA-256⁩). ملاحظة: لم يُستجلَب ⁨FIPS 180-4⁩ من مجموعة ⁨RAG⁩ لهذه الصفحة؛ والخوارزمية مُعلَنة في الشيفرة (hash('sha256', …)) وموسومة هنا بأنها مُعلَنة في الشيفرة لا متحقَّق منها عبر ⁨RAG⁩.

عقد السلوك

• المستأجِر سياق ثابت (معرّف المستأجِر، ومصدر الحلّ، والنطاقات المُصرَّح بها)؛ وتُحلّ الهوية دائمًا من السياق المُصادَق عليه، لا من ترويسة أو قيمة استعلام يزوّدهما العميل.
• تتحقّق مصادقة مفتاح الـ ⁨API⁩ من المجموع الاختباري، وتُجزِّئ بـ ⁨SHA-256⁩، وتبحث عن التجزئة، وترفض المفاتيح غير المعروفة أو المُبطَلة أو المنتهية بنتائج متمايزة؛ والمفاتيح لا تُسجَّل ولا تُخزَّن بنص صريح أبدًا والتحقق آمن زمنيًا.
• يحذّر فاحص الحصّة عند 80% من خلال ردّ النداء الذي يزوّده المستدعي ويرفض عند 100% بحالة تجاوز الحصّة تحمل لحظة إعادة التعيين (حدّ الشهر التالي، ⁨UTC⁩).
• يُعيد إخفاق سحب مزامنة القياس دورة بلا عمل ويحفظ المؤشّر لكل مصدر؛ وتُوجَّه الأحداث الفردية المُخفِقة إلى ردّ نداء الرسائل المهملة بدلًا من حجب الدورة.
• المجموع الاختباري وسيلة راحة لرفض الأخطاء الطباعية، لا آليّة أمنية.

حدود النشر

تُوثِّق هذه الصفحة السلوك القابل للملاحظة خارجيًا والسطح العام المدعوم للـ ⁨API⁩ فقط. أما مسارات فضاء الأسماء الداخلية، والأصناف المساعِدة، وجداول الآليات، وأسماء ملفات دليل التشغيل، وبادئات التذاكر فخارجة عن النطاق.

الاحتياط في ⁨Core⁩

لا يملك ⁨NextPDF Core⁩ (⁨Apache-2.0⁩) أي سطح للمستأجِرين أو مفتاح ⁨API⁩ أو حصّة — لا شيء؛ وليس لهذه القدرة أي مكافئ على مستوى ⁨Core⁩.

الاحتياط في ⁨Pro⁩

لا يملك ⁨NextPDF Pro⁩ أي سطح للمستأجِرين أو مفتاح ⁨API⁩ أو حصّة — لا شيء؛ وليس لهذه القدرة أي مكافئ على مستوى ⁨Pro⁩. يُشحَن سياق المستأجِر، ومصادقة مفتاح الـ ⁨API⁩، وفاحص الحصّة، ومُحوِّل مزامنة القياس في حزمة nextpdf/enterprise فقط.

ملاحظة حدود ⁨Enterprise⁩

يُوصَف توليد مفتاح الـ ⁨API⁩، والمجموع الاختباري، والتحقق الآمن زمنيًا على مستوى السلوك. أما أجزاء التحقّق من الرمز الداخلية، واستراتيجية تخزين تجزئة المفتاح، وأجزاء مُحوِّل مزوّد الفوترة الداخلية فخارجة عن نطاق السطح العام؛ وتكامل مزوّد الفوترة واجهة وقابل للاستبدال.

حدود النشر التشغيلي

يملك المشغِّل مستودع مفتاح الـ ⁨API⁩، وتنفيذ مُحوِّل مزوّد الفوترة، ومصدر الاستخدام الموثوق الذي يقرؤه فاحص الحصّة ومزامنة القياس، وإزالة تكرار ردّ نداء التنبيه. يجب أن تنشأ هوية المستأجِر من السياق المُصادَق عليه الذي يهيّئه المشغِّل (رمز، أو ⁨mutual-TLS⁩، أو مفتاح ⁨API⁩). لا يحفظ ⁨NextPDF Enterprise⁩ بنفسه المفاتيح ولا الاستخدام.

حدود الامتثال القانوني

لا تنطبق أي قيود لضوابط التصدير على سطح ⁨SaaS⁩. قد تكون مفاتيح الـ ⁨API⁩ ومعرّفات المستأجِرين حسّاسة؛ ونطاق التخزين والاحتفاظ مسؤولية امتثال المشغِّل. هذه الوثائق ليست رأيًا قانونيًا؛ استشر مستشاري الامتثال والشؤون القانونية لديك.

انظر أيضًا

• الفوترة — ⁨NextPDF Enterprise⁩
• القياس — ⁨NextPDF Enterprise⁩
• ‏⁨Webhook⁩ — ⁨NextPDF Enterprise⁩
• الترخيص — ⁨NextPDF Enterprise⁩