Implantação do NextPDF Connect

Visão geral

Os transportes REST e gRPC são executados em pools de worker do RoadRunner. O pacote inclui três perfis do RoadRunner: somente HTTP, somente gRPC e um perfil combinado. O transporte MCP roda como um subprocesso simples e não precisa de supervisor.

Instalação

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

Visão conceitual

O RoadRunner é o supervisor de processos. Ele gerencia o pool de workers, reinicia os workers sob pressão de memória e encaminha cada requisição para um worker disponível. O pacote PHP fornece o ponto de entrada do worker: bin/nextpdf-server para HTTP e bin/nextpdf-grpc para gRPC. O RoadRunner envolve esse ponto de entrada em um pool. Cada worker processa uma requisição por vez.

O transporte MCP funciona de forma diferente. bin/nextpdf-mcp é um único processo PHP. Ele fala JSON-RPC sobre stdio, e o cliente o inicia diretamente.

Superfície da API

Perfis do RoadRunner

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

O perfil HTTP vincula o listener REST a 0.0.0.0:8080. Ele expõe um endpoint de status em :2114 e métricas em :2112. O pool de workers é dimensionado a partir de NEXTPDF_WORKER_COUNT, cujo padrão é quatro. Nos perfis distribuídos, o supervisor limita cada worker a 256 MB.

O perfil combinado adiciona o pool de workers gRPC em tcp://0.0.0.0:9090. Esse pool é dimensionado a partir de NEXTPDF_GRPC_WORKER_COUNT, cujo padrão é dois. Ele também configura o TLS mútuo do gRPC.

Exemplo de código — Início rápido

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

Exemplo de código — Produção

Execute um container de produção com o perfil combinado, chaves baseadas em arquivo e stores compartilhados baseados em 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 extremos e armadilhas

Os stores em memória não abrangem vários workers. Sem o Redis, cada worker mantém seus próprios stores de limite de taxa, idempotência e documentos. Em um pool com vários workers, os stores em memória geram limitação de taxa inconsistente e podem perder documentos entre workers. Para qualquer pool maior que um worker, defina NEXTPDF_REDIS_HOST e instale o ext-redis. O servidor recorre automaticamente aos stores em memória se a conexão com o Redis falhar. Verifique a saúde do Redis; não presuma que ela está íntegra.
O store de jobs é o SQLite em modo WAL. Os jobs assíncronos são persistidos em um único arquivo SQLite compartilhado por todos os workers HTTP e gRPC. Coloque esse arquivo em um volume no qual todos os workers possam gravar. Quando um worker é encerrado, ele marca como falhos, em caráter de melhor esforço, os jobs ainda em execução, para que eles não fiquem órfãos.
O bin/nextpdf-prune é um ponto de entrada de manutenção. Ele é distribuído no repositório, não em vendor/bin/. Invoque-o diretamente para tarefas de limpeza dos stores. Ele não é um transporte de servidor.
A versão do PHP da imagem pode não ter o ext-redis. O Dockerfile distribuído compila o ext-redis em caráter de melhor esforço. Ele prossegue sem a extensão se não houver uma versão compatível para o PHP base. Confirme que a extensão está presente na imagem em execução antes de depender de stores baseados em Redis.

Desempenho

Defina NEXTPDF_WORKER_COUNT de acordo com a CPU e a memória disponíveis. Cada worker é um processo PHP limitado pelo teto de memória do supervisor. Para cargas de trabalho com renderização intensa, comece com um worker por núcleo e ajuste depois com base no endpoint de métricas. Dimensione o pool gRPC de forma independente. Ele costuma ser menor que o pool HTTP, porque os clientes gRPC geralmente são menos numerosos e mais duradouros.

Notas de segurança

TLS mútuo do gRPC

O perfil combinado configura o transporte gRPC para Transport Layer Security (TLS) mútuo: o servidor apresenta um certificado e, em seguida, exige e verifica um certificado de cliente. Forneça a chave do servidor, o certificado do servidor e a CA do cliente como secrets de implantação, sem incorporá-los à imagem. Gere e rotacione esses secrets por um canal separado; não execute o transporte gRPC com um listener em texto puro em uma rede não confiável.

Terminação de TLS do REST

O perfil REST vincula um listener HTTP em texto puro. Termine o TLS à frente dele com um proxy reverso, balanceador de carga ou service mesh, e vincule o listener somente à rede interna. Encaminhe a identidade do cliente pelo cabeçalho Authorization sem alterações; o servidor faz a própria validação da chave. O listener não fornece transporte seguro por si só; é esta configuração de implantação que o fornece.

Secrets

Monte as chaves de API com NEXTPDF_API_KEYS_FILE apontando para um arquivo de secret em vez de usar a variável inline NEXTPDF_API_KEYS. O store baseado em arquivo é recarregado a quente quando há alterações, de modo que a rotação não exige reinicialização. Nunca incorpore chaves nem material privado de TLS à imagem. Consulte /connect/security-and-operations/.

Conformidade

A mecânica de implantação não faz nenhuma afirmação normativa sobre protocolo. As citações de autenticação e segurança de transporte estão fixadas em /connect/security-and-operations/.

Contexto comercial

Instale o nextpdf/premium na imagem para registrar as ferramentas adicionais Pro e Enterprise dentro dos mesmos workers. Nenhum processo nem porta separados estão envolvidos. Você define o limite de empacotamento no momento da compilação da imagem.

Consulte também

/connect/configuration/ — número de workers, Redis e tetos por tier
/connect/security-and-operations/ — TLS, TLS mútuo, secrets, modelo de ameaças
/transports/rest/ · /transports/grpc/ — detalhes de runtime por transporte
/connect/production-usage/ — health probes, escalonamento e observabilidade
/connect/troubleshooting/ — diagnóstico de falhas de worker, store e autenticação