graph-go는 CLI 우선 인프라 매퍼입니다. Docker 데몬에 연결하고, 실행 중인 컨테이너를 검사하며, 데이터베이스 및 스토리지 서비스를 프로빙하여 인프라를 자동으로 발견합니다. 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

자체 스택에 대해 실행하기

하나의 컨테이너, 하나의 포트입니다. 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 외부에 있는 서비스(원격 데이터베이스, 관리형 클라우드 서비스)의 경우 구성 파일을 마운트하세요. 구성을 참조하십시오.

사전 빌드된 바이너리

단일 자체 포함 바이너리 — 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. 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 인터페이스: 모든 발견 백엔드에 대한 통일된 계약 (Discover, Watch, Close) — Docker와 Kubernetes가 병렬로 실행되고 결과가 연결됩니다.
• Docker 발견: 컨테이너를 검사하고, 이미지를 분류하며, 환경 변수에서 자격 증명을 추출하고, Docker 이벤트를 감시하여 실시간 토폴로지 변경을 처리합니다.
• Kubernetes 발견: 디바운스된 이벤트 처리를 통해 client-go 인포머를 사용합니다; 네임스페이스, 디플로이먼트, 스테이트풀셋, 데몬셋, 파드, 서비스를 상태 매핑과 함께 발견합니다.
• 어댑터: Adapter 인터페이스를 구현하여 데이터베이스 및 스토리지 서비스를 프로빙합니다.
• 레지스트리: 어댑터 및 토폴로지 세트를 관리하고, 서비스 수준의 부모 노드를 생성하며, 그래프 데이터를 집계합니다.
• 캐시: 30초 TTL과 singleflight 패턴을 사용하여 thundering herd를 방지합니다.
• WebSocket: 5초마다 상태 업데이트를 스트리밍합니다.

프론트엔드 (React + TypeScript)

• 수영장 레인 레이아웃: 네임스페이스 인식 레이아웃으로 영역 분류(시스템, 인프라, 애플리케이션 네임스페이스)를 제공합니다.
• 그룹 컨테이너: K8s 네임스페이스는 React Flow 그룹핑을 통해 접을 수 있는 경계 상자로 렌더링됩니다.
• 노드 인스펙터: 상세 메타데이터와 연결을 보여주는 사이드 패널입니다.
• WebSocket 훅: 폴링 없이 실시간 상태 업데이트를 제공합니다.

노드 계층 구조

어댑터에 의해 발견됨:
  서비스 노드 (postgres/mongodb/s3)
      └─ 데이터베이스/버킷 노드
          └─ 테이블/컬렉션/접두사 노드

Kubernetes에 의해 발견됨:
  네임스페이스 (그룹 컨테이너)
      └─ 디플로이먼트 / 스테이트풀셋 / 데몬셋
          └─ 파드
      └─ 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)를 통해 실행되며, 이는 다음을 검증합니다:

• 연결/연결 해제 생명주기
• 노드/엣지 발견 (고유 ID, 유효한 부모 참조, 올바른 유형)
• 상태 메트릭 (상태 키, 필수 키)

단일 어댑터 테스트 실행:

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 — 노드 ID 세트가 변경될 때(발견에 의해 노드가 추가되거나 제거됨) 전송됩니다. 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에서 (init()을 위한 빈 임포트)

새 발견자 추가하기

발견자는 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 오케스트레이터 (네임스페이스, 디플로이먼트, 스테이트풀셋, 데몬셋, 파드, 서비스)
• 디바운스된 인포머 기반 실시간 K8s 감시
• 네임스페이스 그룹 컨테이너가 있는 수영장 레인 레이아웃
• K8s 어댑터 브리징 (이미지별 파드 분류, 파드 내 데이터베이스에 어댑터 연결)
• 흐름 관찰 가능성 (실시간 데이터 흐름 시각화)
• 통합 스트레스 트리거 (k6로 실시간 영향 시각화)
• Kafka 어댑터
• 추가 오케스트레이터 (ECS, Nomad)

지원

• 이슈: github.com/guilherme-grimm/graph-go/issues
• 토론: github.com/guilherme-grimm/graph-go/discussions

DevOps 및 인프라 엔지니어를 위해 ❤️로 제작되었습니다.