---

graph-go 是一个 CLI 优先的基础设施映射工具。它通过连接 Docker 守护进程、检查运行中的容器以及探测数据库和存储服务来自动发现你的基础设施。UI 由后端提供，反映实时的后端状态——无需手动清单。

能力	详情
自动发现	从 Docker 容器和 Kubernetes 集群中检测基础设施——无需手动清单
Kubernetes	命名空间、Deployments、StatefulSets、DaemonSets、Pods、Services——基于 informer 的实时监控
Docker	对运行中的容器进行分类、提取凭据、监控 Docker 事件、支持 graphgo.* 标签以覆盖类型/DSN/节点类型/名称或忽略某个容器
PostgreSQL	表、外键关系、模式拓扑
MongoDB	数据库和集合
MySQL	表、外键关系
Redis	Keyspaces 和键分布
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. graph-go scan 用于一次性自动化、导出或 CI 检查。

---

端口

端口	用途
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)

关键组件：

• Discoverer 接口：所有发现后端的统一契约（Discover, Watch, Close）——Docker 和 Kubernetes 并行运行，结果合并
• Docker 发现：检查容器、对镜像进行分类、从环境变量提取凭据、监控 Docker 事件以获取实时拓扑变化
• Kubernetes 发现：使用 client-go informer 及去抖事件处理；发现命名空间、Deployments、StatefulSets、DaemonSets、Pods 和 Services，并附带健康映射
• 适配器：实现 Adapter 接口，用于探测数据库和存储服务
• 注册中心：管理适配器和拓扑集，创建服务级父节点，聚合图数据
• 缓存：30 秒 TTL，使用 singleflight 模式防止惊群效应
• 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 发现 + informer)
• 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 处理器测试。

集成测试