跳转到内容
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/ —— 发布流程的运维。