Distribuzione di NextPDF Connect

In breve

I transport REST e gRPC vengono eseguiti all’interno di pool di worker RoadRunner. Il pacchetto include tre profili RoadRunner: solo HTTP, solo gRPC e un profilo combinato. Il transport MCP viene eseguito come un semplice sottoprocesso e non richiede alcun supervisor.

Installazione

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

Panoramica concettuale

RoadRunner è il supervisor dei processi. Gestisce il pool di worker, riavvia i worker quando la memoria è sotto pressione e instrada ogni richiesta verso un worker libero. Il pacchetto PHP fornisce l’entry point del worker: bin/nextpdf-server per HTTP e bin/nextpdf-grpc per gRPC. RoadRunner gestisce il pool attorno a tale entry point. Ogni worker gestisce una richiesta alla volta.

Il transport MCP funziona in modo diverso. bin/nextpdf-mcp è un unico processo PHP. Comunica tramite JSON-RPC su stdio ed è avviato direttamente dal client.

Superficie API

Profili RoadRunner

Profilo	Transport	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`

Il profilo HTTP associa il listener REST a 0.0.0.0:8080. Espone un endpoint di stato su :2114 e le metriche su :2112. Dimensiona il pool di worker in base a NEXTPDF_WORKER_COUNT, il cui valore predefinito è quattro. Nei profili forniti il supervisor limita la memoria di ogni worker a 256 MB.

Il profilo combinato aggiunge il pool di worker gRPC su tcp://0.0.0.0:9090, dimensionato in base a NEXTPDF_GRPC_WORKER_COUNT, il cui valore predefinito è due. Configura inoltre il mutual TLS gRPC.

Esempio di codice — Avvio rapido

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

Esempio di codice — Produzione

Eseguire un container di produzione con il profilo combinato, chiavi basate su file e store condivisi basati su 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

Casi limite e insidie

Gli store in memoria non sono condivisi tra i worker. Senza Redis, ogni worker mantiene i propri store di rate-limit, idempotenza e documenti. Un pool con più worker e store in memoria rende incoerente il rate limiting e fa perdere i documenti tra i worker. Per qualsiasi pool con più di un worker, impostare NEXTPDF_REDIS_HOST e installare ext-redis. Se la connessione a Redis fallisce, il server ripiega automaticamente sulla modalità in memoria. Verificare lo stato di salute di Redis; non darlo per scontato.
Lo store dei job è SQLite in modalità WAL. I job asincroni vengono persistiti in un unico file SQLite condiviso da tutti i worker HTTP e gRPC. Collocare tale file su un volume scrivibile da tutti i worker. Quando un worker si arresta, contrassegna come non riusciti, per quanto possibile, i job ancora in esecuzione, in modo che non rimangano orfani.
bin/nextpdf-prune è un entry point di manutenzione. È fornito nel repository, non in vendor/bin/. Richiamarlo direttamente per le attività di pruning degli store. Non è un transport del server.
La versione di PHP dell’immagine potrebbe non disporre di ext-redis. Il Dockerfile fornito compila ext-redis quando possibile. Prosegue senza l’estensione se non esiste alcuna release compatibile con il PHP di base. Verificare che l’estensione sia presente nell’immagine in esecuzione prima di affidarsi agli store basati su Redis.

Prestazioni

Dimensionare NEXTPDF_WORKER_COUNT in base a CPU e memoria disponibili. Ogni worker è un processo PHP limitato dal limite di memoria del supervisor. Per i carichi di lavoro con rendering intensivo, iniziare con un worker per core, quindi regolare in base all’endpoint delle metriche. Dimensionare il pool gRPC in modo indipendente. In genere è più piccolo del pool HTTP, perché i client gRPC sono solitamente meno numerosi e più longevi.

Note sulla sicurezza

Mutual TLS gRPC

Il profilo combinato configura il transport gRPC per il mutual TLS: il server presenta un certificato e richiede e verifica un certificato client. La chiave del server, il certificato del server e la CA del client vengono forniti come secret di distribuzione, non integrati nell’immagine. Generarli e ruotarli fuori banda; non eseguire il transport gRPC con un listener in chiaro su una rete non attendibile.

Terminazione TLS per REST

Il profilo REST associa un listener HTTP in chiaro. Terminare il TLS a monte — con un reverse proxy, un load balancer o una service mesh — e associare il listener solo alla rete interna. Inoltrare l’identità del client tramite l’header Authorization senza modificarlo; il server esegue la propria convalida della chiave. Il listener da solo non fornisce un transport sicuro; lo fa la configurazione di distribuzione.

Secret

Montare le chiavi API con NEXTPDF_API_KEYS_FILE che punta a un file di secret anziché con la variabile inline NEXTPDF_API_KEYS; lo store basato su file viene ricaricato a caldo a ogni modifica, quindi la rotazione non richiede alcun riavvio. Non integrare mai chiavi o materiale privato TLS nell’immagine. Vedere /connect/security-and-operations/.

Conformità

I meccanismi di distribuzione non comportano alcuna dichiarazione normativa di protocollo. Le citazioni relative all’autenticazione e alla sicurezza del transport sono fissate in /connect/security-and-operations/.

Contesto commerciale

Installare nextpdf/premium nell’immagine per registrare gli strumenti aggiuntivi Pro ed Enterprise all’interno degli stessi worker. Non è coinvolto alcun processo o porta separati. Il confine di pacchettizzazione viene definito al momento della build dell’immagine.

Vedere anche

/connect/configuration/ — numero di worker, Redis e limiti massimi dei tier
/connect/security-and-operations/ — TLS, mutual TLS, secret, modello delle minacce
/transports/rest/ · /transports/grpc/ — dettagli di runtime per ciascun transport
/connect/production-usage/ — probe di integrità, scalabilità e osservabilità
/connect/troubleshooting/ — diagnosi degli errori di worker, store e autenticazione