Enterprise phiên bản

SaaS

Tổng quan nhanh

NextPDF Enterprise cung cấp các khối xây dựng cho một triển khai SaaS đa thuê bao: một tenant context bất biến, các API key có phạm vi cùng checksum và xác minh an toàn về thời gian, một bước kiểm tra hạn mức trước yêu cầu với hành vi 80%/100%, và một đồng bộ đo lường theo kiểu kéo tới một nhà cung cấp lập hóa đơn bên ngoài. Trang này mô tả hành vi có thể quan sát được và hợp đồng công khai.

Tình trạng sẵn có & cấp phép

Năng lực này đi kèm trong NextPDF Enterprise (nextpdf/enterprise) và kích hoạt bằng một phong bì giấy phép bậc Enterprise. Một triển khai không có quyền đó sẽ không nạp các lớp của năng lực này. So sánh các phiên bản và lấy giấy phép.

Bề mặt đa thuê bao SaaS là một năng lực Enterprise cơ sở, sẵn dùng ngay khi gói được cài đặt; không có cờ riêng theo từng tính năng.

Tổng quan khái niệm

Một thuê bao được biểu diễn bởi một tenant context bất biến: một mã định danh thuê bao, nguồn đã phân giải ra nó (một token, mutual-TLS, hoặc một API key), và một tập các scope được cấp phép. Danh tính thuê bao luôn được phân giải từ ngữ cảnh đã xác thực — không bao giờ từ một header hay tham số truy vấn do client cung cấp. Một triển khai đơn thuê bao dùng một context mặc định cố định với đầy đủ scope.

Các API key mang theo một prefix dễ đọc phân biệt production với sandbox, một thân ngẫu nhiên entropy cao, và một checksum ngắn. Checksum là một tiện ích từ chối lỗi gõ nhầm nhanh, không phải một cơ chế bảo mật — nó cho phép một key dị dạng bị từ chối trước bất kỳ tra cứu kho dữ liệu nào. Việc xác thực kiểm tra checksum, băm key bằng SHA-256, tra cứu bản băm trong một repository, và từ chối các key không xác định, đã thu hồi, hoặc đã hết hạn. Các key không bao giờ được ghi nhật ký hay lưu trữ ở dạng văn bản rõ, và giá trị được lưu là bản băm. Việc thực thi scope là tường minh: một context có thể bị yêu cầu phải giữ một scope nhất định.

Bộ kiểm tra hạn mức chạy trước khi một yêu cầu tiếp tục. Nó đọc mức sử dụng của kỳ hiện tại của thuê bao, cảnh báo ở giới hạn mềm (80%) thông qua một callback cảnh báo do bên gọi cung cấp, và từ chối ở giới hạn cứng (100%) với một điều kiện vượt-hạn-mức mang theo thời điểm đặt lại. Việc đặt lại kỳ là ranh giới tháng kế tiếp theo UTC.

Adapter đồng bộ đo lường kéo các sự kiện sử dụng từ nguồn sử dụng có thẩm quyền của triển khai, biến đổi chúng thành hình dạng meter-event của nhà cung cấp lập hóa đơn cùng một khóa bất biến ổn định, và gửi chúng. Các sự kiện thất bại được định tuyến tới một callback dead-letter, và bộ đồng bộ theo dõi một con trỏ theo từng nguồn để một chu kỳ đồng bộ tiếp tục từ nơi chu kỳ trước đã dừng. Việc tích hợp nhà cung cấp lập hóa đơn là một interface, nên nhà cung cấp có thể thay thế.

Vì sao nó hoạt động theo cách này

Quyết định chịu tải là việc NextPDF đi kèm các nguyên thủy thực thi, không phải một nền tảng được lưu trữ. TenantContext, ApiKeyAuthenticator, QuotaChecker, và adapter đồng bộ đo lường là các hợp đồng mà triển khai của bạn nối tới kho lưu trữ của riêng nó. Danh tính thuê bao chỉ phân giải từ ngữ cảnh đã xác thực, nên một client không bao giờ có thể tự khẳng định thuê bao của nó qua một header. Các key nằm trong repository của bạn dưới dạng bản băm SHA-256, hạn mức đọc nguồn sử dụng của bạn, và nhà cung cấp lập hóa đơn là một interface có thể thay thế. NextPDF không lưu trữ gì cả, nên dữ liệu thuê bao, key, và lập hóa đơn vẫn nằm dưới sự kiểm soát của bạn. Vì bề mặt phân giải qua hợp đồng Core, cùng một đoạn mã gọi chạy trên Core, Pro, hoặc Enterprise — một lần nâng cấp phiên bản không bao giờ viết lại mã tích hợp.

Bối cảnh thiết kế: Open core, không khóa nhà cung cấp.

Bề mặt API công khai

composer require nextpdf/enterprise:^3

Các điểm tích hợp được hỗ trợ là tenant context (hasScope, hasAnyScope, singleTenant), bộ sinh API key (generateLive, generateTest, validateChecksum, hashKey, isLiveKey, isTestKey), bộ xác thực API key (authenticate, requireScope), interface repository API key, bộ kiểm tra hạn mức (check), value object tenant-quota, và interface adapter đồng bộ đo lường. Hãy cung cấp các triển khai repository và billing-adapter bền vững cho sản phẩm.

Mẫu mã — Bắt đầu nhanh

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.

Mẫu mã — Sản phẩm

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
}

Trường hợp ngoại lệ & lưu ý

Checksum không phải bảo mật. Một checksum hợp lệ chỉ nghĩa là key đúng định dạng; việc xác thực vẫn băm và tra cứu nó và thực thi thu hồi cùng hết hạn.
So sánh an toàn về thời gian. Việc xác minh key dùng so sánh theo thời gian hằng số; đừng tái đưa vào một phép so sánh chuỗi đoản mạch trong một wrapper.
Nguồn gốc danh tính thuê bao. Đừng bao giờ dựng một tenant context từ một header hay giá trị truy vấn do client cung cấp; chỉ phân giải nó từ ngữ cảnh đã xác thực.
Hạn mức cảnh báo so với từ chối. 80% cảnh báo và để yêu cầu tiếp tục (với một tỷ lệ phần trăm cảnh báo); 100% từ chối với thời điểm đặt lại. Callback cảnh báo nên loại trùng theo từng kỳ.
Khả năng chịu lỗi của đồng bộ. Một lần kéo đồng bộ đo lường thất bại trả về một chu kỳ no-op và giữ nguyên con trỏ; các sự kiện riêng lẻ thất bại đi tới callback dead-letter thay vì chặn chu kỳ.

Hiệu năng

Các bước kiểm tra tenant-context và xác thực checksum là theo thời gian hằng số. Chi phí xác thực là một lần băm cộng một lần tra cứu repository. Chi phí kiểm tra hạn mức là một lần đọc mức sử dụng cộng số học theo thời gian hằng số. Đồng bộ đo lường là một thao tác theo lô chạy theo lịch, nằm ngoài đường yêu cầu.

Lưu ý bảo mật

Các API key chỉ được lưu dưới dạng bản băm SHA-256 và không bao giờ được ghi nhật ký ở dạng văn bản rõ; việc xác minh là an toàn về thời gian; các key đã thu hồi và đã hết hạn bị từ chối với các kết quả riêng biệt. Danh tính thuê bao phải đến từ ngữ cảnh đã xác thực. Các service token ngắn hạn được đúc cho các lệnh gọi giữa các thành phần mang theo các claim đã đăng ký tiêu chuẩn và một hạn ngắn. Trang này chỉ mô tả hành vi; chi tiết nội bộ về xác minh token không thuộc hợp đồng công khai.

Tính phù hợp

Các service token giữa các thành phần mang theo các claim đã đăng ký iss, aud, sub, exp, và jti và tuân thủ quy tắc not-after exp của RFC 7519 (JWT), §4.1.4.
Các service token dùng bộ ba tuần tự hóa nén JWS của RFC 7515 (JSON Web Signature), §3.1.
Các API key được lưu dưới dạng digest SHA-256 (FIPS 180-4 SHA-256). Lưu ý: FIPS 180-4 không được truy xuất từ kho RAG cho trang này; thuật toán được khai báo trong mã (hash('sha256', …)) và được đánh dấu ở đây là khai báo trong mã thay vì đã xác minh bằng RAG.

Hợp đồng hành vi

Một thuê bao là một context bất biến (tenant id, nguồn phân giải, các scope được cấp phép); danh tính luôn được phân giải từ ngữ cảnh đã xác thực, không bao giờ từ một header hay giá trị truy vấn do client cung cấp.
Xác thực API key kiểm tra checksum, băm bằng SHA-256, tra cứu bản băm, và từ chối các key không xác định, đã thu hồi, hoặc đã hết hạn với các kết quả riêng biệt; các key không bao giờ được ghi nhật ký hay lưu trữ ở dạng văn bản rõ và việc xác minh là an toàn về thời gian.
Bộ kiểm tra hạn mức cảnh báo ở 80% thông qua callback do bên gọi cung cấp và từ chối ở 100% với một điều kiện vượt-hạn-mức mang theo thời điểm đặt lại (ranh giới tháng kế tiếp, UTC).
Một lần kéo đồng bộ đo lường thất bại trả về một chu kỳ no-op và giữ nguyên con trỏ theo từng nguồn; các sự kiện riêng lẻ thất bại định tuyến tới callback dead-letter thay vì chặn chu kỳ.
Checksum là một tiện ích từ chối lỗi gõ nhầm, không phải một cơ chế bảo mật.

Ranh giới xuất bản

Trang này chỉ ghi lại hành vi có thể quan sát được từ bên ngoài và bề mặt public API được hỗ trợ. Các đường dẫn namespace nội bộ, các lớp trợ giúp, các bảng cơ chế, các tên tệp runbook, và các tiền tố ticket nằm ngoài phạm vi.

Phương án dự phòng Core

NextPDF Core (Apache-2.0) không có bề mặt thuê bao, API key, hay hạn mức nào — không hề có; năng lực này không có tương đương ở bậc Core.

Phương án dự phòng Pro

NextPDF Pro không có bề mặt thuê bao, API key, hay hạn mức nào — không hề có; năng lực này không có tương đương ở bậc Pro. Tenant context, xác thực API key, bộ kiểm tra hạn mức, và adapter đồng bộ đo lường chỉ đi kèm trong gói nextpdf/enterprise.

Lưu ý về ranh giới Enterprise

Việc sinh API key, checksum, và xác minh an toàn về thời gian được mô tả ở mức hành vi. Chi tiết nội bộ về xác minh token, chiến lược lưu trữ key-hash, và chi tiết nội bộ về adapter nhà cung cấp lập hóa đơn nằm ngoài phạm vi của bề mặt công khai; việc tích hợp nhà cung cấp lập hóa đơn là một interface và có thể thay thế.

Ranh giới triển khai

Người vận hành sở hữu repository API key, triển khai adapter nhà cung cấp lập hóa đơn, nguồn sử dụng có thẩm quyền mà bộ kiểm tra hạn mức và đồng bộ đo lường đọc, và việc loại trùng callback cảnh báo. Danh tính thuê bao phải bắt nguồn từ ngữ cảnh đã xác thực mà người vận hành cấu hình (token, mutual-TLS, hoặc API key). Bản thân NextPDF Enterprise không lưu các key hay mức sử dụng.

Ranh giới tuân thủ pháp lý

Không có hạn chế kiểm soát xuất khẩu nào áp dụng cho bề mặt SaaS. Các API key và mã định danh thuê bao có thể nhạy cảm; phạm vi lưu trữ và việc lưu giữ là trách nhiệm tuân thủ của người vận hành. Tài liệu này không phải là một ý kiến pháp lý; hãy tham vấn các cố vấn tuân thủ và pháp lý của riêng bạn.