在 NextPDF Connect 中执行环境诊断

概览

在处理实际工作负载前，请先确认 NextPDF Connect 服务器运行正常，并且具备你的工作流程所需的能力。这是任何代理式管线都建议优先执行的第一步。这些工具已经对照服务器工具注册表重新验证，分别为 diagnostic.doctor、diagnostic.capabilities 与 diagnostic.verify。注册表以点分隔的协议名称公开这些工具，另有一个相关的 diagnostic.inspect。它们全部属于 Core。

安装

composer require nextpdf/server

绑定一种传输。veraPDF 仅在可选的合规验证步骤中需要；结构验证不需要任何外部工具。

概念总览

• diagnostic.doctor 会返回一份基准健康报告：PHP 版本、已加载的扩展、服务器版本、当前生效的层级，以及任何警告。请将 status 视为闸门：在 ok 时继续，在 warning 时阅读 warnings，并在 error 时停止。
• diagnostic.capabilities 会列出已注册的能力，以及对应层级与执行阶段状态（available、unavailable、degraded）。能力数量取决于执行阶段与层级，因此请勿硬编码总数。请逐项检查工作流程所依赖的每一项能力。
• diagnostic.verify 会检查结构完整性：PDF 标头、EOF 标记与交叉引用表。检查目标是可通过页面树抵达的文件结构（ISO 32000-2 §7.5）。搭配 compliance_flavour 使用时，它还会调用 veraPDF。

诊断结果在每一种传输中都是正常响应（PSR-18 §p2）。

API 接口

工具	角色	风险层级
diagnostic.doctor	环境健康报告	Safe
diagnostic.capabilities	能力列表与状态	Safe
diagnostic.verify	结构/合规验证	Safe
create_pdf、add_text、output_pdf	对文件执行冒烟测试	如他处所述

这些名称是注册表中的协议名称。工具目录才是正式的目录记录。可用的工具与能力取决于已安装的层级，因此切勿断言固定的工具或能力数量。

代码示例 — 快速上手

1. diagnostic.doctor（无参数）→ 读取 status。
2. diagnostic.capabilities（无参数）→ 确认每一项所需能力均为 available。
3. create_pdf 然后 add_text → 生成一份最小的冒烟测试文件。
4. 带 document_id 的 diagnostic.verify → 结构检查。
5. 可选：以 compliance_flavour: "4" 执行 diagnostic.verify → veraPDF。
6. output_pdf（base64）→ 销毁冒烟测试会话。

代码示例 — 生产环境

以 diagnostic.doctorstatus 作为管线闸门。将每一项工作流程依赖映射到特定的能力 id，并在执行依赖该能力的步骤之前断言其为 available。请将 degraded 视为需要抽查的质量风险。一律执行结构性的 diagnostic.verify。仅在符合性重要的场景才执行合规变体；如果 veraPDF 不存在，应接受明确返回的 not-found 结果，而非将其视为服务器缺陷。

边缘案例与陷阱

• veraPDF 不存在。 合规调用会返回一个明确的 not-found 结果。结构检查仍可运行。若你需要合规验证，请安装 veraPDF 并将它放到服务器进程的 PATH 上。
• veraPDF 超时。 大型文件可能会触发验证超时。请缩小文件大小，或在服务器设置中调高超时时间。
• degraded 能力。 某项依赖仅部分可用，因此输出质量可能下降。请检查服务器日志，以了解当前使用的回退方案。
• Doctor error。 有一项关键需求未满足。请勿继续进行。

性能

结构验证很快。合规路径会派生 veraPDF，并受验证超时时间限制。较宽松的预算反映了该子进程的开销。

安全注意事项

诊断输出会泄露环境细节：PHP 版本、扩展与层级。请将它视为仅供运维人员使用的信息，不要公开给不受信任的调用方。

符合性

陈述	规范	条款	reference_id
诊断结果是正常的传输响应。	PSR-18	§p2
结构完整性以页面树锚定的结构为检查目标。	ISO 32000-2	§7.5

合规变体会执行 veraPDF 并报告其裁定。NextPDF 本身并不断言符合性；裁定由验证器决定。

商业情境

不适用 — 所有诊断工具均属于 Core。

传输可用性

传输	可用	备注
MCP（stdio）	是	诊断结果即工具结果。
REST	是	健康端点映射到这些工具。
gRPC	是	一元（Unary）；结果携带相同的状态字段。

HITL 风险层级

三项诊断工具都属于 Safe：只读、无副作用。它们绝不会触发确认闸门。冒烟测试的 output_pdf 为 base64 模式（Review，无闸门）。

确认闸门 JSON 封套

诊断绝不会设置闸门。

{ "allowed": true }

参见

• Hello world
• 版面检查
• 工具目录