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

Docker 标签

graph-go 支持一小部分 graphgo.* 容器标签（可设置在你的任何容器上）：

使用这些标签可以挽救被错误分类的容器、将 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 页面。

命令

全局标志（适用于每个子命令）：--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 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 处理器测试。

集成测试

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

流式传输实时更新。发出两种消息类型，均包装为 { "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() 进行空白导入）

添加新的 Discoverer

Discoverer 位于 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}/ 创建 discoverer 包
2. 实现 Discoverer 接口——从 Discover() 返回 []ServiceInfo。产生拓扑的 discoverer（如 K8s）直接填充 Nodes/Edges；面向适配器的 discoverer（如 Docker）填充 Config 用于适配器桥接。
3. 在 internal/server/server.go 中接入服务器——添加一个 build{Name}Discovery() 函数并与现有 discoverer 一起调用。
4. 添加集成测试，使用 //go:build integration——使用真实基础设施（K8s 用 kind/k3d，其他用 testcontainers）。无模拟。

详细指南请参见 CONTRIBUTING.md。

贡献

我们欢迎贡献！详见 CONTRIBUTING.md 了解以下指南：

• 开发环境搭建
• 代码风格约定
• 如何添加新适配器
• 提交 Pull Request

使用范围与伦理

预期用途：

• 可视化并监控你拥有或有权访问的基础设施
• DevOps 仪表盘和拓扑映射
• 基础设施文档和入职培训
• 探索数据库模式和关系

非预期用途：

• 未经授权的系统扫描或侦察
• 未经明确许可的安全测试
• 访问你不拥有或控制权的系统

用户有责任确保在将 graph-go 连接到任何基础设施之前已获得适当的授权。

许可证

本项目采用 GNU Affero General Public License v3.0 (AGPL-3.0) 许可证。

详情参见 LICENSE 文件。AGPL 要求通过网络使用的修改版本也必须开源。

CI/CD 与发布

项目使用 GitHub Actions 进行持续集成和自动发布。

• CI 在每次推送到 main 或发起 PR 时运行——后端单元测试、集成测试（testcontainers）和前端构建
• 发布由版本标签（v*）触发，并生成：
  • 跨平台二进制文件（Linux, macOS, Windows）通过 GoReleaser
  • 推送到 ghcr.io/guilherme-grimm/graph-go 的单个 Docker 镜像

创建发布版本：

git tag v0.1.0
git push --tags

路线图

• Docker 自动发现
• HTTP 服务健康监控
• MySQL 适配器
• Redis 适配器
• Elasticsearch 适配器
• 使用 testcontainers-go 的集成测试（所有适配器）
• 适配器接口合规契约测试套件
• Discoverer 接口（可插拔的发现后端）
• Kubernetes 编排器（命名空间、Deployments、StatefulSets、DaemonSets、Pods、Services）
• 基于 informer 的实时 K8s 监控（带去抖）
• 带命名空间组容器的泳道布局
• K8s 适配器桥接（按镜像对 Pod 进行分类，将适配器连接到 Pod 中的数据库）
• 流可观测性（实时数据流可视化）
• 集成压力触发（k6 与实时影响可视化）
• Kafka 适配器
• 其他编排器（ECS, Nomad）
• 图持久化（保存/加载视图）

支持

• 问题反馈： github.com/guilherme-grimm/graph-go/issues
• 讨论： github.com/guilherme-grimm/graph-go/discussions

为 DevOps 和基础设施工程师打造 ❤️