From 008ae1b0dbc95c5c6f12063fd4b870febe6e17e1 Mon Sep 17 00:00:00 2001 From: ayurishchev Date: Wed, 23 Sep 2026 14:10:21 +0300 Subject: [PATCH] Trim README.md down to an entry point with links, add a component role table 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 --- README.md | 127 ++++++++++++++---------------------------------------- 1 file changed, 33 insertions(+), 94 deletions(-) diff --git a/README.md b/README.md index 46b6791..d78bb5e 100644 --- a/README.md +++ b/README.md @@ -1,115 +1,54 @@ # Cloud IP Validator Система проверки освобождённых публичных IPv4-адресов перед их повторной -выдачей: каждый адрес привязывается как Floating IP к ВМ-валидатору в -облаке (OpenStack), после чего проверяется одновременно в двух +выдачей: каждый адрес временно привязывается как Floating IP к +ВМ-валидатору в облаке (OpenStack) и проверяется одновременно в двух направлениях — исходящий трафик валидатора (egress: HTTPS/ICMP/опционально -SSH до внешних целей) и входящая доступность самого адреса с трёх +SSH до внешних целей) и входящая доступность самого адреса с нескольких независимых внешних площадок (inbound: TCP 22/80/443/8080 + ICMP). Итог по -каждому адресу — `pass`/`partial`/`fail`, с полной историей проверок в -базе данных. +каждому адресу — `pass`/`partial`/`fail`, с полной историей проверок, +которая сохраняется даже после того, как адрес убрали из очереди (см. +[«Реестр адресов»](docs/USAGE.md#реестр-адресов-и-глубина-истории)). -Четыре компонента: `control-api` (управляющий сервис, единственный со -состоянием), `validator-agent` (работает на каждой ВМ-валидаторе, без -состояния), `prober` (работает на каждой из трёх внешних площадок, без -состояния) и `admin-dashboard` (браузерная веб-панель администратора, без -состояния, опциональна). Все четыре общаются между собой только через -HTTP API control-api. +## Роли компонентов + +| Компонент | Роль | Состояние | Где работает | +|---|---|---|---| +| `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/DIAGRAMS.md). ## Документация | Документ | Для чего | |---|---| -| [docs/SETUP.md](docs/SETUP.md) | Развёртывание из готовых бинарников (`bin/`) или сборка из исходников, конфигурация, первый запуск стенда — с нуля, включая исчерпывающую инструкцию по Docker/docker-compose | -| [docs/USAGE.md](docs/USAGE.md) | Повседневная работа: постановка адресов в очередь, наблюдение за статусом, разбор результатов | -| [docs/API.md](docs/API.md) | Спецификация HTTP API control-api и примеры запросов (curl) | -| [docs/DASHBOARD.md](docs/DASHBOARD.md) | Браузерная админ-панель (`admin-dashboard`) — то же самое API, но графически | -| [docs/DIAGRAMS.md](docs/DIAGRAMS.md) | Диаграммы потоков данных: control plane, поток проверки до целевого сервера, поток телеметрии | +| [docs/SETUP.md](docs/SETUP.md) | Развёртывание с нуля: бинарники или сборка из исходников, конфигурация, systemd **и** Docker/docker-compose — пошагово | +| [docs/USAGE.md](docs/USAGE.md) | Повседневная работа: постановка адресов в очередь, сканирование Floating IP, наблюдение за статусом, реестр и история, разбор результатов | +| [docs/API.md](docs/API.md) | Спецификация HTTP API `control-api` и примеры запросов (curl) | +| [docs/DASHBOARD.md](docs/DASHBOARD.md) | Устройство `admin-dashboard`: страницы, поиск/фильтр, обработка ошибок | +| [docs/DIAGRAMS.md](docs/DIAGRAMS.md) | Диаграммы потоков данных: control plane, egress-проверка, телеметрия | | [docs/LOCAL_E2E.md](docs/LOCAL_E2E.md) | Полностью офлайн-прогон всей системы одним скриптом — без реального облака и интернета | -| [deploy/docker/RUN.txt](deploy/docker/RUN.txt) | Краткая шпаргалка команд `docker build`/`docker run` по компонентам (без пояснений) — подробный пошаговый разбор, включая docker-compose, см. в [docs/SETUP.md](docs/SETUP.md#развёртывание-в-docker) | -| [docs/CONTROL_DATA_PLANE.html](docs/CONTROL_DATA_PLANE.html) | Презентационные схемы control plane и data plane для микросервисного (docker-compose) деплоя — открыть в браузере | +| [docs/CONTROL_DATA_PLANE.html](docs/CONTROL_DATA_PLANE.html) | Презентационные схемы control/data plane для docker-compose-деплоя — открыть в браузере | -## Быстрый старт (60 секунд, без OpenStack) +## Быстрый старт -Хотите просто увидеть систему в работе — без реального облака: +Посмотреть систему в работе без реального облака (60 секунд): ```bash go build ./... && go test ./... scripts/run-local-e2e.sh ``` -Скрипт сам поднимет все три компонента как локальные процессы (в режиме -`openstack.mode: mock`) и прогонит один тестовый адрес через полный цикл -проверки, включая демонстрацию восстановления после сбоя валидатора. -Подробности — в [docs/LOCAL_E2E.md](docs/LOCAL_E2E.md). +Поднимет все компоненты как локальные процессы (`openstack.mode: mock`) и +прогонит тестовый адрес через полный цикл проверки. Подробности — +[docs/LOCAL_E2E.md](docs/LOCAL_E2E.md). -## Быстрый старт (реальный стенд) - -1. Возьмите готовые бинарники из `bin/` (Linux x86_64, статические, без - зависимостей) или соберите из исходников, подготовьте конфиги — - [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://:8080/api/v1/admin/status | python3 -m json.tool -``` - -## Развёртывание в Docker - -Все четыре компонента можно собрать и запустить как отдельные Docker-образы -вместо systemd-юнитов — Dockerfile'ы лежат в `deploy/docker/<компонент>/`. -Исчерпывающая пошаговая инструкция (docker-compose для одного хоста и для -распределённого по нескольким хостам стенда, точечный `docker build`/`docker -run` по компоненту, обновление образов, диагностика) — -[docs/SETUP.md → «Развёртывание в Docker»](docs/SETUP.md#развёртывание-в-docker); -краткая шпаргалка тех же команд — в -[deploy/docker/RUN.txt](deploy/docker/RUN.txt). - -- `prober`, `validator-agent`, `admin-dashboard` — конфиг генерируется - внутри контейнера из переменных окружения (`docker-entrypoint.sh` + - `envsubst`), готовых образов для монтирования не требуется. -- `control-api` — конфиг содержит списки (validators/sites/targets/ - ip_addresses) и имена env-переменных для OpenStack-креденшлов, поэтому - монтируется файлом (`-v .../control-api.yaml:/etc/cloud-ip-validator/control-api.yaml:ro`), - а база данных — отдельным volume для персистентности. - -Пример для `prober`: - -```bash -docker build --platform linux/amd64 -t cloud-ip-validator-prober -f deploy/docker/prober/Dockerfile . -docker run -d --platform linux/amd64 --cap-add NET_RAW --name prober \ - -e PROBER_SITE_ID= \ - -e PROBER_CONTROL_API_URL= \ - cloud-ip-validator-prober -``` - -`site_id` должен быть заранее зарегистрирован на control-api -(`PUT /api/v1/admin/config/sites/{index}`) — иначе контейнер завершится с -ошибкой регистрации. Аналогичные команды для остальных трёх компонентов — -в [deploy/docker/RUN.txt](deploy/docker/RUN.txt). - -### Запуск всех компонентов через docker-compose - -Для совместного запуска (сеть, healthcheck, volume для базы данных) есть -`docker-compose.yml` в `deploy/docker/` — разбит на базовый файл и -окружения: `docker-compose.override.yml` (dev, подхватывается автоматически) -и `docker-compose.prod.yml` (прод). Набор запускаемых сервисов на каждом -хосте задаётся через `COMPOSE_PROFILES` в `.env`-файле (`control-plane`, -`dashboard`, `prober`, `validator`) — так один и тот же compose можно -поднять целиком локально или по частям на разных хостах (управляющая -машина / внешняя площадка с `prober` / ВМ-валидатор), как в реальной -топологии. - -```bash -cd deploy/docker -cp .env.example .env -cp control-api/control-api.docker.example.yaml control-api/control-api.docker.yaml -docker compose up -d --build -``` - -Для прода: `docker compose -f docker-compose.yml -f docker-compose.prod.yml --env-file .env.prod up -d --build` -(см. комментарии в `.env.prod.example`). +Для реального стенда (systemd-юниты или Docker/docker-compose, на одной +машине или распределённо) — по шагам в +[docs/SETUP.md](docs/SETUP.md), начиная с +[«Получение бинарников»](docs/SETUP.md#получение-бинарников).