graph-go

Увидьте свою инфраструктуру. Ноль конфигурации.

Направьте graph-go на ваш стек и получите живую интерактивную карту каждой базы данных, таблицы, сервиса и хранилища — с мониторингом состояния в реальном времени.

graph-go demo

graph-go — это инфраструктурный картограф с CLI-интерфейсом. Он автоматически обнаруживает вашу инфраструктуру, подключаясь к демону Docker, проверяя запущенные контейнеры и опрашивая базы данных и службы хранения. Веб-интерфейс обслуживается бэкендом и отражает реальное состояние — ручной инвентаризации не требуется.

Возможность	Подробности
Автообнаружение	Обнаруживает инфраструктуру через контейнеры Docker и кластеры Kubernetes — без ручного ввода.
Kubernetes	Пространства имён, Deployment'ы, StatefulSet'ы, DaemonSet'ы, Pod'ы, Service'ы — с отслеживанием в реальном времени на основе информеров.
Docker	Классифицирует работающие контейнеры, извлекает учётные данные, отслеживает события Docker, учитывает метки `graphgo.*` для переопределения типа/DSN/типа узла/имени или игнорирования контейнера.
PostgreSQL	Таблицы, связи внешних ключей, топология схемы.
MongoDB	Базы данных и коллекции.
MySQL	Таблицы, связи внешних ключей.
Redis	Пространства ключей и распределение ключей.
Elasticsearch	Индексы, состояние кластера, статус шардов.
S3 / MinIO	Корзины и префиксы верхнего уровня.
HTTP-сервисы	Эндпоинты здоровья, сопоставление зависимостей между службами.
Мониторинг в реальном времени	Обновления состояния через WebSocket каждые 5 секунд.
Интерактивный граф	Swimlane-раскладка, группировка контейнеров по пространствам имён, панорамирование/масштабирование, фильтрация по типу/состоянию, поиск узлов.

Docker-метки

graph-go поддерживает небольшой набор меток контейнеров graphgo.* (установите их на любой контейнер, которым хотите управлять):

Используйте их для «спасения» неправильно классифицированных контейнеров, указания graph-go на произвольный DSN или скрытия контейнера из графа без его удаления.

Быстрый старт — попробуйте за 30 секунд

Запустите демонстрационный стек с предварительно заполненными данными с помощью CLI. Это самый быстрый способ увидеть graph-go в действии в реалистичном окружении и рекомендуемый путь для первых пользователей:

git clone https://github.com/guilherme-grimm/graph-go.git
cd graph-go
go run ./cmd/app demo

Откройте http://localhost:8080. Команда выполняется в прикреплённом режиме через Docker Compose. Нажмите Ctrl+C, чтобы остановить сессию.

Первый запуск может занять несколько минут на «холодной» машине, так как Docker может потребоваться скачать базовые образы и собрать локальные демо-образы. Последующие запуски выполняются значительно быстрее.

Демо-стек ожидает, что следующие порты на хосте свободны: 8080, 5432, 27017, 9000 и 9001.

Если требуется явный сброс окружения после:

docker compose -f docker-compose.demo.yml down

Запуск против своего стека

Один контейнер, один порт. Подключите сокет Docker только для чтения — и graph-go автоматически обнаружит всё, что работает на хосте:

docker run -d -p 8080:8080 \
  -v /var/run/docker.sock:/var/run/docker.sock:ro \
  ghcr.io/guilherme-grimm/graph-go:latest

graph-go только читает из сокета Docker. Флаг :ro обеспечивает это — сохраняйте его.

Откройте http://localhost:8080. Автообнаружение обрабатывает контейнеры Docker и (при наличии kubeconfig или сервисного аккаунта внутри кластера) ресурсы Kubernetes без какого-либо конфигурационного файла.

Для сервисов, работающих вне Docker/Kubernetes (удалённые базы данных, управляемые облачные сервисы), смонтируйте конфигурационный файл — см. Конфигурация.

Предварительно собранный бинарник

Один самодостаточный бинарный файл — веб-интерфейс встроен, но точка входа остаётся CLI.

# Linux amd64 (требуется GitHub CLI; другие платформы смотрите в Releases)
gh release download --repo guilherme-grimm/graph-go --pattern 'graph-go_*_linux_amd64.tar.gz' --clobber
tar xzf graph-go_*_linux_amd64.tar.gz
./graph-go serve   # или просто `./graph-go` — то же самое

Откройте http://localhost:8080. Другие платформы на странице релизов.

Команды

Глобальные флаги (применяются ко всем подкомандам): --config, --log-level, --log-format. Для полного описания каждой команды используйте graph-go <command> --help.

Типичный рабочий процесс:

graph-go demo — реалистичное локальное знакомство.
graph-go serve — запуск на собственной инфраструктуре.
graph-go scan — одноразовая автоматизация, экспорт или проверки CI.

Порты

Порт	Назначение
`8080`	graph-go (UI + API + WebSocket — production)
`5173`	Dev-сервер Vite (только разработка — см. CONTRIBUTING.md)

Конфигурация

Автообнаружение — это путь. Подключите сокет Docker и/или запустите внутри кластера Kubernetes — graph-go обнаружит вашу инфраструктуру без конфигурационного файла.

Используйте YAML-конфигурацию (conf/config.yaml) только как запасной вариант для сервисов, недоступных через обнаружение — удалённые базы данных, управляемые облачные службы, внешние эндпоинты. Полную схему с примерами для каждого адаптера и каждого блока конфигурации (server, docker, kubernetes, connections) см. в conf/config.sample.yaml.

Для использования конфигурационного файла при запуске через Docker (см. выше):

docker run -d -p 8080:8080 \
  -v /var/run/docker.sock:/var/run/docker.sock:ro \
  -v $(pwd)/conf/config.yaml:/app/conf/config.yaml:ro \
  ghcr.io/guilherme-grimm/graph-go:latest

Только авторизованное использование: graph-go предназначен для визуализации инфраструктуры, которой вы владеете или на доступ к которой имеете разрешение. Не направляйте его на системы без авторизации.

Архитектурный обзор

Бэкенд (Go)

                          ┌─────────────────────────────────────┐
                          │         Discoverer Interface         │
                          │  Discover() · Watch() · Close()     │
                          └──────────┬──────────┬───────────────┘
                                     │          │
                          ┌──────────▼──┐  ┌────▼──────────────┐
                          │   Docker    │  │   Kubernetes       │
                          │  Discoverer │  │   Discoverer       │
                          │ (containers,│  │ (informers, pods,  │
                          │  classify,  │  │  deployments,      │
                          │  events)    │  │  services, health) │
                          └──────┬──────┘  └────┬──────────────┘
                                 │               │
                          ┌──────▼───────────────▼──────┐
                          │  Parallel Discovery + Merge  │
                          │  (concatenate ServiceInfo)   │
                          └──────────────┬──────────────┘
                                         │
Config (YAML) ──→ YAML Merge ───────────▶│
                                         ▼
                          ┌─────────────────────────────┐
                          │     Adapter Registry         │
                          │  ├─ PostgreSQL  → Tables + FK│
                          │  ├─ MongoDB    → Collections │
                          │  ├─ MySQL      → Tables + FK │
                          │  ├─ Redis      → Keyspaces   │
                          │  ├─ Elasticsearch → Indices   │
                          │  ├─ S3         → Buckets      │
                          │  └─ HTTP       → Health + deps│
                          │                               │
                          │  + Topology (K8s nodes/edges) │
                          └──────────────┬───────────────┘
                                         ▼
                          Graph Model (Nodes + Edges)
                                         ▼
                          REST API + WebSocket (Real-time)

Ключевые компоненты:

Discoverer Interface: Единый контракт (Discover, Watch, Close) для всех механизмов обнаружения — Docker и Kubernetes выполняются параллельно, результаты объединяются.
Docker Discovery: Проверяет контейнеры, классифицирует образы, извлекает учётные данные из переменных окружения, отслеживает события Docker для живых изменений топологии.
Kubernetes Discovery: Использует информеры client-go с обработкой событий с задержкой (debounce); обнаруживает пространства имён, Deployment'ы, StatefulSet'ы, DaemonSet'ы, Pod'ы и Service'ы с отображением состояния здоровья.
Адаптеры: Реализуют интерфейс Adapter для опроса баз данных и служб хранения.
Registry: Управляет адаптерами и наборами топологии, создаёт родительские узлы уровня служб, агрегирует данные графа.
Cache: TTL 30 секунд с паттерном singleflight для предотвращения лавинообразных запросов.
WebSocket: Передаёт обновления состояния каждые 5 секунд.

Фронтенд (React + TypeScript)

Swimlane-раскладка: Учитывает пространства имён с классификацией зон (системные, инфраструктурные, прикладные пространства имён).
Группирующие контейнеры: Пространства имён K8s отображаются как сворачиваемые ограничивающие прямоугольники с помощью группировки React Flow.
Инспектор узлов: Боковая панель с подробными метаданными и связями.
WebSocket Hook: Обновления состояния в реальном времени без опроса.

Иерархия узлов

Обнаруженные адаптером:
  Service Node (postgres/mongodb/s3)
      └─ Database/Bucket Node
          └─ Table/Collection/Prefix Node

Обнаруженные Kubernetes:
  Namespace (групповой контейнер)
      └─ Deployment / StatefulSet / DaemonSet
          └─ Pod
      └─ K8sService ──routes_to──→ Pod

Рёбра представляют отношения (contains, foreign_key, routes_to и т.д.).

Технологический стек

Бэкенд:

Go 1.25.6
gorilla/mux (маршрутизация HTTP)
k8s.io/client-go (обнаружение Kubernetes + информеры)
pgxpool (PostgreSQL)
mongo-driver v2 (MongoDB)
go-sql-driver/mysql (MySQL)
go-redis/v9 (Redis)
go-elasticsearch/v8 (Elasticsearch)
AWS SDK v2 (S3)
coder/websocket (WebSocket)
testcontainers-go (интеграционные тесты)

Фронтенд:

TypeScript
React 19
@xyflow/react v12 (визуализация графа)
Vite (сборочный инструмент)

Инфраструктура:

Docker + Docker Compose
PostgreSQL 17
MongoDB 7
MySQL 8
Redis 7
Elasticsearch 8
MinIO (S3-совместимое хранилище)

Тестирование

Модульные тесты

go test ./...

Выполняются без Docker. Включают тесты чистых функций и тесты HTTP-обработчиков.

Интеграционные тесты

go test -tags=integration -v -timeout=5m ./internal/adapters/...

Требуют Docker. Используют testcontainers-go для запуска реальных экземпляров баз данных (PostgreSQL, MongoDB, MySQL, Redis, Elasticsearch, MinIO) — без заглушек.

Каждый адаптер проходит набор контрактных тестов (adaptertest.RunContractTests), который проверяет:

Жизненный цикл подключения/отключения.
Обнаружение узлов/рёбер (уникальные идентификаторы, корректные ссылки на родительские узлы, правильные типы).
Метрики состояния (ключ status, требуемые ключи).

Запуск тестов одного адаптера:

go test -tags=integration -v ./internal/adapters/redis/

Все тесты

make test  # unit + type-check
go test -tags=integration -timeout=5m ./internal/adapters/...  # integration

Справочник API

GET `/api/graph`

Возвращает полный граф инфраструктуры (узлы + рёбра).

Ответ:

{
  "data": {
    "nodes": [
      {
        "id": "service-postgres",
        "type": "postgres",
        "name": "postgres",
        "metadata": { "adapter": "postgres" },
        "health": "healthy"
      }
    ],
    "edges": [
      {
        "id": "edge-1",
        "source": "service-postgres",
        "target": "pg-mydb",
        "type": "contains",
        "label": "contains"
      }
    ]
  }
}

GET `/api/node/{id}`

Возвращает подробности о конкретном узле.

GET `/api/health`

Возвращает состояние здоровья адаптеров (ok/degraded/error).

WS `/websocket`

Передаёт обновления в реальном времени. Отправляются два типа сообщений, оба обёрнуты в { "type": "...", "payload": { ... } }. Поле timestamp отсутствует — клиенты определяют порядок по времени получения.

health_update — отправляется для каждого узла один раз за проход (каждые 5 с). Узлы, принадлежащие адаптерам, получают состояние через поиск в адаптере; топологические узлы (например, ресурсы K8s) несут состояние непосредственно в себе.

{
  "type": "health_update",
  "payload": {
    "nodeId": "service-postgres",
    "health": "healthy"
  }
}

health может быть healthy (здоров), degraded (деградировал), unhealthy (нездоров).

graph_update — отправляется при изменении набора идентификаторов узлов (узел был добавлен или удалён при обнаружении). payload пуст; клиентам следует повторно запросить /api/graph.

{
  "type": "graph_update",
  "payload": {}
}

Добавление нового адаптера

Создайте пакет адаптера в internal/adapters/{name}/

Реализуйте интерфейс Adapter:

type Adapter interface {
    Connect(config ConnectionConfig) error
    Discover() ([]nodes.Node, []edges.Edge, error)
    Health() (HealthMetrics, error)
    Close() error
}

Саморегистрация через init() с помощью adapters.RegisterFactory("name", ...)
Добавьте интеграционные тесты (обязательно) — создайте {name}_integration_test.go с:
- Тегом сборки //go:build integration
- TestMain с использованием testcontainers-go для запуска реального экземпляра
- Заполнением репрезентативными данными
- Вызовом adaptertest.RunContractTests для проверки контракта интерфейса
- Добавлением специфичных для адаптера тестов (фильтрация, формат ID, метаданные и т.д.)
Импортируйте адаптер в internal/server/server.go (пустой импорт для )

Добавление нового обнаружения (Discoverer)

Discoverer'ы находятся в internal/discovery/{name}/ и реализуют интерфейс Discoverer:

type Discoverer interface {
    Name() string
    Discover(ctx context.Context) ([]ServiceInfo, error)
    Watch(ctx context.Context, onChange func()) error
    Close() error
}

Создайте пакет discoverer в internal/discovery/{name}/
Реализуйте интерфейс Discoverer — возвращайте []ServiceInfo из Discover(). Discoverer'ы, генерирующие топологию (например, K8s), заполняют Nodes/Edges напрямую; адаптеро-ориентированные (например, Docker) заполняют Config для связывания с адаптерами.
Подключите в сервер в internal/server/server.go — добавьте функцию build{Name}Discovery() и вызовите её наряду с существующими discoverer'ами.
Добавьте интеграционные тесты с //go:build integration — используйте реальную инфраструктуру (kind/k3d для K8s, testcontainers для остальных). Без заглушек.

Подробные рекомендации см. в CONTRIBUTING.md.

Участие в разработке

Мы приветствуем вклад! См. CONTRIBUTING.md с рекомендациями по:

Настройке окружения разработки
Соглашениям о стиле кода
Как добавлять новые адаптеры
Отправке pull request'ов

Область использования и этика

Предназначено для:

Визуализации и мониторинга инфраструктуры, которой вы владеете или на доступ к которой имеете разрешение.
DevOps-дашбордов и карт топологии.
Документирования инфраструктуры и онбординга.
Исследования схем баз данных и связей.

Не предназначено для:

Несанкционированного сканирования систем или разведки.
Тестирования безопасности без явного разрешения.
Доступа к системам, которыми вы не владеете или не управляете.

Пользователи обязаны убедиться, что имеют надлежащие разрешения перед подключением graph-go к любой инфраструктуре.

Лицензия

Этот проект лицензирован под GNU Affero General Public License v3.0 (AGPL-3.0).

См. файл LICENSE для подробностей. AGPL требует, чтобы модифицированные версии, используемые через сеть, также распространялись с открытым исходным кодом.

CI/CD и релизы

Проект использует GitHub Actions для непрерывной интеграции и автоматических релизов.

CI выполняется при каждом push/PR в main — модульные тесты бэкенда, интеграционные тесты (testcontainers) и сборка фронтенда.
Релизы запускаются по тегам версий (v*) и включают:
- Кроссплатформенные бинарные файлы (Linux, macOS, Windows) через GoReleaser
- Единый Docker-образ, публикуемый на ghcr.io/guilherme-grimm/graph-go

Чтобы создать релиз:

git tag v0.1.0
git push --tags

План развития

Поддержка

Issues: github.com/guilherme-grimm/graph-go/issues
Discussions: github.com/guilherme-grimm/graph-go/discussions

Сделано с ❤️ для DevOps-инженеров и инженеров инфраструктуры

`graphgo.ignore=true`	Полностью пропустить этот контейнер.
`graphgo.type=postgres`	Принудительно задать тип адаптера (`postgres`, `mongodb`, `mysql`, `redis`, `elasticsearch`, `s3`, `http`).
`graphgo.dsn=...`	Внедрить строку подключения (DSN для postgres/mysql, URI для mongodb, иначе используется `dsn`).
`graphgo.node-type=gateway`	Переопределить визуальный тип узла (`service`, `gateway`, `auth`, `api`, `queue`, `cache`).
`graphgo.name=...`	Переопределить имя узла, отображаемое в графе и используемое в идентификаторах узлов/логах.

`graph-go demo`	Запускает предварительно заполненный демо-стек из репозитория (Docker Compose) и выводит его лог на передний план.
`graph-go serve`	Запускает HTTP-сервер с автообнаружением и обновлениями в реальном времени (по умолчанию — то же, что и запуск без аргументов).
`graph-go scan`	Выполняет одноразовое обнаружение и выводит граф в формате JSON в stdout. Полезно для передачи в `jq`, проверок CI или одноразового экспорта.
`graph-go version`	Выводит версию, коммит и дату сборки.
`graph-go --health-check`	Отправляет запрос на локальный `/health` и завершается с кодом `0`/`1`. Используется в качестве `HEALTHCHECK` контейнера; не предназначено для интерактивного использования.

graph-go

Популярное

graph-go

Docker-метки

Быстрый старт — попробуйте за 30 секунд

Запуск против своего стека

Предварительно собранный бинарник

Команды

Порты

Конфигурация

Архитектурный обзор

Бэкенд (Go)

Фронтенд (React + TypeScript)

Иерархия узлов

Технологический стек

Тестирование

Модульные тесты

Интеграционные тесты

Все тесты

Справочник API

GET /api/graph

GET /api/node/{id}

GET /api/health

WS /websocket

Добавление нового адаптера

Добавление нового обнаружения (Discoverer)

Участие в разработке

Область использования и этика

Лицензия

CI/CD и релизы

План развития

Поддержка

GET `/api/graph`

GET `/api/node/{id}`

GET `/api/health`

WS `/websocket`