跳到內容
NextPDF

Backport 建構器的安全性與維運

這是建構工具，不是執行階段相依套件。本頁說明如何維運此建構流程，以及如何評估其可信度。PDF 引擎本身的安全姿態記載於引擎文件中，而非此處。

概覽

標題為「概覽」的區段

此建構器會轉換自身未撰寫的原始碼，並產出並非為其本身開發的散布版本。它的安全模型也因此而來。信任邊界落在原始碼簽出與工具鏈上。所產出的產物是唯讀且由機器產生的。公開套件與 Pro 套件之間的授權分流，已直接寫死在程式碼中。

信任邊界

標題為「信任邊界」的區段

此建構器的輸入是原始碼儲存庫與釘選的工具鏈，輸出則是衍生產物。有三項性質適用：

  • 所產生的散布版本是唯讀且由機器產生的。 它是以版本標籤發布，而不是作為此儲存庫的分支。開發、錯誤回報與功能請求都應送往原始的 nextpdf/* 原始碼儲存庫，絕不送往所產生的目錄樹。已對照專案的 README.md 警示區塊與 .github/workflows/build.yml 驗證（發布流程會從頭重新提交並標記所產生的目錄樹）。
  • 發布權杖的範圍受到嚴格限制。 secrets.BACKPORT_TRIGGER_TOKEN 僅授權在發布標籤處複製原始碼儲存庫。它只會在原始碼簽出步驟中被引用。已對照 build.yml（GH_TOKEN 的使用）驗證。
  • CI 執行器的分流是刻意設計的。 受信任的事件在自架的 PHP 執行器上執行；fork 的拉取請求與 Dependabot 的執行則被強制使用 GitHub 託管的執行器。不受信任的程式碼絕不會在受信任的執行器池上執行。已對照 .github/workflows/0-ci.yml（runs-on 的條件式）驗證。

供應鏈姿態

標題為「供應鏈姿態」的區段
  • 工具鏈在 composer.json 中受到約束。 Rector ^2.0、PHPStan ^2.1、PHPUnit ^13.0，以及 symfony/polyfill-* 套件組。此建構器沒有任何 NextPDF 執行階段相依套件，因此 NextPDF 執行階段套件遭入侵也無法影響建構器。已對照 composer.json 驗證。
  • 相依套件更新由機器人驅動，並設有閘門。 設有一份 Dependabot 設定與一個自動合併工作流程；Dependabot 的執行被釘選到 GitHub 託管的執行器，且合併前仍必須通過完整的 CI 閘門（PHPStan、測試、乾跑）。已對照 .github/dependabot.yml 與 .github/workflows/0-ci.yml、9-dependabot-auto-merge.yml 驗證。
  • 輸出不包含建構狀態。 建立發布封存檔時會排除 vendor/ 與 .git/，因此所發布的產物只攜帶原始碼與所產生的資訊清單，而非建構器自身的相依套件樹。已對照 build.yml（zip ... -x '*/vendor/*' '*/.git/*'）驗證。
  • 靜態分析為建構程式碼把關。 composer analyse 會在每次推送，以及針對任一永久分支的拉取請求時，對 rector/rules 與 scripts 執行 level 10 的 PHPStan。這會在任何乾跑之前執行。已對照 composer.json 與 0-ci.yml 驗證。

語法驗證閘門

標題為「語法驗證閘門」的區段

此建構腳本不會在本機對輸出進行語法檢查，原因在於建構主機執行的 PHP 比目標版本更新。具權威性的閘門位於發布工作流程中。建構完成後，執行器會切換到目標 PHP，並以 php -l 對 output/src 進行檢查；只要出現任何剖析或致命錯誤，發布就會失敗。接著會安裝該產物，並在驗證矩陣上逐一檢驗——PHP 8.1 通道涵蓋 PHP 8.1 到 8.4，PHP 7.4 通道涵蓋 PHP 7.4 與 8.0。會被目標執行階段拒絕的散布版本，不會進入發布。已對照 scripts/build.php（validateOutput()）與 .github/workflows/build.yml（語法檢查與 validate-* 作業）驗證。

這是一項以觀察到的行為為依據的保證，其範圍限於此流程實際檢驗過的執行階段。它並非一致性認證。除了語法接受度與專案自身的測試套件之外，它並不主張轉換後程式的正確性。

授權分流

標題為「授權分流」的區段

所產出的兩個套件帶有不同的授權，並已寫死在 scripts/adjust-composer.php 中：

套件授權欄位由何處設定
nextpdf/backportApache-2.0generatePublicComposer()
nextpdf/backport-proproprietarygenerateProComposer()

此建構器儲存庫本身採用 Apache-2.0（composer.jsonlicense）。它的 CHANGELOG.md 記錄了先前一次從 LGPL-3.0-or-later 改授權為 Apache-2.0 的變更。在該變更之前發布的版本仍維持較舊的授權並可繼續取得，而每個新版本則採用 Apache-2.0。Pro 散布版本為專有授權，僅針對 PHP 8.1 目標產出，並需要 phpseclib/phpseclib ^3.0。已對照 CHANGELOG.md、composer.json 與 scripts/adjust-composer.php 驗證。

維運保證及其限制

標題為「維運保證及其限制」的區段

此流程保證的內容，僅限於程式碼實際強制執行的部分：

  • 遇首次失敗即停止。 建構會在第一個失敗階段以具名錯誤中止。由於發布作業相依於成功的建構與驗證，因此永遠不會發布部分完成的散布版本。已對照 scripts/build.php（step()）與 build.yml 作業的 needs 驗證。
  • 序列化的建構。 backport-build 並行群組搭配 cancel-in-progress: false，可避免兩個原始碼發布爭用同一個發布標籤。已對照 build.yml 驗證。
  • 可重現的輸入。 此流程會在建構前，從確切的發布標籤複製每一個原始碼儲存庫。已對照 build.yml（--branch "${TAG}"）驗證。

它不主張的事項：

  • 除了語法接受度與測試套件之外，它並不認證標準一致性、完整的 PHP 版本相容性，或轉換後程式的正確性。
  • 這項降級會移除執行階段強制的不可變性（剝除 readonly）。原本仰賴執行階段拒絕對 readonly 屬性寫入的程式碼，在降級後的輸出中將失去這道防護。這是為了 clone-with 安全性所做出的一項有文件記載、刻意的取捨——參見 /integrations/backport/troubleshooting/.

回報問題

標題為「回報問題」的區段

建構器本身的安全性問題應依循儲存庫的 SECURITY.md：透過 GitHub Security Advisory 或安全聯絡管道回報，而不是公開 issue。所產生程式碼中的問題則應回報至原始的原始碼儲存庫，因為所產生的目錄樹由機器產生，並非針對其進行開發。已對照 SECURITY.md 與專案的 README.md 驗證。

後續

標題為「後續」的區段
  • /integrations/backport/overview/ —— 此建構器的用途與產出。
  • /integrations/backport/production-usage/ —— 維運發布流程。