repo init

2026-08-21 07:34:45 +03:00
commit 7e44db87b2
@@ -0,0 +1,53 @@
+# Cloud IP Validator
+
+Система проверки освобождённых публичных IPv4-адресов перед их повторной
+выдачей: каждый адрес привязывается как Floating IP к ВМ-валидатору в
+облаке (OpenStack), после чего проверяется одновременно в двух
+направлениях — исходящий трафик валидатора (egress: HTTPS/ICMP/опционально
+SSH до внешних целей) и входящая доступность самого адреса с трёх
+независимых внешних площадок (inbound: TCP 22/80/443/8080 + ICMP). Итог по
+каждому адресу — `pass`/`partial`/`fail`, с полной историей проверок в
+базе данных.
+
+Три компонента: `control-api` (управляющий сервис, единственный со
+состоянием), `validator-agent` (работает на каждой ВМ-валидаторе, без
+состояния) и `prober` (работает на каждой из трёх внешних площадок, без
+состояния). Все три общаются между собой только через HTTP API
+control-api.
+
+## Документация
+
+| Документ | Для чего |
+|---|---|
+| [docs/SETUP.md](docs/SETUP.md) | Сборка, конфигурация, первый запуск стенда — с нуля |
+| [docs/USAGE.md](docs/USAGE.md) | Повседневная работа: постановка адресов в очередь, наблюдение за статусом, разбор результатов |
+| [docs/API.md](docs/API.md) | Спецификация HTTP API control-api и примеры запросов (curl) |
+| [docs/LOCAL_E2E.md](docs/LOCAL_E2E.md) | Полностью офлайн-прогон всей системы одним скриптом — без реального облака и интернета |
+
+## Быстрый старт (60 секунд, без OpenStack)
+
+Хотите просто увидеть систему в работе — без реального облака:
+
+```bash
+go build ./... && go test ./...
+scripts/run-local-e2e.sh
+```
+
+Скрипт сам поднимет все три компонента как локальные процессы (в режиме
+`openstack.mode: mock`) и прогонит один тестовый адрес через полный цикл
+проверки, включая демонстрацию восстановления после сбоя валидатора.
+Подробности — в [docs/LOCAL_E2E.md](docs/LOCAL_E2E.md).
+
+## Быстрый старт (реальный стенд)
+
+1. Соберите три бинарника и подготовьте конфиги —
+   [docs/SETUP.md](docs/SETUP.md).
+2. Разверните `control-api` на управляющей машине, `validator-agent` —
+   на каждой ВМ-валидаторе, `prober` — на каждой из трёх площадок
+   ([пошагово в docs/SETUP.md](docs/SETUP.md#развёртывание-control-api)).
+3. Добавьте адреса в очередь и наблюдайте за результатом —
+   [docs/USAGE.md](docs/USAGE.md).
+
+```bash
+curl -s http://<control-api>:8080/api/v1/admin/status | python3 -m json.tool
+```