NextPDF Connect 故障排查

快速概览

大多数故障都属于五大类之一：JSON-RPC 握手格式错误、缺少 API 密钥、当前层级未安装对应工具、未响应的确认挑战，或 worker（工作进程）之间未共享的存储。每一类都有明确的特征。

安装

composer require nextpdf/server

概念总览

MCP 传输会返回带有标准错误码的 JSON-RPC 2.0 错误对象。 REST 传输则返回 RFC 7807 问题详情文档。每一项都带有一个 type URL，用于识别相应状况。遇到环境问题时，先从诊断工具入手（diagnostic.doctor、diagnostic.capabilities）。这些工具始终包含在核心目录中。

API 接口

MCP JSON-RPC 错误码

错误码	名称	成因
`-32700`	解析错误	该行不是有效的 JSON
`-32600`	无效的请求	不是 JSON-RPC 2.0 消息（缺少 `jsonrpc`/`method`）
`-32601`	找不到方法	不属于以下任一方法：`initialize`、`tools/list`、`tools/call`
`-32602`	无效的参数	方法为 `tools/call` 时缺少 `params.name`
`-32603`	内部错误	工具在执行期间抛出异常

一个以正常方式失败的工具不会使用这些错误码。它会改为返回一个成功的 JSON-RPC 响应，其 result 带有 isError: true 和一段文字说明，例如未知工具、被策略停用或参数无效。

REST 问题详情类型

HTTP	`type` 识别码	成因
`401`	`unauthorized`	API 密钥缺失、无效、停用或已过期
`403`	`capability-denied`	密钥层级无权执行此操作
`413`	`payload-too-large` / `tier-payload-exceeded`	正文超出全局或层级上限
`422`	`validation-failed`	请求正文未通过结构描述验证
`429`	`ip-rate-exceeded` / `client-rate-exceeded`	触及速率限制
`404`	`not-found`	未知路由，或 job/session id
`504`	（请求超时）	操作超过该层级的超时上限

代码示例 —— 快速开始

运行环境健康检查。它不需要文件，也不需要确认：

./vendor/bin/nextpdf-mcp <<'EOF'
{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"diag","version":"1.0.0"}}}
{"jsonrpc":"2.0","method":"notifications/initialized"}
{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"diagnostic.doctor","arguments":{}}}
EOF

代码示例 —— 正式环境

在你调试「缺少工具」之前，先确认这个部署实际对外开放了哪些工具：

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

或者，针对正在运行的 REST 服务器：

curl -sS http://localhost:8080/api/v1/capabilities \
  -H "Authorization: Bearer $NEXTPDF_KEY"

边界情况与陷阱

Pro/Enterprise 工具出现「Unknown tool」。 该工具的包尚未安装。注册表会探测 provider 类，并在没有警告的情况下跳过未安装的层级。这是预期行为，并不是 bug。请在服务器端一并安装 nextpdf/premium，或改用核心工具。错误消息中会包含安装路径。
我在 enabled_tools 中设置的工具没有出现。 此允许列表会与探测到的工具取交集。它无法加入注册表没有找到的工具。请检查层级的安装状态以及任何环境 gate。举例来说，parse_pdf 需通过 NEXTPDF_MCP_TOOL_PARSE_PDF_ENABLED 主动启用。
tools/call 返回了要求令牌的文本。 那是确认挑战，不是错误。请在 300 秒内，将 _confirmation_token 设为签发的令牌，然后再次调用该工具。请参阅 /connect/hitl-risk-tiers/.
通知这一行没有产生输出。 这是正确行为。没有 id 的 JSON-RPC 消息属于通知，处理程序不会返回任何内容。请改为发送带有 id 的请求，以取得响应。
重复的请求 id 返回了过时的响应。 处理程序会按请求 id 在一个 64 条目的缓冲区中去重。请为每个逻辑请求使用全新的 id。
速率限制在多个 worker 之间表现异常。 内存存储按 worker 独立。若要共享计数，请设置 NEXTPDF_REDIS_HOST 并安装 ext-redis。请参阅 /connect/deployment/.
文件在不同请求之间消失了。 内存文件存储按 worker 独立，并受存活时间限制（document_ttl，默认 1800 秒）。若要让文件在多个 worker 之间保留，请使用 Redis 后端存储、session 端点，或将整组操作保持在单个同步渲染中完成。
尽管已设置 Redis，服务器仍退回内存模式。 若 Redis 连接在启动时失败，REST 服务器会自动退回内存模式。请检查 Redis 是否可连接，并确认正在运行的镜像内包含 ext-redis。不要在未经验证的情况下假设 Redis 正在使用中。
服务器因配置错误而拒绝启动。 某个 risk_level_overrides 项目试图将一个 ApprovalRequired 工具降级。加载器会按设计拒绝此操作。请移除该降级；覆盖只能调高风险等级。

效能

如果负载下渲染变慢，请确认 worker 池并未饱和。请检查 RoadRunner 的 metrics 端点。接着将长时间渲染移到异步 job 路径，以免占用 worker。请参阅 /connect/production-usage/.

安全性注意事项

不要为了规避 401 而把未经验证的 MCP 传输暴露到网络上——这等于完全移除了验证。请改为修正 API 密钥。不要为了查看工具参数而在共享环境中提高日志详细程度；参数内容可能包含敏感数据。请参阅 /connect/security-and-operations/.

合规性

本页属于操作指南。协议与安全性引用固定收录在 /transports/mcp/、/transports/rest/ 与 /connect/security-and-operations/.

另请参阅

/connect/tool-catalog/ —— 核心目录包含什么，以及数量为何会变化
/connect/hitl-risk-tiers/ —— 确认挑战的细节
/connect/deployment/ —— Redis、worker 池与存储共享
/connect/security-and-operations/ —— 验证失败与安全态势