graph-go は CLI ファーストのインフラマッパーです。Docker デーモンに接続し、実行中のコンテナを検査し、データベースやストレージサービスをプローブすることで、インフラを自動検出します。UI はバックエンドによって提供され、バックエンドの状態をリアルタイムに反映します。手動のインベントリは不要です。

Docker ラベル

graph-go は限られた graphgo.* コンテナラベルのセットを尊重します（制御したい任意のコンテナに設定できます）。

これらを使用して、誤分類されたコンテナを救出したり、カスタム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 がベースイメージをプルし、ローカルのデモイメージをビルドする必要があるため、数分かかることがあります。2回目以降ははるかに高速です。

デモスタックは、ホストの以下のポートが空いていることを前提としています: 8080、5432、27017、9000、9001。

明示的に後片付けが必要な場合:

docker compose -f docker-compose.demo.yml down

自身のスタックに対して実行

1つのコンテナ、1つのポート。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 のインフォーマーを使用し、デバウンスされたイベント処理を行います。Namespace、Deployment、StatefulSet、DaemonSet、Pod、Service を検出し、ヘルスマッピングを行います。
• アダプター: Adapter インターフェースを実装してデータベースやストレージサービスをプローブします。
• レジストリ: アダプターとトポロジセットを管理し、サービスレベルの親ノードを作成し、グラフデータを集約します。
• キャッシュ: 30秒のTTLとシングルフライトパターンを採用し、輻輳を防止します。
• WebSocket: 5秒ごとにヘルス更新をストリーミングします。

フロントエンド (React + TypeScript)

• スイムレーンレイアウト: 名前空間を認識したレイアウトで、ゾーン分類（システム、インフラ、アプリケーション名前空間）を備えています。
• グループコンテナ: K8s の名前空間は、React Flow のグループ化機能により折りたたみ可能なバウンディングボックスとしてレンダリングされます。
• ノードインスペクター: 詳細なメタデータと接続を表示するサイドパネル。
• WebSocket フック: ポーリングなしのリアルタイムヘルス更新。

ノード階層

アダプター検出:
  サービスノード (postgres/mongodb/s3)
      └─ データベース/バケットノード
          └─ テーブル/コレクション/プレフィックスノード

Kubernetes 検出:
  名前空間 (グループコンテナ)
      └─ 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 ディスカバリ + インフォーマー)
• 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

リアルタイム更新をストリーミングします。2種類のメッセージが発行され、どちらも { "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 オーケストレーター（Namespace、Deployment、StatefulSet、DaemonSet、Pod、Service）
• デバウンス付きインフォーマーベースのリアルタイム K8s 監視
• 名前空間グループコンテナ付きスイムレーンレイアウト
• K8s アダプターブリッジ（イメージによる Pod 分類、Pod 内データベースへのアダプター接続）
• フロー監視（リアルタイムデータフロー可視化）
• 統合ストレストリガー（k6 とリアルタイム影響可視化）
• Kafka アダプター
• 追加のオーケストレーター（ECS、Nomad）

サポート

• 問題: github.com/guilherme-grimm/graph-go/issues
• ディスカッション: github.com/guilherme-grimm/graph-go/discussions

DevOps とインフラエンジニアの方々へ ❤️ を込めて