跳到內容
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 會拒絕安裝。

概念總覽

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

這個套件是 Composer 的 library 類型套件。安裝後會在 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/ —— 這套安裝公開哪些工具