S.Gromov
0751c4b469
- добавлена сборка Caddy с Souin, Otter и NutsDB - добавлена конфигурация dev, prod и test Docker Compose - настроено кеширование через Otter L1 и NutsDB L2 - добавлены e2e-тесты Bun для кеша, restart и purge - добавлена документация по запуску, API кеша и тестам
129 lines
3.8 KiB
Markdown
129 lines
3.8 KiB
Markdown
# Руководство разработчика
|
||
|
||
## Требования
|
||
|
||
- Docker
|
||
- Docker Compose
|
||
|
||
## Режимы запуска
|
||
|
||
### Development (`docker-compose.dev.yml`)
|
||
|
||
Bridge-сеть, проброс портов:
|
||
- `8888` — Caddy (изображения)
|
||
- `2019` — Caddy Admin API (Souin purge)
|
||
|
||
```bash
|
||
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 сети.
|
||
|
||
```bash
|
||
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` | Исключения прокси |
|
||
|
||
### Генерация ключей подписи
|
||
|
||
```bash
|
||
openssl rand -hex 32 # KEY
|
||
openssl rand -hex 32 # SALT
|
||
```
|
||
|
||
## HTTPS (production)
|
||
|
||
Укажите домен в `.env`:
|
||
|
||
```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`:
|
||
|
||
```yaml
|
||
services:
|
||
app:
|
||
# ...
|
||
networks:
|
||
- gateway
|
||
|
||
networks:
|
||
gateway:
|
||
external: true
|
||
name: image-gateway_gateway
|
||
```
|
||
|
||
## Корпоративная сеть
|
||
|
||
```env
|
||
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-... # не закешировано
|
||
```
|
||
|
||
### Логи
|
||
|
||
```bash
|
||
docker compose -f docker-compose.dev.yml logs -f caddy # Caddy + Souin
|
||
docker compose -f docker-compose.dev.yml logs -f imgproxy # imgproxy
|
||
```
|