Files

S.Gromov 0751c4b469 feat: добавить Image Gateway с кешем Souin

- добавлена сборка Caddy с Souin, Otter и NutsDB

- добавлена конфигурация dev, prod и test Docker Compose

- настроено кеширование через Otter L1 и NutsDB L2

- добавлены e2e-тесты Bun для кеша, restart и purge

- добавлена документация по запуску, API кеша и тестам

2026-05-04 12:18:37 +03:00

3.8 KiB

Raw Blame History

Руководство разработчика

Требования

Docker
Docker Compose

Режимы запуска

Development (`docker-compose.dev.yml`)

Bridge-сеть, проброс портов:

8888 — Caddy (изображения)
2019 — Caddy Admin API (Souin purge)

docker compose -f docker-compose.dev.yml up -d --build
docker compose -f docker-compose.dev.yml down
docker compose -f docker-compose.dev.yml logs -f caddy
docker compose -f docker-compose.dev.yml logs -f imgproxy

Production (`docker-compose.yml`)

Bridge-сеть, порт 80 (или 443 с HTTPS). Порт 2019 не пробрасывается — доступен только внутри Docker сети.

docker compose up -d --build

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

Все настройки через .env файл (см. .env.example).

imgproxy

Переменная	Описание	По умолчанию
`IMGPROXY_KEY`	Hex-ключ для подписи URL (пусто = unsigned)	—
`IMGPROXY_SALT`	Hex-соль для подписи URL	—
`IMGPROXY_WORKERS`	Количество воркеров обработки	`2`
`IMGPROXY_MAX_SRC_RESOLUTION`	Макс. разрешение исходника (MP)	`20`
`IMGPROXY_ALLOWED_SOURCES`	Whitelist доменов (через запятую)	—
`IMGPROXY_DOWNLOAD_TIMEOUT`	Таймаут загрузки исходника (сек)	`30`

Caddy

Переменная	Описание	По умолчанию
`CADDY_PORT`	Порт Caddy	`8888` (dev) / `80` (prod)
`DOMAIN`	Домен для HTTPS (пусто = localhost, prod only)	—

Сеть (опционально)

Переменная	Описание
`HTTP_PROXY`	HTTP-прокси для imgproxy
`HTTPS_PROXY`	HTTPS-прокси для imgproxy
`NO_PROXY`	Исключения прокси

Генерация ключей подписи

openssl rand -hex 32  # KEY
openssl rand -hex 32  # SALT

HTTPS (production)

Укажите домен в .env:

DOMAIN=images.example.com

Caddy автоматически получит Let's Encrypt сертификат.

Интеграция с внешними сервисами

Next.js или другой сервис внутри Docker сети ходит к Caddy Admin API для purge:

http://caddy:2019/souin-api/souin/        — GET список ключей
http://caddy:2019/souin-api/souin/flush    — PURGE полный сброс
http://caddy:2019/souin-api/souin/{regex}  — PURGE по regex

Для добавления Next.js в сеть — подключить контейнер к сети gateway:

services:
  app:
    # ...
    networks:
      - gateway

networks:
  gateway:
    external: true
    name: image-gateway_gateway

Корпоративная сеть

HTTP_PROXY=http://proxy.company.com:8080
HTTPS_PROXY=http://proxy.company.com:8080
NO_PROXY=localhost,127.0.0.1,.company.com

GODEBUG=http2client=0 уже задан в compose — отключает HTTP/2 в Go, решает проблемы с Cloudflare через прокси.

Мониторинг

Cache-Status заголовок

Cache-Status: Souin; hit; ttl=31535999; detail=DEFAULT          # из кеша
Cache-Status: Souin; fwd=uri-miss; stored; key=GET-...          # закешировано
Cache-Status: Souin; fwd=uri-miss; detail=UNCACHEABLE-...       # не закешировано

Логи

docker compose -f docker-compose.dev.yml logs -f caddy     # Caddy + Souin
docker compose -f docker-compose.dev.yml logs -f imgproxy  # imgproxy

3.8 KiB Raw Blame History Unescape Escape