正式環境維運

一覽

本頁是將 NextPDF 帶入正式環境並持續維運的檢查清單。它彙整整份手冊： 每個項目都連往詳載其細節的頁面，因此您可在此逐項確認，細節則到對應頁面閱讀。請在首次發布前逐項完成部署前檢查清單。並將重新檢視升級節奏與 事故分級處理入口納入日常維運（day-two operations）。

部署前檢查清單

• 確認執行環境：NextPDF 需要 PHP >=8.4 <9.0。任何超出此範圍的版本， Composer 都會拒絕。請參閱安裝。
• 以 php -m 驗證六個必要擴充功能：ext-mbstring、ext-zlib、 ext-intl、ext-gd、ext-curl 與 ext-openssl。安裝頁面 會說明各項擴充功能的用途。
• 執行 vendor/bin/nextpdf doctor 以一次完成環境檢查 （在單一報告中涵蓋 PHP 版本、擴充功能，以及字型可用性）。
• 在規劃硬體規模前，先決定您的轉譯路徑。行程內管線（writeHtml()） 不需要額外服務。Artisan、Gotenberg 與 Cloudflare 則各自需要一個瀏覽器或網路服務才能運作。請透過選擇您的路徑來決定。
• 若您選擇了 renderer 橋接，請在上線前閱讀其安全性與維運頁面。 請參閱強化 renderer 暴露面。
• 在建置階段只打包您會轉譯的字型，僅此而已。請參閱 在正式環境中佈建字型。

資源規模配置

請以您所產生的最大文件（而非平均值）來規劃規模。getPdfData() 會在記憶體中建構整份 PDF 文件（可攜式文件格式，Portable Document Format），並以單一字串回傳。

• 依據無伺服器規模配置指引 設定 worker 或函式的記憶體：數頁的文件在 512–1024 MB 下相當充裕；影像密集或頁數眾多的文件則需要更多。
• 將逾時設定在最壞情況建構時間之上，並保留餘裕。將過大的工作移至寫入物件儲存的非同步佇列——同一個規模配置章節 示範了此模式。
• 為長時間執行的 worker 啟用 opcache，並關閉時間戳記驗證。Docker 範例的 opcache 章節 提供了正式環境的 ini 值。
• 當上線後記憶體或吞吐量出現漂移時，請從 症狀對應調整手段的決策表著手。

Worker 安全性規則

Document 是一次性的。建構它、寫出一次，然後讓它離開作用域；請為每個請求或每個佇列工作建立全新的實例。只共用與行程同生命週期的登錄——FontRegistry 與 ImageRegistry——並只在 worker 啟動時建立一次。這符合 PHP-FPM、佇列 worker， 以及長時間執行的應用程式伺服器所採用的每請求、每工作模型。

• 包含啟動順序與每輪重設的範例： Worker 安全的批次轉譯。
• 一則回答說明契約： 它是否為 worker-safe 與 thread-safe？

強化 renderer 暴露面

請將 HTML 視為不可信，尤其是任何受使用者影響的內容。 選擇您的路徑闡明了此界線：預設情況下， 內建管線不執行任何指令碼，也不抓取遠端資源；而每個橋接則透過瀏覽器或網路服務進行轉譯。在將某個橋接開放給正式環境流量之前，請完整閱讀其安全性與維運頁面：

• Artisan 安全性與維運 —— Chrome renderer 暴露面。
• Gotenberg 安全性與維運 —— Gotenberg 服務暴露面。
• Cloudflare 安全性與維運 —— 邊緣部署暴露面。
• 將引擎作為服務執行嗎？請加上 Connect 安全性與維運。

可觀測性

NextPDF 不發布任何服務等級目標（service-level objective，SLO）；請從您於下方量測的轉譯時長與記憶體指標，推導出您自己的目標。

請在第一起事故發生之前（而非之後）就為轉譯路徑建立檢測（instrument）。

• 行程內引擎： 以 OpenTelemetry 觀測。
• NextPDF Connect 部署： Connect OpenTelemetry 範例。
• 每次轉譯都記錄：實際耗時（wall time）、尖峰記憶體、頁數、輸出大小，以及執行結果， 連同它在錯誤參考中對應的例外類別。
• 針對趨勢發出警示，而不僅是失敗：建構時間上升、尖峰記憶體上升，以及逾時或記憶體耗盡的次數，都是記憶體與效能條目 中的先行訊號。

升級節奏

• 完整讀過版本支援政策一次，然後讓所有發布都遵循它。它定義了語意化版本控制契約、穩定性標籤、棄用生命週期，以及本手冊所使用的生命週期詞彙（active、lts、maintenance、frozen、eol）。
• 提交 composer.lock，讓每個部署的 worker 都解析到相同的引擎版本—— 安裝頁面闡述了此紀律。
• 在每次版本升級前，先檢視變更日誌。

事故分級處理入口

若是 renderer 橋接的事故（Chrome 當機、Gotenberg 中斷、邊緣轉譯失敗），請從 強化 renderer 暴露面中該橋接的失效模式章節著手。

• 在疑難排解知識庫中，請從症狀著手，而非類別名稱。
• 在錯誤參考中，將捕捉到的例外對應到其類別與情境契約。

另見

• 在正式環境中維運 NextPDF —— Insider 專欄文章，說明引擎為何在負載下如此運作。
• 將 NextPDF 應用程式容器化 —— 從頭到尾的正式環境 Docker 映像。
• 在無伺服器環境部署 —— Lambda、Cloud Run 與 App Runner 的具體細節。
• Connect 上的 Worker 安全轉譯 —— 將同樣的生命週期規則套用於伺服器。