生产运维

速览

本页是将 NextPDF 部署到生产环境并持续保持其正常运行的检查清单。它对本手册做了精选导览：每一项都链接到承载详细内容的页面，因此你在这里核对、到那里深入阅读。首次发布之前，请逐项完成 部署前检查清单。作为日常运维 （day-two operations）的一部分，请定期回顾 升级节奏 和 事故分诊入口。

部署前检查清单

• 确认运行时：NextPDF 要求 PHP >=8.4 <9.0。Composer 会拒绝该区间之外的任何版本。参见 安装。
• 使用 php -m 验证六个必需的扩展：ext-mbstring、ext-zlib、ext-intl、 ext-gd、ext-curl 和 ext-openssl。安装页面 说明了每个扩展的作用。
• 运行 vendor/bin/nextpdf doctor 进行一次性的环境检查（在一份报告中同时给出 PHP 版本、扩展和字体可用性）。
• 在规划硬件规格之前，先确定你的渲染路径。进程内流水线（writeHtml()）不需要额外的服务。Artisan、Gotenberg 和 Cloudflare 各自都需要运维一个浏览器或网络服务。请借助 选择你的路径 来做决定。
• 如果你选择了某个 renderer 桥接器，请在上线前阅读其安全与运维页面。参见 加固 renderer 暴露面。
• 在构建时打包你实际用于渲染的字体，且仅打包这些字体。参见 在生产环境中配置字体。

资源规格设定

请按你生成的最大文档来设定规格，而不是按平均值。getPdfData() 会在内存中构建整个可移植文档格式（Portable Document Format，PDF）文档，并将其作为单个字符串返回。

• 根据 serverless 规格设定指南 设定 worker 或函数的内存：几页的文档在 512–1024 MB 下运行从容；图像密集或页数很多的文档则需要更多。
• 将超时设定在最坏情况构建时间之上，并留出余量。将超大的任务转移到写入对象存储的异步队列中——同一 规格设定章节 展示了这种模式。
• 为长期运行的 worker 启用 opcache，并关闭时间戳校验。Docker recipe 的 opcache 章节 提供了生产环境的 ini 取值。
• 如果上线后内存或吞吐量出现漂移，请从 症状到调节手段决策表 开始排查。

worker 安全规则

Document 是一次性的。构建它、只写出一次，然后让它离开作用域；为每个请求或每个队列任务创建一个全新的实例。只有进程生命周期级别的注册表——FontRegistry 和 ImageRegistry——才应共享，做法是在 worker 启动时创建一次。这与 PHP-FPM、队列 worker 和长期运行的应用服务器所采用的按请求、按任务的模型相吻合。

• 包含启动序列和每轮次重置的 recipe： worker 安全的批量渲染。
• 用一个答案概括这一契约： 它是否 worker 安全、线程安全？

加固 renderer 暴露面

请将 HTML 视为不可信内容，尤其是任何受用户影响的部分。 选择你的路径 阐明了这条边界：默认情况下， 内置流水线不运行任何脚本，也不获取任何远程资源；而每个桥接器都会通过浏览器或网络服务进行渲染。在将某个桥接器暴露给生产流量之前，请逐项完成其安全与运维页面：

• Artisan 安全与运维 — Chrome renderer 暴露面。
• Gotenberg 安全与运维 — Gotenberg 服务暴露面。
• Cloudflare 安全与运维 — 边缘部署暴露面。
• 以服务形式运行引擎？请补充阅读 Connect 安全与运维。

可观测性

NextPDF 不发布任何服务等级目标（service-level objective，SLO）；请根据你在下文所测量的渲染时长和内存指标，推导出你自己的目标。

请在第一次事故发生之前、而非之后，就为渲染路径接入观测埋点。

• 进程内引擎： 使用 OpenTelemetry 进行观测。
• NextPDF Connect 部署： Connect 的 OpenTelemetry recipe。
• 每次渲染都记录：wall time（挂钟时间）、峰值内存、页数、输出大小，以及结果及其来自 错误参考 的异常分类。
• 不仅要对失败告警，也要对趋势告警：构建时间上升、峰值内存上升，以及超时或内存耗尽的次数，都是 内存与性能条目 中的先行信号。

升级节奏

• 请通读一遍 版本支持策略，然后让所有发布都遵循它。它定义了语义化版本契约、稳定性标签、废弃生命周期，以及本手册使用的生命周期词汇（active、lts、maintenance、frozen、eol）。
• 提交 composer.lock，让每个部署的 worker 都解析到相同的引擎版本—— 安装页面 阐明了这一做法。
• 在每次版本升级之前，请查看 变更日志。

事故分诊入口

对于 renderer 桥接器的事故（Chrome 崩溃、Gotenberg 中断、边缘渲染失败），请从 加固 renderer 暴露面 中该桥接器的失败模式（failure-modes） 章节开始。

• 请从症状出发，而不是从类名出发，查阅 故障排查知识库。
• 在 错误参考 中将捕获到的异常映射到它的分类和上下文契约。

另请参阅

• 在生产环境中运维 NextPDF — Insider_ 系列文章，讲解引擎在负载下为何如此运作。
• 将 NextPDF 应用程序容器化 — 完整介绍生产环境的 Docker 镜像，从头到尾。
• 在 serverless 上部署 — Lambda、Cloud Run 和 App Runner 的具体细节。
• 在 Connect 上进行 worker 安全的渲染 — 将同样的生命周期规则应用到服务器上。