1. Base de conocimiento
2. Despliegue

Guía de configuración de Image Converter

Image converter es un microservicio de Node.js que renderiza fondos SVG de recintos en imágenes WebP optimizadas. Produce tres variantes por cada fondo: resolución completa, una previsualización de 1000px y un marcador de posición difuminado de 400px con datos base64 incorporados para la carga progresiva. Las imágenes se almacenan en almacenamiento de objetos compatible con S3 o en el sistema de archivos local.

Stack: Node.js 22, Express 5, Puppeteer (Chromium headless para renderizar SVG), Sharp (procesamiento de imágenes), Redis (cola de conversiones).

Ajustes principales

Ajustes de manejo de archivos

Ajustes de procesamiento de imágenes

Ajustes de almacenamiento

Configuración de AWS S3

Estos ajustes son obligatorios cuando STORAGE_TYPE=s3.

ImportantLas credenciales de AWS deben proporcionarse mediante variables de entorno seguras o secretos de Kubernetes. Nunca incluyas credenciales en el control de versiones.

Resolución de la URL pública

El conversor genera URL públicas para las imágenes subidas. La base de la URL se resuelve en este orden de prioridad:

1. AWS_PUBLIC_BASE_URL (si está definida) — se usa tal cual. Ejemplo: https://bucket.nyc3.digitaloceanspaces.com
2. AWS_ENDPOINT_URL (derivada) — path-style: {endpoint}/{bucket}. Ejemplo: https://storage.yandexcloud.net/my-bucket
3. Por defecto — estilo virtual-hosted de AWS: https://{bucket}.s3.{region}.amazonaws.com

Los clientes self-hosted que usan proveedores de S3 distintos de AWS (DigitalOcean Spaces, MinIO, Garage, Yandex Cloud) deben definir AWS_PUBLIC_BASE_URL para garantizar URL públicas correctas.

Política del bucket de S3

Para permitir el acceso público de lectura a las imágenes, aplica la siguiente política de bucket:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "PublicReadGetObject",
      "Effect": "Allow",
      "Principal": "*",
      "Action": "s3:GetObject",
      "Resource": "arn:aws:s3:::your-bucket-name/*"
    }
  ]
}

Configuración de CORS

Para evitar problemas de tainted canvas al procesar imágenes en navegadores web, configura CORS en el bucket:

[
  {
    "AllowedHeaders": ["*"],
    "AllowedMethods": ["GET"],
    "AllowedOrigins": ["*"],
    "ExposeHeaders": []
  }
]

NotePara entornos de producción, restringe AllowedOrigins a tus dominios específicos en lugar de *.

Ajustes de Redis

Las conversiones se encolan en Redis cuando REDIS_ENABLED=true (valor por defecto del chart de Helm). Cada solicitud se registra como un trabajo; un conversor con GPU lo reclama primero, un conversor por CPU lo reclama tras CPU_CLAIM_DELAY_MS, y un trabajo cuyo worker muere a mitad del renderizado vuelve a la cola y se reintenta. Con REDIS_ENABLED=false el conversor renderiza dentro de la solicitud y no necesita Redis. Si Redis está activado pero no accesible, el conversor también renderiza dentro de la solicitud, responde 503 en GET /jobs/{id} y registra errores de conexión; el encolado arranca solo cuando Redis vuelve a estar accesible.

Autenticación

Endpoints de la API

POST /, /background/ y /thumbnail/ aceptan multipart/form-data con un archivo SVG (image/svg+xml). POST /photo/ acepta un archivo JPEG, PNG o WebP de hasta 10 MB y responde con url y thumbUrl.

Con el encolado activado, una ruta de conversión responde 202 Accepted con un id de trabajo y el resultado se lee en GET /jobs/{id}; editor-service hace este sondeo por sí mismo. Con el encolado desactivado las rutas responden directamente con el resultado.

Limitación de tasa: RATE_LIMIT_MAX solicitudes (600 por defecto) cada RATE_LIMIT_WINDOW_MS (60000 por defecto) por dirección IP en las rutas de conversión, /photo/ incluida. GET /jobs/{id} tiene su propio presupuesto, JOBS_RATE_LIMIT_MAX solicitudes por minuto (5000 por defecto). /health y /metrics no se limitan.

Tiempo de espera de la solicitud: 5 minutos (300 segundos).

Formato de salida

El conversor genera imágenes WebP (no PNG), lo que proporciona archivos un 30-50% más pequeños con soporte de canal alfa.

Se producen tres variantes para cada fondo:

Los archivos se almacenan en backgrounds/{filename}/{variant}.webp en el backend de almacenamiento configurado.

Docker

El servicio se ejecuta en un contenedor Docker basado en node:22.14.0-alpine con Chromium instalado para Puppeteer.

Puerto: 3000

Comprobación de estado: GET /health cada 30 segundos (3 reintentos, período de inicio de 5 segundos)

Variables de entorno para Puppeteer:

• PUPPETEER_SKIP_CHROMIUM_DOWNLOAD=true (usa el Chromium del sistema)
• PUPPETEER_EXECUTABLE_PATH=/usr/bin/chromium-browser

Seguridad: Se ejecuta como usuario non-root (uid 10001). Usa tini como proceso init para evitar procesos zombie.

Monitorización

Métricas de Prometheus

El endpoint /metrics expone:

• http_request_duration_seconds — histograma con etiquetas method, route, status_code
• http_requests_total — contador con etiquetas method, route, status_code
• Métricas por defecto del proceso de Node.js (memoria, CPU, latencia del event loop, GC)

Los buckets de métricas están optimizados para cargas de procesamiento de imágenes: 0.01, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10, 30 segundos.

Endpoints de estado

• GET /health — devuelve 200 si el servicio está en ejecución
• GET /health/redis — devuelve el estado de la conexión con Redis, el role de conversión del pod y las profundidades de las colas pending y processing

Métodos de configuración

La aplicación se puede configurar mediante varios métodos, enumerados en orden de prioridad:

1. Variables de entorno
2. Kubernetes ConfigMap/Secrets
3. Archivo .env (solo para desarrollo)

Despliegue en Kubernetes

Al desplegar en Kubernetes, la configuración se gestiona mediante valores de Helm y secretos:

converter:
  image:
    repository: registry.gitlab.com/seatmap.pro/seatmap/converter-service
    tag: latest
  env:
    PORT: '3000'
    LOG_LEVEL: 'info'
    STORAGE_TYPE: 's3'
    AWS_REGION: 'us-east-1'
    AWS_BUCKET_NAME: 'your-bucket'
    # AWS_PUBLIC_BASE_URL: "https://your-cdn.example.com"  # if using non-AWS S3

Gestión de secretos

Las credenciales de AWS y las contraseñas de Redis deben gestionarse de forma segura mediante uno de estos métodos:

• Kubernetes Secrets (inyectados a través de seatmap-helm-secrets)
• External Secrets Operator
• IAM roles for Service Accounts (IRSA)

Configuración para desarrollo

Para el desarrollo local usando Docker Compose:

cd products/converter-service
cp .env.sample .env
# Edit .env with your settings (use STORAGE_TYPE=local for development)
docker compose up

Esto inicia el servicio del conversor en el puerto 3000 y una instancia de Redis en el puerto 6379.

Nunca incluyas credenciales sensibles en el control de versiones.

Resolución de problemas

Problemas de configuración comunes:

• Fallo al subir la imagen: Comprueba MAX_CONTENT_LENGTH y la configuración del tamaño del cuerpo en el ingress. El límite por defecto de 16 MB puede necesitar un aumento para archivos SVG grandes.
• Acceso denegado a S3: Verifica las credenciales de AWS y los permisos del bucket. Comprueba que AWS_PUBLIC_BASE_URL coincide con el esquema de URL real de tu bucket.
• Imágenes en blanco o corruptas: Verifica que Chromium esté instalado (/usr/bin/chromium-browser). En Docker, asegúrate de que la variable de entorno PUPPETEER_EXECUTABLE_PATH esté configurada correctamente.
• Uso elevado de memoria: Sharp y Puppeteer pueden consumir mucha memoria con archivos SVG grandes. Establece límites de memoria del contenedor de al menos 512 MB, con 2 GB recomendados para producción.
• WebP no se carga en el renderer: Asegúrate de que las cabeceras CORS estén configuradas en el bucket de S3. El renderer necesita acceso de origen cruzado para cargar las imágenes de fondo.
• URL públicas incorrectas: Si usas un proveedor de S3 distinto de AWS, define AWS_PUBLIC_BASE_URL de forma explícita. La generación de URL por defecto asume el estilo de bucket virtual-hosted de AWS.