在正式環境中維運 NextPDF

Spec: ISO 9241-112:2025, §6.1.2.3Spec: ISO/IEC/IEEE 26514:2022, §3.x162

概覽

在正式環境中運作 PDF 引擎，不只是「呼叫它，然後把位元組送出去」這麼簡單。你必須掌握：一次健康彩現會回報什麼、一次不健康彩現會怎麼處理、你可以在哪裡接上可觀測性，以及它會拒絕悄悄執行哪些危險操作。本頁說明這個運維面，也就是 NextPDF 真正上線運作時，團隊必須承擔的接縫與特性。

為什麼這很重要

文件引擎的失敗方式與一般服務不同。這些失敗往往是無聲的：降級的版面仍然產出檔案、被封鎖的外部資源改變了輸出、未簽署的文件看起來卻像已簽署。如果引擎把這些狀況藏起來，你會透過客戶、而不是儀表板，才發現它們。如果引擎把它們浮現出來，它們就會成為一則告警和一條維運手冊條目，而不是一場事故。

因此，可運維性不是日後才補上的功能。它取決於引擎是否從設計之初，就為了向你如實交代每一次彩現而打造，而 NextPDF 正是如此。

精簡版

**每一次彩現都會產生一份結構化報告。**是否成功、頁數、彩現時間、記憶體峰值、警告代碼、回退發生次數、被封鎖的外部資源——都能序列化為 JSON，供你的儀表板使用。
引擎會發出具型別的生命週期事件，透過 PSR-14 分派器發送；沒有任何監聽者時開銷為零——你的稽核與指標掛鉤就掛在這裡。
**失敗模式是明確的，而非無聲的。**降級對等性會被回報；高階簽章介面會快速失敗；輸出以原子方式寫入；在處理程序內的 HTML 路徑中，抓取外部子資源依設計就是關閉的。
**危險操作在 Connect 中需要人工介入。**當 NextPDF 暴露給 AI 代理時，具破壞性或攸關隱私的工具會由一道確認挑戰把關——這是最重要的運維特性，並且會陳述在你實際看得到它的位置（ISO 9241-112 §6.1.2.3）。

NextPDF 如何處理這件事

運維模型建立在一項原則上：**一次彩現絕不應該對它做了什麼說謊。**有三項機制會落實這一點——一份報告、一條事件串流，以及一組故障安全行為。當引擎由代理驅動時，還會套用第四項機制。

Observe each renderCollect the per-render report — success, timing, peak memory, warnings, fallbacks, blocked-resource counts — into your telemetry sink.
Subscribe to lifecycle eventsAttach PSR-14 listeners for document, security, and serialization events for audit logging and metrics.
Detect degradationTreat degraded-parity and fallback signals as health indicators, not noise. They mean the output differs from the ideal render.
Gate the dangerous pathIn Connect, route destructive or privacy-critical operations through the human confirmation gate before they execute.

端到端的運維面：檢測是選擇性加入的，未使用時零成本；失敗模式會以資料或快速失敗的形式浮現，絕不會以一個悄悄出錯的檔案呈現。

這份報告是一個為彙總設計的不可變快照。它記錄彩現是否成功、耗時多久、記憶體峰值、各代碼的警告數量、是否啟用安全彩現模式、有多少外部資源請求遭到拒絕，以及發生了哪些版面回退。最後這一組在運維上很重要。在整個機群中，「flex 回退為 block」的次數逐漸上升，就是某個範本被變更的訊號，而你會在任何使用者抱怨之前看到它。

事件接縫相容於 PSR-14，而且刻意設計得很低成本。當某個事件類別沒有註冊任何監聽者時，分派器會立即返回。正因如此，在你真正使用之前，加入這道接縫不會產生任何成本。針對文件建立與輸出、頁面新增、內容與字型載入、加密已套用、簽章已套用，以及 PDF 已序列化，都有對應的具型別事件。這些正是稽核日誌或指標計數器真正在意的時點。可觀測性契約（指標計數器、量規、直方圖、追蹤區段、HSM 稽核日誌）隨附的是無操作（no-op）實作。因此，引擎在完全沒有接上遙測的情況下仍可正常運作；當你綁定真正的實作時，它就變得可觀測。

實務範例

下方程式碼展示了可觀測性接縫：一個 PSR-14 監聽者，將生命週期事件與彩現報告轉換成遙測資料。它示範的是這道接縫本身；指標匯入端則由你自行決定。

<?php

declare(strict_types=1);

use NextPDF\Event\Document\DocumentOutputEvent;
use NextPDF\Event\Security\SignatureAppliedEvent;
use Psr\Log\LoggerInterface;

/**
 * Audit + metrics listener for production operation.
 *
 * Attaching this costs nothing until events fire — the dispatcher
 * short-circuits when no listener is registered for an event class.
 */
final readonly class OperationsListener
{
    public function __construct(
        private LoggerInterface $logger,
    ) {}

    public function onSignatureApplied(SignatureAppliedEvent $event): void
    {
        // Compliance trail: who signed, at what level, why.
        $this->logger->info('pdf.signature.applied', [
            'level'  => $event->signatureLevel,
            'signer' => $event->signerName,
            'reason' => $event->reason,
        ]);
    }

    public function onDocumentOutput(DocumentOutputEvent $event): void
    {
        // Pair this with the engine's RenderReport for the full picture:
        // success, render_time_ms, peak_memory_bytes, fallback_occurrences.
        $this->logger->info('pdf.document.output', [
            'event' => $event::class,
        ]);
    }
}

重點在於這道接縫，而不在於其中的具體內容。引擎交給你的是具型別的事件與一份結構化報告。你要轉送、取樣或對哪些內容發出告警，是一項運維決策，引擎刻意把它留給你。

常見誤解

運維上的誤解是*「只要它回傳了位元組，就代表它運作正常。」*一次彩現可以成功，卻仍然降級。某個版面回退了、某張外部圖片被封鎖而悄悄缺席、某項功能在當前模式下並未獲得支援。位元組確實存在，但這份文件並不是範本原本所要呈現的樣子。引擎把這些回報為警告與回退次數，正是為了避免「回傳了位元組」被誤認為「正確彩現了」。把回傳值當成唯一成功訊號，正是這個運維面要防止的錯誤。

第二個誤解是 Connect 特有的：以為把 PDF 工具暴露給代理是安全的，因為這些工具「只是在彩現而已」。具破壞性、會覆寫或攸關隱私的操作之所以由人工確認挑戰把關，是有原因的。繞過該閘門或自動回應它，會重新引入它原本移除的風險。

限制與邊界

**引擎負責檢測；它不會替你運行你的可觀測性堆疊。**它會發出一份報告與具型別的事件；蒐集、告警、儀表板與保留則由你負責。
**無操作的可觀測性是預設值。**指標、追蹤與 HSM 稽核日誌在你綁定真正的實作之前都是惰性的——這是刻意設計，好讓引擎在完全不接線的情況下也能運作。但這也代表在你選擇加入之前，不會記錄任何東西。
**SSRF 故障安全機制適用於處理程序內的 HTML 路徑。**外部彩現器橋接（瀏覽器/Office）本質上會發出對外呼叫，並各自帶有自己的傳輸層強化。這項保證專指處理程序內的路徑。
**人工確認閘門是 NextPDF Connect 的特性。**它管控的是由代理驅動的呼叫。它並非一般的 PDF 功能，而且它綁定在工具名稱與一個 nonce 上，而非綁定在參數雜湊上。
**高階簽章介面會快速失敗。它並不是一個已接好線的簽署器。**在運維上，請把它的診斷當成訊號，並使用已接好線的較低階路徑來執行實際的簽署。
本頁有產出物佐證：所提及的每一道接縫都是真實的類別或契約，但如何把它們運維好，是你的責任。

Observability and operational seams — edition availability
Edition	Availability
Core	`RenderReport`、PSR-14 事件分派器與具型別事件階層、無操作的可觀測性契約、原子化輸出寫入，以及處理程序內的 SSRF 故障安全機制，都屬於 Core。
Pro	加入安全性生命週期事件（加密/簽章已套用），一旦你開始使用簽署，這些事件便具有運維上的實質意義。
Enterprise	加入 HSM 稽核日誌接縫，並將驗證結果作為運維訊號；NextPDF Connect 則為由代理驅動的高風險操作加入人工確認閘門。

詞彙表

RenderReport——引擎不可變、可序列化為 JSON 的每次彩現指標快照，用作主要的健康訊號。
PSR-14——事件分派器的 PHP 標準；NextPDF 的分派器相容於此標準，且在未使用時開銷為零。
降級對等性——一次已完成的彩現，但因為某項功能回退或不受支援，其輸出與理想結果不同。
回退發生——版面引擎改用較簡單行為時留下的一筆記錄（例如 flex 被彩現為 block）。
SSRF（伺服器端請求偽造）——一種讓伺服器被誘騙向內部目標發出請求的攻擊。在處理程序內的 HTML 路徑中，設計上即被移除。
確認閘門——NextPDF Connect 的機制，在高風險、由代理呼叫的工具執行之前，要求一個由人工轉達的一次性權杖。
原子寫入——一種輸出寫入方式，並行讀取者看到的不是先前的檔案，就是完整的新檔案，絕不會是部分檔案。