Desplegar NextPDF Connect

De un vistazo

Los transportes REST y gRPC se ejecutan en pools de workers de RoadRunner. El paquete incluye tres perfiles de RoadRunner: solo HTTP, solo gRPC y un perfil combinado. El transporte MCP se ejecuta como subproceso normal y no necesita supervisor.

Instalación

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

Visión conceptual

RoadRunner es el supervisor de procesos. Gestiona el pool de workers, reinicia los workers cuando hay presión de memoria y dirige cada solicitud a un worker disponible. El paquete de PHP proporciona el punto de entrada del worker: bin/nextpdf-server para HTTP y bin/nextpdf-grpc para gRPC. RoadRunner proporciona el pool para ese punto de entrada. Cada worker atiende una sola solicitud a la vez.

El transporte MCP funciona de otra manera. bin/nextpdf-mcp es un único proceso de PHP. Se comunica mediante JSON-RPC sobre stdio, y el cliente lo inicia directamente.

Superficie de la API

Perfiles de RoadRunner

Perfil	Transportes	Comando
`.rr.yaml`	Solo REST	`rr serve -c .rr.yaml`
`.rr.grpc.yaml`	Solo gRPC	`rr serve -c .rr.grpc.yaml`
`.rr.full.yaml`	REST + gRPC	`rr serve -c .rr.full.yaml`

El perfil HTTP enlaza el listener de REST en 0.0.0.0:8080. Expone un endpoint de estado en :2114 y métricas en :2112. Dimensiona el pool de workers a partir de NEXTPDF_WORKER_COUNT, cuyo valor predeterminado es cuatro. El supervisor limita la memoria de cada worker a 256 MB en los perfiles incluidos.

El perfil combinado añade el pool de workers de gRPC en tcp://0.0.0.0:9090, dimensionado a partir de NEXTPDF_GRPC_WORKER_COUNT, cuyo valor predeterminado es dos. También configura el TLS mutuo de gRPC.

Ejemplo de código — Inicio rápido

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

Ejemplo de código — Producción

Para ejecutar un contenedor de producción con el perfil combinado, claves basadas en archivo y almacenes compartidos respaldados por 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

Casos límite y trampas

Los almacenes en memoria no se comparten entre varios workers. Sin Redis, cada worker mantiene sus propios almacenes de límite de tasa, idempotencia y documentos. Un pool con varios workers y almacenes en memoria produce un control de tasa inconsistente y pierde documentos entre workers. Para cualquier pool con más de un worker, definir NEXTPDF_REDIS_HOST e instalar ext-redis. El servidor recurre automáticamente al modo en memoria si la conexión con Redis falla. Verificar el estado de Redis; no darlo por sentado.
El almacén de trabajos es SQLite en modo WAL. Los trabajos asíncronos se persisten en un único archivo SQLite compartido por todos los workers de HTTP y gRPC. Colocar ese archivo en un volumen en el que todos los workers puedan escribir. Cuando un worker se apaga, marca como fallidos, según el mejor esfuerzo posible, los trabajos que aún tenía en ejecución, de modo que esos trabajos no queden huérfanos.
bin/nextpdf-prune es un punto de entrada de mantenimiento. Está incluido en el repositorio, no en vendor/bin/. Debe invocarse directamente para las tareas de poda de almacenes. No es un transporte de servidor.
Puede que la versión de PHP de la imagen no tenga ext-redis. El Dockerfile incluido compila ext-redis según el mejor esfuerzo posible. La compilación continúa sin la extensión si no existe ninguna versión compatible para el PHP base. Confirmar que la extensión esté presente en la imagen en ejecución antes de depender de los almacenes respaldados por Redis.

Rendimiento

Dimensionar NEXTPDF_WORKER_COUNT según la CPU y la memoria disponibles. Cada worker es un proceso de PHP limitado por el techo de memoria del supervisor. Para cargas de trabajo con mucho renderizado, empezar con un worker por núcleo y luego ajustarlo según el endpoint de métricas. Dimensionar el pool de gRPC de forma independiente. Normalmente es más pequeño que el pool de HTTP, porque los clientes de gRPC suelen ser menos numerosos y de mayor duración.

Notas de seguridad

TLS mutuo de gRPC

El perfil combinado configura el transporte de gRPC para usar TLS mutuo: el servidor presenta un certificado y exige y verifica un certificado de cliente. La clave del servidor, el certificado del servidor y la CA de cliente se suministran como secretos de despliegue; no se incrustan en la imagen. Generar y rotar ese material fuera de banda; no ejecutar el transporte de gRPC con un listener en texto plano sobre una red no confiable.

Terminación de TLS de REST

El perfil de REST enlaza un listener HTTP en texto plano. Terminar el TLS delante de él —con un proxy inverso, un balanceador de carga o una malla de servicios— y enlazar el listener únicamente a la red interna. Reenviar la identidad del cliente a través de la cabecera Authorization sin modificarla; el servidor realiza su propia validación de claves. El listener no proporciona transporte seguro por sí solo; esta configuración de despliegue sí lo hace.

Secretos

Montar las claves de API con NEXTPDF_API_KEYS_FILE apuntando a un archivo de secretos en lugar de la variable en línea NEXTPDF_API_KEYS; el almacén basado en archivo se recarga en caliente cuando cambia, así que la rotación no necesita reinicio. Nunca incrustar claves ni material privado de TLS en la imagen. Consultar /connect/security-and-operations/.

Conformidad

La mecánica de despliegue no conlleva afirmaciones normativas sobre el protocolo. Las citas de autenticación y de seguridad del transporte están fijadas en /connect/security-and-operations/.

Contexto comercial

Instalar nextpdf/premium en la imagen para registrar las herramientas adicionales de Pro y Enterprise dentro de los mismos workers. No interviene ningún proceso ni puerto aparte. El límite de empaquetado se fija al construir la imagen.

Consulta también

/connect/configuration/ — número de workers, Redis y techos de nivel
/connect/security-and-operations/ — TLS, TLS mutuo, secretos y modelo de amenazas
/transports/rest/ · /transports/grpc/ — detalle de ejecución por transporte
/connect/production-usage/ — sondas de estado, escalado y observabilidad
/connect/troubleshooting/ — diagnóstico de fallos de workers, almacenes y autenticación