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

4.2 KiB

Raw Blame History

URL-справочник

Формат URL

Unsigned (по умолчанию)

/unsafe/{processing_options}/plain/{source_url}

Signed

/{signature}/{processing_options}/plain/{source_url}

Source URL

Два варианта кодирования source URL:

Вариант	Пример
`plain/{url}`	`plain/https://example.com/photo.jpg`
`{base64url}`	`aHR0cHM6Ly9leGFtcGxlLmNvbS9waG90by5qcGc`

Processing options

Resize

Вписать в размер (сохраняет пропорции, не увеличивает):

/unsafe/resize:fit:{width}:{height}:0/plain/https://example.com/photo.jpg

Заполнить размер (сохраняет пропорции, обрезает лишнее):

/unsafe/resize:fill:{width}:{height}:0/plain/https://example.com/photo.jpg

Точный размер (растягивает/сжимает):

/unsafe/resize:force:{width}:{height}:0/plain/https://example.com/photo.jpg

height:0 = автоопределение высоты по пропорциям.

Crop

/unsafe/crop:{width}:{height}:0/plain/https://example.com/photo.jpg

Качество

/unsafe/q:{1-100}/plain/https://example.com/photo.jpg

Конвертация формата

Добавить расширение к source URL:

/unsafe/q:80/plain/https://example.com/photo.jpg.webp
/unsafe/q:80/plain/https://example.com/photo.jpg.avif

Поддерживаемые форматы: JPEG, PNG, WebP, AVIF, GIF, ICO, SVG, TIFF, HEIC

Гравитация (для crop/fill)

/unsafe/resize:fill:400:300:0/g:ce/plain/https://example.com/photo.jpg

Значение	Описание
`ce`	Центр (по умолчанию)
`no`	Верх
`so`	Низ
`ea`	Право
`we`	Лево
`noea`	Верх-право
`nowe`	Верх-лево
`soea`	Низ-право
`sowe`	Низ-лево

Автоопределение высоты

height = 0 — imgproxy автоматически вычисляет высоту, сохраняя пропорции:

/unsafe/resize:fit:800:0:0/q:80/plain/https://example.com/photo.jpg

Примеры

Вписать в 800px по ширине, качество 80

http://localhost:8888/unsafe/resize:fit:800:0:0/q:80/plain/https://example.com/photo.jpg

Превью 200x200, качество 60

http://localhost:8888/unsafe/resize:fill:200:200:0/g:ce/q:60/plain/https://example.com/photo.jpg

Конвертация в WebP

http://localhost:8888/unsafe/q:80/plain/https://example.com/photo.jpg.webp

Комбинированная обработка

http://localhost:8888/unsafe/resize:fit:1200:0:0/g:ce/q:75/plain/https://example.com/photo.jpg.webp

Использование base64url

echo -n "https://example.com/photo.jpg" | base64 -w0 | tr '+/' '-_' | tr -d '='
# → aHR0cHM6Ly9leGFtcGxlLmNvbS9waG90by5qcGc

http://localhost:8888/unsafe/resize:fit:800:0:0/q:80/aHR0cHM6Ly9leGFtcGxlLmNvbS9waG90by5qcGc

Подпись URL (HMAC-SHA256)

Когда заданы IMGPROXY_KEY и IMGPROXY_SALT, каждый запрос должен быть подписан.

import crypto from 'crypto'

function signUrl(key: string, salt: string, path: string): string {
  const hmac = crypto.createHmac('sha256', Buffer.from(key, 'hex'))
  hmac.update(Buffer.from(salt, 'hex'))
  hmac.update(path)
  const signature = hmac.digest().slice(0, 32).toString('base64url')
  return `/${signature}${path}`
}

// Использование:
const path = '/resize:fit:800:0:0/q:80/plain/https://example.com/photo.jpg'
const url = signUrl(IMGPROXY_KEY, IMGPROXY_SALT, path)
// → /SIGNED_SIGNATURE/resize:fit:800:0:0/q:80/plain/https://example.com/photo.jpg

Внимание: В SPA-приложениях ключи подписи утекают в браузер. Рекомендуется использовать unsigned режим (/unsafe/) с IMGPROXY_ALLOWED_SOURCES для защиты.

Справочник

Полная документация по параметрам обработки: imgproxy.net/docs

4.2 KiB Raw Blame History Unescape Escape