NextPDF Connect 生产环境运行指南

概览

生产环境中的 NextPDF Connect 部署会对外开放若干运维接口：健康与就绪探测、同步与异步渲染路径、idempotency（幂等性）控制、按客户端与按 IP 的流量限制，以及可选的有状态会话。本页说明你如何操作这些接口。

安装

composer require nextpdf/server

概念总览

REST 传输是一条 PSR-15 middleware（中间件）管线。每个请求都会依次通过这些 middleware：request-id 分配、主体大小限制、CORS、身份验证、能力授权、流量限制、idempotency 以及超时，随后才会抵达 handler（处理器）。gRPC 传输则在 RoadRunner gRPC worker 之后复用同一套应用程序服务。

渲染有两种形式。同步的 POST /api/v1/render 会执行各项操作，并在响应中返回 PDF。异步任务则使用 POST /api/v1/jobs。它会立即返回一个 job id，之后你可以从 GET /api/v1/jobs/{id}/result 获取结果。任务会保存在共享的 SQLite 存储区中，因此任一 worker 都能处理状态或结果查询。

API 接口

健康与就绪

endpoint（端点）	验证	含义
GET /healthz	无	进程仍存活
GET /readyz	无	服务器已就绪，可接受请求

请将 /healthz 接入 liveness 探测，将 /readyz 接入 readiness 探测。这两个 endpoint 都允许匿名访问，因此编排器不需要任何凭证。

异步任务

端点	方法	用途
/api/v1/jobs	POST	提交渲染任务
/api/v1/jobs/{id}	GET	任务状态
/api/v1/jobs/{id}/result	GET	任务结果（即 PDF）
/api/v1/jobs/{id}	DELETE	取消任务

会话（可选启用）

当 NEXTPDF_SESSIONS_ENABLED 设为 true 且工具已就绪时，会话 endpoint 会对外开放有状态的构建流程。你会先创建一个会话，添加页面、文本、图像、表格与 HTML，设置字体，然后渲染。会话有按客户端计算的数量上限和空闲超时。默认关闭。

代码示例 — 快速上手

提交异步任务，并轮询获取结果：

JOB=$(curl -sS -X POST http://localhost:8080/api/v1/jobs \
  -H "Authorization: Bearer $NEXTPDF_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"operations":[{"type":"add_text","text":"async render"}]}' \
  | python3 -c 'import sys,json;print(json.load(sys.stdin)["id"])')

curl -sS "http://localhost:8080/api/v1/jobs/$JOB/result" \
  -H "Authorization: Bearer $NEXTPDF_KEY" --output out.pdf

代码示例 — 生产环境

通过发送一组 idempotency key，让提交操作可以安全重试：

curl -sS -X POST http://localhost:8080/api/v1/jobs \
  -H "Authorization: Bearer $NEXTPDF_KEY" \
  -H 'Idempotency-Key: 7b1c2d3e-…' \
  -H 'Content-Type: application/json' \
  -d '{"operations":[{"type":"add_text","text":"safe retry"}]}'

以相同 idempotency key 重放的请求会返回原本的结果，而不会创建第二个任务。这让提交操作在发生通信失败后仍可安全地再次发送。这种安全性来自幂等方法的特性：重复发送请求所达到的预期效果，与只发送一次相同（RFC 9110 §9.2.2）；因此，当连接在读到响应之前就中断时，请求可以自动重试（RFC 9110 §9.2.2）。

边界情况与陷阱

• 流量限制需要 Redis 才能在多个 worker 间保持正确。 按客户端与按 IP 的限制器会使用已配置的存储区。如果使用内存存储区且 worker 不止一个，每个 worker 都会独立计数，实际限制会按 worker 数量倍增。任何多 worker 池都应改用 Redis 存储区。

• 被限流的请求会返回 429。 当超出限制时，服务器会按照流量限制状态语义返回 429 Too Many Requests，并附带一个 Retry-After 标头（RFC 6585 §4）。请遵循 Retry-After，不要立即重试。

• 任务结果不会永久保留。 任务存储区会在条目超过 NEXTPDF_JOB_GC_MAX_AGE_SECONDS 之后，对旧条目执行垃圾回收。请在结果过期之前获取它们。

• 会话会消耗内存。 一个会话会持有一份进行中的文档。按客户端计算的会话上限与空闲超时会限制这项成本。在尚未针对最坏情况估算内存之前，请勿调高它们。

性能

同步路径会在整个渲染过程中占用一个 worker。对于大型或耗时的渲染，请优先采用异步任务路径：它会立即释放 worker，再由客户端轮询获取结果。请根据观测到的渲染延迟与并发量规划 worker 池大小，并关注 RoadRunner 的 metrics endpoint。

安全须知

除健康探测外，每个 endpoint 都需要一组有效的 API key。客户端的方案层级会限制允许的操作和负载大小。idempotency key 由客户端提供。请将它们视为不透明值，并确保每个逻辑操作对应的 key 都唯一。请参阅 /connect/security-and-operations/。

符合性

主张	来源	reference_id
幂等：重复的请求 = 单一效果	RFC 9110 §9.2.2
幂等请求在失败后可重试	RFC 9110 §9.2.2
429 + Retry-After 用于流量限制	RFC 6585 §4

商业情境

当这些工具已安装时，Pro 与 Enterprise key 在各方案层级的负载与超时上限会提高。core 层级的上限适用于默认部署。

另请参阅

• /connect/deployment/ — worker 池、Redis、RoadRunner profile
• /transports/rest/ — 完整的 middleware 管线与 OpenAPI 合约
• /connect/troubleshooting/ — 诊断 401/403/413/429/5xx 与存储区失败
• /connect/security-and-operations/ — 身份验证与流量限制的部署态势