Perseus

PostgreSQL 기반 의존성 그래프 저장소

Perseus는 별도의 전용 그래프 데이터베이스 대신 PostgreSQL을 사용하여 의존성 데이터를 저장합니다. 비교적 적은 항목 수와 사내 인프라 활용 가능성 때문에 PostgreSQL이 선택되었으며, 모듈의 시맨틱 버전 저장을 위해 pg-semver 확장이 함께 사용됩니다.

Connect 기반 API 서버

perseus 서비스는 Connect로 빌드되어 단일 포트에서 바이너리 gRPC와 HTTP JSON/REST 요청을 동시에 지원합니다. JSON/REST 엔드포인트는 /api/v1/* 경로에 위치하며, 기본적인 웹 기반 사용자 인터페이스는 /ui 경로에서 접근할 수 있습니다.

관측 및 디버깅 엔드포인트

서버는 /healthz 헬스 체크와 /metrics Prometheus 메트릭을 노출합니다. 또한 문제 해결을 위해 HTTP 기반의 Go pprof 데이터를 /debug/pprof* 경로에서 조회할 수 있도록 지원합니다.

perseus CLI의 update 및 query 명령

동일한 perseus 바이너리는 클라이언트 역할도 수행합니다. update는 디스크에 있는 Go 모듈 또는 공개 Go 모듈 프록시에서 모듈을 분석해 그래프에 추가하며, Git 저장소인 경우 현재 커밋의 Git 태그에서 버전을 추론합니다. query는 list-modules, list-module-versions, ancestors, descendants 네 가지 하위 명령을 제공합니다.

다양한 출력 형식과 그래프 시각화

조회 결과는 --json, --list, --format 같은 텍스트 기반 옵션과 함께, ancestors 및 descendants 명령에서 --dot 플래그로 DOT 그래프 출력을 지원합니다. 트리 깊이는 --max-depth 플래그로 제어하며 기본값은 4홉입니다.

설치 및 시작 방법

가장 간단한 배포 방법은 GitHub Container Registry에 게시된 사전 빌드 Docker 이미지를 사용하는 것입니다. 이미지는 scratch 베이스 위에 빌드되어 perseus server를 실행하며 31138 포트를 노출합니다.

• Docker 실행 예: docker run --rm -e DB_ADDR=... -e DB_USER=... -e DB_PASS=... -p 31138:31138 ghcr.io/crowdstrike/perseus:latest (안정성을 위해 latest 대신 특정 버전 태그 사용 권장)
• 데이터베이스 이름 기본값은 perseus이며, 필요 시 DB_NAME 환경 변수로 덮어쓸 수 있습니다.
• Windows에서는 winget install --id CrowdStrike.Perseus --exact 명령으로 설치할 수 있으며, Linux와 macOS용 사전 빌드 바이너리는 GitHub 릴리스 페이지에서 직접 다운로드할 수 있습니다.

perseus CLI 기본 사용

CLI는 서버 주소가 필요하며, PERSEUS_SERVER_ADDR 환경 변수 또는 --server-addr 플래그로 지정할 수 있습니다.

• 현재 디렉토리 모듈 처리: perseus update --path ~/code/github.com/CrowdStrike/perseus
• 특정 버전 모듈 처리: perseus update --path ~/code/github.com/example/foo --version v1.2.3
• 공개 모듈은 버전이 항상 필요합니다: perseus update --module github.com/example/foo --version v1.2.3
• 조직 단위 모듈 목록 조회: perseus query list-modules 'github.com/example/*' --list
• 특정 버전의 의존 모듈 조회: perseus query ancestors github.com/example/[email protected] --list
• 하류 의존 모듈 조회: perseus query descendants github.com/pkg/[email protected] --json | jq .
• DOT 그래프 출력: perseus query ancestors github.com/example/foo --dot | dot -Tsvg -o ~/foo_deps.svg

활용 예시

• Go 모듈의 후손 의존성(어떤 모듈이 내 모듈을 사용하는지)을 그래프로 확인하여 변경 영향 범위를 분석할 때 활용할 수 있습니다.
• pkg.go.dev의 Imported By 보기에서 노출되지 않는 사설 모듈에 대한 의존성 추적에 사용할 수 있습니다.
• DOT 형식 출력을 SVG 등 그래픽으로 변환하여 의존 관계를 시각화한 문서를 만들 수 있습니다.
• 마이크로서비스 단위로 로컬 작업 공간을 축소한 팀에서, 특정 모듈 버전을 사용하는 다른 모듈과 버전을 함께 조회할 때 활용할 수 있습니다.

제한·라이선스·확인사항

Perseus는 MIT 라이선스로 배포되는 오픈소스 프로젝트이며, CrowdStrike의 공식 제품이 아니므로 명시적 또는 묵시적인 공식 지원이 제공되지 않습니다. Amazon RDS는 현재 pg-semver 확장을 지원하지 않으므로 데이터베이스 호스팅 환경을 선택할 때 이 점을 확인해야 합니다. go mod graph, go list -m all, pkg.go.dev의 Imported By 보기, goda, godepgraph 등 기존 도구들은 상류 의존성(내가 의존하는 대상) 확인에는 유용하지만, Perseus는 하류 의존성(나를 의존하는 대상) 추적에 초점을 두고 있습니다.