---

graph-go는 CLI 우선 인프라 매퍼입니다. Docker 데몬에 연결하고, 실행 중인 컨테이너를 검사하며, 데이터베이스와 스토리지 서비스를 탐색하여 인프라를 자동으로 검색합니다. UI는 백엔드에서 제공되며 실제 백엔드 상태를 반영합니다 — 수동 인벤토리가 필요하지 않습니다.

기능	세부 사항
자동 검색	Docker 컨테이너와 Kubernetes 클러스터에서 인프라를 감지합니다 — 수동 인벤토리가 필요하지 않습니다
Kubernetes	Namespaces, Deployments, StatefulSets, DaemonSets, Pods, Services — informer 기반 실시간 감시
Docker	실행 중인 컨테이너를 분류하고, 자격 증명을 추출하며, Docker 이벤트를 감시하고, graphgo.* 레이블을 사용하여 type/DSN/node-type/name을 재정의하거나 컨테이너를 무시합니다
PostgreSQL	테이블, 외래 키 관계, 스키마 토폴로지
MongoDB	데이터베이스와 컬렉션
MySQL	테이블, 외래 키 관계
Redis	키스페이스와 키 분포
Elasticsearch	인덱스, 클러스터 상태, 샤드 상태
S3 / MinIO	버킷과 최상위 접두사
HTTP 서비스	상태 엔드포인트, 서비스 간 의존성 매핑
실시간 상태	WebSocket 기반 5초마다 라이브 상태 업데이트
인터랙티브 그래프	스윔레인 레이아웃, 네임스페이스 그룹 컨테이너, 팬/줌, 유형/상태별 필터링, 노드 검색

Docker 레이블

graph-go는 소수의 graphgo.* 컨테이너 레이블을 지원합니다 (제어하려는 모든 컨테이너에 설정하세요):

레이블	효과
graphgo.ignore=true	이 컨테이너를 완전히 건너뜁니다
graphgo.type=postgres	어댑터 유형을 강제합니다 (postgres, mongodb, mysql, redis, elasticsearch, s3, http)
graphgo.dsn=...	연결 문자열을 주입합니다 (postgres/mysql의 경우 DSN, mongodb의 경우 URI, 그 외의 경우 dsn으로 대체)
graphgo.node-type=gateway	시각적 노드 유형을 재정의합니다 (service, gateway, auth, api, queue, cache)
graphgo.name=...	그래프에 표시되고 노드 ID/로그에 사용되는 노드 이름을 재정의합니다

이 레이블을 사용하여 잘못 분류된 컨테이너를 복구하거나, 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 페이지에서 확인하세요.

---

명령어

명령어	기능
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에서 사용되며 대화형 사용에는 적합하지 않습니다.

전역 플래그 (모든 하위 명령어에 적용): --config, --log-level, --log-format. 전체 명령어별 옵션은 graph-go <command> --help를 참조하세요.

일반적인 흐름:

1. 현실적인 로컬 워크스루를 위해 graph-go demo.
2. 자체 인프라에 대해 실행하려면 graph-go serve.
3. 일회성 자동화, 내보내기, CI 검사를 위해 graph-go scan.

---

포트

포트	용도
8080	graph-go (UI + API + WebSocket — 프로덕션)
5173	Vite 개발 서버 (개발 전용 — CONTRIBUTING.md 참조)
9001	MinIO 콘솔 (데모 스택 전용)

---

구성

자동 검색이 기본 경로입니다. 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)