graph-go هو أداة لرسم البنية التحتية تعمل من سطر الأوامر أولاً. يكتشف تلقائياً بنيتك التحتية عن طريق الاتصال بخدمة Docker، وفحص الحاويات الجارية، واختبار قواعد البيانات وخدمات التخزين. يتم تقديم واجهة المستخدم من الواجهة الخلفية وتعكس حالة الواجهة الخلفية الحقيقية — لا حاجة لجرد يدوي.

وسوم 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 للحصول على السطح الكامل لكل أمر.

التدفق النموذجي:

1. graph-go demo للحصول على جولة محلية واقعية.
2. graph-go serve للتشغيل على بنيتك التحتية الخاصة.
3. graph-go scan للأتمتة لمرة واحدة، أو عمليات التصدير، أو فحوصات CI.

المنافذ

الإعدادات

الاكتشاف التلقائي هو المسار. قم بتركيب مقبس Docker و/أو التشغيل داخل مجموعة 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: يفحص الحاويات، يصنف الصور، يستخرج بيانات الاعتماد من متغيرات البيئة، يراقب أحداث Docker للتغييرات الحية في الطوبولوجيا
• Kubernetes Discovery: يستخدم informers من client-go مع معالجة أحداث مخففة (debounced)؛ يكتشف المساحات الاسمية، النشر، StatefulSets، DaemonSets، البودات، والخدمات مع رسم الصحة
• المهايئات: تطبق واجهة Adapter لاختبار قواعد البيانات وخدمات التخزين
• السجل: يدير المهايئات ومجموعات الطوبولوجيا، ينشئ عقداً أصلية على مستوى الخدمة، يجمع بيانات الرسم البياني
• الذاكرة المؤقتة: مدة صلاحية 30 ثانية مع نمط singleflight لمنع تدفق الطلبات
• WebSocket: يُدفع تحديثات الصحة كل 5 ثوانٍ

الواجهة الأمامية (React + TypeScript)

• تخطيط المسارات السباحية: تخطيط واعي بالمساحات الاسمية مع تصنيف المناطق (مساحات اسمية للنظام والبنية التحتية والتطبيقات)
• حاويات المجموعة: تُعرض مساحات K8s الاسمية كمربعات حدودية قابلة للطي عبر تجميع React Flow
• مفتش العقدة: لوحة جانبية تعرض بيانات التعريف والاتصالات التفصيلية
• خطاف WebSocket: تحديثات صحية حية بدون استطلاع

التسلسل الهرمي للعُقد

Adapter-discovered:
  Service Node (postgres/mongodb/s3)
      └─ Database/Bucket Node
          └─ Table/Collection/Prefix Node

Kubernetes-discovered:
  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 + informers)
• 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) التي تتحقق من:

• دورة حياة الاتصال/قطع الاتصال
• اكتشاف العقد والأطراف (معرفات فريدة، مراجع أصل صالحة، أنواع صحيحة)
• مقاييس الصحة (مفتاح الحالة، المفاتيح المطلوبة)

تشغيل اختبارات مهايئ واحد:

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 ثوانٍ). العقد المملوكة للمهايئ تحصل على الصحة عبر البحث في المهايئ؛ العقد الطوبولوجية (مثل موارد Kubernetes) تحمل الصحة مباشرة على العقدة.

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

health هي إحدى healthy, degraded, unhealthy.

graph_update — تُرسل عندما تتغير مجموعة معرفات العقد (تمت إضافة أو إزالة عقدة بواسطة الاكتشاف). 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
   • TestMain باستخدام testcontainers-go لتشغيل مثيل حقيقي
   • زرع بيانات تمثيلية
   • استدعاء adaptertest.RunContractTests للتحقق من عقد الواجهة
   • إضافة اختبارات خاصة بالمهايئ (تصفية، تنسيق معرف، بيانات تعريف، إلخ.)
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 — تُرجع []ServiceInfo من Discover(). المكتشفات المنتجة للطوبولوجيا (مثل K8s) تُملأ Nodes/Edges مباشرة؛ المكتشفات الموجهة للمهايئ (مثل Docker) تُملأ Config لجسر المهايئ.
3. ربطها بالخادم في internal/server/server.go — أضف دالة build{Name}Discovery() واستدعها بجانب المكتشفات الموجودة.
4. إضافة اختبارات تكامل مع //go:build integration — استخدم بنية تحتية حقيقية (kind/k3d لـ K8s، 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 يعمل مع كل دفع/PR إلى main — اختبارات وحدة الواجهة الخلفية، اختبارات التكامل (testcontainers)، وبناء الواجهة الأمامية
• الإصدارات تُطلق بواسطة وسوم الإصدار (v*) وتنتج:
  • برامج ثنائية متعددة المنصات (Linux, macOS, Windows) عبر GoReleaser
  • صورة Docker واحدة تُدفع إلى ghcr.io/guilherme-grimm/graph-go

لإنشاء إصدار:

git tag v0.1.0
git push --tags

خريطة الطريق

• اكتشاف Docker التلقائي
• مراقبة صحة خدمة HTTP
• مهايئ MySQL
• مهايئ Redis
• مهايئ Elasticsearch
• اختبارات التكامل مع testcontainers-go (جميع المهايئات)
• مجموعة اختبار العقد للامتثال لواجهة المهايئ
• واجهة Discoverer (واجهات اكتشاف قابلة للتوصيل)
• منسق Kubernetes (مساحات اسمية، نشر، StatefulSets، DaemonSets، بودات، خدمات)
• مراقبة فورية قائمة على informer لـ K8s مع debounce
• تخطيط المسارات السباحية مع حاويات مجموعات المساحات الاسمية
• جسر مهايئ K8s (تصنيف البودات حسب الصورة، ربط المهايئ بقواعد البيانات في البودات)
• مراقبة التدفق (تصور تدفق البيانات في الوقت الحقيقي)
• مشغل إجهاد متكامل (k6 مع تصور التأثير الفوري)
• مهايئ Kafka

الدعم

• المشكلات: github.com/guilherme-grimm/graph-go/issues
• المناقشات: github.com/guilherme-grimm/graph-go/discussions

بُني بحب ❤️ لمهندسي DevOps والبنية التحتية