SaaS

ภาพรวมโดยสังเขป

NextPDF Enterprise มอบส่วนประกอบพื้นฐานสำหรับการปรับใช้แบบ multi-tenant SaaS ได้แก่ tenant context ที่ไม่เปลี่ยนแปลง, API key ที่ขอบเขตด้วย scope พร้อม checksum และการตรวจสอบแบบ timing-safe, การตรวจสอบโควตาก่อนคำขอที่มีพฤติกรรม 80%/100% และ metering sync แบบ pull-based ไปยังผู้ให้บริการ billing ภายนอก หน้านี้อธิบายพฤติกรรมที่สังเกตได้และสัญญาสาธารณะ

ความพร้อมใช้งานและสิทธิ์การใช้งาน

ความสามารถนี้มาใน NextPDF Enterprise (nextpdf/enterprise) และเปิดใช้งานด้วย license envelope ระดับชั้น Enterprise การปรับใช้ที่ไม่มีสิทธิ์ดังกล่าวจะไม่โหลดคลาสของความสามารถนี้ เปรียบเทียบรุ่นและขอรับสิทธิ์การใช้งาน

พื้นผิว multi-tenancy ของ SaaS เป็นความสามารถพื้นฐานของ Enterprise ที่พร้อมใช้งานเมื่อติดตั้งแพ็กเกจ ไม่มีแฟล็กต่อฟีเจอร์แยกต่างหาก

ภาพรวมเชิงแนวคิด

tenant ถูกแทนด้วย tenant context ที่ไม่เปลี่ยนแปลง ได้แก่ tenant identifier, แหล่งที่ resolve มัน (token, mutual-TLS หรือ API key) และชุด scope ที่ได้รับอนุญาต tenant identity ถูก resolve จาก authenticated context เสมอ — ไม่เคยมาจาก header หรือ query parameter ที่ client จัดหา การปรับใช้แบบ single-tenant ใช้ default context ที่กำหนดไว้ตายตัวพร้อม scope เต็ม

API key พา prefix ที่อ่านได้ซึ่งแยก production จาก sandbox, body แบบสุ่มที่มี entropy สูง และ checksum สั้น checksum เป็นความสะดวกในการปฏิเสธการพิมพ์ผิดที่รวดเร็ว ไม่ใช่กลไกความปลอดภัย — มันทำให้คีย์ที่ผิดรูปถูกปฏิเสธก่อนการค้นหาใน datastore ใด ๆ การตรวจสอบสิทธิ์ตรวจสอบ checksum, hash คีย์ด้วย SHA-256, ค้นหา hash ใน repository และปฏิเสธคีย์ที่ไม่รู้จัก ถูกเพิกถอน หรือหมดอายุ คีย์จะไม่ถูกบันทึกหรือจัดเก็บในรูปข้อความธรรมดา และค่าที่จัดเก็บคือ hash การบังคับใช้ scope เป็นแบบชัดแจ้ง คือ context สามารถถูกกำหนดให้ต้องถือ scope ที่ระบุ

ตัวตรวจสอบโควตารันก่อนคำขอดำเนินต่อ มันอ่านการใช้งานในรอบปัจจุบันของ tenant เตือนที่ soft limit (80%) ผ่าน alert callback ที่ผู้เรียกใช้จัดหา และปฏิเสธที่ hard limit (100%) ด้วยเงื่อนไข quota-exceeded ที่พาช่วงเวลารีเซ็ตมาด้วย การรีเซ็ตรอบคือขอบเขตเดือนถัดไปในเวลา UTC

metering-sync adapter pull เหตุการณ์การใช้งานจากแหล่งการใช้งานที่เชื่อถือได้ของการปรับใช้ แปลงเป็นรูปร่าง meter-event ของผู้ให้บริการ billing พร้อม idempotency key ที่เสถียร และส่งออกไป เหตุการณ์ที่ล้มเหลวถูกกำหนดเส้นทางไปยัง dead-letter callback และตัว sync ติดตาม cursor ต่อแหล่งเพื่อให้รอบ sync กลับมาทำต่อจากที่รอบก่อนหยุด การผสานรวมผู้ให้บริการ billing เป็น interface ดังนั้นผู้ให้บริการจึงสลับเปลี่ยนได้

ทำไมจึงทำงานแบบนี้

การตัดสินใจที่สำคัญคือ NextPDF ส่งมอบ enforcement primitive ไม่ใช่แพลตฟอร์มแบบ hosted TenantContext, ApiKeyAuthenticator, QuotaChecker และ metering-sync adapter เป็นสัญญาที่การปรับใช้ของคุณเชื่อมต่อกับ store ของตัวเอง tenant identity resolve จาก authenticated context เท่านั้น ดังนั้น client จึงไม่มีทางยืนยัน tenant ของตัวเองผ่าน header คีย์อยู่ใน repository ของคุณในรูป hash SHA-256, โควตาอ่านจากแหล่งการใช้งานของคุณ และผู้ให้บริการ billing เป็น interface ที่สลับเปลี่ยนได้ NextPDF ไม่เก็บข้อมูลใด ๆ ดังนั้นข้อมูล tenant, คีย์ และ billing จึงอยู่ภายใต้การควบคุมของคุณ เนื่องจากพื้นผิว resolve ผ่านสัญญาของ Core โค้ดที่เรียกใช้เดียวกันจึงรันบน Core, Pro หรือ Enterprise ได้ — การอัปเกรดรุ่นไม่เคยต้องเขียนโค้ดการผสานรวมใหม่

พื้นหลังการออกแบบ: Open core, ไม่มี lock-in

พื้นผิว API สาธารณะ

composer require nextpdf/enterprise:^3

จุดผสานรวมที่รองรับคือ tenant context (hasScope, hasAnyScope, singleTenant), ตัวสร้าง API-key (generateLive, generateTest, validateChecksum, hashKey, isLiveKey, isTestKey), ตัวตรวจสอบสิทธิ์ API-key (authenticate, requireScope), interface ของ API-key repository, ตัวตรวจสอบโควตา (check), ออบเจกต์ค่า tenant-quota และ interface ของ metering-sync adapter จัดหาการนำไปใช้จริงของ repository และ billing-adapter แบบคงทนสำหรับการใช้งานจริง

ตัวอย่างโค้ด — เริ่มต้นอย่างรวดเร็ว

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
}

กรณีขอบและข้อควรระวัง

• checksum ไม่ใช่ความปลอดภัย checksum ที่ผ่านหมายความเพียงว่าคีย์มีรูปแบบที่ถูกต้อง การตรวจสอบสิทธิ์ยังคง hash และค้นหา และบังคับใช้การเพิกถอนและการหมดอายุ
• การเปรียบเทียบแบบ timing-safe การตรวจสอบคีย์ใช้การเปรียบเทียบในเวลาคงที่ อย่านำการเปรียบเทียบสตริงแบบ short-circuit กลับมาใช้ใน wrapper
• ที่มาของ tenant identity อย่าสร้าง tenant context จากค่า header หรือ query ที่ client จัดหา ให้ resolve จาก authenticated context เท่านั้น
• โควตาเตือนเทียบกับปฏิเสธ 80% เตือนและให้คำขอดำเนินต่อ (พร้อมเปอร์เซ็นต์คำเตือน); 100% ปฏิเสธพร้อมช่วงเวลารีเซ็ต alert callback ควร deduplicate ต่อรอบ
• ความทนทานของการ sync ความล้มเหลวในการ pull ของ metering-sync จะคืนรอบแบบ no-op และรักษา cursor ไว้ เหตุการณ์รายตัวที่ล้มเหลวไปยัง dead-letter callback แทนที่จะปิดกั้นรอบ

ประสิทธิภาพ

การตรวจสอบ tenant-context และการตรวจสอบ checksum เป็นเวลาคงที่ ต้นทุนการตรวจสอบสิทธิ์คือ hash หนึ่งครั้งบวกการค้นหาใน repository หนึ่งครั้ง ต้นทุนการตรวจสอบโควตาคือการอ่านการใช้งานหนึ่งครั้งบวกการคำนวณในเวลาคงที่ metering sync เป็นการดำเนินการแบบ batch ที่รันตามกำหนดเวลา นอกเส้นทางคำขอ

บันทึกด้านความปลอดภัย

API key ถูกจัดเก็บเป็น hash SHA-256 เท่านั้นและไม่เคยถูกบันทึกในรูปข้อความธรรมดา การตรวจสอบเป็นแบบ timing-safe คีย์ที่ถูกเพิกถอนและหมดอายุถูกปฏิเสธด้วยผลลัพธ์ที่แตกต่างกัน tenant identity ต้องมาจาก authenticated context service token อายุสั้นที่สร้างขึ้นสำหรับการเรียกระหว่างคอมโพเนนต์พา registered claims มาตรฐานและการหมดอายุสั้นมาด้วย หน้านี้อธิบายเฉพาะพฤติกรรมเท่านั้น รายละเอียดภายในของการตรวจสอบ token ไม่ใช่ส่วนหนึ่งของสัญญาสาธารณะ

ความสอดคล้อง

• service token ระหว่างคอมโพเนนต์พา registered claims iss, aud, sub, exp และ jti มาด้วย และปฏิบัติตามกฎ not-after ของ exp ของ RFC 7519 (JWT) §4.1.4
• service token ใช้ JWS compact serialization triple ของ RFC 7515 (JSON Web Signature) §3.1
• API key ถูกจัดเก็บเป็นค่าย่อย SHA-256 (FIPS 180-4 SHA-256) หมายเหตุ: FIPS 180-4 ไม่ได้ถูกดึงมาจากคลังข้อมูล RAG สำหรับหน้านี้ อัลกอริทึมประกาศไว้ในโค้ด (hash('sha256', …)) และถูกทำเครื่องหมายในที่นี้ว่าประกาศไว้ในโค้ดแทนที่จะเป็นแบบ RAG-verified

สัญญาพฤติกรรม

• tenant เป็น context ที่ไม่เปลี่ยนแปลง (tenant id, แหล่งที่ resolve, scope ที่ได้รับอนุญาต) identity ถูก resolve จาก authenticated context เสมอ ไม่เคยมาจากค่า header หรือ query ที่ client จัดหา
• การตรวจสอบสิทธิ์ด้วย API-key ตรวจสอบ checksum, hash ด้วย SHA-256, ค้นหา hash และปฏิเสธคีย์ที่ไม่รู้จัก ถูกเพิกถอน หรือหมดอายุด้วยผลลัพธ์ที่แตกต่างกัน คีย์ไม่เคยถูกบันทึกหรือจัดเก็บในรูปข้อความธรรมดา และการตรวจสอบเป็นแบบ timing-safe
• ตัวตรวจสอบโควตาเตือนที่ 80% ผ่าน callback ที่ผู้เรียกใช้จัดหา และปฏิเสธที่ 100% ด้วยเงื่อนไข quota-exceeded ที่พาช่วงเวลารีเซ็ตมาด้วย (ขอบเขตเดือนถัดไป, UTC)
• ความล้มเหลวในการ pull ของ metering-sync จะคืนรอบแบบ no-op และรักษา cursor ต่อแหล่งไว้ เหตุการณ์รายตัวที่ล้มเหลวกำหนดเส้นทางไปยัง dead-letter callback แทนที่จะปิดกั้นรอบ
• checksum เป็นความสะดวกในการปฏิเสธการพิมพ์ผิด ไม่ใช่กลไกความปลอดภัย

ขอบเขตการเผยแพร่

หน้านี้จัดทำเอกสารเฉพาะพฤติกรรมที่สังเกตได้จากภายนอกและพื้นผิว API สาธารณะที่รองรับเท่านั้น เส้นทาง namespace ภายใน, คลาสตัวช่วย, ตารางกลไก, ชื่อไฟล์ runbook และคำนำหน้า ticket อยู่นอกขอบเขต

ทางเลือกสำรองของ Core

NextPDF Core (Apache-2.0) ไม่มีพื้นผิว tenancy, API-key หรือโควตา — ไม่มีเลย ความสามารถนี้ไม่มีสิ่งเทียบเท่าในระดับชั้น Core

ทางเลือกสำรองของ Pro

NextPDF Pro ไม่มีพื้นผิว tenancy, API-key หรือโควตา — ไม่มีเลย ความสามารถนี้ไม่มีสิ่งเทียบเท่าในระดับชั้น Pro tenant context, การตรวจสอบสิทธิ์ด้วย API-key, ตัวตรวจสอบโควตา และ metering-sync adapter มาในแพ็กเกจ nextpdf/enterprise เท่านั้น

หมายเหตุขอบเขตของ Enterprise

การสร้าง API-key, checksum และการตรวจสอบแบบ timing-safe ได้รับการอธิบายในระดับพฤติกรรม รายละเอียดภายในของการตรวจสอบ token, กลยุทธ์การจัดเก็บ key-hash และรายละเอียดภายในของ billing-provider adapter อยู่นอกขอบเขตของพื้นผิวสาธารณะ การผสานรวมผู้ให้บริการ billing เป็น interface และสลับเปลี่ยนได้

ขอบเขตการปรับใช้

ผู้ดำเนินการเป็นเจ้าของ API-key repository, การนำไปใช้จริงของ billing-provider adapter, แหล่งการใช้งานที่เชื่อถือได้ที่ตัวตรวจสอบโควตาและ metering sync อ่าน และการ deduplicate ของ alert-callback tenant identity ต้องมาจาก authenticated context ที่ผู้ดำเนินการกำหนดค่า (token, mutual-TLS หรือ API key) NextPDF Enterprise ไม่ได้เก็บคีย์หรือการใช้งานเอง

ขอบเขตการปฏิบัติตามกฎหมาย

ไม่มีข้อจำกัดด้านการควบคุมการส่งออกที่มีผลกับพื้นผิว SaaS API key และ tenant identifier อาจเป็นข้อมูลอ่อนไหว ขอบเขตการจัดเก็บและการเก็บรักษาเป็นความรับผิดชอบด้านการปฏิบัติตามข้อกำหนดของผู้ดำเนินการ เอกสารนี้ไม่ใช่คำให้ความเห็นทางกฎหมาย โปรดปรึกษาที่ปรึกษาด้านการปฏิบัติตามข้อกำหนดและด้านกฎหมายของคุณเอง

ดูเพิ่มเติม

• Billing — NextPDF Enterprise
• Metering — NextPDF Enterprise
• Webhook — NextPDF Enterprise
• Licensing — NextPDF Enterprise