NextPDF Connect 中 worker 安全的会话生命周期

概览

在长时间运行的 PHP worker（RoadRunner、Swoole、Laravel Octane）中使用正确的会话生命周期。每个请求都会创建自己的文件会话，并在 output_pdf 之后将其销毁。没有任何字体、页面或句柄状态会越过 worker 的请求边界而泄漏。这些工具包括 create_pdf、set_font、add_text 与 output_pdf — 全部都是 Core。

安装

composer require nextpdf/server

绑定一个传输层。此模式在任何传输层上的工作方式都相同。

概念总览

document_id 是一个不透明句柄，其范围仅限于单个请求。规则是 每个请求各自创建、每个请求各自销毁，绝不缓存或共享。在默认的 destroy: true 下，output_pdf 会在单个原子步骤中渲染文件并释放会话。同一个 worker 上的下一个请求会取得一个全新、独立的会话。先前会话的字体与内容都已不存在。每个工具的结果都是一个普通的传输层响应（PSR-18 §p2）。服务器代码本身则通过自动加载边界（PSR-4 §3）来隔离。会话存储区是唯一的跨请求状态，并以 id 作为键。

API 接口

工具	角色	风险层级
`create_pdf`	开启一个请求专属会话	安全
`set_font`	设置当前会话使用的字体	注意
`add_text`	写入内容	注意
`output_pdf`	渲染并销毁会话	需要批准/审查（base64）

工具目录是正式目录依据。你可使用的工具取决于已安装的层级。

代码范例 — 快速开始

请求 1：create_pdf → set_font → add_text → output_pdf（destroy: true）。同一个 worker 上的请求 2 会启动一个全新的 create_pdf 会话。旧的 id 现在已失效。请重新设置字体，因为它不会延续到下一个会话。

代码范例 — 正式环境

封装生命周期，确保清理工作一定会执行：

在请求开始时获取会话。
构建内容。
在等同于 finally 的代码块中，调用 output_pdf，它会销毁会话。如果你为了输出后检查流程而使用了 destroy: false，请改为显式销毁会话。

切勿将 document_id 存储在 worker 全局、静态变量或共享容器中。切勿在协程、fiber 或请求处理程序之间传递它。

边界情况与陷阱

销毁后重复使用 id。 会返回未知文件错误。请为每个请求创建新的会话。
忘记调用 output_pdf。 内存会悄然增长，直到会话 TTL 到期或进程重新启动为止。请务必完成收尾。
高负载下的会话上限。 存储区有并发上限。及时销毁可让你维持在上限之下。
使用 destroy: false 却未进行清理。 内存会逐渐增长。请仅在明确的输出后检查流程中使用它，之后再销毁会话。
在并发请求之间共享 id。 这是一种会损坏输出的竞态条件。每个请求都拥有自己的会话。

效能

每个请求的输出大小为几 KB。其优势在于 worker 在整个生命周期中的内存用量都受到限制。此配置文件为 structural。

安全性注意事项

会话隔离同时也是一项机密性属性。某个请求的内容绝不会传递到另一个请求，因为句柄不会共享，而且会话会在输出时销毁。

合规性

陈述	规格	条款	reference_id
每个工具的结果都是一个一般的传输层回应。	PSR-18	§p2
代码借由自动加载的类→文件对应来隔离。	PSR-4	§3

商业情境

不适用 — 所有工具均为 Core。

传输层可用性

传输层	是否可用	备注
MCP（stdio）	是	通常每个 worker 对应一个 stdio 进程。
REST	是	HTTP 请求边界对应会话边界。
gRPC	是	每个 RPC 序列对应一个会话。

HITL 风险层级

create_pdf 属于 Safe。set_font 与 add_text 属于 Caution。output_pdf 属于 Approval Required，在 base64 模式下会降级为 Review。在 worker 中，base64 输出是常见路径，且不会设置任何关卡（HITL 风险层级）。

确认关卡 JSON 封装

Base64 worker 输出：

{ "allowed": true }