Enterprise 版本

SaaS

速覽

NextPDF Enterprise 提供建構多租戶 SaaS 部署所需的基礎元件：一個不可變的租戶情境、帶有 checksum 與時序安全驗證的範圍化 API key、一個帶有 80%/100% 行為的請求前配額檢查，以及一個對外部計費供應商的拉取式計量同步。本頁描述可觀察的行為與公開合約。

可用性與授權

此能力隨附於 NextPDF Enterprise（nextpdf/enterprise），並在 Enterprise 層級的授權封套下啟用。沒有該授權的部署不會載入此能力的類別。比較各版本並取得授權。

SaaS 多租戶介面是一項基礎 Enterprise 能力，只要安裝了套件即可使用；並沒有獨立的逐功能旗標。

概念總覽

一個租戶由一個不可變的租戶情境表示：一個租戶識別碼、解析它的來源（一個 token、mutual-TLS 或一個 API key），以及一組已授權的範圍。租戶身分一律從已驗證情境解析——絕不從由客戶端提供的標頭或查詢參數取得。單租戶部署使用一個帶有完整範圍的固定預設情境。

API key 帶有一個人類可讀、用以區分 production 與 sandbox 的前綴、一個高熵隨機本體，以及一個短的 checksum。checksum 是一種快速拒絕打字錯誤的便利機制，不是安全機制——它讓格式錯誤的金鑰能在任何資料存放區查詢之前被拒絕。驗證會驗證 checksum、以 SHA-256 雜湊金鑰、在儲存庫中查詢該雜湊，並拒絕未知、已撤銷或已過期的金鑰。金鑰絕不以明文記錄或儲存，而所儲存的值就是該雜湊。範圍強制是明確的：可要求一個情境必須持有某個給定的範圍。

配額檢查器在請求繼續進行之前執行。它讀取租戶當期的用量、在 soft limit（80%）時透過呼叫端提供的警示回呼發出警告，並在 hard limit（100%）時以一個攜帶重設時點的配額超出狀況拒絕。期間重設是 UTC 中下個月的邊界。

計量同步配接器會從部署的權威用量來源拉取用量事件、將它們轉換為計費供應商的計量事件形態並帶有一個穩定的冪等鍵，然後送出它們。失敗的事件會被路由到一個死信回呼，而同步器會追蹤一個逐來源的游標，讓同步週期從上一個週期停止之處續行。計費供應商整合是一個介面，因此供應商可替換。

為何這樣設計

其關鍵的承載決策是：NextPDF 交付的是強制執行原語，而不是一個代管平台。TenantContext、ApiKeyAuthenticator、QuotaChecker 與計量同步配接器都是你的部署接上自身存放區的合約。租戶身分只從已驗證情境解析，因此客戶端永遠無法透過標頭主張自己的租戶。金鑰以 SHA-256 雜湊形式存在於你的儲存庫中、配額讀取你的用量來源，而計費供應商是一個可替換的介面。NextPDF 不持久化任何東西，因此租戶資料、金鑰與計費都在你的掌控之下。由於此介面透過 Core 合約解析，同一份呼叫端程式碼能在 Core、Pro 或 Enterprise 上執行——版本升級絕不改寫整合程式碼。

設計背景：開放核心，無鎖定。

公開 API 介面

composer require nextpdf/enterprise:^3

受支援的整合點是租戶情境（hasScope、hasAnyScope、singleTenant）、API-key 產生器（generateLive、generateTest、validateChecksum、hashKey、isLiveKey、isTestKey）、API-key 驗證器（authenticate、requireScope）、API-key 儲存庫介面、配額檢查器（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
}

邊界案例與陷阱

checksum 不是安全。 通過的 checksum 只代表金鑰格式正確；驗證仍會雜湊並查詢它，並強制撤銷與到期。
時序安全比較。 金鑰驗證使用常數時間比較；請勿在包裝層中重新引入一個會短路的字串比較。
租戶身分來源。 絕不從由客戶端提供的標頭或查詢值建構租戶情境；只從已驗證情境解析它。
配額警告 vs 拒絕。 80% 會警告並讓請求繼續進行（帶有一個警告百分比）；100% 會以重設時點拒絕。警示回呼應逐期去重。
同步韌性。 計量同步拉取失敗會回傳一個無操作的週期並保留游標；失敗的個別事件會進入死信回呼，而非阻塞週期。

效能

租戶情境檢查與 checksum 驗證為常數時間。驗證成本是一次雜湊加一次儲存庫查詢。配額檢查成本是一次用量讀取加常數時間運算。計量同步是一個依排程執行、在請求路徑之外的批次操作。

安全注意事項

API key 僅以 SHA-256 雜湊儲存，且絕不以明文記錄；驗證採時序安全；已撤銷與已過期的金鑰以各自獨立的結果拒絕。租戶身分必須來自已驗證情境。為元件間呼叫鑄造的短效服務 token 帶有標準的已註冊 claims 與一個短的到期時間。本頁僅描述行為；token 驗證內部實作不是公開合約的一部分。

一致性

元件間服務 token 帶有已註冊的 claims iss、aud、sub、exp 與 jti，並遵守 RFC 7519（JWT）§4.1.4 的 exp not-after 規則。
服務 token 使用 RFC 7515（JSON Web Signature）§3.1 的 JWS compact serialization 三段式。
API key 以 SHA-256 摘要（FIPS 180-4 SHA-256）儲存。注意：本頁未從 RAG 語料庫取得 FIPS 180-4；該演算法由程式碼宣告（hash('sha256', …)），此處標示為程式碼宣告，而非 RAG 驗證。

行為合約

一個租戶是一個不可變的情境（tenant id、解析來源、已授權範圍）；身分一律從已驗證情境解析，絕不從由客戶端提供的標頭或查詢值取得。
API-key 驗證會驗證 checksum、以 SHA-256 雜湊、查詢該雜湊，並以各自獨立的結果拒絕未知、已撤銷或已過期的金鑰；金鑰絕不以明文記錄或儲存，且驗證採時序安全。
配額檢查器在 80% 時透過呼叫端提供的回呼發出警告，並在 100% 時以一個攜帶重設時點（下個月邊界、UTC）的配額超出狀況拒絕。
計量同步拉取失敗會回傳一個無操作的週期並保留逐來源游標；失敗的個別事件會路由到死信回呼，而非阻塞週期。
checksum 是一種拒絕打字錯誤的便利機制，不是安全機制。

發布邊界

本頁僅記載外部可觀察的行為與受支援的公開 API 介面。內部命名空間路徑、輔助類別、機制對照表、runbook 檔名，以及工單前綴皆不在範圍內。

Core 回退

NextPDF Core（Apache-2.0）沒有租戶、API-key 或配額介面——完全沒有；此能力沒有 Core 層級的對應。

Pro 回退

NextPDF Pro 沒有租戶、API-key 或配額介面——完全沒有；此能力沒有 Pro 層級的對應。租戶情境、API-key 驗證、配額檢查器與計量同步配接器僅隨附於 nextpdf/enterprise 套件。

Enterprise 邊界註記

API-key 產生、checksum 與時序安全驗證皆以行為層級描述。token 驗證內部實作、金鑰雜湊儲存策略，以及計費供應商配接器內部實作皆不在公開介面的範圍內；計費供應商整合是一個介面，且可替換。

部署邊界

操作者負責 API-key 儲存庫、計費供應商配接器實作、配額檢查器與計量同步所讀取的權威用量來源，以及警示回呼的去重。租戶身分必須源自操作者所設定的已驗證情境（token、mutual-TLS 或 API key）。NextPDF Enterprise 本身不持久化金鑰或用量。

法律合規邊界

SaaS 介面不適用任何出口管制限制。API key 與租戶識別碼可能屬於敏感資訊；儲存範圍與保留是操作者的合規責任。本文件不是法律意見；請諮詢你自己的合規與法律顧問。