部署 NextPDF Connect

概览

REST 与 gRPC 传输都在 RoadRunner 的 worker pool 中运行。该软件包提供三种 RoadRunner 配置文件：仅 HTTP、仅 gRPC，以及同时启用两者的配置文件。MCP 传输以普通子进程（subprocess）方式运行，不需要 supervisor。

安装

composer require nextpdf/server
./vendor/bin/rr get-binary

概念总览

RoadRunner 是进程 supervisor（管理程序）。它负责管理 worker pool，在内存压力过大时重启 worker，并将每个请求路由到空闲 worker。该 PHP 软件包提供 worker 入口点：HTTP 使用 bin/nextpdf-server，gRPC 使用 bin/nextpdf-grpc。RoadRunner 在这些入口点外层提供 pool。每个 worker 同一时间只处理一个请求。

MCP 传输的运行方式不同。bin/nextpdf-mcp 是单个 PHP 进程。它通过 stdio 使用 JSON-RPC 通信，并由客户端直接启动。

API 接口

RoadRunner 配置文件

配置文件	传输	命令
.rr.yaml	仅 REST	rr serve -c .rr.yaml
.rr.grpc.yaml	仅 gRPC	rr serve -c .rr.grpc.yaml
.rr.full.yaml	REST + gRPC	rr serve -c .rr.full.yaml

HTTP 配置文件会将 REST 监听器绑定到 0.0.0.0:8080。它在 :2114 提供状态 endpoint，并在 :2112 提供 metrics。它根据 NEXTPDF_WORKER_COUNT 设置 worker pool 的大小，默认为四。在随附的配置文件中，supervisor 将每个 worker 的内存上限设为 256 MB。

合并配置文件会在 tcp://0.0.0.0:9090 上加入 gRPC worker pool，其大小由 NEXTPDF_GRPC_WORKER_COUNT 决定，默认为二。它也会配置 gRPC 双向 TLS。

代码示例 — 快速上手

export NEXTPDF_API_KEYS_FILE=/run/secrets/api-keys
./vendor/bin/rr serve -c .rr.full.yaml

代码示例 — 生产环境

使用合并配置文件、基于文件的密钥以及 Redis 后端共享存储运行生产环境容器：

docker/docker-compose.yml (production shape)

services:
  nextpdf-connect:
    image: ghcr.io/nextpdf-labs/server:latest
    command: ["rr", "serve", "-c", "/app/.rr.full.yaml"]
    ports:
      - "8080:8080"   # REST
      - "9090:9090"   # gRPC
    environment:
      - NEXTPDF_API_KEYS_FILE=/run/secrets/api-keys
      - NEXTPDF_WORKER_COUNT=8
      - NEXTPDF_GRPC_WORKER_COUNT=4
      - NEXTPDF_REDIS_HOST=redis
    secrets:
      - api-keys
    depends_on:
      redis:
        condition: service_healthy
    restart: unless-stopped
  redis:
    image: redis:8

边界情况与陷阱

• 内存存储无法跨 worker 共享。 没有 Redis 时，每个 worker 都会各自持有自己的速率限制、idempotency 与文档存储。对多 worker pool 使用内存存储会导致速率限制不一致，并且文档会在不同 worker 之间丢失。只要 pool 大于一个 worker，就要设置 NEXTPDF_REDIS_HOST 并安装 ext-redis。如果 Redis 连接失败，服务器会自动回退到内存存储。请务必验证 Redis 的健康状态，不要直接假设它运行正常。

• job 存储使用 WAL 模式的 SQLite。 异步 job 会持久化到一个由所有 HTTP 与 gRPC worker 共享的单个 SQLite 文件中。请将该文件放在所有 worker 都能写入的 volume 上。worker 关闭时，会尽力（best-effort）将自己仍在运行的 job 标记为失败，因此这些 job 不会残留为孤儿。

• bin/nextpdf-prune 是运维用的入口点。 它随仓库提供，不在 vendor/bin/ 中。执行存储清理（prune）任务时，请直接调用它。它不是服务器传输。

• 镜像的 PHP 版本可能没有 ext-redis。 随附的 Dockerfile 会尽力（best-effort）构建 ext-redis。如果该基础 PHP 没有可用的兼容版本，它会在不包含此扩展的情况下继续。依赖 Redis 后端存储之前，请先确认运行中的镜像确实包含该扩展。

性能

根据可用 CPU 与内存调整 NEXTPDF_WORKER_COUNT 的大小。每个 worker 都是一个 PHP 进程，受 supervisor 内存上限限制。对于渲染（render）密集型工作负载，先从每个核心一个 worker 开始，再根据 metrics endpoint 的数据调整。请单独调整 gRPC pool 的大小。gRPC pool 通常比 HTTP pool 小，因为 gRPC 客户端一般更少，且存活时间更长。

安全性说明

gRPC 双向 TLS

合并配置文件会将 gRPC 传输配置为双向 TLS：服务器会出示证书，并要求和验证客户端证书。服务器密钥、服务器证书与客户端 CA 作为部署 secret 提供，而不是打包进镜像中。请在带外（out of band）生成并轮换这些证书；不要在不受信任的网络上使用明文监听器运行 gRPC 传输。

REST TLS 终止

REST 配置文件会绑定一个明文 HTTP 监听器。请在它前面终止 TLS，例如通过反向 proxy、负载均衡器或 service mesh，并将监听器仅绑定到内部网络。请原封不动地转发承载客户端身份的 Authorization 标头；服务器会自行执行密钥验证。监听器本身不提供安全传输；安全传输由这套部署配置提供。

机密信息（Secret）

请使用 NEXTPDF_API_KEYS_FILE 指向一个 secret 文件来挂载 API 密钥，而不要使用内嵌的 NEXTPDF_API_KEYS 变量；基于文件的存储会在变更时热重载，因此轮换不需要重启。绝对不要将密钥或 TLS 私密材料打包进镜像中。请参阅 /connect/security-and-operations/.

一致性

部署机制不包含任何规范性的协议主张。认证与传输安全的引用都固定在 /connect/security-and-operations/.

商业情境

将 nextpdf/premium 安装进镜像后，即可在同一批 worker 中注册额外的 Pro 与 Enterprise 工具。不会涉及任何独立进程或端口。封装边界在镜像构建时即已确定。

另请参阅

• /connect/configuration/ — worker 数量、Redis 与层级上限
• /connect/security-and-operations/ — TLS、双向 TLS、secret 与威胁模型
• /transports/rest/ · /transports/grpc/ — 各传输的运行时细节
• /connect/production-usage/ — 健康探测、扩展与可观测性
• /connect/troubleshooting/ — 诊断 worker、存储与认证失败