graph-go ist ein CLI-first Infrastruktur-Mapper. Es erkennt Ihre Infrastruktur automatisch, indem es eine Verbindung zum Docker-Daemon herstellt, laufende Container inspiziert und Datenbanken sowie Speicherdienste abfragt. Die UI wird vom Backend bereitgestellt und spiegelt den echten Backend-Status wider – kein manuelles Inventar erforderlich.

Docker-Labels

graph-go respektiert eine kleine Anzahl von graphgo.*-Container-Labels (setzen Sie diese auf jedem Container, den Sie kontrollieren möchten):

Verwenden Sie diese, um falsch klassifizierte Container zu korrigieren, graph-go auf eine benutzerdefinierte DSN zu lenken oder einen Container aus dem Graphen auszublenden, ohne ihn zu entfernen.

Schnellstart – in 30 Sekunden ausprobieren

Starten Sie den vorkonfigurierten Demo-Stack mit der CLI. Dies ist der schnellste Weg, graph-go in einer realistischen Umgebung zu sehen und der empfohlene Onboarding-Pfad für Erstbenutzer:

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

Öffnen Sie http://localhost:8080. Der Befehl läuft als attachter Docker Compose-Container. Drücken Sie Ctrl+C, um die Sitzung zu beenden.

Der erste Start kann auf einem kalten Rechner mehrere Minuten dauern, da Docker möglicherweise Basis-Images herunterladen und die lokalen Demo-Images erstellen muss. Spätere Starts sind viel schneller.

Der Demo-Stack erwartet, dass die folgenden Host-Ports frei sind: 8080, 5432, 27017, 9000 und 9001.

Falls Sie einen expliziten Teardown benötigen:

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

Gegen Ihren eigenen Stack ausführen

Ein Container, ein Port. Mounten Sie den Docker-Socket schreibgeschützt und graph-go erkennt automatisch alles, was auf dem Host läuft:

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 liest nur vom Docker-Socket. Das :ro-Flag erzwingt dies – behalten Sie es bei.

Öffnen Sie http://localhost:8080. Auto-Discovery behandelt Docker-Container und (wenn eine Kubeconfig oder ein In-Cluster-Service-Account vorhanden ist) Kubernetes-Ressourcen ohne Konfigurationsdatei.

Für Dienste außerhalb von Docker/Kubernetes (Remote-Datenbanken, Managed-Cloud-Dienste) mounten Sie eine Konfigurationsdatei – siehe Konfiguration.

Vorgefertigte Binärdatei

Einzige eigenständige Binärdatei – UI ist eingebettet, aber der Einstiegspunkt bleibt die CLI.

# Linux amd64 (erfordert die GitHub-CLI; andere Plattformen in den Releases durchsuchen)
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   # oder einfach `./graph-go` – dasselbe

Öffnen Sie http://localhost:8080. Andere Plattformen auf der Releases-Seite.

Befehle

Globale Flags (für jeden Unterbefehl): --config, --log-level, --log-format. Siehe graph-go <command> --help für die vollständige befehlsspezifische Oberfläche.

Typischer Ablauf:

1. graph-go demo für einen realistischen lokalen Durchlauf.
2. graph-go serve zur Ausführung gegen Ihre eigene Infrastruktur.
3. graph-go scan für einmalige Automatisierung, Exporte oder CI-Checks.

Ports

Konfiguration

Auto-Discovery ist der Weg. Mounten Sie den Docker-Socket und/oder führen Sie ihn innerhalb eines Kubernetes-Clusters aus – graph-go erkennt Ihre Infrastruktur ohne Konfigurationsdatei.

Verwenden Sie die YAML-Konfiguration (conf/config.yaml) nur als Notausstieg für Dienste, die nicht über Discovery erreichbar sind – Remote-Datenbanken, Managed Cloud Services, externe Endpunkte. Siehe conf/config.sample.yaml für das vollständige Schema – Beispiele für jeden Adapter und jeden Konfigurationsblock (server, docker, kubernetes, connections).

Zur Verwendung einer Konfigurationsdatei mit dem obigen Docker-Run:

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

Nur für autorisierte Nutzung: graph-go dient der Visualisierung von Infrastruktur, die Ihnen gehört oder auf die Sie Zugriff haben. Richten Sie es nicht gegen Systeme ohne Autorisierung.

Architekturübersicht

Backend (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)

Schlüsselkomponenten:

• Discoverer Interface: Einheitlicher Vertrag (Discover, Watch, Close) für alle Discovery-Backends – Docker und Kubernetes laufen parallel, Ergebnisse werden zusammengeführt
• Docker Discovery: Inspiziert Container, klassifiziert Images, extrahiert Anmeldedaten aus Umgebungsvariablen, überwacht Docker-Ereignisse auf Live-Topologieänderungen
• Kubernetes Discovery: Verwendet client-go-Informer mit entprellter Ereignisverarbeitung; findet Namespaces, Deployments, StatefulSets, DaemonSets, Pods und Services mit Health-Zuordnung
• Adapter: Implementieren das Adapter-Interface zum Abfragen von Datenbanken und Speicherdiensten
• Registry: Verwaltet Adapter und Topologiesets, erstellt service-level Parent-Knoten, aggregiert Graphdaten
• Cache: 30-Sekunden-TTL mit Singleflight-Muster zur Vermeidung von Thundering-Herd
• WebSocket: Streamt Health-Updates alle 5 Sekunden

Frontend (React + TypeScript)

• Swimlane-Layout: Namespace-bewusstes Layout mit Zonenklassifikation (System-, Infra-, Anwendungs-Namespaces)
• Gruppencontainer: K8s-Namespaces werden als zusammenklappbare Begrenzungsboxen über React Flow-Gruppierung dargestellt
• Node Inspector: Seitenpanel mit detaillierten Metadaten und Verbindungen
• WebSocket-Hook: Echtzeit-Health-Updates ohne Polling

Knotenhierarchie

Adapter-entdeckt:
  Service-Knoten (postgres/mongodb/s3)
      └─ Datenbank/Bucket-Knoten
          └─ Tabelle/Collection/Prefix-Knoten

Kubernetes-entdeckt:
  Namespace (Gruppencontainer)
      └─ Deployment / StatefulSet / DaemonSet
          └─ Pod
      └─ K8sService ──routes_to──→ Pod

Kanten repräsentieren Beziehungen (contains, foreign_key, routes_to usw.).

Tech-Stack

Backend:

• Go 1.25.6
• gorilla/mux (HTTP-Routing)
• k8s.io/client-go (Kubernetes-Discovery + Informer)
• 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 (Integrationstests)

Frontend:

• TypeScript
• React 19
• @xyflow/react v12 (Graphvisualisierung)
• Vite (Build-Tool)

Infrastruktur:

• Docker + Docker Compose
• PostgreSQL 17
• MongoDB 7
• MySQL 8
• Redis 7
• Elasticsearch 8
• MinIO (S3-kompatibel)

Tests

Unit-Tests

go test ./...

Läuft ohne Docker. Enthält reine Funktionstests und HTTP-Handler-Tests.

Integrationstests

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

Erfordert Docker. Verwendet testcontainers-go, um reale Datenbankinstanzen (PostgreSQL, MongoDB, MySQL, Redis, Elasticsearch, MinIO) zu starten – keine Mocks.

Jeder Adapter durchläuft die Vertragstestsuite (adaptertest.RunContractTests), die Folgendes validiert:

• Connect/Disconnect-Lebenszyklus
• Node/Edge-Discovery (eindeutige IDs, gültige Elternreferenzen, korrekte Typen)
• Health-Metriken (Status-Schlüssel, erforderliche Schlüssel)

Führen Sie die Tests eines einzelnen Adapters aus:

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

Alle Tests

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

API-Referenz

GET /api/graph

Gibt den vollständigen Infrastrukturgraphen (Knoten + Kanten) zurück.

Antwort:

{
  "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}

Gibt Details zu einem bestimmten Knoten zurück.

GET /api/health

Gibt den Adapter-Health-Status zurück (ok/degraded/error).

WS /websocket

Streamt Echtzeit-Updates. Es werden zwei Nachrichtentypen ausgegeben, beide verpackt als { "type": "...", "payload": { ... } }. Es gibt kein timestamp-Feld – Clients leiten die Reihenfolge durch Ankunft ab.

health_update – wird für jeden Knoten einmal pro Durchlauf (alle 5s) gesendet. Adapter-eigene Knoten erhalten Health über die Adapter-Suche; Topologie-Knoten (z. B. Kubernetes-Ressourcen) tragen Health direkt auf dem Knoten.

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

health ist einer von healthy, degraded, unhealthy.

graph_update – wird gesendet, wenn sich der Satz der Knoten-IDs ändert (ein Knoten wurde durch Discovery hinzugefügt oder entfernt). payload ist leer; Clients sollten /api/graph erneut abrufen.

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

Hinzufügen eines neuen Adapters

1. Adapter-Paket erstellen in internal/adapters/{name}/
2. Das Adapter-Interface implementieren:
   root@kitploit:~

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

3. Selbstregistrierung über init() mit adapters.RegisterFactory("name", ...)
4. Integrationstests hinzufügen (erforderlich) – erstellen Sie {name}_integration_test.go mit:
   • Build-Tag //go:build integration
   • TestMain mit testcontainers-go, um eine reale Instanz zu starten
   • Repräsentative Daten vorbefüllen
   • adaptertest.RunContractTests aufrufen, um das Interface-Vertrag zu validieren
   • Adapter-spezifische Tests hinzufügen (Filterung, ID-Format, Metadaten usw.)
5. Adapter importieren in internal/server/server.go (Blank-Import für )

Hinzufügen eines neuen Discoverers

Discoverer leben in internal/discovery/{name}/ und implementieren das Discoverer-Interface:

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

1. Discoverer-Paket erstellen in internal/discovery/{name}/
2. Das Discoverer-Interface implementieren – geben Sie []ServiceInfo von Discover() zurück. Topologie-erzeugende Discoverer (wie K8s) füllen Nodes/Edges direkt; adapterorientierte (wie Docker) füllen Config für das Adapter-Bridging.
3. In Server einbinden in internal/server/server.go – fügen Sie eine build{Name}Discovery()-Funktion hinzu und rufen Sie sie parallel zu den bestehenden Discoverern auf.
4. Integrationstests hinzufügen mit //go:build integration – verwenden Sie echte Infrastruktur (kind/k3d für K8s, testcontainers für andere). Keine Mocks.

Siehe CONTRIBUTING.md für detaillierte Anleitungen.

Mitwirken

Wir freuen uns über Beiträge! Siehe CONTRIBUTING.md für Richtlinien zu:

• Entwicklungseinrichtung
• Code-Stil-Konventionen
• Hinzufügen neuer Adapter
• Einreichen von Pull Requests

Nutzungsumfang & Ethik

Bestimmungsgemäße Verwendung:

• Visualisierung und Überwachung von Infrastruktur, die Ihnen gehört oder auf die Sie autorisierten Zugriff haben
• DevOps-Dashboards und Topologieabbildung
• Infrastrukturdokumentation und Onboarding
• Erkundung von Datenbankschemas und -beziehungen

Nicht vorgesehen für:

• Unautorisierte System-Scans oder Aufklärung
• Sicherheitstests ohne ausdrückliche Genehmigung
• Zugriff auf Systeme, die Ihnen nicht gehören oder die Sie nicht kontrollieren

Benutzer sind dafür verantwortlich, sicherzustellen, dass sie vor dem Verbinden von graph-go mit jeglicher Infrastruktur über die entsprechende Autorisierung verfügen.

Lizenz

Dieses Projekt ist unter der GNU Affero General Public License v3.0 (AGPL-3.0) lizenziert.

Siehe LICENSE-Datei für Details. AGPL erfordert, dass modifizierte Versionen, die über ein Netzwerk genutzt werden, ebenfalls quelloffen sein müssen.

CI/CD & Releases

Das Projekt verwendet GitHub Actions für kontinuierliche Integration und automatisierte Releases.

• CI wird bei jedem Push/PR auf main ausgeführt – Backend-Unit-Tests, Integrationstests (testcontainers) und Frontend-Build
• Releases werden durch Versions-Tags (v*) ausgelöst und erzeugen:
  • Plattformübergreifende Binärdateien (Linux, macOS, Windows) via GoReleaser
  • Einzelnes Docker-Image, das an ghcr.io/guilherme-grimm/graph-go gesendet wird

So erstellen Sie ein Release:

git tag v0.1.0
git push --tags

Roadmap

• Docker-Auto-Discovery
• HTTP-Service-Health-Überwachung
• MySQL-Adapter
• Redis-Adapter
• Elasticsearch-Adapter
• Integrationstests mit testcontainers-go (alle Adapter)
• Vertragstestsuite für Adapter-Interface-Konformität
• Discoverer-Interface (steckbare Discovery-Backends)
• Kubernetes-Orchestrator (Namespaces, Deployments, StatefulSets, DaemonSets, Pods, Services)
• Informer-basiertes Echtzeit-K8s-Watching mit Entprellung
• Swimlane-Layout mit Namespace-Gruppencontainern
• K8s-Adapter-Bridging (Pods nach Image klassifizieren, Adapter mit Datenbanken in Pods verbinden)
• Flow-Beobachtbarkeit (Echtzeit-Datenflussvisualisierung)
• Integrierter Stress-Trigger (k6 mit Echtzeit-Auswirkungsvisualisierung)
• Kafka-Adapter

Support

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

Mit ❤️ für DevOps- und Infrastruktur-Ingenieure entwickelt