設定 NextPDF Connect

概覽

NextPDF Connect 有兩個組態介面。MCP 伺服器會讀取 YAML 檔案，並套用 NEXTPDF_MCP_* 變數。REST 與 gRPC 伺服器則讀取 NEXTPDF_* 環境變數。伺服器一旦啟動，組態便不可變更。

安裝

composer require nextpdf/server

概念總覽

MCP 伺服器會依固定優先順序 resolve（解析）組態。優先序最高的來源會勝出：

環境變數（NEXTPDF_MCP_*）。
YAML 組態檔的 nextpdf_mcp 區段。
內建預設值。

使用 --config=PATH 指定這個 YAML 檔案。若未指定，伺服器只會使用預設值與環境變數。產生的 McpConfig 是一個 readonly 值物件；啟動後不會再有任何設定變動。

REST 與 gRPC 伺服器會在啟動時從環境讀取 HttpConfig。支援的環境覆寫項目為 NEXTPDF_BIND、NEXTPDF_WORKER_COUNT、NEXTPDF_SESSIONS_ENABLED 與 NEXTPDF_CORS_ENABLED。其餘上限值都採用安全的預設值。

API 介面

MCP 組態（`nextpdf-mcp`）

YAML 檔案中的 nextpdf_mcp 區段：

nextpdf_mcp:
  enabled_tools: []          # empty/absent = all available tools allowed
  temp_directory: /tmp/nextpdf-mcp
  max_documents: 50
  document_ttl: 1800
  max_file_size_bytes: 104857600
  allow_file_output: true
  compress: true
  risk_level_overrides:
    fill_form: 3             # raise fill_form to ApprovalRequired (see below)

MCP 伺服器可用的環境覆寫：

變數	組態鍵	預設值
`NEXTPDF_MCP_ENABLED_TOOLS`	`enabled_tools`	允許所有工具
`NEXTPDF_MCP_TEMP_DIR`	`temp_directory`	系統暫存目錄 + `/nextpdf-mcp`
`NEXTPDF_MCP_MAX_FILE_SIZE`	`max_file_size_bytes`	`104857600`（100 MB）
`NEXTPDF_MCP_MAX_DOCUMENTS`	`max_documents`	`50`
`NEXTPDF_MCP_DOCUMENT_TTL`	`document_ttl`	`1800` 秒
`NEXTPDF_MCP_TOOL_PARSE_PDF_ENABLED`	（控管 `parse_pdf`）	未設定（停用）
`NEXTPDF_AST_TOOLS_ENABLED`	（控管 AST 工具）	已啟用
`NEXTPDF_MUTATION_TOOLS_ENABLED`	（控管 AST 變異工具）	未設定（停用）

REST 與 gRPC 組態

變數	預設值	作用
`NEXTPDF_BIND`	`0.0.0.0:8080`	REST 監聽位址
`NEXTPDF_WORKER_COUNT`	`4`	RoadRunner PHP worker 數量
`NEXTPDF_SESSIONS_ENABLED`	`false`	啟用有狀態的工作階段 endpoint
`NEXTPDF_CORS_ENABLED`	`false`	啟用 CORS 回應標頭
`NEXTPDF_API_KEYS`	未設定	行內 API 金鑰定義
`NEXTPDF_API_KEYS_FILE`	未設定	API 金鑰檔案路徑
`NEXTPDF_JOB_STORE_PATH`	系統暫存目錄	SQLite job store 路徑
`NEXTPDF_REDIS_HOST`	未設定	設定後即啟用 Redis 後端儲存

Redis（由 REST 伺服器使用；須已設定 NEXTPDF_REDIS_HOST 並載入 ext-redis）：

變數	預設值
`NEXTPDF_REDIS_PORT`	`6379`
`NEXTPDF_REDIS_PASSWORD`	空值
`NEXTPDF_REDIS_DATABASE`	`0`
`NEXTPDF_REDIS_PREFIX`	`nextpdf:`
`NEXTPDF_REDIS_CONNECT_TIMEOUT`	`2.0` 秒
`NEXTPDF_REDIS_READ_TIMEOUT`	`2.0` 秒

程式碼範例 — 快速上手

使用明確指定的組態檔啟動 MCP 伺服器：

./vendor/bin/nextpdf-mcp --config=/etc/nextpdf/nextpdf-mcp.yaml

程式碼範例 — 正式環境

將 MCP 工具目錄限定在明確的允許清單內，並調高某個工具的風險等級：

nextpdf_mcp:
  enabled_tools:
    - create_pdf
    - add_text
    - output_pdf
    - diagnostic.doctor
  temp_directory: /var/lib/nextpdf/tmp
  max_file_size_bytes: 26214400
  risk_level_overrides:
    add_text: 2          # upgrade add_text from caution to review

只要 enabled_tools 不是空清單，安全政策就只允許清單列出的工具名稱。其餘所有工具都會從登錄表中靜默移除。若清單為空或未提供清單，則允許所有可用工具。

邊界案例與陷阱

這兩個關鍵工具不可調降。 output_pdf 與 sign_pdf 設計上就需要核准把關：若 risk_level_overrides 項目將其中任一個調到 ApprovalRequired 以下，載入時就會拋出 InvalidArgumentException，伺服器也會拒絕啟動。其他每個工具的風險等級都可以調高或調低，因此請依你的威脅模型審視任何調降。請參閱 /connect/hitl-risk-tiers/。
enabled_tools 只會過濾，不會新增。 在 nextpdf/premium 不存在時列出某個 Pro 工具名稱，並不會讓它因此出現。允許清單會與登錄表實際探索到的工具取交集。
對 MCP 伺服器而言，環境變數優先於 YAML。 任何 NEXTPDF_MCP_* 變數都會覆寫 YAML 檔案中的同名鍵。REST 與 gRPC 伺服器完全不會讀取 MCP 的 YAML 檔案。
parse_pdf 採選擇性啟用。 parse_pdf 工具只有在 NEXTPDF_MCP_TOOL_PARSE_PDF_ENABLED 為 true 或 1 時才會註冊。即使在核心目錄中，它預設也不存在。

效能

組態只會在啟動時剖析一次。max_documents 與 document_ttl 這兩個設定會限制記憶體內的文件儲存。調低它們可以降低尖峰記憶體用量，代價是文件存活時間較短。Worker 數量與各層級的 payload 上限，是部署調校時可調整的旋鈕，詳見 /connect/deployment/。

安全注意事項

請將 enabled_tools 視為最小權限部署的「預設拒絕」控管面：只列出該整合實際需要的工具。
切勿將 API 金鑰存放在 YAML 檔案中。請改用 NEXTPDF_API_KEYS_FILE，並搭配以 Docker 或 Kubernetes secret 掛載的檔案。伺服器偏好使用可即時重新載入的檔案儲存，讓金鑰不必重啟即可輪替。請參閱 /connect/security-and-operations/。
這個 temp_directory 是檔案輸出強制使用的基準目錄。伺服器會正規化輸出路徑，並拒絕任何解析後落在該目錄之外的路徑。

符合性

本頁說明的是組態的運作機制。驗證與傳輸安全的符合性引用，皆固定列於 /connect/security-and-operations/。

商業脈絡

各層級的 payload 與逾時上限（corePayloadLimit、proPayloadLimit、enterprisePayloadLimit 以及對應的逾時值）會依已驗證 API 金鑰的層級套用到 REST 傳輸。只有在已安裝 Pro 或 Enterprise 工具，且該金鑰有權使用它們時，這些上限才會生效。

另請參閱

/connect/install/ — 安裝與選用套件
/connect/boot-and-discovery/ — 組態如何餵入啟動流程
/connect/hitl-risk-tiers/ — 風險模型與只能調高的覆寫
/connect/security-and-operations/ — API 金鑰組態與傳輸安全
/connect/deployment/ — 正式環境中的 worker 數量、Redis 與層級上限