ipam_control/docs/changes/034-caddy-publication/PLAN.md

# Публикация IPAM через Caddy: rxipam.rxmsk.ru (изменение 034)

> Отклонение при выполнении: схема с общей сетью `app_internal` (раздел 1) отменена из-за коллизии имён `app`/`db` — см. `SUMMARY.md`.

## Context
IPAM сейчас доступен только из LAN по HTTP (`192.168.5.9:8088`). Его нужно опубликовать в интернет через общий Caddy
(`/opt/lvraid/apps/caddy`) под `rxipam.rxmsk.ru` с TLS.

**Решения пользователя:**
- из интернета доступны UI и `/api/v1`;
- Swagger и OpenAPI (`/docs`, `/redoc`, `/openapi.json`) доступны только из частных сетей (RFC 1918 / RFC 4193, loopback);
- CNAME `rxipam` → `mkt.rxmsk.ru` в Cloudflare пользователь создаёт сам.

Отличить вызов API из UI от прямого вызова на уровне прокси нельзя: браузер SPA сам ходит в `/api/v1`.
Поэтому API в интернете защищают JWT, роли и лимиты входа приложения.

**Факты разведки:**
- Caddy работает в контейнере `caddy`, сети `app_external` (172.18/16) и `app_internal` (172.19/16).
  Сертификаты — ACME DNS-01 через Cloudflare, работает и без открытого 80.
- Caddy видит настоящие публичные IP клиентов (в логах `93.123.x`, `13.210.x` …), поэтому `remote_ip` для разграничения надёжен.
  LAN-клиенты, заходящие по публичному имени, приходят с `192.168.5.253`: это шлюз MikroTik (hairpin NAT), он в частном диапазоне.
- Приложение (`ipam_control_006-app-1`) — в своей сети `ipam_control_006_default`, Caddy его сейчас не видит.
- `X-Forwarded-For` приложение учитывает только от `TRUSTED_PROXIES` (`app/request_context.py::resolve_client_ip`, справа налево).
  Сейчас список пуст. Без него после публикации все интернет-клиенты получат один IP — IP Caddy, тогда:
  - лимит 20 неудач на IP блокирует вход всем сразу;
  - в журнале исчезнут реальные адреса.

## Изменения

### 1. Сеть: приложение в `app_internal` (репозиторий ipam_control)
- Новый `docker-compose.caddy.yml`: сервису `app` добавить сеть `app_internal` (external) с алиасом `ipam-app`, сеть `default` сохранить.
  Отдельный файл нужен, чтобы стенд на машине без Caddy (без сети `app_internal`) продолжал подниматься базовым `docker-compose.yml`.
- `.env` стенда:
  - `COMPOSE_FILE=docker-compose.yml:docker-compose.caddy.yml` — команды `docker compose -p ipam_control_006 …` из README и тестов не меняются;
  - `TRUSTED_PROXIES=172.19.0.0/16` — подсеть `app_internal`. IP контейнера Caddy при пересоздании может смениться, поэтому /32 не подходит.
    Остальные контейнеры этой сети — свои сервисы, риск подделки XFF от них приемлем.
- `.env.example`: закомментированные `COMPOSE_FILE` и `TRUSTED_PROXIES` с пояснением.
- `APP_BIND` оставить `0.0.0.0`: прямой LAN-доступ `:8088` сохраняется, порт на шлюзе наружу не проброшен.

### 2. Caddyfile (`/opt/lvraid/apps/caddy/Caddyfile`)
- Перед правкой — копия `Caddyfile.bak-2026-09-27`.
- Править **на месте**: файл смонтирован в контейнер одиночным bind-mount `:ro`. Замена inode, как делают редакторы с atomic-rename,
  оставит контейнер со старым файлом — после правки сверить `docker exec caddy cat /etc/caddy/Caddyfile`.
- Новый блок в стиле соседних (`vault`, `artstore`):
```
# IPAM Manager
rxipam.rxmsk.ru {
    log {
        output file /var/log/caddy/rxipam.log {
            roll_size 100mb
            roll_keep 5
            roll_keep_for 720h
        }
        format json
        level INFO
    }

    # Swagger/OpenAPI — только из частных сетей (RFC 1918/4193, loopback); из интернета — как будто их нет
    @docs_external {
        path /docs /docs/* /redoc /redoc/* /openapi.json
        not remote_ip private_ranges
    }
    respond @docs_external 404

    reverse_proxy ipam-app:8000

    header {
        Strict-Transport-Security "max-age=31536000; includeSubDomains; preload"
        -Server
    }
}
```
- `remote_ip` (TCP-пир), а не `client_ip`: у Caddy нет `trusted_proxies`, поэтому заголовки клиента на решение не влияют.
- XFF к приложению Caddy формирует сам и не доверяет входящему. Приложение берёт из него реальный IP (п. 1).
- `level INFO` — access-лог для разбора инцидентов (у соседей `ERROR`). CSP и прочие заголовки ставит приложение.
- Применение:
  - `docker exec caddy caddy validate --config /etc/caddy/Caddyfile`;
  - `docker exec caddy caddy reload --config /etc/caddy/Caddyfile`, без рестарта: остальные сайты не прерываются.

### 3. Документация (правила проекта)
- `docs/changes/034-caddy-publication/PLAN.md` — этот план; по завершении — `SUMMARY.md`.
- `README.md`, раздел «Публикация и эксплуатация»:
  - пример Caddy заменить фактической схемой: `docker-compose.caddy.yml`, `COMPOSE_FILE`, `TRUSTED_PROXIES`, ограничение Swagger;
  - добавить строку 034 в историю изменений.
- План 031 частично перекрыт. Часть 2 (свой Caddy-профиль) заменяется общим Caddy. Часть 1 (`DOCS_ENABLED=false` по умолчанию)
  остаётся как вторая линия защиты — отдельной задачей, в этот объём не входит.

## Замечания (без действий в этом объёме)
- LAN-пользователи через публичное имя идут через hairpin и для приложения выглядят одним IP `192.168.5.253`. Они делят лимит
  «20 неудач на IP» и неразличимы в журнале. Лечится split DNS на MikroTik (`rxipam.rxmsk.ru` → `192.168.5.9` внутри LAN):
  трафик пойдёт на Caddy напрямую с реальным LAN-IP. Рекомендация пользователю.
- Если шлюз когда-либо начнёт делать SNAT входящего интернет-трафика (masquerade на WAN→LAN), интернет-клиенты
  станут «частными» и получат Swagger. Это проверяется пунктом «из интернета» ниже; при смене конфигурации шлюза — перепроверять.

## Порядок выполнения
1. Пользователь: CNAME `rxipam` → `mkt.rxmsk.ru` (proxy в Cloudflare выключен, как у соседних: иначе `remote_ip` = IP Cloudflare).
2. ipam_control: `docker-compose.caddy.yml`, `.env` (`COMPOSE_FILE`, `TRUSTED_PROXIES`), `docker compose -p ipam_control_006 up -d`;
   проверить `docker exec caddy wget -qO- http://ipam-app:8000/healthz`.
3. Caddy: бэкап, правка блока, validate, reload.
4. Проверки (ниже), затем документация и коммит в ipam_control (Caddyfile вне репозитория).

## Проверка
- DNS: `getent hosts rxipam.rxmsk.ru` → `62.176.10.113`. Сертификат выпущен: `docker logs caddy` без ошибок ACME,
  `curl -sI https://rxipam.rxmsk.ru/` → 200, HSTS присутствует.
- Из LAN (частный IP): `/` 200, `/api/v1/auth/me` без токена 401, `/docs` и `/openapi.json` 200.
- Из интернета (мобильный интернет пользователя или внешний хост):
  - `/` 200 и вход в UI работает;
  - `/docs`, `/docs/`, `/redoc`, `/openapi.json`, `/openapi.json?x=1`, `//docs`, `/%64ocs` → 404;
  - в `rxipam.log` у этих запросов `remote_ip` публичный, `status` 404.
- Реальный IP в приложении: войти из интернета → в журнале (событие входа) `client_ip` — публичный адрес, не `172.19.x`.
  Вход из LAN через FQDN даёт `192.168.5.253`.
- Регрессия: `venv/bin/python -m pytest -q` (15 passed) — тесты идут на `127.0.0.1:8088`, мимо Caddy.
- Остальные сайты Caddy после reload отвечают: `curl -sI https://vault.rxmsk.ru`, `https://artstore.rxmsk.ru` → не 5xx.

## Откат
- Caddy: вернуть `Caddyfile.bak-2026-09-27` (на месте) и `caddy reload`.
- ipam_control: убрать `COMPOSE_FILE`/`TRUSTED_PROXIES` из `.env`, `docker compose -p ipam_control_006 up -d`.