---

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

能力	详情
自动发现	从 Docker 容器和 Kubernetes 集群中检测基础设施——无需手动清点
Kubernetes	Namespaces、Deployments、StatefulSets、DaemonSets、Pods、Services——基于 informer 的实时监听
Docker	对运行中的容器进行分类，提取凭据，监听 Docker 事件，遵循 graphgo.* 标签以覆盖 type/DSN/node-type/name 或忽略某个容器
PostgreSQL	表、外键关系、模式拓扑
MongoDB	数据库和集合
MySQL	表、外键关系
Redis	键空间和键分布
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 socket，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 socket 读取。: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 socket 和/或运行在 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 informers 并带防抖事件处理；发现 Namespaces、Deployments、StatefulSets、DaemonSets、Pods 和 Services，并映射健康状态
• 适配器：实现 Adapter 接口以探测数据库和存储服务
• 注册表：管理适配器和拓扑集合，创建服务级父节点，聚合图数据
• 缓存：30 秒 TTL，采用 singleflight 模式防止惊群
• WebSocket：每 5 秒流式推送健康更新

前端 (React + TypeScript)

• 泳道布局：命名空间感知布局，带区域分类（system、infra、application 命名空间）
• 分组容器：K8s 命名空间通过 React Flow 分组渲染为可折叠的边界框
• 节点检查器：侧面板显示详细元数据和连接
• WebSocket Hook：无需轮询的实时健康更新

节点层级

适配器发现：
  Service Node (postgres/mongodb/s3)
      └─ Database/Bucket Node
          └─ Table/Collection/Prefix Node

Kubernetes 发现：
  Namespace (group container)
      └─ 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 发现 + informers）
• 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（集成测试）