ayurishchevandClaude Sonnet 5
008ae1b0db
Replaced the duplicated Docker walkthrough (now fully covered in docs/SETUP.md) with a single link, and turned the prose description of each component into an explicit role/state/host table so the architecture reads at a glance. Cuts the file roughly in half. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Cloud IP Validator
Система проверки освобождённых публичных IPv4-адресов перед их повторной
выдачей: каждый адрес временно привязывается как Floating IP к
ВМ-валидатору в облаке (OpenStack) и проверяется одновременно в двух
направлениях — исходящий трафик валидатора (egress: HTTPS/ICMP/опционально
SSH до внешних целей) и входящая доступность самого адреса с нескольких
независимых внешних площадок (inbound: TCP 22/80/443/8080 + ICMP). Итог по
каждому адресу — pass/partial/fail, с полной историей проверок,
которая сохраняется даже после того, как адрес убрали из очереди (см.
«Реестр адресов»).
Роли компонентов
| Компонент | Роль | Состояние | Где работает |
|---|---|---|---|
control-api |
Управляющий сервис: ведёт очередь адресов и реестр их истории, назначает валидаторов, агрегирует результаты. Единственная точка, с которой общаются все остальные компоненты. | Хранит (SQLite) | Одна управляющая машина |
validator-agent |
Привязывает к себе выданный Floating IP и прогоняет egress-проверки до внешних целей. | Без состояния | Каждая ВМ-валидатор в облаке |
prober |
Проверяет входящую доступность адреса снаружи (TCP/ICMP) — с независимой от облака сети. | Без состояния | Каждая внешняя тестовая площадка |
admin-dashboard |
Браузерная админ-панель — то же самое, что доступно через API control-api, но графически. Опционален. |
Без состояния | Любая машина с сетевым доступом к control-api |
Все четыре общаются между собой только через HTTP API control-api —
прямых связей между остальными компонентами нет. Подробная схема
control/data plane — в docs/DIAGRAMS.md.
Документация
| Документ | Для чего |
|---|---|
| docs/SETUP.md | Развёртывание с нуля: бинарники или сборка из исходников, конфигурация, systemd и Docker/docker-compose — пошагово |
| docs/USAGE.md | Повседневная работа: постановка адресов в очередь, сканирование Floating IP, наблюдение за статусом, реестр и история, разбор результатов |
| docs/API.md | Спецификация HTTP API control-api и примеры запросов (curl) |
| docs/DASHBOARD.md | Устройство admin-dashboard: страницы, поиск/фильтр, обработка ошибок |
| docs/DIAGRAMS.md | Диаграммы потоков данных: control plane, egress-проверка, телеметрия |
| docs/LOCAL_E2E.md | Полностью офлайн-прогон всей системы одним скриптом — без реального облака и интернета |
| docs/CONTROL_DATA_PLANE.html | Презентационные схемы control/data plane для docker-compose-деплоя — открыть в браузере |
Быстрый старт
Посмотреть систему в работе без реального облака (60 секунд):
go build ./... && go test ./...
scripts/run-local-e2e.sh
Поднимет все компоненты как локальные процессы (openstack.mode: mock) и
прогонит тестовый адрес через полный цикл проверки. Подробности —
docs/LOCAL_E2E.md.
Для реального стенда (systemd-юниты или Docker/docker-compose, на одной машине или распределённо) — по шагам в docs/SETUP.md, начиная с «Получение бинарников».