S.Gromov
98b162f2b8
- добавлены Gitea workflows для CI и ручного CD - настроен prod compose для запуска за reverse proxy - добавлена публикация Caddy image в Container Registry - обновлена документация по CI/CD и prod-сети
142 lines
4.3 KiB
Markdown
142 lines
4.3 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`)
|
||
|
||
Production compose рассчитан на запуск за внешним reverse proxy.
|
||
|
||
- host-порты не публикуются;
|
||
- `caddy` подключается к external Docker network `web`;
|
||
- reverse proxy должен ходить на `http://image-gateway:80` внутри сети `web`;
|
||
- порт `2019` не пробрасывается наружу и доступен только внутри Docker networks.
|
||
|
||
Перед первым запуском на сервере создайте сеть, если ее еще нет:
|
||
|
||
```bash
|
||
docker network create web
|
||
```
|
||
|
||
```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) | — |
|
||
| `CADDY_IMAGE` | Готовый Caddy image для CD-деплоя | `image-gateway-caddy:local` |
|
||
| `WEB_NETWORK` | External Docker network внешнего reverse proxy | `web` |
|
||
|
||
### Сеть (опционально)
|
||
|
||
| Переменная | Описание |
|
||
|---|---|
|
||
| `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
|
||
```
|