
단순히 노드와 그래프
인프라를 확인하세요. 설정은 필요 없습니다.
graph-go를 스택에 연결하면 모든 데이터베이스, 테이블, 서비스, 스토리지 버킷의 실시간 대화형 맵을 얻을 수 있습니다 — 실시간 상태 모니터링과 함께.
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초마다 실시간 상태 업데이트 |
| 대화형 그래프 | 스윔레인 레이아웃, 네임스페이스 그룹 컨테이너, 팬/줌, 유형/상태별 필터링, 노드 검색 |
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으로 지정하거나, 컨테이너를 제거하지 않고 그래프에서 숨길 수 있습니다.
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 \
--group-add "$(stat -c %g /var/run/docker.sock)" \
ghcr.io/guilherme-grimm/graph-go:latest
이미지는 비루트 사용자로 실행되므로,
--group-add는 이미지에 소켓의 그룹을 부여합니다(stat -c는 Linux 전용이며, macOS에서는--group-add 0으로 시작하세요). Docker 검색이 여전히 YAML 전용으로 폴백된다면, 시작 로그에 무엇을 변경해야 하는지(해당 수정 사항일 경우 정확한--group-add값 포함)가 표시됩니다.graph-go는 Docker API에서 읽기만 합니다(list, inspect, events). 하지만
:ro가 API 호출을 제한하지는 않습니다. 즉, 소켓에 접근할 수 있는 모든 것은 데몬을 제어할 수 있습니다. 최소 권한을 위해tecnativa/docker-socket-proxy와 같은 읽기 전용 API 프록시를 소켓 앞에 두고DOCKER_HOST=tcp://<proxy>:2375로 graph-go가 이를 가리키도록 설정하세요(소켓 마운트나--group-add가 필요 없습니다).docker-compose.demo.yml은 동작하는 설정을 보여줍니다.
**http://localhost:8080**을 여세요. 자동 검색은 구성 파일 없이도 Docker 컨테이너와 (kubeconfig 또는 클러스터 내 서비스 계정이 접근 가능한 클러스터를 가리킬 때) Kubernetes 리소스를 처리합니다.
Docker/Kubernetes 외부에 있는 서비스(원격 데이터베이스, 관리형 클라우드 서비스)의 경우 구성 파일을 마운트하세요 — 구성을 참조하세요.
단일 자체 포함 바이너리 — UI는 내장되어 있지만, 진입점은 여전히 CLI입니다.
# Linux amd64 (requires the GitHub CLI; browse Releases for other platforms)
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 # or just `./graph-go` - same thing
**http://localhost:8080**을 엽니다. 다른 플랫폼은 Releases 페이지에서 확인하세요.
| 명령어 | 기능 |
|---|---|
graph-go demo | 저장소에서 시드된 Docker Compose 데모 스택을 부팅하고 출력을 포그라운드로 스트리밍합니다. |
graph-go serve | 자동 검색 및 실시간 업데이트와 함께 HTTP 서버를 시작합니다(기본값 - 인자 없이 실행하는 것과 동일). 첫 검색이 완료되면 각 어댑터에 대해 발견한 내용 또는 실패한 이유와 함께 ✓/✗ 줄을 stderr에 출력합니다(--log-format json 사용 시 생략됨). |
graph-go scan | 검색을 한 번 실행하고 그래프를 stdout으로 출력합니다. --format json(기본값)은 jq 또는 CI 검사로 파이프할 때 사용하고, mermaid, markdown(펜스 블록 안의 Mermaid, GitHub에서 렌더링됨) 또는 dot(Graphviz)은 다이어그램용입니다. graph-go export는 별칭입니다. |
graph-go validate | 설정 파일을 검사하고 유효하지 않으면 0이 아닌 값으로 종료합니다. 누락된 모든 필드, 알 수 없는 연결 유형, 알 수 없는 키(serve가 조용히 무시하는 항목)를 보고합니다. 서버는 시작되지 않습니다. |
graph-go mcp | Model Context Protocol(stdio)을 통해 AI 에이전트에 토폴로지를 제공합니다. AI 에이전트와 함께 사용하기(MCP)를 참조하세요. |
graph-go version | 버전, 커밋, 빌드 날짜를 출력합니다. |
graph-go --health-check | 로컬 /health에 요청하고 0/1로 종료합니다. 컨테이너 HEALTHCHECK에서 사용되며 대화형 사용 용도가 아닙니다. |
전역 플래그(모든 하위 명령어에 적용): --config, --log-level, --log-format. 명령어별 전체 옵션은 graph-go <command> --help를 참조하세요.
일반적인 흐름:
graph-go demo.graph-go serve.graph-go scan — 예: GitHub에서 렌더링되는 다이어그램을 위해 graph-go export --format markdown --log-level=warn > ARCHITECTURE.md.graph-go mcp는 코딩 에이전트(Claude Code, Cursor, 모든 MCP 클라이언트)에게 인프라에 대한 결정론적 뷰를 제공하여, compose 파일과 매니페스트에서 추측하는 일을 멈추게 합니다.
graph-go demo에 대한 실제 Claude Code 세션: 하나의 질문, graph-go의 도구들, 그리고 아무것도 쓰지 않는 백업 버킷을 포함해 라이브 그래프로부터 구성된 답변.
stdio를 통해 실행되며 세 가지 읽기 전용 도구를 제공합니다:
| 도구 | 사용 용도 |
|---|---|
get_topology | 무엇이 존재하는지, 어떻게 연결되는지, 그리고 그 상태. 필터: namespaces, types, health, name. 300개 노드를 초과하면 요약(네임스페이스 및 유형별 개수, 모든 비정상 또는 성능 저하 노드의 전체 내용)을 반환하고 좁히는 방법을 알려줍니다. |
get_node | 들어오거나 나가는 모든 엣지와 이웃을 포함한 하나의 노드: "이 Redis에 의존하는 것은 무엇인가?" |
find_nodes | 이름으로 id를 조회합니다. |
검색은 클라이언트가 서버를 시작할 때 백그라운드에서 시작되며(핸드셰이크는 이를 기다리지 않음) 세션 동안 유지됩니다. 모든 답변에는 반영하는 상태에 대한 observed_at이 포함됩니다. 연결 문자열과 오류의 자격 증명은 반환되기 전에 마스킹되며, 각 응답은 제한됩니다(--max-response-bytes, 기본값 80 KB).
Claude Code:
claude mcp add graph-go -- graph-go mcp
# with a config file:
claude mcp add graph-go -- graph-go mcp --config /path/to/config.yaml
기타 클라이언트(Cursor, Claude Desktop, …)는 일반적인 mcpServers 블록을 사용합니다:
{
"mcpServers": {
"graph-go": { "command": "graph-go", "args": ["mcp"] }
}
}
컨테이너 이미지에서 (-i는 프로토콜을 위해 stdin을 열린 상태로 유지하며, 소켓 플래그는 위와 동일합니다):
{
"mcpServers": {
"graph-go": {
"command": "docker",
"args": ["run", "-i", "--rm",
"-v", "/var/run/docker.sock:/var/run/docker.sock:ro",
"--group-add", "<docker socket gid>",
"ghcr.io/guilherme-grimm/graph-go:latest", "./graph-go", "mcp"]
}
}
}
로그는 warn 레벨로 stderr에 출력됩니다(--log-level / LOG_LEVEL로 변경 가능). 도구 표면의 설계와 그 근거는 ADR-0003에 있습니다.