NextPDF Connect 正式環境使用指南

概覽

正式環境的 NextPDF Connect 部署會對外開放數個操作介面：健康與就緒探測、同步與非同步繪製路徑、idempotency（冪等性）控制、依用戶端與依 IP 的流量限制，以及選用的具狀態工作階段。本頁說明你該如何操作這些介面。

安裝

composer require nextpdf/server

概念總覽

REST 傳輸是一條 PSR-15 middleware（中介層）管線。每個請求都會依序經過這些 middleware：request-id 指派、主體大小限制、CORS、身分驗證、能力授權、流量限制、idempotency，以及逾時。之後才會抵達 handler（處理器）。gRPC 傳輸則位於 RoadRunner gRPC worker 之後，重用同一套應用程式服務。

繪製有兩種形式。同步的 POST /api/v1/render 會執行各項操作，並在回應中回傳 PDF。非同步工作則使用 POST /api/v1/jobs。此 endpoint 會立即回傳一個 job id，之後你再從 GET /api/v1/jobs/{id}/result 取得結果。工作會保存在共用的 SQLite 儲存區，因此任一 worker 都能處理狀態或結果查詢。

API 介面

健康與就緒

endpoint（端點）	驗證	意義
GET /healthz	無	行程仍存活
GET /readyz	無	伺服器已就緒，可接受請求

請將 /healthz 接到 liveness 探測，將 /readyz 接到 readiness 探測。這兩個 endpoint 都允許匿名存取，所以編排器不需要任何憑證。

非同步工作

端點	方法	用途
/api/v1/jobs	POST	提交繪製工作
/api/v1/jobs/{id}	GET	工作狀態
/api/v1/jobs/{id}/result	GET	工作結果（即 PDF）
/api/v1/jobs/{id}	DELETE	取消工作

工作階段（選擇性啟用）

當 NEXTPDF_SESSIONS_ENABLED 設為 true 且工具已備妥時，工作階段 endpoint 會對外開放具狀態的建構流程。你會先建立工作階段，加入頁面、文字、影像、表格與 HTML，設定字型，然後繪製。工作階段會套用依用戶端計算的數量上限與閒置逾時。預設為關閉。

程式碼範例 — 快速上手

提交非同步工作，並透過輪詢取得結果：

JOB=$(curl -sS -X POST http://localhost:8080/api/v1/jobs \
  -H "Authorization: Bearer $NEXTPDF_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"operations":[{"type":"add_text","text":"async render"}]}' \
  | python3 -c 'import sys,json;print(json.load(sys.stdin)["id"])')

curl -sS "http://localhost:8080/api/v1/jobs/$JOB/result" \
  -H "Authorization: Bearer $NEXTPDF_KEY" --output out.pdf

程式碼範例 — 正式環境

透過送出一組 idempotency key，讓提交作業可以安全重試：

curl -sS -X POST http://localhost:8080/api/v1/jobs \
  -H "Authorization: Bearer $NEXTPDF_KEY" \
  -H 'Idempotency-Key: 7b1c2d3e-…' \
  -H 'Content-Type: application/json' \
  -d '{"operations":[{"type":"add_text","text":"safe retry"}]}'

以相同 idempotency key 重播的請求會回傳原本的結果，而不會建立第二個工作。這讓提交作業在發生通訊失敗後，仍可安全地重複送出。這種安全性正是冪等方法所提供的特性：重複送出請求所達成的預期效果，與只送一次相同（RFC 9110 §9.2.2），因此當連線在讀到回應之前中斷時，請求可以自動重試（RFC 9110 §9.2.2）。

邊際情況與陷阱

• 流量限制需要 Redis 才能在多個 worker 間維持正確。 依用戶端與依 IP 的限制器使用已設定的儲存區。若使用記憶體內儲存區，而且 worker 不只一個，每個 worker 都會各自獨立計數，實際限制就會被 worker 數量倍增。任何多 worker 集區都請改用 Redis 儲存區。

• 被節流的請求會回傳 429。 當超出限制時，伺服器會依流量限制的狀態語義，回應 429 Too Many Requests 以及一個 Retry-After 標頭（RFC 6585 §4）。請遵循 Retry-After，而不是立刻重試。

• 工作結果不會永久保留。 工作儲存區會在項目超過 NEXTPDF_JOB_GC_MAX_AGE_SECONDS 之後，透過垃圾回收移除舊項目。請在結果逾期之前取得它們。

• 工作階段會耗用記憶體。 每個工作階段都會保有一份進行中的文件。依用戶端設定的工作階段上限與閒置逾時會限制這項成本。在尚未針對最壞情況估算記憶體之前，請勿調高這些設定。

效能

同步路徑會在整個繪製過程中佔用一個 worker。對於大型或耗時的繪製，請優先採用非同步工作路徑：它會立即釋出 worker，再由用戶端輪詢取得結果。請依觀測到的繪製延遲與並行量來規劃 worker 集區的大小，同時留意 RoadRunner 的 metrics endpoint。

安全性須知

除了健康探測之外，每個 endpoint 都需要一組有效的 API key。用戶端的方案層級會限制可用操作與酬載大小上限。idempotency key 是由用戶端提供的。請將這些 key 視為不透明，並確保每個邏輯操作使用的 key 都唯一。請參閱 /connect/security-and-operations/.

符合性

主張	來源	reference_id
冪等：重複的請求 = 單一效果	RFC 9110 §9.2.2
冪等請求在失敗後可重試	RFC 9110 §9.2.2
429 + Retry-After 用於流量限制	RFC 6585 §4

商業情境

當這些工具已安裝時，Pro 與 Enterprise key 的各方案層級酬載與逾時上限會提高。core 層級的上限則適用於預設部署。

另請參閱

• /connect/deployment/ — worker 集區、Redis、RoadRunner profile
• /transports/rest/ — 完整的 middleware 管線與 OpenAPI 合約
• /connect/troubleshooting/ — 診斷 401/403/413/429/5xx 與儲存區失敗
• /connect/security-and-operations/ — 身分驗證與流量限制的部署態勢