NextPDF Connect 的 worker 安全工作階段生命週期

概覽

在長時間執行的 PHP worker（RoadRunner、Swoole、Laravel Octane）中，請使用正確的工作階段生命週期。每個請求都會建立自己的文件工作階段，並在 output_pdf 後將其銷毀。字型、頁面或控制代碼狀態都不會跨越 worker 的請求邊界外洩。這些工具包括 create_pdf、set_font、add_text 與 output_pdf，且全部都是 Core。

安裝

composer require nextpdf/server

請綁定一個傳輸層。此模式在任何傳輸層上的運作方式都相同。

概念總覽

document_id 是一個不透明的控制代碼，其範圍僅限於單一請求。規則是 每個請求各自建立、每個請求各自銷毀，絕不快取或共用。在預設的 destroy: true 下，output_pdf 會在單一原子步驟中算繪文件並釋放工作階段。同一個 worker 上的下一個請求會取得全新且獨立的工作階段。先前工作階段的字型與內容都已不存在。每個工具的結果都是一般的傳輸層回應（PSR-18 §p2）。伺服器程式碼本身則透過自動載入邊界（PSR-4 §3）隔離。工作階段儲存區是唯一的跨請求狀態，並以 id 作為鍵值。

API 介面

工具	角色	風險層級
`create_pdf`	開啟每個請求專屬的工作階段	安全
`set_font`	設定目前使用的字型（每工作階段）	注意
`add_text`	寫入內容	注意
`output_pdf`	算繪並銷毀工作階段	需要核准/審查（base64）

工具目錄是正式的目錄依據。可用工具取決於已安裝的層級。

程式碼範例 — 快速開始

請求 1：create_pdf → set_font → add_text → output_pdf（destroy: true）。同一個 worker 上的請求 2 會啟動全新的 create_pdf 工作階段。舊的 id 此時已失效。請重新設定字型，因為它不會延續到下一個工作階段。

程式碼範例 — 正式環境

封裝生命週期，確保清理工作一定會執行：

請求開始時取得工作階段。
建立內容。
在等同於 finally 的區塊中呼叫 output_pdf，它會銷毀工作階段。如果你為了輸出後檢視流程而使用了 destroy: false，請改為明確銷毀工作階段。

切勿將 document_id 儲存在 worker 全域、靜態變數或共用容器中。切勿在協程、fiber 或請求處理常式之間傳遞它。

邊界情況與陷阱

銷毀後重複使用 id。 會傳回未知文件錯誤。請為每個請求建立新的工作階段。
忘記呼叫 output_pdf。 記憶體會悄悄增長，直到工作階段 TTL 到期或行程重新啟動為止。請務必完成收尾。
高負載下的工作階段上限。 儲存區有並行上限。及時銷毀可讓你維持在上限之下。
使用 destroy: false 卻未進行清理。 記憶體會逐漸增長。請僅在明確的輸出後檢視流程中使用它，之後再銷毀工作階段。
在並行請求之間共用 id。 這會造成損毀輸出的競爭情況。每個請求都擁有自己的工作階段。

效能

每個請求的輸出大小為幾 KB。其優勢在於 worker 整個生命週期中的記憶體用量都受到限制。此設定檔為 structural。

安全性注意事項

工作階段隔離同時也是一項機密性屬性。某個請求的內容絕不會流向另一個請求，因為控制代碼不會共用，而且工作階段會在輸出時銷毀。

合規性

陳述	規格	條款	reference_id
每個工具的結果都是一般的傳輸層回應。	PSR-18	§p2
程式碼透過自動載入的類別→檔案對應隔離。	PSR-4	§3

商業情境

不適用 — 所有工具都是 Core。

傳輸層可用性

傳輸層	是否可用	備註
MCP（stdio）	是	通常每個 worker 對應一個 stdio 行程。
REST	是	HTTP 請求邊界對應到工作階段邊界。
gRPC	是	每個 RPC 序列對應一個工作階段。

HITL 風險層級

create_pdf 屬於 Safe。set_font 與 add_text 屬於 Caution。output_pdf 屬於 Approval Required，在 base64 模式下會降級為 Review。在 worker 中，base64 輸出是常見路徑，且不會設置任何關卡（HITL 風險層級）。

確認關卡 JSON 封裝

Base64 worker 輸出：

{ "allowed": true }