跳到內容
NextPDF

NextPDF Connect 整合

概覽

標題為「概覽」的區段

將 NextPDF Connect 作為伺服器執行，即可完成整合。你不會將函式庫接入宿主應用程式。先選擇一種傳輸方式（transport）；如果該傳輸會經過網路，再設定驗證。引擎工具一律位於確認 gate 之後。

安裝

標題為「安裝」的區段
Terminal window
composer require nextpdf/server

Composer 的版本限制為 nextpdf/core: ^3.0，搭配 php: >=8.4 <9.0。若要使用選用的 ext-redis 與 nextpdf/premium，請參閱 /connect/install/.

概念總覽

標題為「概念總覽」的區段

這個套件是一個獨立服務。不需要在宿主 Framework（框架）中註冊 service provider（服務提供者）、bundle 套件或容器模組。整合點就是你所執行的處理程序。每種傳輸都有自己的進入點（entry point），並各自獨立啟動。請參閱 /connect/boot-and-discovery/.

API 介面

標題為「API 介面」的區段
進入點傳輸設定檔（profile）
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

啟動與自動探索

標題為「啟動與自動探索」的區段

登錄表（registry）一律會探索核心層（core tier）。當 Pro 與 Enterprise 提供者的類別可以 resolve（解析）時，登錄表會接著把它們加入，然後在環境 gate 控制下載入隨附的 AST 與 mutation 提供者。enabled_tools 這份安全允許清單會再過濾上述所有內容，因此對外公開的工具目錄是此部署本身的屬性。請參閱 /connect/tool-catalog/ 與 /connect/boot-and-discovery/.

容器繫結

標題為「容器繫結」的區段

無。每個伺服器工廠（factory）都會明確建構自己的物件圖（object graph）。那些可注入的接縫（seam）是供測試使用，而不是供應用程式接線使用。

發布組態

標題為「發布組態」的區段

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 key，MCP 版本為 2025-06-18。請參閱 /transports/mcp/.
  • REST —— RoadRunner HTTP worker pool、OpenAPI 3.1 合約、bearer API key，以及依層級控管的路由。請參閱 /transports/rest/.
  • gRPC —— RoadRunner gRPC worker pool、nextpdf.connect.v1 Protobuf 服務、server-streaming RPC、metadata 中夾帶 bearer 的驗證，combined 設定檔下另有 mutual TLS。請參閱 /transports/grpc/.

只有在某種傳輸的進入點或 RoadRunner 設定檔正在執行時，該傳輸才算「可用」。各傳輸之間不會互相自動啟動。

HITL 風險層級

標題為「HITL 風險層級」的區段

每個工具都會宣告四種風險層級之一 —— safe、caution、review、approval_required。位於 approval_required 的工具在首次呼叫時不會執行。確認 gate 會發出一次性的挑戰權杖（challenge token），必須經由人為授權。組態覆寫只能調升工具的風險，絕不能調降 approval_required 工具。在所有會驅動工具的傳輸上，這套模型的套用方式都完全相同。請參閱 /connect/hitl-risk-tiers/.

確認 gate 的 JSON 封套

標題為「確認 gate 的 JSON 封套」的區段

gate 的檢查會回傳兩種 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）時仍會啟動，並提供其核心工具目錄。
  • 網路傳輸需要 key。 只有 /healthz 與 /readyz（REST），以及健康檢查 RPC（gRPC）是匿名的。

效能

標題為「效能」的區段

啟動成本就是登錄表掃描與層級偵測，每個處理程序只會執行一次。每個請求的成本就是引擎運算本身。請依觀察到的渲染延遲，調整 RoadRunner worker pool 的大小。請參閱 /connect/production-usage/.

安全注意事項

標題為「安全注意事項」的區段

網路傳輸會以 npk_live_ bearer key 進行驗證，並以固定時間（constant time）比對；無論使用哪種傳輸，gate 都會對破壞性操作強制要求人為確認。在不受信任的網路上，請在 REST 前方終結 TLS，並對 gRPC 使用 mutual 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/ —— 確認 gate 詳述
  • /connect/tool-catalog/ —— 依執行階段而定的工具目錄
  • /connect/security-and-operations/ —— 驗證與威脅模型