
シンプルなノードとグラフ
インフラを見える化。設定不要。
graph-go をあなたのスタックに向けるだけで、すべてのデータベース、テーブル、サービス、ストレージバケットのライブでインタラクティブなマップが手に入ります — リアルタイムのヘルスモニタリング付きです。
graph-go は CLI ファーストのインフラマッパーです。Docker デーモンに接続し、実行中のコンテナを検査し、データベースやストレージサービスをプローブすることで、インフラを自動検出します。UI はバックエンドから配信され、実際のバックエンド状態を反映します — 手動のインベントリは不要です。
| 機能 | 詳細 |
|---|---|
| 自動検出 | Docker コンテナと Kubernetes クラスタからインフラを検出 — 手動のインベントリは不要 |
| Kubernetes | Namespace、Deployment、StatefulSet、DaemonSet、Pod、Service — informer ベースのリアルタイム監視付き |
| Docker | 実行中のコンテナを分類し、認証情報を抽出し、Docker イベントを監視し、graphgo.* ラベルを尊重して type/DSN/node-type/name を上書きしたりコンテナを無視したりします |
| PostgreSQL | テーブル、外部キーリレーションシップ、スキーマトポロジー |
| MongoDB | データベースとコレクション |
| MySQL | テーブル、外部キーリレーションシップ |
| Redis | キースペースとキー分布 |
| Elasticsearch | インデックス、クラスタヘルス、シャードステータス |
| S3 / MinIO | バケットとトップレベルのプレフィックス |
| HTTP サービス | ヘルスエンドポイント、サービス間の依存関係マッピング |
| リアルタイムヘルス | WebSocket による 5 秒ごとのライブステータス更新 |
| インタラクティブグラフ | スイムレーンレイアウト、namespace グループコンテナ、パン/ズーム、type/health によるフィルタ、ノード検索 |
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
コンテナ1つ、ポート1つ。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
イメージは非 root ユーザーとして実行されるため、
--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 の外部にあるサービス(リモートデータベース、マネージドクラウドサービス)については、設定ファイルをマウントしてください — Configuration を参照してください。
単一の自己完結型バイナリ — 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 | 設定ファイルをチェックし、無効な場合は非ゼロで終了します。不足しているすべてのフィールド、不明な接続タイプ、不明なキー(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 セッション: 1 つの質問、graph-go のツール、そしてライブグラフから構築された回答。何も書き込まないバックアップバケットも含まれます。
stdio 上で動作し、3 つの読み取り専用ツールを公開します:
| ツール | 用途 |
|---|---|
get_topology | 何が存在し、どのように接続され、そのヘルス状態はどうか。フィルター: namespaces、types、health、name。300 ノードを超える場合はサマリー(名前空間とタイプごとのカウント、すべての異常または劣化ノードの完全な情報)を返し、絞り込み方法を示します。 |
get_node | 1 つのノードと、それに出入りするすべてのエッジおよび隣接ノード: 「この 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 はプロトコル用に標準入力を開いたままにします。ソケットフラグは上記と同じです):
{
"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 に記載されています。