Настройка NextPDF Connect

Кратко

В NextPDF Connect есть две области конфигурации. Сервер Model Context Protocol (MCP) читает файл YAML и переменные NEXTPDF_MCP_*. Серверы REST и gRPC читают переменные окружения NEXTPDF_*. После запуска сервера конфигурация остаётся неизменяемой.

Установка

composer require nextpdf/server

Концептуальный обзор

Сервер MCP формирует итоговую конфигурацию по фиксированному порядку приоритета. Применяется источник с самым высоким приоритетом:

1. Переменные окружения (NEXTPDF_MCP_*).
2. Секция nextpdf_mcp в файле конфигурации YAML.
3. Встроенные значения по умолчанию.

Передайте файл YAML через --config=PATH. Если вы его не укажете, сервер использует только значения по умолчанию и переменные окружения. Итоговый McpConfig — это readonly-объект-значение. После запуска ни один параметр уже не может измениться.

При запуске серверы REST и gRPC считывают HttpConfig из окружения. Через окружение можно переопределить NEXTPDF_BIND, NEXTPDF_WORKER_COUNT, NEXTPDF_SESSIONS_ENABLED и NEXTPDF_CORS_ENABLED. Для остальных предельных значений используются безопасные значения по умолчанию.

Поверхность API

Конфигурация MCP (nextpdf-mcp)

Секция nextpdf_mcp в файле YAML:

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 МБ)
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	Количество PHP-воркеров RoadRunner
NEXTPDF_SESSIONS_ENABLED	false	Включает эндпоинты сессий с сохранением состояния
NEXTPDF_CORS_ENABLED	false	Включает заголовки ответов CORS
NEXTPDF_API_KEYS	не задано	Встроенные определения ключей API
NEXTPDF_API_KEYS_FILE	не задано	Путь к файлу ключей API
NEXTPDF_JOB_STORE_PATH	системный временный каталог	Путь к хранилищу заданий SQLite
NEXTPDF_REDIS_HOST	не задано	Если задано, включает хранилища на основе Redis

Сервер REST использует Redis, если задана переменная 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 явным списком разрешений и повысьте уровень риска инструмента:

/etc/nextpdf/nextpdf-mcp.yaml

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 фильтрует, а не добавляет. Если указать имя инструмента Pro без nextpdf/premium, он не появится. Список разрешений пересекается с набором инструментов, которые реестр фактически обнаружил.

• Для сервера MCP окружение имеет приоритет над YAML. Переменная NEXTPDF_MCP_* переопределяет одноимённый ключ в файле YAML. Серверы REST и gRPC вообще не читают YAML-файл MCP.

• parse_pdf требует явного включения. Сервер регистрирует инструмент parse_pdf только если NEXTPDF_MCP_TOOL_PARSE_PDF_ENABLED равно true или 1. По умолчанию он отсутствует даже в каталоге core.

Производительность

Конфигурация разбирается один раз при запуске. Параметры max_documents и document_ttl ограничивают хранилище документов в памяти. Если снизить эти значения, пиковое потребление памяти уменьшится, но время жизни документов сократится. Количество воркеров и предельные размеры полезной нагрузки для каждого уровня — параметры развёртывания, описанные в /connect/deployment/.

Примечания по безопасности

• Рассматривайте enabled_tools как механизм запрета по умолчанию для развёртываний по принципу минимальных привилегий: перечисляйте только те инструменты, которые нужны конкретной интеграции.
• Никогда не храните ключи API в файле YAML. Используйте NEXTPDF_API_KEYS_FILE с файлом, смонтированным как секрет Docker или Kubernetes. Сервер выбирает файловое хранилище с горячей перезагрузкой, поэтому ключи можно ротировать без перезапуска. См. /connect/security-and-operations/.
• Параметр temp_directory — это принудительно заданный базовый каталог для вывода файлов. Сервер канонизирует пути вывода и отклоняет всё, что после разрешения оказывается за его пределами.

Соответствие

Эта страница описывает механику конфигурации. Ссылки на требования соответствия для аутентификации и безопасности транспорта закреплены в /connect/security-and-operations/.

Коммерческий контекст

Предельные размеры полезной нагрузки и тайм-ауты для каждого уровня (corePayloadLimit, proPayloadLimit, enterprisePayloadLimit и соответствующие тайм-ауты) применяются к транспорту REST в зависимости от уровня аутентифицированного ключа API. Они действуют только тогда, когда установлены инструменты Pro или Enterprise и ключ авторизован для них.

См. также

• /connect/install/ — установка и необязательные пакеты
• /connect/boot-and-discovery/ — роль конфигурации в последовательности запуска
• /connect/hitl-risk-tiers/ — модель риска и переопределение, допускающее только повышение
• /connect/security-and-operations/ — настройка ключей API и безопасность транспорта
• /connect/deployment/ — количество воркеров, Redis и предельные значения уровней в продакшене