Enterprise 版本

計量

速覽

NextPDF Enterprise 會在 PHP 協調層收集使用計量——操作數、已處理頁數、執行時間——以供計費與稽核。項目會在記憶體中緩衝，以批次方式刷新到一個或多個後端，且後端失敗絕不會阻擋處理。本頁描述可觀察的計量行為與公開合約。

可用性與授權

此能力隨 NextPDF Enterprise（nextpdf/enterprise）出貨，並以 Enterprise 層級的授權封套啟用。沒有該授權的部署不會載入此能力的類別。計量是一項基礎的 Enterprise 能力，沒有獨立的逐功能旗標。比較各版本並取得授權。

概念總覽

計量收集器會為每次操作記錄一筆不可變的項目：一個操作類型、一個單位計數、一個時間戳記、租戶與授權識別碼、已處理頁數、操作執行時間，以及自由形式的中繼資料。項目會累積在一個記憶體內緩衝區中。當緩衝區達到其設定大小時會自動刷新；你也可以明確刷新，並可註冊一個關機處理常式，讓 PHP-FPM worker 在請求結束時刷新任何剩餘項目。長時間運行的 worker（例如 Octane 或 Symfony worker）則應改以週期性計時器刷新。

回報器會將一個批次扇出到一個或多個後端。各後端彼此隔離：某個後端的失敗不會阻止其他後端收到該批次。每個後端的傳遞最多重試到設定的嘗試次數；若所有嘗試皆失敗，該後端的批次會被記錄並丟棄——計量在設計上是盡力而為且非致命的，因此計量中斷絕不會降低文件處理品質。後端是計量後端介面的任一實作——一個 Prometheus push 目標、一個計費 API、一個資料庫或一個佇列——且實作必須具備冪等性，使重複的批次能被妥善處理。

這種協調層級的計量是為了計費與稽核可見性。它在設計上刻意不是配額強制執行的權威來源；配額決定是在部署的其他位置，依一個權威的使用數字做出的。

為何如此設計

計量位於計費與稽核路徑上，而非文件處理路徑上，這種分離是刻意為之。每次 record 呼叫都會將一筆不可變的 MeterEntry 附加到記憶體內緩衝區，因此擷取使用量始終是 O(1) 操作。刷新以批次進行，扇出到 MeteringBackendInterface 合約背後彼此隔離的後端。緩慢或無回應的計費端點因此能優雅地降級，而用盡重試的批次會被記錄並丟棄，而非拋出。因此計量中斷絕不會使高流量工作停擺，也不會與文件吞吐量競爭。取捨在於：協調層計量是盡力而為且非權威的——因此配額強制執行是在其他位置依一個權威數字做出的。

設計背景：大量文件生成。

公開 API 介面

composer require nextpdf/enterprise:^3

受支援的整合點包括：計量收集器（record、flush、bufferCount、registerShutdownFlush）、計量回報器（report）、計量後端介面（report、isHealthy、backendName），以及不可變的計量項目值物件。為達正式環境的耐久性，提供一個重試安全、具冪等性的後端實作是你的責任。

程式碼範例——快速上手

use NextPDF\Enterprise\Metering\MeterCollector;
use NextPDF\Enterprise\Metering\MeteringReporter;

$collector = new MeterCollector(new MeteringReporter([$backend]), bufferSize: 100);
$collector->registerShutdownFlush(); // PHP-FPM: flush remainder at request end

$collector->record(
    operation: 'parse',
    count: 1,
    tenantId: $tenantId,
    licenseId: $licenseId,
    pagesProcessed: 12,
    durationMs: 84.0,
);

程式碼範例——正式環境

use NextPDF\Enterprise\Metering\MeteringReporter;

// Multi-backend fan-out with retry and failure isolation.
$reporter = new MeteringReporter(
    backends: [$prometheusBackend, $billingApiBackend],
    maxRetries: 3,
    logger: $logger,
);

// A failing billing API does not stop Prometheus from receiving the batch;
// exhausted retries are logged and the batch is dropped — never thrown.
$collector = new MeterCollector($reporter, bufferSize: 500);

邊界案例與陷阱

**Flush 具冪等性。**對空緩衝區呼叫 flush 是 no-op；重複 flush 是安全的。
**後端失敗非致命。**用盡重試會記錄一則錯誤並丟棄該後端的批次；呼叫仍正常返回。不要依賴計量進行硬性配額強制執行。
**至少需要一個後端。**以空白後端清單建構回報器會遭拒。
**冪等性是後端的責任。**介面合約要求後端去重（依時間戳記、操作與租戶）——重試或重複的批次不得重複計數。
**Worker 模型很重要。**PHP-FPM 請使用關機處理常式；長時間運行的 worker 請使用週期性計時器刷新，否則項目會緩衝到 worker 結束為止。

效能

record 是一次 O(1) 的緩衝區附加。Flush 成本與批次大小及後端數量成正比；它透過緩衝與關機處理常式被移出請求路徑。重試會逐後端套用，並以設定的嘗試次數為界限。

安全注意事項

計量項目承載租戶與授權識別碼及操作中繼資料。請將中繼資料視為可能敏感，並依你的合規要求界定後端儲存與保留範圍。租戶與授權識別碼必須源自已認證的情境。

一致性

計量在公開邊界上不定義任何自有的傳輸格式——後端介面會將序列化委派給各後端實作（例如，一個 Prometheus push 目標會遵循 Prometheus 揭露慣例）。此介面不主張任何外部標準；本頁沒有 RAG 引用，因為沒有任何規範性規格管轄這個行程內的收集器合約。

行為合約

收集器會為每次操作記錄一筆不可變項目，並將項目累積在一個記憶體內緩衝區中，該緩衝區會在達到設定大小時自動刷新；明確刷新與關機刷新處理常式亦可使用。
Flush 具冪等性：刷新空緩衝區是 no-op，且重複 flush 是安全的。
回報器會將一個批次扇出到一個或多個後端，並逐後端隔離；某個後端的失敗不會阻止其他後端。
每個後端的傳遞最多重試到設定的嘗試次數；用盡的重試會被記錄並丟棄——計量是盡力而為的，且絕不會把例外拋進處理路徑。
以空白後端清單建構回報器會遭拒；後端必須具備冪等性，使重複的批次不會重複計數。
record 是一次 O(1) 的緩衝區附加；flush 成本與批次大小及後端數量成正比，並保持在請求路徑之外。

發布邊界

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

Core 回退

NextPDF Core（Apache-2.0）沒有任何計量收集器、回報器或後端介面——一概沒有；此能力沒有任何 Core 層級的等價物。NextPDF 不會對 Core 處理進行計量。

Pro 回退

NextPDF Pro 沒有任何計量介面——一概沒有；此能力沒有任何 Pro 層級的等價物。計量收集器、回報器與後端介面僅隨 nextpdf/enterprise 套件提供。

Enterprise 邊界註記

緩衝區生命週期、扇出、重試與隔離皆以行為層級描述。後端介面會將序列化委派給各後端實作；內部的緩衝內部實作與任何內部扇出細節皆不在公開介面範圍內。

部署邊界

運維人員擁有後端實作、其耐久性與冪等性、計量中繼資料的保留與儲存範圍，以及 worker 模型刷新策略（PHP-FPM 用關機處理常式，長時間運行的 worker 用週期性計時器）。計量後端中斷絕不會降低文件處理品質。租戶與授權識別碼必須源自運維人員所設定的已認證情境。

法律合規邊界

計量介面不適用任何出口管制限制。計量中繼資料可能敏感；保留與儲存範圍是運維人員的合規責任。本文件不是法律意見；請諮詢你自己的合規與法律顧問。