Operaciones en producción

De un vistazo

Esta página es la lista de verificación para llevar NextPDF a producción y mantenerlo ahí. Selecciona lo esencial del manual: cada elemento enlaza con la página que aporta la profundidad, de modo que aquí se verifica y allí se lee. Conviene recorrer la Lista de verificación previa al despliegue antes de la primera versión. Revisar de nuevo la Cadencia de actualización y los Puntos de entrada para el triaje de incidentes como parte de las operaciones del día dos.

Lista de verificación previa al despliegue

• Confirmar el entorno de ejecución: NextPDF requiere PHP >=8.4 <9.0. Composer rechaza cualquier cosa fuera de esa ventana. Véase Instalación.
• Verificar las seis extensiones requeridas con php -m: ext-mbstring, ext-zlib, ext-intl, ext-gd, ext-curl y ext-openssl. La página de instalación explica qué hace cada una.
• Ejecutar vendor/bin/nextpdf doctor para una comprobación única del entorno (versión de PHP, extensiones y disponibilidad de fuentes en un solo informe).
• Decidir la vía de renderizado antes de dimensionar el hardware. El pipeline en proceso (writeHtml()) no necesita ningún servicio adicional. Artisan, Gotenberg y Cloudflare añaden cada uno un navegador o un servicio de red que operar. Usar Elegir la ruta para decidir.
• Si se ha elegido un puente de renderer, leer su página de seguridad y operaciones antes de la puesta en marcha. Véase Reforzar la superficie del renderer.
• Empaquetar en tiempo de compilación las fuentes que se renderizan, y solo esas. Véase Aprovisionar fuentes en producción.

Dimensionamiento de recursos

Dimensionar para el documento más grande que se genere, no para el promedio. getPdfData() construye en memoria todo el documento Portable Document Format (PDF) y lo devuelve como una sola cadena.

• Configurar la memoria del worker o de la función a partir de la guía de dimensionamiento para serverless: un documento de pocas páginas funciona con holgura entre 512 y 1024 MB; los documentos con muchas imágenes o con muchas páginas necesitan más.
• Establecer los tiempos de espera por encima del tiempo de construcción en el peor caso, con margen. Trasladar los trabajos de tamaño excesivo a una cola asíncrona que escriba en almacenamiento de objetos: la misma sección de dimensionamiento muestra el patrón.
• Habilitar opcache en los workers de larga duración con la validación de marcas de tiempo desactivada. La sección de opcache de la receta de Docker recoge los valores ini de producción.
• Cuando la memoria o el rendimiento se desvíen tras el lanzamiento, empezar por la tabla de decisión de síntoma a palanca.

Reglas de seguridad para workers

Un Document es de un solo uso. Construirlo, escribirlo una vez y dejar que salga del ámbito; crear una instancia nueva por cada petición o por cada trabajo en cola. Compartir únicamente los registros de ámbito de proceso —FontRegistry e ImageRegistry— creándolos una sola vez en el arranque del worker. Esto se corresponde con el modelo por petición y por trabajo de PHP-FPM, los workers en cola y los servidores de aplicaciones de larga duración.

• Receta con la secuencia de arranque y el reinicio por ciclo: Renderizado por lotes seguro en workers.
• El contrato en una sola respuesta: ¿Es seguro para workers y para hilos?

Reforzar la superficie del renderer

Tratar el HTML como no confiable, especialmente cualquier contenido influido por el usuario. Elegir la ruta establece el límite: de forma predeterminada, el pipeline integrado no ejecuta scripts ni obtiene recursos remotos, mientras que cada puente renderiza a través de un navegador o de un servicio de red. Antes de exponer un puente al tráfico de producción, revisar su página de seguridad y operaciones:

• Seguridad y operaciones de Artisan — la superficie del renderer de Chrome.
• Seguridad y operaciones de Gotenberg — la superficie del servicio de Gotenberg.
• Seguridad y operaciones de Cloudflare — la superficie de despliegue en el edge.
• ¿Se ejecuta el motor como servicio? Añadir Seguridad y operaciones de Connect.

Observabilidad

NextPDF no publica objetivos de nivel de servicio (SLO); derivar los propios a partir de las métricas de duración del renderizado y de memoria que se miden más abajo.

Instrumentar la vía de renderizado antes del primer incidente, no después.

• Motor en proceso: Observar con OpenTelemetry.
• Despliegues de NextPDF Connect: Receta de OpenTelemetry para Connect.
• Por cada renderizado, registrar: tiempo real, pico de memoria, número de páginas, tamaño de la salida y el resultado con su categoría de excepción de la referencia de errores.
• Alertar sobre tendencias, no solo sobre fallos: el aumento de los tiempos de construcción, el aumento del pico de memoria y el número de tiempos de espera agotados o de agotamientos de memoria son las señales principales en las entradas de memoria y rendimiento.

Cadencia de actualización

• Leer una vez la política de soporte de versiones y, a partir de ahí, ajustar las versiones a ella. Define el contrato de versionado semántico, las etiquetas de estabilidad, el ciclo de vida de la obsolescencia y el vocabulario de ciclo de vida (active, lts, maintenance, frozen, eol) que utiliza este manual.
• Confirmar composer.lock para que cada worker desplegado resuelva la misma versión del motor: la página de instalación expone esta disciplina.
• Revisar el registro de cambios antes de cada incremento de versión.

Puntos de entrada para el triaje de incidentes

Para un incidente de un puente de renderer (un fallo de Chrome, una caída de Gotenberg, un error de renderizado en el edge), empezar por la sección de modos de fallo de ese puente en Reforzar la superficie del renderer.

• Empezar por el síntoma, no por el nombre de la clase, en la base de conocimiento de solución de problemas.
• Asignar una excepción capturada a su categoría y a su contrato de contexto en la referencia de errores.

Véase también

• Operar NextPDF en producción — el ensayo de Insider_ sobre por qué el motor se comporta así bajo carga.
• Contenerizar una aplicación NextPDF — la imagen de Docker de producción, de principio a fin.
• Desplegar en serverless — particularidades de Lambda, Cloud Run y App Runner.
• Renderizado seguro en workers en Connect — las mismas reglas de tiempo de vida aplicadas al servidor.