配置 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（在 NEXTPDF_REDIS_HOST 已设置且已加载 ext-redis 时由 REST 服务器使用）：

变量	默认值
`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 与层级上限