跳到內容
NextPDF

部署 NextPDF Connect

概覽

標題為「概覽」的區段

REST 與 gRPC 傳輸都在 RoadRunner 的 worker pool 中執行。此套件提供三種 RoadRunner 設定檔：僅 HTTP、僅 gRPC，以及兩者合併的設定檔。MCP 傳輸則以單純的子行程（subprocess）執行，不需要 supervisor。

安裝

標題為「安裝」的區段
Terminal window
composer require nextpdf/server
./vendor/bin/rr get-binary

概念總覽

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

RoadRunner 是行程 supervisor（監督程序）。它負責管理 worker pool，在記憶體壓力過大時重啟 worker，並把每個請求路由到空閒的 worker。此 PHP 套件提供 worker 進入點：HTTP 使用 bin/nextpdf-server，gRPC 使用 bin/nextpdf-grpc。RoadRunner 會在這些進入點外層提供 pool。每個 worker 一次只處理一個請求。

MCP 傳輸的運作方式不同。bin/nextpdf-mcp 是單一 PHP 行程。它透過 stdio 進行 JSON-RPC 溝通，並由用戶端直接啟動。

API 介面

標題為「API 介面」的區段

RoadRunner 設定檔

標題為「RoadRunner 設定檔」的區段
設定檔傳輸指令
.rr.yaml僅 RESTrr serve -c .rr.yaml
.rr.grpc.yaml僅 gRPCrr serve -c .rr.grpc.yaml
.rr.full.yamlREST + gRPCrr serve -c .rr.full.yaml

HTTP 設定檔會把 REST 監聽器繫結在 0.0.0.0:8080。它在 :2114 提供狀態 endpoint，並在 :2112 提供 metrics。它依 NEXTPDF_WORKER_COUNT 設定 worker pool 的大小，預設為四。在隨附的設定檔中，supervisor 會把每個 worker 的記憶體上限設為 256 MB。

合併設定檔會在 tcp://0.0.0.0:9090 上加入 gRPC worker pool，其大小依 NEXTPDF_GRPC_WORKER_COUNT 決定，預設為二。它也會設定 gRPC 雙向 TLS。

程式碼範例 — 快速上手

標題為「程式碼範例 — 快速上手」的區段
Terminal window
export NEXTPDF_API_KEYS_FILE=/run/secrets/api-keys
./vendor/bin/rr serve -c .rr.full.yaml

程式碼範例 — 正式環境

標題為「程式碼範例 — 正式環境」的區段

以合併設定檔、檔案式金鑰，以及以 Redis 為後端的共用儲存執行正式環境容器：

docker/docker-compose.yml (production shape)
services:
  nextpdf-connect:
    image: ghcr.io/nextpdf-labs/server:latest
    command: ["rr", "serve", "-c", "/app/.rr.full.yaml"]
    ports:
      - "8080:8080"   # REST
      - "9090:9090"   # gRPC
    environment:
      - NEXTPDF_API_KEYS_FILE=/run/secrets/api-keys
      - NEXTPDF_WORKER_COUNT=8
      - NEXTPDF_GRPC_WORKER_COUNT=4
      - NEXTPDF_REDIS_HOST=redis
    secrets:
      - api-keys
    depends_on:
      redis:
        condition: service_healthy
    restart: unless-stopped
  redis:
    image: redis:8

邊界情況與陷阱

標題為「邊界情況與陷阱」的區段

  • 記憶體內儲存無法跨 worker 共用。 沒有 Redis 時，每個 worker 會各自保有自己的速率限制、idempotency 與文件儲存。使用記憶體內儲存的多 worker pool 會造成速率限制不一致，並在 worker 之間遺失文件。只要 pool 大於一個 worker，就要設定 NEXTPDF_REDIS_HOST 並安裝 ext-redis。若 Redis 連線失敗，伺服器會自動回退到記憶體內儲存。請確實驗證 Redis 的健康狀態，不要直接假設它正常。

  • job 儲存使用 WAL 模式的 SQLite。 非同步 job 會持久化到由所有 HTTP 與 gRPC worker 共用的單一 SQLite 檔案。請把這個檔案放在所有 worker 都能寫入的 volume 上。當 worker 關閉時，它會盡力（best-effort）把自己仍在執行中的 job 標記為失敗，因此這些 job 不會被遺留成孤兒。

  • bin/nextpdf-prune 是維運用的進入點。 它隨儲存庫提供，而不在 vendor/bin/ 中。執行儲存清理（prune）作業時，直接呼叫它。它並不是伺服器傳輸。

  • 映像的 PHP 版本可能沒有 ext-redis。 隨附的 Dockerfile 會盡力（best-effort）建置 ext-redis。若基礎 PHP 沒有可用的相容版本，它會在不含此擴充功能的情況下繼續。在你依賴 Redis 後端儲存之前，請先確認執行中的映像確實有這個擴充功能。

效能

標題為「效能」的區段

依可用的 CPU 與記憶體調整 NEXTPDF_WORKER_COUNT 的大小。每個 worker 都是一個 PHP 行程，受 supervisor 記憶體上限的限制。對於繪製（render）密集的工作負載，先從每個核心一個 worker 開始，再依 metrics endpoint 的數據調整。請獨立調整 gRPC pool 的大小。它通常比 HTTP pool 小，因為 gRPC 用戶端一般數量較少且存活時間較長。

安全性說明

標題為「安全性說明」的區段

gRPC 雙向 TLS

標題為「gRPC 雙向 TLS」的區段

合併設定檔會把 gRPC 傳輸設定為雙向 TLS：伺服器會出示一份憑證，並要求且驗證用戶端憑證。伺服器金鑰、伺服器憑證與用戶端 CA 是以部署 secret 的形式提供，而非烘焙進映像中。請在頻道外（out of band）產生並輪替這些憑證；不要在不受信任的網路上以明文監聽器執行 gRPC 傳輸。

REST TLS 終止

標題為「REST TLS 終止」的區段

REST 設定檔會繫結一個明文 HTTP 監聽器。請在它前面終止 TLS——例如反向 proxy、負載平衡器或 service mesh——並把監聽器只繫結到內部網路。請原封不動地透過 Authorization 標頭轉發用戶端身分；伺服器會自行執行金鑰驗證。監聽器本身並不提供安全傳輸；提供安全傳輸的是這套部署設定。

機密資訊（Secret）

標題為「機密資訊（Secret）」的區段

請使用 NEXTPDF_API_KEYS_FILE 指向一個 secret 檔案來掛載 API 金鑰，而不要使用內嵌的 NEXTPDF_API_KEYS 變數；檔案式儲存會在變更時熱重載，因此輪替不需要重啟。絕對不要把金鑰或 TLS 私密材料烘焙進映像中。請參閱 /connect/security-and-operations/。

一致性

標題為「一致性」的區段

部署機制本身不包含任何規範性的協定主張。驗證與傳輸安全的引用都釘選在 /connect/security-and-operations/。

商業情境

標題為「商業情境」的區段

把 nextpdf/premium 安裝進映像，即可在同一批 worker 中註冊額外的 Pro 與 Enterprise 工具。不會牽涉到任何獨立的行程或連接埠。封裝邊界是在映像建置時就確定的。

另請參閱

標題為「另請參閱」的區段
  • /connect/configuration/ — worker 數量、Redis 與層級上限
  • /connect/security-and-operations/ — TLS、雙向 TLS、secret 與威脅模型
  • /transports/rest/ · /transports/grpc/ — 各傳輸的執行階段細節
  • /connect/production-usage/ — 健康探測、擴展與可觀測性
  • /connect/troubleshooting/ — 診斷 worker、儲存與驗證失敗