Развёртывание NextPDF Connect

Кратко

Транспорты REST и gRPC работают в пулах воркеров RoadRunner. Пакет включает три профиля RoadRunner: только HTTP, только gRPC и комбинированный профиль. Транспорт MCP работает как обычный дочерний процесс и не требует супервизора.

Установка

composer require nextpdf/server
./vendor/bin/rr get-binary

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

RoadRunner — супервизор процессов. Он управляет пулом воркеров, перезапускает воркеры при нехватке памяти и передаёт каждый запрос свободному воркеру. PHP-пакет предоставляет точку входа воркера: bin/nextpdf-server для HTTP и bin/nextpdf-grpc для gRPC. RoadRunner запускает эту точку входа в составе пула. Каждый воркер обрабатывает один запрос за раз.

Транспорт MCP работает иначе. bin/nextpdf-mcp — это отдельный процесс PHP. Он использует JSON-RPC поверх stdio, а клиент запускает его напрямую.

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

Профили RoadRunner

Профиль	Транспорты	Команда
`.rr.yaml`	только REST	`rr serve -c .rr.yaml`
`.rr.grpc.yaml`	только gRPC	`rr serve -c .rr.grpc.yaml`
`.rr.full.yaml`	REST + gRPC	`rr serve -c .rr.full.yaml`

Профиль HTTP привязывает слушатель REST к 0.0.0.0:8080, предоставляет эндпоинт состояния на :2114 и метрики на :2112. Размер пула воркеров берётся из NEXTPDF_WORKER_COUNT; по умолчанию — четыре. В поставляемых профилях супервизор ограничивает каждый воркер 256 MB.

Комбинированный профиль добавляет пул воркеров gRPC на tcp://0.0.0.0:9090. Размер этого пула берётся из NEXTPDF_GRPC_WORKER_COUNT; по умолчанию — два. Он также настраивает взаимный TLS для gRPC.

Пример кода — быстрый старт

export NEXTPDF_API_KEYS_FILE=/run/secrets/api-keys
./vendor/bin/rr serve -c .rr.full.yaml

Пример кода — продакшен

Запустите продакшен-контейнер с комбинированным профилем, файловыми ключами и общими хранилищами на базе Redis:

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

Граничные случаи и подводные камни

Хранилища в памяти не распространяются на несколько воркеров. Без Redis каждый воркер использует собственные хранилища для ограничения частоты, идемпотентности и документов. В пуле из нескольких воркеров хранилища в памяти дают несогласованное ограничение частоты, а документы могут теряться между воркерами. Для любого пула с более чем одним воркером задайте NEXTPDF_REDIS_HOST и установите ext-redis. При сбое подключения к Redis сервер автоматически переходит на хранилища в памяти. Проверяйте работоспособность Redis; не считайте доступность Redis само собой разумеющейся.
Хранилище задач — это SQLite в режиме WAL. Асинхронные задачи сохраняются в один файл SQLite, общий для всех воркеров HTTP и gRPC. Разместите этот файл на томе, доступном для записи всем воркерам. Во время завершения работы воркер по возможности помечает свои ещё выполняющиеся задачи как завершившиеся с ошибкой, чтобы они не оставались без владельца.
bin/nextpdf-prune — это точка входа для обслуживания. Она поставляется в репозитории, а не в vendor/bin/. Вызывайте её напрямую для задач очистки хранилищ. Это не серверный транспорт.
В версии PHP в образе может не быть ext-redis. Поставляемый Dockerfile собирает ext-redis по мере возможности. Если для базовой версии PHP нет совместимого выпуска, сборка продолжается без этого расширения. Прежде чем полагаться на хранилища на базе Redis, убедитесь, что расширение есть в работающем образе.

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

Задайте NEXTPDF_WORKER_COUNT с учётом доступных CPU и памяти. Каждый воркер — это процесс PHP с ограничением памяти, заданным супервизором. Для нагрузок с интенсивной отрисовкой начните с одного воркера на ядро, а затем подберите значения по данным эндпоинта метрик. Размер пула gRPC задавайте независимо. Обычно он меньше пула HTTP, поскольку клиентов gRPC, как правило, меньше, а их соединения живут дольше.

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

Взаимный TLS для gRPC

Комбинированный профиль настраивает транспорт gRPC для взаимного Transport Layer Security (TLS): сервер предъявляет сертификат, затем запрашивает и проверяет сертификат клиента. Передавайте ключ сервера, сертификат сервера и клиентский CA как секреты развёртывания, а не зашивайте их в образ. Создавайте и ротируйте их по отдельному каналу; не запускайте транспорт gRPC со слушателем без TLS в недоверенной сети.

Терминация TLS для REST

Профиль REST привязывает слушатель HTTP без TLS. Завершайте TLS перед ним с помощью обратного прокси, балансировщика нагрузки или сервисной сетки, а слушатель привязывайте только к внутренней сети. Передавайте идентификатор клиента в заголовке Authorization без изменений; сервер выполняет собственную проверку ключа. Защищённый транспорт обеспечивает не сам слушатель, а конфигурация развёртывания.

Секреты

Монтируйте ключи API через переменную NEXTPDF_API_KEYS_FILE, которая указывает на файл секрета, а не через встроенную переменную NEXTPDF_API_KEYS. Файловое хранилище перезагружается на лету при изменении, поэтому для ротации перезапуск не нужен. Никогда не зашивайте ключи или закрытый материал TLS в образ. См. /connect/security-and-operations/.

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

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

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

Установите nextpdf/premium в образ, чтобы зарегистрировать дополнительные инструменты Pro и Enterprise в тех же воркерах. Отдельный процесс или порт при этом не задействуются. Границу пакетирования задавайте на этапе сборки образа.

См. также

/connect/configuration/ — число воркеров, Redis и лимиты частоты
/connect/security-and-operations/ — TLS, взаимный TLS, секреты, модель угроз
/transports/rest/ · /transports/grpc/ — детали выполнения для каждого транспорта
/connect/production-usage/ — проверки работоспособности, масштабирование и наблюдаемость
/connect/troubleshooting/ — диагностика сбоев воркеров, хранилищ и аутентификации