输出管线

概览

NextPDF Enterprise 以可配置的并发上限，以及对已完成输出的可选合规交接，协调对 NextPDF Pro 输出管线清单进行大规模批量执行。它是位于 Pro 输出管线之上的批处理层。

可用性与授权

此能力发行于 NextPDF Enterprise（nextpdf/enterprise），并随一份 Enterprise 级授权信封激活。没有该权益的部署不会加载此能力的相关类。比较各版本并获取授权。

Enterprise 批处理表面构建于 Pro 输出管线（pro.output.pipeline）之上，后者是先决条件，而非闸门。此处没有单独的每功能能力代码；凡是安装了已授权 nextpdf/enterprise 软件包的地方，批处理编排器与合规交接都可用。

安装

composer require nextpdf/enterprise:^3

概念概述

BatchPipelineOrchestrator 将许多个 PipelineManifest 实例作为一个批次来执行。每份清单都会经由 Pro 的 PipelineExecutor 运行；编排器在此之上增加了批次协调、一道有界资源守卫（每批次的清单数量设有上限）、按批次的超时处理，以及一道可选的合规交接。

BatchPipelineConfig 控制三件事：最大并发工作回调数、一个以毫秒为单位的可选全局批次超时，以及在管线完成后是否对每个输出运行合规检查。当合规检查启用时，ComplianceHandoff 会作为一个管线步骤集成进来，对每个派生 PDF 经由 Enterprise 合规网关重新校验，因此被管线修改过的文档会被重新检查，而不是沿用其修改前的状态而被信任。

在生产部署中，并行的工作分发与背压由一个独立的执行边车处理；此处描述的 PHP 编排器提供批次协调与合规交接逻辑，并由作业工作器调用，而非由请求处理器直接调用。

为何如此设计

大批量批处理生成可拆分为两项关注点：协调哪些清单在何种保证下运行，以及驱动原始的并行吞吐量。NextPDF 将协调与合规语义保留在这个确定性的 PHP 编排器中，而将并行的工作分发与背压委托给一个独立的执行边车。这条边界让吞吐层可以独立地扩展并发，而编排器则保持简单、有界且可审计。对每批次清单数量的硬上限使峰值内存保持可预测，从而一次大规模提交不会拖垮工作池。合规交接会对每个派生输出重新校验，而不是信任其修改前的状态，并且会失败即关闭。一份已完成的清单只有在网关确认符合性时才通过，绝不会默认通过。

设计背景：大批量文档生成。

API 表面

类	职责
BatchPipelineOrchestrator	以有界并发将许多份清单作为一个批次执行。
BatchPipelineConfig	最大并发数、批次超时、完成时合规开关。
BatchPipelineResult	汇总：按清单的结果、已完成与失败计数、耗时。
ComplianceHandoff	可选的管线末端合规重新校验步骤。

代码示例 —— 快速开始

use NextPDF\Enterprise\OutputPipeline\BatchPipelineOrchestrator;

$result = (new BatchPipelineOrchestrator($executor))->executeBatch($manifests);

代码示例 —— 生产环境

use NextPDF\Enterprise\OutputPipeline\BatchPipelineOrchestrator;
use NextPDF\Enterprise\OutputPipeline\BatchPipelineConfig;

$config = new BatchPipelineConfig(
    maxConcurrency: 4,
    timeoutMs: 600_000,
    complianceCheckOnComplete: true,
);

$result = (new BatchPipelineOrchestrator($executor, $config))
    ->executeBatch($manifests, $variablesMap);

$logger->info('pipeline.batch', [
    'completed' => $result->completedCount,
    'failed'    => $result->failedCount,
]);

边界情况与陷阱

• 批次对清单数量强制设有上限；超过上限会触发一道资源守卫错误，而不是静默降级。
• 全局超时为零意味着没有批次超时；在生产环境中请设置一个有限值，使得一份卡住的清单无法无限期地阻塞整个批次。
• 合规交接要求上游步骤输出中存在一个可识别的 PDF；若未找到，该步骤会为那份清单报告一次失败，而不是静默通过。
• 本模块依赖于 Pro 输出管线；它增加的是批次协调，而非一套新的步骤模型。

性能

吞吐量随配置的并发数与每份清单的成本而扩展。并发数应相对于工作池保守设置，以免回调将其饱和。每批次的清单上限限定了峰值内存。

安全说明

批处理编排器会处理调用方提供的任何清单与变量；请像对待任何其他不受信任的 PDF 工作负载一样对待管线输入。合规交接是一项重新校验辅助手段，而非授权控制。

数据驻留与 PII 缓解

批次输出可能包含个人数据。处理是在进程内且在本地进行的；本编排器不发起任何对外网络调用。请对批次输出施加你自己的留存控制。

安全遥测与日志清洗

批次结果报告的是计数与耗时，而非文档内容。如果清单标识符编码了租户或案件数据，请在日志中将其清洗掉。

符合性

本模块不声明任何标准符合性；它是一个编排层。可选的合规交接交由 Enterprise 合规网关处理，后者带有自己的引用。

FIPS 模式行为

本模块不执行任何密码学操作。

威胁模型

主要输入是调用方提供的清单与变量。缓解措施：对每批次的清单数量设有硬上限、有界并发、对派生输出的可选重新校验，以及编排器本身没有网络 I/O。

行为契约

• executeBatch() 会让每份清单经由 Pro 管线执行器运行，并返回按清单的结果以及已完成与失败计数和耗时。
• 一道硬上限限定每批次的清单数量；超过它会触发一道资源守卫错误，而不是静默降级。
• 全局超时为零意味着没有批次超时；一个有限值会限定一份卡住的清单。
• 当启用时，合规交接会对每个派生 PDF 重新校验，并在上游未找到可识别的 PDF 时报告一次步骤失败，而不是静默通过。

发布边界

本页仅记述外部可观察的行为与受支持的公共 API 表面。内部命名空间路径、辅助类、机制表、运行手册文件名，以及工单前缀不在范围内。

Core 回退

NextPDF Core 没有输出管线模型。一个仅使用 Core 的部署直接针对 Core API 自行组合各步骤；没有清单、没有批次协调，也没有合规交接。

Pro 回退

在仅使用 Pro 的部署中，受支持的表面是单清单 Pro 输出管线（pro.output.pipeline）：Pro 的 PipelineExecutor 一次运行一份清单。Pro 不提供批处理编排器、有界并发批次守卫、按批次超时，以及 Enterprise 合规交接；在仅使用 Pro 的部署中，一个请求批处理编排或合规交接的配置没有可满足它的 Enterprise 组件。Pro 管线表面请参阅 Pro 概述。

Enterprise 边界说明

批次协调、资源守卫边界，以及合规交接的接线仅在行为层面描述。内部边车分发协议、内部背压语义，以及内部合规网关接线不在公共表面的范围内，此处不予复现。

部署边界

在生产环境中，并行的工作分发与背压由一个独立的执行边车处理；此处描述的 PHP 编排器提供批次协调与合规交接逻辑，并由作业工作器调用，而非由请求处理器直接调用。工作池规模设定、边车供给，以及相对于 PHP 工作池的并发上限是运维方的责任。合规交接是一项重新校验辅助手段，而非授权控制。

法律合规边界

可选的合规交接会对派生文档重新运行一遍校验。它报告发现项；它不对文档进行认证、不保证监管充分性，也不构成法律意见。判断某个输出是否满足你的义务是你的责任。

另请参阅

• 输出管线（Enterprise 参考）——批处理编排器 API 参考。
• Pro 概述——底层的输出管线。
• Enterprise 概述
• Core、Pro 与 Enterprise 功能对照表