1. База знаний
2. Развёртывание

Руководство по настройке Image Converter

Image converter — это микросервис на Node.js, который рендерит SVG-фоны площадок в оптимизированные изображения WebP. Он создаёт три варианта для каждого фона — в полном разрешении, превью на 1000px и размытый плейсхолдер на 400px со встроенными данными base64 для прогрессивной загрузки. Изображения хранятся в S3-совместимом объектном хранилище или в локальной файловой системе.

Стек: Node.js 22, Express 5, Puppeteer (headless Chromium для рендеринга SVG), Sharp (обработка изображений), Redis (очередь конвертаций).

Основные настройки

Настройки работы с файлами

Настройки обработки изображений

Настройки хранилища

Конфигурация AWS S3

Эти настройки обязательны при STORAGE_TYPE=s3.

ImportantУчётные данные AWS следует передавать через защищённые переменные окружения или секреты Kubernetes. Никогда не коммитьте учётные данные в систему контроля версий.

Разрешение публичного URL

Конвертер генерирует публичные URL для загруженных изображений. Базовый URL разрешается в следующем порядке приоритета:

1. AWS_PUBLIC_BASE_URL (если задан) — используется как есть. Пример: https://bucket.nyc3.digitaloceanspaces.com
2. AWS_ENDPOINT_URL (производный) — path-style: {endpoint}/{bucket}. Пример: https://storage.yandexcloud.net/my-bucket
3. По умолчанию — virtual-hosted style AWS: https://{bucket}.s3.{region}.amazonaws.com

Клиентам с self-hosted-развёртыванием, использующим не-AWS S3-провайдеров (DigitalOcean Spaces, MinIO, Garage, Yandex Cloud), следует задать AWS_PUBLIC_BASE_URL, чтобы обеспечить корректные публичные URL.

Политика бакета S3

Чтобы разрешить публичный доступ на чтение к изображениям, примените следующую политику бакета:

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

Конфигурация CORS

Чтобы предотвратить проблемы с tainted canvas при обработке изображений в веб-браузерах, настройте CORS на бакете:

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

NoteДля production-окружений ограничьте AllowedOrigins вашими конкретными доменами вместо *.

Настройки Redis

Конвертации ставятся в очередь Redis при REDIS_ENABLED=true (значение по умолчанию в Helm-чарте). Каждый запрос записывается как задание; конвертер с GPU забирает его первым, CPU-конвертер — после CPU_CLAIM_DELAY_MS, а задание, чей worker упал во время рендеринга, возвращается в очередь и повторяется. При REDIS_ENABLED=false конвертер рендерит внутри запроса и Redis не нужен. Если Redis включён, но недоступен, конвертер тоже рендерит внутри запроса, отвечает 503 на GET /jobs/{id} и пишет ошибки подключения в лог; очередь запускается сама, как только Redis становится доступен.

Аутентификация

Эндпоинты API

POST /, /background/ и /thumbnail/ принимают multipart/form-data с SVG-файлом (image/svg+xml). POST /photo/ принимает файл JPEG, PNG или WebP до 10 МБ и отвечает полями url и thumbUrl.

При включённой очереди маршрут конвертации отвечает 202 Accepted с id задания, а результат читается из GET /jobs/{id}; editor-service выполняет этот опрос сам. При выключенной очереди маршруты отвечают результатом напрямую.

Ограничение частоты: RATE_LIMIT_MAX запросов (по умолчанию 600) за RATE_LIMIT_WINDOW_MS (по умолчанию 60000) на один IP-адрес для маршрутов конвертации, включая /photo/. У GET /jobs/{id} свой бюджет — JOBS_RATE_LIMIT_MAX запросов в минуту (по умолчанию 5000). /health и /metrics не ограничиваются.

Таймаут запроса: 5 минут (300 секунд).

Формат вывода

Конвертер генерирует изображения WebP (не PNG), обеспечивая на 30–50% меньший размер файлов с поддержкой альфа-канала.

Для каждого фона создаётся три варианта:

Файлы хранятся по пути backgrounds/{filename}/{variant}.webp в настроенном бэкенде хранилища.

Docker

Сервис работает в Docker-контейнере на базе node:22.14.0-alpine с установленным Chromium для Puppeteer.

Порт: 3000

Проверка работоспособности: GET /health каждые 30 секунд (3 повтора, период старта 5 секунд)

Переменные окружения для Puppeteer:

• PUPPETEER_SKIP_CHROMIUM_DOWNLOAD=true (использует системный Chromium)
• PUPPETEER_EXECUTABLE_PATH=/usr/bin/chromium-browser

Безопасность: Работает от имени non-root-пользователя (uid 10001). Использует tini в качестве init-процесса для предотвращения зомби-процессов.

Мониторинг

Метрики Prometheus

Эндпоинт /metrics предоставляет:

• http_request_duration_seconds — гистограмма с метками method, route, status_code
• http_requests_total — счётчик с метками method, route, status_code
• Стандартные метрики процесса Node.js (память, CPU, задержка event loop, GC)

Бакеты метрик оптимизированы для нагрузок обработки изображений: 0.01, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10, 30 секунд.

Эндпоинты работоспособности

• GET /health — возвращает 200, если сервис работает
• GET /health/redis — возвращает статус подключения к Redis, роль пода при конвертации (role) и глубину очередей pending и processing

Способы конфигурации

Приложение можно настраивать несколькими способами, перечисленными в порядке приоритета:

1. Переменные окружения
2. Kubernetes ConfigMap/Secrets
3. Файл .env (только для разработки)

Развёртывание в Kubernetes

При развёртывании в Kubernetes конфигурация управляется через значения Helm и секреты:

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

Управление секретами

Учётные данные AWS и пароли Redis следует хранить безопасно, используя один из этих методов:

• Kubernetes Secrets (внедряются через seatmap-helm-secrets)
• External Secrets Operator
• IAM roles for Service Accounts (IRSA)

Настройка для разработки

Для локальной разработки с использованием Docker Compose:

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

Это запускает сервис конвертера на порту 3000 и экземпляр Redis на порту 6379.

Никогда не коммитьте чувствительные учётные данные в систему контроля версий.

Устранение неполадок

Распространённые проблемы конфигурации:

• Загрузка изображения не удаётся: Проверьте MAX_CONTENT_LENGTH и настройку ограничения размера тела запроса в ingress. Лимит по умолчанию 16 МБ может потребоваться увеличить для больших SVG-файлов.
• Отказ в доступе к S3: Проверьте учётные данные AWS и права доступа к бакету. Убедитесь, что AWS_PUBLIC_BASE_URL соответствует реальной схеме URL вашего бакета.
• Пустые или повреждённые изображения: Убедитесь, что Chromium установлен (/usr/bin/chromium-browser). В Docker убедитесь, что переменная окружения PUPPETEER_EXECUTABLE_PATH задана корректно.
• Высокое потребление памяти: Sharp и Puppeteer могут потреблять значительный объём памяти при работе с большими SVG-файлами. Установите лимиты памяти контейнера не менее 512 МБ, рекомендуется 2 ГБ для production.
• WebP не загружается в renderer: Убедитесь, что заголовки CORS настроены на бакете S3. Renderer’у нужен кросс-доменный доступ для загрузки фоновых изображений.
• Неверные публичные URL: Если вы используете не-AWS S3-провайдера, задайте AWS_PUBLIC_BASE_URL явно. Генерация URL по умолчанию предполагает virtual-hosted-стиль бакета AWS.