NextPDF Symfony 安全与运维

概览

响应辅助方法会应用一组固定的安全性标头。异步消息 DTO 会对输出路径执行两次验证。签名是可选功能；在 Pro 层级下，仅支持本文记录的 baseline 配置文件。

HTTP 响应安全性标头

NextPDF\Symfony\Http\PdfResponse 会为它构建的每个响应（内嵌、下载，以及两种流式变体）应用同一组标头。对照源常量验证后，确切标头如下：

标头	值
Cache-Control	private, max-age=0, must-revalidate
Pragma	public
X-Content-Type-Options	nosniff
X-Frame-Options	DENY
Content-Security-Policy	default-src 'none'
X-Robots-Tag	noindex, nofollow
Referrer-Policy	no-referrer

这些设置可降低生成文档遭受 content-type 探测、被嵌入框架、被索引收录以及 referrer 外泄的风险。缓冲变体会额外设置 Content-Type: application/pdf 与 Content-Length。流式变体会设置 content type，但会有意省略 Content-Length。

这组标头由 bundle 固定设置。若要新增或更改标头（例如，对已认证的下载应用更严格的 Cache-Control），请在控制器返回前修改返回的 Response。

Content-Disposition 与文件名处理

PdfResponse 会以防御性方式构建 Content-Disposition 标头，并已通过 PdfResponseTest 验证：

• 文件名会被净化；路径分隔字符与遍历序列都会被移除（像 ../../../etc/passwd.pdf 这样的文件名无法逸出）。
• 缺少扩展名时会追加 .pdf；已有扩展名不会被重复追加，包括大写的 .PDF。
• 双引号与反斜杠会按 quoted-string 形式转义。
• 非 ASCII 文件名会获得一个 ASCII 后备字符串 以及 一个 RFC-5987 的 filename*=UTF-8'' 变体。
• 空文件名会回退为 document.pdf。

只有在你已完成应用层授权检查后，才可传入受用户影响的文件名；此 bundle 的净化只保证标头安全，不用于访问控制。

异步输出路径验证

NextPDF\Symfony\Message\GeneratePdfMessage 会在构造函数中验证输出路径，而 NextPDF\Symfony\Message\GeneratePdfHandler 会在写入前的执行阶段再次验证。已验证的构造时拒绝规则如下：

• 空路径，或包含 null byte 的路径；
• 像 php://... 这类 stream-wrapper scheme；
• 包含 .. 遍历片段，且使用 / 或 \ 任一分隔字符；
• 未以 .pdf 结尾（不区分大小写）的路径；
• 并非语法上有效类名的 builderClass。

处理器中的第二次验证很重要，因为消息可能会在派发与消费之间停留在队列中。处理器不信任队列中的路径，会在保存前再次应用路径防护。请使用最小权限的文件系统账号运行 worker，并将其权限范围限制在预期输出目录内。

构建器 resolve（解析）的边界

GeneratePdfHandler 会通过以类名为键的 PSR-11 service locator 解析构建器，并拒绝任何不是 PdfBuilderInterface 的对象。由于 locator 只公开已注册的构建器，因此即使被篡改的传输负载带有受攻击者控制的 builderClass，也无法实例化任意类。在 PSR-11 下，当容器报告某个 id 不存在时，对它的解析会失败，而不是默默返回非预期对象（PSR-11 §1.1.2）。请只在 locator 中注册受信任的构建器类。

可选的数字签名配置

数字签名 并非 核心 bundle 的一部分。只有在 nextpdf/premium（会安装 Pro 层级）存在，且编译器阶段检测到 Pro 签名类时，它才会启用。在同时安装 bundle 与 Pro 层级的情况下，受支持且已记录的签名配置是 baseline B-B 配置文件。

为了在 NextPDF 配置家族之间保持 schema 兼容性，signature.level 配置节点仍接受其他字符串值。此 bundle 交付并支持的签名能力是 B-B。超出 B-B 的签名配置文件、相关要求及运维考量，记录在 NextPDF Premium 文档中，本文有意不展开说明。

B-B 签名路径的运维注意事项：

• 签名器仅在 signature.enabled 为 true 且 已设置 signature.certificate 时才会注册；否则此区段保持惰性，不产生作用。
• 请通过 Symfony secrets 或环境变量提供证书、私钥与密码，绝不可提交到代码仓库。
• 请将密钥材料的读取权限限制给应用程序账号。

可选的日志功能

字体与图像注册表接受一个可选的 Psr\Log\LoggerInterface，并通过 nullOnInvalid() 绑定。当提供该 logger 时，它会作为遵循 PSR-3 logger 契约的可替换协作组件（PSR-3）。请从你在文档生成周边添加的任何日志上下文中清除可识别用户的数据；此 bundle 不会记录文档内容。

运维加固检查清单

• 请保留固定响应标头；在控制器层为已认证的下载添加更严格的缓存。
• 请在生成或返回文档前先对请求完成授权；此 bundle 不执行访问控制。
• 请将签名密钥材料以最小权限的文件权限存放于 Symfony secrets/环境变量中。
• 请使用最小权限账号运行 Messenger worker，并将其写入权限限制在输出目录内。
• 请保持启用 ext-mbstring 与 ext-zlib（否则此 bundle 会快速失败）。
• 请在应用程序中固定单一的 nextpdf/core 主版本，确保引擎版本在各次部署间保持确定。

符合性

每一行都是本页提出的一项规范性主张，并绑定到受管控 SDO 语料库中的一个完整 64-hex reference_id。provenance（来源信息），也就是语料库清单与检索传输，位于 _sidecars/rag-citations.yaml。

规范	条款	参考 ID	主张
PSR-11	psr_11_container#1.1.2.p5		has() 为 false 即意味着 get() 会抛出 NotFoundException
PSR-3	psr_3_logger#x3.p17		可选的 logger 协作组件

商业情境

唯有安装 nextpdf/premium（Pro）时，数字签名才可用；此 bundle 交付的配置文件是 baseline B-B。这是一项可选的 Pro 能力；本文记录的 Core bundle 无需任何代码变更即可采用它。请参阅 </get-license/?intent=symfony-pro>。

另请参阅

• /integrations/symfony/production-usage/ — worker 安全与流式传输。
• /integrations/symfony/configuration/ — signature、tsa 与服务对照表。
• /integrations/symfony/troubleshooting/ — 诊断签名与 Messenger 问题。
• /integrations/symfony/integration/ — 端到端接入参考。