跳转到内容
NextPDF

NextPDF Connect 集成

概览

标题为“概览”的章节

要完成集成，只需将 NextPDF Connect 作为服务器运行。你无需把某个库接入宿主应用。选择一种传输方式；如果该传输方式基于网络，再配置身份认证。引擎工具位于确认门之后。

安装

标题为“安装”的章节
Terminal window
composer require nextpdf/server

Composer 约束为 nextpdf/core: ^3.0，并配合 php: >=8.4 <9.0。有关可选的 ext-redis 和 nextpdf/premium，请参阅 /connect/install/.

概念概述

标题为“概念概述”的章节

这个软件包是一个独立服务。无需在宿主框架中注册任何服务提供者、bundle 或容器模块。集成点就是你运行的那个进程。每种传输方式都有各自的入口点，并且独立启动。请参阅 /connect/boot-and-discovery/.

API 接口面

标题为“API 接口面”的章节
入口点传输方式配置文件
bin/nextpdf-mcp基于 stdio 的 MCP（无 —— 直接子进程）
bin/nextpdf-server基于 RoadRunner HTTP 的 REST.rr.yaml
bin/nextpdf-grpc基于 RoadRunner gRPC 的 gRPC.rr.grpc.yaml
两种网络传输方式REST + gRPC.rr.full.yaml

启动与自动发现

标题为“启动与自动发现”的章节

注册表会无条件发现 core 层级。随后，如果 Pro 和 Enterprise 提供者的类可以解析，注册表会纳入这些提供者；接着在环境开关控制下纳入随附的 AST 和变异（mutation）提供者。enabled_tools 安全允许列表会过滤所有这些工具，因此对外暴露的目录是该部署的一项属性。请参阅 /connect/tool-catalog/ 和 /connect/boot-and-discovery/.

容器绑定

标题为“容器绑定”的章节

没有。每个服务器工厂都会显式构建自己的对象图。这些可注入的接缝用于测试，而不是用于应用接线。

发布配置

标题为“发布配置”的章节

MCP 服务器接受一个可选的 YAML 文件（--config=PATH，nextpdf_mcp 区段）以及 NEXTPDF_MCP_* 环境变量覆盖项。REST 和 gRPC 服务器读取 NEXTPDF_* 环境变量。详情请参阅 /connect/configuration/.

传输可用性（MCP / REST / gRPC）

标题为“传输可用性（MCP / REST / gRPC）”的章节

这三种传输方式都使用同一个注册表：

  • MCP —— 本地子进程，基于 stdio 的 JSON-RPC 2.0，无需 API 密钥，MCP 修订版 2025-06-18。参阅 /transports/mcp/.
  • REST —— RoadRunner HTTP 工作进程池，OpenAPI 3.1 契约，Bearer API 密钥，按层级门控的路由。参阅 /transports/rest/.
  • gRPC —— RoadRunner gRPC 工作进程池，nextpdf.connect.v1 Protobuf 服务，服务端流式 RPC，通过元数据携带 Bearer 完成身份认证，并在组合配置文件中采用双向 TLS。参阅 /transports/grpc/.

只要某种传输方式的入口点或 RoadRunner 配置文件正在运行，它就处于「可用」状态。各传输方式不会相互自动启动。

HITL 风险层级

标题为“HITL 风险层级”的章节

每个工具都会声明四种风险层级之一 —— safe、caution、review、approval_required。位于 approval_required 的工具，首次调用时不会执行。确认门会发出一个一次性挑战令牌（challenge token），必须由人工授权。配置覆盖只能调高工具的风险，绝不能调低一个 approval_required 工具。无论由哪种传输方式驱动工具，该模型的应用方式都完全相同。请参阅 /connect/hitl-risk-tiers/.

确认门的 JSON 封套

标题为“确认门的 JSON 封套”的章节

确认门检查会返回两种 JSON 形态之一。允许时：

{ "allowed": true }

挑战时：

{
  "allowed": false,
  "challenge": "<human-readable text naming the operation, its description, an overwrite warning when applicable, and the re-invocation instruction>",
  "token": "confirm_<nonce>"
}

该令牌绑定的是工具名称、一个随机 nonce 以及 300 秒的 TTL —— 而不是参数。若要继续，调用方需重新调用同一个工具，并把 _confirmation_token 参数设为所发出的令牌。该挑战只是说明文字加上令牌；它并不是经过密码学签名的封套。请参阅 /connect/hitl-risk-tiers/.

服务冒烟测试

标题为“服务冒烟测试”的章节
Terminal window
./vendor/bin/generate-skills --dry-run --list-tools

这会启动注册表与层级检测，然后打印出对外暴露的工具，但不会实际提供流量服务。这是一种快速检查方式，用来确认集成已接好，并查看这套安装会产生哪份工具目录。

边界情况与陷阱

标题为“边界情况与陷阱”的章节
  • 没有框架挂钩。 不要寻找服务提供者或 bundle。集成的本体就是那个正在运行的进程。
  • 缺少某个层级并不是错误。 仅安装核心（core-only）的安装照样会启动，并提供它的核心工具目录。
  • 网络传输需要密钥。 只有 /healthz 和 /readyz（REST）以及健康检查 RPC（gRPC）是匿名的。

性能

标题为“性能”的章节

启动开销来自注册表扫描与层级检测，每个进程只执行一次。每个请求的开销就是引擎运算本身。请根据观察到的渲染延迟，调整 RoadRunner worker pool 的大小。请参阅 /connect/production-usage/.

安全注意事项

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

网络传输会使用 npk_live_ bearer key 进行身份认证，并以固定时间（constant time）比对；无论使用哪种传输，确认门都会对破坏性操作强制要求人工确认。在不受信任的网络上，请在 REST 前面终结 TLS，并对 gRPC 使用双向 TLS。请参阅 /connect/security-and-operations/.

符合性

标题为“符合性”的章节

协议与安全相关的引用已固定在 /transports/mcp/、/transports/rest/、/transports/grpc/ 和 /connect/security-and-operations/.

商业背景

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

在服务器旁一并安装 nextpdf/premium，会把额外的 Pro 和 Enterprise 工具注册到同一个正在运行的服务器中。不会涉及另一个独立的进程。

另请参阅

标题为“另请参阅”的章节
  • /connect/overview/ —— 架构
  • /connect/quickstart/ —— 首次可运行的往返
  • /transports/mcp/ · /transports/rest/ · /transports/grpc/ —— 各传输方式的参考文档
  • /connect/hitl-risk-tiers/ —— 确认门详解
  • /connect/tool-catalog/ —— 取决于运行时的工具目录
  • /connect/security-and-operations/ —— 身份认证与威胁模型