跳转到内容
NextPDF

NextPDF Connect 启动与发现

概览

标题为“概览”的章节

每个传输都有自己的入口点和启动流程。这些传输在概念上共用注册表（registry）、配置与 gate。它们在彼此独立的进程中运行，因此启动其中一个并不会连带启动其他传输。

安装

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

概念总览

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

MCP 启动顺序

标题为“MCP 启动顺序”的章节

McpServer::create() 会按固定顺序连接 MCP 服务器。它先加载配置，根据该配置构建安全性策略，建立工具注册表，并执行层级发现。随后，它按设定的 TTL 与容量建立内存中的文档存储区，建立 stdio 传输，并组装带有确认 gate 与审计日志记录器的 JSON-RPC 协议处理器。完成上述步骤后，服务器便进入“读取—处理—写入”循环，并持续运行到标准输入到达文件结尾为止。

REST 启动顺序

标题为“REST 启动顺序”的章节

HttpServer::create() 会从环境读取 HttpConfig，并应用 CLI 覆盖项。接着，它按以下优先级 resolve（解析） API 密钥存储区：先使用可热重载的文件存储区，再使用静态文件，最后才使用环境。然后，它解析速率限制与幂等性存储区；当 Redis 已配置且可连接时，二者会使用 Redis，否则退回内存存储。接着，它打开共用的 SQLite 作业存储区，构建应用服务，并建立路由表。由于路由表是根据检测到的层级建立的，因此会反映实际安装的软件包。最后，由 RoadRunner 驱动 worker 的请求循环。

gRPC 启动顺序

标题为“gRPC 启动顺序”的章节

GrpcServer::create() 会解析同一个密钥存储区、构建同一组应用服务，并通过 Spiral gRPC worker 注册 nextpdf.connect.v1 服务。当引擎依赖不可用时，gRPC 服务器仍会启动，并继续提供健康状态与能力查询。在这种状态下，进程并不会拒绝启动；相应地，承载数据的 RPC 会以明确、可控的方式失败。

工具发现

标题为“工具发现”的章节

发现过程就是注册表的默认注册步骤。core 层级会最先注册。随后，若 Pro 与 Enterprise 提供者的类能通过 class_exists() 解析到，它们也会注册。之后，内置的 AST 与 mutation 提供者会在 Pro 层级下注册，并受其环境 gate 约束。每次注册都会经过 enabled_tools 安全性允许列表过滤，而各层级最终的工具数量会报告到 MCP 的 initialize 响应中。请参阅 /connect/tool-catalog/。

传输发现

标题为“传输发现”的章节

没有任何单一配置项可以“启用传输”。每个传输都是独立的入口点。REST 与 gRPC 各自拥有独立的 RoadRunner 配置文件。部署会根据运行时使用的配置文件来选择传输：.rr.yaml 对应 REST，.rr.grpc.yaml 对应 gRPC，而 .rr.full.yaml 则同时包含二者。这些传输会在彼此独立的进程中运行。缺少 MCP 客户端绝不会阻止 REST 服务器，缺少 REST 客户端也绝不会阻止 MCP。请参阅 /connect/deployment/。

配置解析顺序

标题为“配置解析顺序”的章节

MCP 服务器会按以下优先级解析配置：环境（NEXTPDF_MCP_*）优先于 YAML 文件的 nextpdf_mcp 区段，而后者又优先于内置默认值。REST 与 gRPC 服务器则会读取 HttpConfig，其来源为 NEXTPDF_* 环境变量，并带有安全的默认值。它们并不会读取 MCP 的 YAML 文件。请参阅 /connect/configuration/。

容器绑定

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

这里没有需要注册的依赖注入容器或服务提供者。每个 create() 工厂都会以明确且确定的方式构建自己的对象图。这里存在两个可注入的接缝——传输与 worker 工厂——但二者都用于测试，而不是用于应用程序装配。

代码示例——快速上手

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

在不对外接收流量的情况下，查看发现过程产生了哪些结果：

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

代码示例——生产环境

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

在同一个监管进程下启动合并后的传输：

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

边界情况与陷阱

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

  • 缺少某个层级不会导致启动失败。 层级发现会静默跳过不存在的 Pro 或 Enterprise 软件包。服务器会带着 core 工具目录启动。

  • 降级覆盖会导致启动失败。 若某个 risk_level_overrides 条目削弱了一个 approval_required 的工具，便会在配置加载时抛出异常；服务器会拒绝启动。这是有意为之的设计。

  • Redis 失败只会触发降级，不会崩溃。 若 Redis 已配置却在启动时无法连接，REST 服务器会退回到内存存储区。请确认 Redis 的健康状态，而不要直接假设 Redis 正在使用中。

性能

标题为“性能”的章节

启动成本包括配置解析，再加上注册表扫描与层级检测。performance_budget 页面会为这项成本设定上限。该成本只在每次进程启动时发生一次，而不是每次请求都会发生。

安全性注意事项

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

安全性策略会在注册表之前先建立，因此 enabled_tools 允许列表从第一次注册起就会约束发现。API 密钥绝不会从 MCP 的 YAML 文件读取；面向网络的传输会从密钥文件或环境解析密钥。请参阅 /connect/security-and-operations/。

符合性

标题为“符合性”的章节

本页描述的是启动机制。协议与安全性的引用来源固定列在 /transports/mcp/、/transports/rest/、/transports/grpc/ 以及 /connect/security-and-operations/。

商业情境

标题为“商业情境”的章节

启动时的层级检测，是 nextpdf/premium 唯一将其 Pro 与 Enterprise 工具贡献到目录的时间点，前提是 nextpdf/premium 与服务器一起安装。

另请参阅

标题为“另请参阅”的章节
  • /connect/tool-catalog/ —— 发现过程注册了哪些工具，以及数量为什么会变化
  • /connect/configuration/ —— 详述解析顺序
  • /connect/deployment/ —— 通过 RoadRunner 配置文件选择传输
  • /transports/mcp/ · /transports/rest/ · /transports/grpc/ —— 各传输的详细说明