跳转到内容
NextPDF

安装 NextPDF Connect

快速概览

标题为“快速概览”的章节

使用 Composer 安装 nextpdf/server。随后从三个传输入口点中选择一个运行。核心安装只需要 PHP 8.4 与 NextPDF 引擎。Redis 与 Premium 均为可选项。

安装

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

这条命令会同时拉入 nextpdf/core: ^3.0。该包声明了 php: >=8.4 <9.0，因此在 PHP 8.3 及以下版本或 PHP 9 上，Composer 会拒绝安装。

概念总览

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

该包是一个 library 类型的 Composer 包。安装后会在 vendor/bin/ 中加入四个控制台入口点：

  • vendor/bin/nextpdf-mcp —— MCP stdio 服务器。
  • vendor/bin/nextpdf-server —— REST 服务器（RoadRunner HTTP worker）。
  • vendor/bin/nextpdf-grpc —— gRPC 服务器（RoadRunner gRPC worker）。
  • vendor/bin/generate-skills —— 将工具目录导出为 agent skills。

第五个脚本 bin/nextpdf-prune 随仓库提供，用于维护任务。你应直接运行它，而不是通过 vendor/bin/ 运行。

这里不涉及任何 service provider、bundle（包）或 Framework（框架）注册。服务器作为独立进程运行。它并不是用于接入宿主应用程序的库。

API 接口

标题为“API 接口”的章节

Composer 还会同时安装该包的运行时依赖。这些传递依赖包含 HTTP 与 gRPC 堆栈：

  • league/route 与 nyholm/psr7 —— REST 路由与 PSR-7 消息。
  • spiral/roadrunner-http 与 spiral/roadrunner-grpc —— 为 REST 与 gRPC 传输提供 RoadRunner worker 运行时。
  • psr/http-server-middleware 与 psr/http-server-handler —— REST 管线实现所需的 PSR-15 middleware（中间件）契约。
  • symfony/yaml —— 配置文件解析。
  • ramsey/uuid —— 请求与资源标识符。

你无需直接安装这些包。Composer 会基于 nextpdf/server 替你 resolve（解析）出这些依赖。

代码示例 —— 快速上手

标题为“代码示例 —— 快速上手”的章节

若要检查安装是否正常，可以在不启动服务器的情况下列出工具目录：

Terminal window
./vendor/bin/generate-skills --dry-run --list-tools

这条命令会启动注册表（registry）、运行层级检测，并打印这套安装公开的工具。该清单会反映当前安装了哪些可选包。请参阅 /connect/tool-catalog/。

代码示例 —— 生产环境

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

生产环境安装应锁定依赖版本，并跳过开发工具：

Terminal window
composer require nextpdf/server --no-dev
composer install --no-dev --optimize-autoloader --classmap-authoritative

若要使用 REST 与 gRPC 传输，还需要额外安装 RoadRunner 二进制文件。RoadRunner 是管理 worker 池的进程监督程序。这个 PHP 包提供的是 worker，而不是监督程序：

Terminal window
./vendor/bin/rr get-binary

边界情况与陷阱

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

  • 可选 Redis。ext-redis 扩展属于 suggest，而非 require。没有它时，REST 服务器会改用内存中的速率限制、idempotency（幂等）与文档存储。这些内存存储在单个 worker 内行为正确，但无法在多 worker 池之间共享。若是多 worker 部署，请安装 ext-redis 并设置 Redis 环境变量。请参阅 /connect/configuration/。

  • 可选 Premium。nextpdf/premium 也属于 suggest。当你把它和服务器一起安装时，注册表中的层级检测探测会找到它的 provider 类。随后，这些探测会注册额外的 Pro 与 Enterprise 工具。没有它时，只会提供核心目录。这是在 composer require 阶段做出的打包决策，而不是运行时的切换开关。

  • MCP 服务器不需要 RoadRunner。nextpdf-mcp 是一个通过 stdio 传输 JSON-RPC 的纯 PHP 进程。只有 REST 与 gRPC 传输才需要 RoadRunner。

性能

标题为“性能”的章节

安装时的开销主要来自 Composer 的依赖解析。在生产镜像中，请使用 --prefer-dist 并搭配权威 classmap，以降低冷启动时的自动加载时间。服务器自身的启动开销则来自注册表扫描与层级检测。本页的 performance_budget 会为这段启动开销设置上限。

安全须知

标题为“安全须知”的章节

请只从官方 Packagist 包 nextpdf/server 安装。请在 composer.json 中锁定版本，并提交 composer.lock，以确保部署出的工具目录可重现。在提供任何非健康检查端点之前，联网传输都必须先配置 API 密钥；请参阅 /connect/security-and-operations/。

符合性

标题为“符合性”的章节

本页只说明安装机制。协议与安全方面的符合性引用锁定在 /transports/mcp/、/transports/rest/、/transports/grpc/ 与 /connect/security-and-operations/。

商业背景

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

核心安装已经具备完整功能。它能在全部三种传输上处理文档创建、检查与诊断。加入 nextpdf/premium 可扩展工具目录，而无需改动传输或认证模型。

另请参阅

标题为“另请参阅”的章节
  • /connect/overview/ —— 这个包提供什么
  • /connect/quickstart/ —— 第一次可实际运行的交换
  • /connect/configuration/ —— 环境变量与配置文件
  • /connect/deployment/ —— RoadRunner、Docker 与多传输合并部署
  • /connect/tool-catalog/ —— 这套安装公开了哪些工具