graph-go एक CLI-प्रथम इंफ्रास्ट्रक्चर मैपर है। यह डॉकर डेमॉन से कनेक्ट करके, चल रहे कंटेनरों का निरीक्षण करके, और डेटाबेस तथा स्टोरेज सेवाओं की जाँच करके आपके इंफ्रास्ट्रक्चर को स्वचालित रूप से खोजता है। UI बैकएंड द्वारा प्रदान किया जाता है और वास्तविक बैकएंड स्थिति को दर्शाता है — कोई मैन्युअल इन्वेंट्री आवश्यक नहीं है।

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

अपने स्वयं के स्टैक के विरुद्ध चलाएँ

एक कंटेनर, एक पोर्ट। डॉकर सॉकेट को केवल-पढ़ने के लिए माउंट करें और 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 केवल डॉकर सॉकेट से पढ़ता है। :ro फ़्लैग इसे लागू करता है — इसे रखें।

http://localhost:8080 खोलें। स्वचालित खोज डॉकर कंटेनरों और (जब क्यूबकॉन्फ़िग या इन-क्लस्टर सेवा खाता मौजूद हो) Kubernetes संसाधनों को बिना किसी कॉन्फ़िग फ़ाइल के संभालती है।

डॉकर/Kubernetes के बाहर रहने वाली सेवाओं (रिमोट डेटाबेस, प्रबंधित क्लाउड सेवाएँ) के लिए, एक कॉन्फ़िग फ़ाइल माउंट करें — कॉन्फ़िगरेशन देखें।

पूर्व-निर्मित बाइनरी

एकल स्व-निहित बाइनरी — UI एम्बेडेड है, लेकिन एंट्रीपॉइंट अभी भी 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 खोलें। अन्य प्लेटफ़ॉर्म Releases पेज पर।

कमांड

वैश्विक फ़्लैग (प्रत्येक उपकमांड पर लागू): --config, --log-level, --log-format। पूर्ण प्रति-कमांड सतह के लिए graph-go <command> --help देखें।

विशिष्ट प्रवाह:

1. यथार्थवादी स्थानीय वॉकथ्रू के लिए graph-go demo।
2. अपने स्वयं के इंफ्रास्ट्रक्चर के विरुद्ध चलाने के लिए graph-go serve।
3. एक-बार स्वचालन, निर्यात, या CI जाँच के लिए graph-go scan।

पोर्ट

कॉन्फ़िगरेशन

स्वचालित खोज मार्ग है। डॉकर सॉकेट माउंट करें और/या Kubernetes क्लस्टर के अंदर चलाएँ — graph-go आपके इंफ्रास्ट्रक्चर को बिना किसी कॉन्फ़िग फ़ाइल की आवश्यकता के खोज लेता है।

YAML कॉन्फ़िग (conf/config.yaml) का उपयोग केवल उन सेवाओं के लिए एस्केप हैच के रूप में करें जो खोज के माध्यम से पहुँच योग्य नहीं हैं — रिमोट डेटाबेस, प्रबंधित क्लाउड सेवाएँ, बाहरी एंडपॉइंट। पूर्ण स्कीमा के लिए conf/config.sample.yaml देखें — प्रत्येक अडैप्टर और प्रत्येक कॉन्फ़िग ब्लॉक (server, docker, kubernetes, connections) के उदाहरण।

ऊपर दिए गए 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: कंटेनरों का निरीक्षण करता है, छवियों को वर्गीकृत करता है, env vars से क्रेडेंशियल्स निकालता है, लाइव टोपोलॉजी परिवर्तनों के लिए डॉकर इवेंट्स देखता है
• Kubernetes Discovery: डीबाउंस इवेंट हैंडलिंग के साथ client-go informers का उपयोग करता है; स्वास्थ्य मैपिंग के साथ Namespaces, Deployments, StatefulSets, DaemonSets, Pods, और Services की खोज करता है
• Adapters: डेटाबेस और स्टोरेज सेवाओं की जाँच करने के लिए Adapter इंटरफ़ेस लागू करते हैं
• Registry: अडैप्टर और टोपोलॉजी सेट का प्रबंधन करता है, सेवा-स्तरीय पैरेंट नोड बनाता है, ग्राफ़ डेटा को एकत्रित करता है
• Cache: थंडरिंग हर्ड को रोकने के लिए सिंगलफ़्लाइट पैटर्न के साथ 30-सेकंड TTL
• WebSocket: हर 5 सेकंड में स्वास्थ्य अपडेट स्ट्रीम करता है

फ्रंटएंड (React + TypeScript)

• Swimlane Layout: नेमस्पेस-जागरूक लेआउट जिसमें ज़ोन वर्गीकरण (सिस्टम, इंफ्रा, एप्लिकेशन नेमस्पेस)
• Group Containers: K8s नेमस्पेस React Flow ग्रुपिंग के माध्यम से संक्षिप्त बाउंडिंग बॉक्स के रूप में रेंडर होते हैं
• Node Inspector: विस्तृत मेटाडेटा और कनेक्शन दिखाने वाला साइड पैनल
• WebSocket Hook: बिना पोलिंग के रीयल-टाइम स्वास्थ्य अपडेट

नोड पदानुक्रम

Adapter-d्वारा खोजे गए:
  Service Node (postgres/mongodb/s3)
      └─ Database/Bucket Node
          └─ Table/Collection/Prefix Node

Kubernetes-d्वारा खोजे गए:
  Namespace (group container)
      └─ 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 की आवश्यकता है। वास्तविक डेटाबेस इंस्टेंस (PostgreSQL, MongoDB, MySQL, Redis, Elasticsearch, MinIO) को स्पिन करने के लिए testcontainers-go का उपयोग करता है — कोई मॉक नहीं।

हर अडैप्टर अनुबंध परीक्षण सूट (adaptertest.RunContractTests) के माध्यम से चलता है जो मान्य करता है:

• कनेक्ट/डिस्कनेक्ट जीवनचक्र
• नोड/एज खोज (अद्वितीय IDs, मान्य पैरेंट संदर्भ, सही प्रकार)
• स्वास्थ्य मीट्रिक्स (स्थिति कुंजी, आवश्यक कुंजियाँ)

एकल अडैप्टर के परीक्षण चलाएँ:

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

सभी परीक्षण

make test  # यूनिट + प्रकार-जाँच
go test -tags=integration -timeout=5m ./internal/adapters/...  # एकीकरण

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 सेकंड) एक बार प्रत्येक नोड के लिए भेजा जाता है। अडैप्टर-स्वामित्व वाले नोड अडैप्टर लुकअप के माध्यम से स्वास्थ्य प्राप्त करते हैं; टोपोलॉजी नोड (जैसे Kubernetes संसाधन) सीधे नोड पर स्वास्थ्य रखते हैं।

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

health इनमें से एक है: healthy, degraded, unhealthy।

graph_update — तब भेजा जाता है जब नोड IDs का सेट बदलता है (खोज द्वारा एक नोड जोड़ा या हटाया गया)। payload खाली है; क्लाइंट को /api/graph को फिर से लाना चाहिए।

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

नया अडैप्टर जोड़ना

1. अडैप्टर पैकेज बनाएँ internal/adapters/{name}/ में
2. Adapter इंटरफ़ेस लागू करें:
   root@kitploit:~

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

3. स्व-पंजीकरण init() के माध्यम से adapters.RegisterFactory("name", ...) के साथ
4. एकीकरण परीक्षण जोड़ें (आवश्यक) — {name}_integration_test.go बनाएँ जिसमें:
   • बिल्ड टैग //go:build integration
   • वास्तविक इंस्टेंस शुरू करने के लिए testcontainers-go का उपयोग करने वाला TestMain
   • प्रतिनिधि डेटा सीड करें
   • इंटरफ़ेस अनुबंध को मान्य करने के लिए adaptertest.RunContractTests कॉल करें
   • अडैप्टर-विशिष्ट परीक्षण जोड़ें (फ़िल्टरिंग, ID प्रारूप, मेटाडेटा, आदि)
5. अडैप्टर आयात करें internal/server/server.go में ( के लिए खाली आयात)

नया डिस्कवरर जोड़ना

डिस्कवरर internal/discovery/{name}/ में रहते हैं और Discoverer इंटरफ़ेस लागू करते हैं:

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

1. डिस्कवरर पैकेज बनाएँ internal/discovery/{name}/ में
2. Discoverer इंटरफ़ेस लागू करें — Discover() से []ServiceInfo लौटाएँ। टोपोलॉजी उत्पन्न करने वाले डिस्कवरर (जैसे K8s) सीधे Nodes/Edges भरते हैं; अडैप्टर-उन्मुख (जैसे Docker) अडैप्टर ब्रिजिंग के लिए Config भरते हैं।
3. सर्वर में वायर करें internal/server/server.go में — build{Name}Discovery() फ़ंक्शन जोड़ें और इसे मौजूदा डिस्कवरर के साथ कॉल करें।
4. एकीकरण परीक्षण जोड़ें //go:build integration के साथ — वास्तविक इंफ्रास्ट्रक्चर (K8s के लिए kind/k3d, अन्य के लिए testcontainers) का उपयोग करें। कोई मॉक नहीं।

विस्तृत मार्गदर्शन के लिए CONTRIBUTING.md देखें।

योगदान

हम योगदान का स्वागत करते हैं! दिशानिर्देशों के लिए CONTRIBUTING.md देखें:

• विकास सेटअप
• कोड शैली परंपराएँ
• नए अडैप्टर कैसे जोड़ें
• पुल रिक्वेस्ट सबमिट करना

उपयोग का दायरा और नैतिकता

इच्छित उपयोग:

• उस इंफ्रास्ट्रक्चर को विज़ुअलाइज़ और मॉनिटर करना जिसके आप मालिक हैं या जिसे एक्सेस करने का अधिकार है
• DevOps डैशबोर्ड और टोपोलॉजी मैपिंग
• इंफ्रास्ट्रक्चर दस्तावेज़ीकरण और ऑनबोर्डिंग
• डेटाबेस स्कीमा और संबंधों की खोज

इसके लिए अभिप्रेत नहीं:

• अनधिकृत सिस्टम स्कैनिंग या टोह लेना
• स्पष्ट अनुमति के बिना सुरक्षा परीक्षण
• उन सिस्टमों तक पहुँचना जिनके आप मालिक या नियंत्रित नहीं हैं

उपयोगकर्ता यह सुनिश्चित करने के लिए जिम्मेदार हैं कि graph-go को किसी भी इंफ्रास्ट्रक्चर से जोड़ने से पहले उनके पास उचित प्राधिकरण हो।

लाइसेंस

यह प्रोजेक्ट GNU Affero General Public License v3.0 (AGPL-3.0) के तहत लाइसेंस प्राप्त है।

विवरण के लिए LICENSE फ़ाइल देखें। AGPL की आवश्यकता है कि नेटवर्क पर उपयोग किए जाने वाले संशोधित संस्करण भी ओपन-सोर्स होने चाहिए।

CI/CD और रिलीज़

प्रोजेक्ट निरंतर एकीकरण और स्वचालित रिलीज़ के लिए GitHub Actions का उपयोग करता है।

• CI main पर प्रत्येक पुश/PR पर चलता है — बैकएंड यूनिट टेस्ट, एकीकरण परीक्षण (testcontainers), और फ्रंटएंड बिल्ड
• रिलीज़ संस्करण टैग (v*) द्वारा ट्रिगर होती हैं और उत्पादन करती हैं:
  • GoReleaser के माध्यम से क्रॉस-प्लेटफ़ॉर्म बाइनरी (Linux, macOS, Windows)
  • ghcr.io/guilherme-grimm/graph-go पर पुश की गई एकल Docker इमेज

रिलीज़ बनाने के लिए:

git tag v0.1.0
git push --tags

रोडमैप

• Docker स्वचालित खोज
• HTTP सेवा स्वास्थ्य निगरानी
• MySQL अडैप्टर
• Redis अडैप्टर
• Elasticsearch अडैप्टर
• testcontainers-go के साथ एकीकरण परीक्षण (सभी अडैप्टर)
• अडैप्टर इंटरफ़ेस अनुपालन के लिए अनुबंध परीक्षण सूट
• Discoverer इंटरफ़ेस (प्लग करने योग्य खोज बैकएंड)
• Kubernetes ऑर्केस्ट्रेटर (Namespaces, Deployments, StatefulSets, DaemonSets, Pods, Services)
• डीबाउंस के साथ इन्फ़ॉर्मर-आधारित रीयल-टाइम K8s वॉचिंग
• नेमस्पेस ग्रुप कंटेनरों के साथ स्विमलेन लेआउट
• K8s अडैप्टर ब्रिजिंग (पॉड्स को छवि द्वारा वर्गीकृत करें, पॉड्स में डेटाबेस से अडैप्टर कनेक्ट करें)
• प्रवाह अवलोकनीयता (रीयल-टाइम डेटा प्रवाह विज़ुअलाइज़ेशन)
• एकीकृत स्ट्रेस ट्रिगर (k6 रीयल-टाइम प्रभाव विज़ुअलाइज़ेशन के साथ)
• Kafka अडैप्टर

सहायता

• मुद्दे: github.com/guilherme-grimm/graph-go/issues
• चर्चाएँ: github.com/guilherme-grimm/graph-go/discussions

DevOps और इंफ्रास्ट्रक्चर इंजीनियरों के लिए ❤️ से बनाया गया