跳转到内容
NextPDF

NextPDF Connect — gRPC 传输

概览

标题为“概览”的章节

gRPC 传输会在 RoadRunner 的 gRPC worker 池中运行 bin/nextpdf-grpc。它提供 nextpdf.connect.v1.NextPDFConnect 服务，支持服务器流式渲染，通过调用 metadata 中的 bearer token 进行验证，并在合并部署配置文件中配置双向 TLS。

安装

标题为“安装”的章节
Terminal window
composer require nextpdf/server
./vendor/bin/rr get-binary

概念总览

标题为“概念总览”的章节

gRPC 服务运行在 Spiral RoadRunner 的 gRPC worker 之后，与 REST 传输共用同一组应用服务：渲染、jobs、sessions、capabilities、operations。传输契约是 Protocol Buffers 包 nextpdf.connect.v1，由包中随附的 .proto 文件定义。

验证沿用 REST 的密钥存储区与验证流程。gRPC 验证器会读取 authorization metadata 键——gRPC 调用 metadata 通过 HTTP/2 标头传递——解析 Bearer npk_live_… token，并通过常数时间比对来验证 kid 与 SHA-256 摘要。当密钥缺失、格式错误、未知、已禁用或已过期时，验证器会使调用以 gRPC UNAUTHENTICATED 状态失败。如果验证实现不正确，就属于 OWASP API2:2023 的失效验证（Broken Authentication）风险；常数时间摘要比对是相应的缓解措施。

API 接口

标题为“API 接口”的章节

服务 RPC

标题为“服务 RPC”的章节

该 nextpdf.connect.v1.NextPDFConnect 服务提供一元（unary）与服务器流式 RPC：

RPC形式用途
Render一元（unary）同步渲染
RenderStream服务器流式渲染，并以区块流式传送
SubmitJob / GetJobStatus / GetJobResult / CancelJob一元（unary）异步 jobs
GetJobResultStream服务器流式异步结果，以流式传送
CreateSession / GetSession / DestroySession / SessionOperation / SessionRender一元（unary）有状态 sessions
SessionRenderStream服务器流式session 渲染，以流式传送
ExecuteCapability / GetCapabilities一元（unary）capability 分派与自省
HealthCheck / ReadinessCheck一元（unary）存活与就绪检查

由 ExecuteCapability 分派、受层级控制（tier-gated）的 operations，与 REST operation 路由相同；Pro 与 Enterprise operations 只有在安装对应包时才能访问。在签名分派场景中，搭配 Pro 的 NextPDF Connect 仅提供 PAdES baseline-B（B-B）签名。

流式

标题为“流式”的章节

服务器流式 RPC 会按顺序以区块流送出结果，适合大型 PDF 与渐进式传递。一元（unary）RPC 则在单一消息中返回完整结果。

代码示例——快速开始

标题为“代码示例——快速开始”的章节

使用仅启用 gRPC 的配置文件启动：

Terminal window
export NEXTPDF_API_KEYS='npk_live_k8a3b2c1_0123456789abcdef0123456789abcdef:demo:core:default'
./vendor/bin/rr serve -c .rr.grpc.yaml

使用你的 gRPC 工具链，根据随附的 proto 生成客户端：

Terminal window
# proto/nextpdf/connect/v1/*.proto — package nextpdf.connect.v1
protoc --proto_path=proto --<lang>_out=. proto/nextpdf/connect/v1/service.proto

每次调用都将 authorization 调用凭据 metadata 设置为 Bearer npk_live_{kid}_{secret}。

代码示例——生产环境

标题为“代码示例——生产环境”的章节

合并配置文件会通过双向 TLS 运行 gRPC：

Terminal window
export NEXTPDF_GRPC_TLS_KEY=/run/secrets/grpc-server.key
export NEXTPDF_GRPC_TLS_CERT=/run/secrets/grpc-server.crt
export NEXTPDF_GRPC_TLS_CA=/run/secrets/grpc-client-ca.crt
./vendor/bin/rr serve -c .rr.full.yaml

在此配置文件中，服务器会出示自身证书，并要求客户端提供证书且完成验证（require_and_verify_client_cert）。连接中断后，可以安全重试具幂等性的一元 job 提交——重复发送一个幂等请求的预期效果，与只发送一次请求相同（RFC 9110 §9.2.2）。

边界情况与陷阱

标题为“边界情况与陷阱”的章节

  • 是 UNAUTHENTICATED，而非 HTTP 状态。 token 错误或缺失时，RPC 会以 gRPC UNAUTHENTICATED 状态码失败，而非 401。bearer 机制和 npk_live_ 格式与 REST 完全相同。

  • 过多预先认证尝试会触发 RESOURCE_EXHAUSTED。 同一客户端身份反复发起预先认证尝试会被节流，并以 gRPC RESOURCE_EXHAUSTED 状态失败——这是 HTTP 429 在 gRPC 中的对应状态，与 REST 表面所采用的反自动化姿态相同。此控制默认启用，因此客户端应退避，不应立即重试。HTTP 速率限制的姿态请见 /connect/production-usage/.

  • 双向 TLS 是一项部署配置，而非默认。 gRPC 监听器需要正确预置的服务器密钥、服务器证书与客户端 CA secrets。缺少这些内容时，合并配置文件就不会提供服务；这是有意为之。请以带外（out of band）方式生成并轮换它们。

  • 层级控制仍然适用。 面向 Pro 或 Enterprise operation 的 ExecuteCapability，需要安装相应包，并使用具备权限的密钥。

  • 高风险 operations 仍会受到控制。 会驱动 ApprovalRequired 工具的 operations，会通过同一道人工介入（human-in-the-loop）关卡。请参阅 /connect/hitl-risk-tiers/.

性能

标题为“性能”的章节

每个 gRPC worker 一次处理一个调用。该池大小独立于 HTTP 池（默认两个 worker）配置，通常较小，因为 gRPC 客户端较少且生命周期较长。大型输出请使用服务器流式 RPC，以避免把整份 PDF 缓冲到单一消息中。

安全注意事项

标题为“安全注意事项”的章节

在任何不受信任的网络上，都必须以双向 TLS 运行 gRPC 传输——绝不使用明文监听器。请将客户端 CA、服务器密钥与服务器证书视为在运行时挂载的 secrets，绝不打包进镜像。bearer 验证是在证书之外额外强制执行的措施，而不是证书的替代。这种安全姿态只有在部署配置正确时才成立。请参阅 /connect/security-and-operations/ 与 /connect/deployment/.

符合性

标题为“符合性”的章节
主张来源reference_id
失效的验证会危及 API 安全OWASP API Security Top 10 标准，API2:2023
幂等请求可在失败后重试RFC 9110 §9.2.2

gRPC 协议本身属于外部规范，不在受控标准语料库中；具有正式效力的传输契约，是随附的 nextpdf.connect.v1 Protocol Buffers 定义。

商业背景

标题为“商业背景”的章节

ExecuteCapability 只有在服务器端安装 nextpdf/premium 时，才能访问 Pro 与 Enterprise operations。已安装的层级不会改变传输、验证与 TLS 配置。

另请参阅

标题为“另请参阅”的章节
  • /connect/security-and-operations/——验证、双向 TLS、威胁模型
  • /connect/deployment/——合并 RoadRunner 配置文件与 TLS secrets
  • /transports/mcp/ · /transports/rest/——其他传输
  • /connect/tool-catalog/——ExecuteCapability 如何映射到 catalog
  • /connect/production-usage/——jobs 与幂等重试