Operações em produção

Visão geral

Esta página é a checklist para levar o NextPDF à produção e mantê-lo lá. Ela organiza o manual: cada item aponta para a página que traz o aprofundamento, então você verifica aqui e lê lá. Percorra a Checklist de pré-implantação antes do primeiro lançamento. Revisite a Cadência de atualização e os Pontos de entrada para triagem de incidentes como parte das operações do dia a dia.

Checklist de pré-implantação

Confirme o runtime: o NextPDF requer PHP >=8.4 <9.0. O Composer recusa qualquer coisa fora dessa faixa. Consulte Instalação.
Verifique as seis extensões obrigatórias com php -m: ext-mbstring, ext-zlib, ext-intl, ext-gd, ext-curl e ext-openssl. A página de instalação explica o que cada uma faz.
Execute vendor/bin/nextpdf doctor para uma verificação única do ambiente (versão do PHP, extensões e disponibilidade de fontes em um só relatório).
Decida seu caminho de renderização antes de dimensionar o hardware. O pipeline in-process (writeHtml()) não precisa de nenhum serviço adicional. Artisan, Gotenberg e Cloudflare adicionam, cada um, um navegador ou serviço de rede a ser operado. Use Escolha seu caminho para decidir.
Se você escolheu uma ponte de renderização, leia a página de segurança e operações dela antes de entrar em produção. Consulte Blindar a superfície do renderizador.
Empacote as fontes que você renderiza no momento do build, e somente essas. Consulte Provisione fontes em produção.

Dimensionamento de recursos

Dimensione para o maior documento que você gera, não para a média. O getPdfData() constrói o documento Portable Document Format (PDF) inteiro em memória e o retorna como uma única string.

Defina a memória do worker ou da função a partir da orientação de dimensionamento serverless: um documento de poucas páginas fica confortável com 512–1024 MB; documentos com muitas imagens ou muitas páginas precisam de mais.
Defina timeouts acima do tempo de build no pior caso, com margem. Mova jobs grandes demais para uma fila assíncrona que grava em armazenamento de objetos — a mesma seção de dimensionamento mostra o padrão.
Habilite o opcache nos workers de longa duração, com a validação de timestamp desativada. A seção de opcache da receita do Docker traz os valores de ini de produção.
Quando a memória ou a taxa de transferência começar a variar após o lançamento, comece pela tabela de decisão sintoma-para-alavanca.

Regras de segurança de workers

Um Document é de uso único. Construa-o, escreva-o uma vez e deixe-o sair do escopo; crie uma instância nova por requisição ou por job de fila. Compartilhe apenas os registries de duração de processo — FontRegistry e ImageRegistry — criando-os uma única vez no boot do worker. Isso corresponde ao modelo por requisição e por job do PHP-FPM, dos workers de fila e dos servidores de aplicação de longa duração.

Receita com a sequência de boot e o reset por ciclo: Renderização em lote segura para workers.
O contrato em uma única resposta: É seguro para workers e threads?

Blindar a superfície do renderizador

Trate o HTML como não confiável, especialmente qualquer coisa influenciada pelo usuário. Escolha seu caminho define o limite: por padrão, o pipeline embutido não executa scripts e não busca recursos remotos, enquanto cada ponte renderiza através de um navegador ou de um serviço de rede. Antes de expor uma ponte ao tráfego de produção, percorra a página de segurança e operações dela:

Segurança e operações do Artisan — a superfície do renderizador Chrome.
Segurança e operações do Gotenberg — a superfície do serviço Gotenberg.
Segurança e operações do Cloudflare — a superfície de implantação na borda (edge).
Executando o motor como um serviço? Adicione Segurança e operações do Connect.

Observabilidade

O NextPDF não publica metas de service-level objective (SLO); derive as suas a partir das métricas de duração de renderização e de memória que você mede abaixo.

Instrumente o caminho de renderização antes do primeiro incidente, não depois.

Motor in-process: Observe com OpenTelemetry.
Implantações do NextPDF Connect: Receita de OpenTelemetry do Connect.
Por renderização, registre: tempo de relógio (wall time), pico de memória, contagem de páginas, tamanho de saída e o resultado com sua categoria de exceção a partir da referência de erros.
Alerte sobre tendências, não apenas sobre falhas: tempos de build crescentes, pico de memória crescente e contagens de timeout ou de esgotamento de memória são os sinais precursores nas entradas de memória e desempenho.

Cadência de atualização

Leia a política de suporte de versões uma vez e, depois, mantenha os lançamentos alinhados a ela. Ela define o contrato de versionamento semântico, os rótulos de estabilidade, o ciclo de vida de depreciação e o vocabulário de ciclo de vida (active, lts, maintenance, frozen, eol) que este manual usa.
Faça o commit do composer.lock para que todo worker implantado resolva a mesma versão do motor — a página de instalação estabelece essa disciplina.
Revise o registro de alterações antes de cada mudança de versão.

Pontos de entrada para triagem de incidentes

Para um incidente de ponte de renderização (um crash do Chrome, uma indisponibilidade do Gotenberg, uma falha de renderização na borda), comece pela seção de modos de falha daquela ponte em Blindar a superfície do renderizador.

Comece pelo sintoma, não pelo nome da classe, na base de conhecimento de solução de problemas.
Mapeie uma exceção capturada para sua categoria e contrato de contexto na referência de erros.

Veja também

Operando o NextPDF em produção — o ensaio Insider_ sobre por que o motor se comporta dessa forma sob carga.
Coloque uma aplicação NextPDF em contêiner — a imagem Docker de produção, de ponta a ponta.
Implante em serverless — especificidades de Lambda, Cloud Run e App Runner.
Renderização segura para workers no Connect — as mesmas regras de duração aplicadas ao servidor.