graph-go 是一个以 CLI 为核心的基础设施映射工具。它通过连接 Docker 守护进程、检查运行中的容器,并探测数据库和存储服务来自动发现你的基础设施。UI 由后端提供,并反映真实的后端状态——无需手动维护清单。
| 能力 | 详情 |
|---|---|
| 自动发现 | 从 Docker 容器和 Kubernetes 集群中检测基础设施——无需手动维护清单 |
| Kubernetes | Namespaces、Deployments、StatefulSets、DaemonSets、Pods、Services——基于 informer 的实时监听 |
| Docker | 对运行中的容器进行分类、提取凭据、监听 Docker 事件,并遵循 graphgo.* 标签来覆盖 type/DSN/node-type/name 或忽略某个容器 |
| PostgreSQL | 表、外键关系、schema 拓扑 |
| MongoDB | 数据库和集合 |
| MySQL | 表、外键关系 |
| Redis | 键空间和键分布 |
| Elasticsearch | 索引、集群健康、分片状态 |
| S3 / MinIO | 存储桶和顶层前缀 |
| HTTP 服务 | 健康端点、服务之间的依赖映射 |
| 实时健康 | 由 WebSocket 驱动的实时状态更新,每 5 秒一次 |
| 交互式图 | 泳道布局、命名空间分组容器、平移/缩放、按类型/健康状态过滤、搜索节点 |
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
一个容器,一个端口。以只读方式挂载 Docker socket,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时,还会给出确切的--group-add值)。graph-go 仅从 Docker API 读取(list、inspect、events)。不过
:ro并不会限制 API 调用:任何能够访问该套接字的对象都可以控制守护进程。为实现最小权限,请在套接字前放置一个只读 API 代理,例如tecnativa/docker-socket-proxy,并通过DOCKER_HOST=tcp://<proxy>:2375将 graph-go 指向它(无需挂载套接字或使用--group-add)。docker-compose.demo.yml展示了一个可用的配置。
打开 **http://localhost:8080**。自动发现无需任何配置文件即可处理 Docker 容器以及(当 kubeconfig 或集群内服务账号指向一个可访问的集群时)Kubernetes 资源。
对于位于 Docker/Kubernetes 之外的服务(远程数据库、托管云服务),请挂载配置文件——参见配置。
单一自包含二进制文件——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 用于一次性自动化、导出或 CI 检查——例如 graph-go export --format markdown --log-level=warn > ARCHITECTURE.md 生成可在 GitHub 上渲染的图表。graph-go mcp 为编码代理(Claude Code、Cursor、任何 MCP 客户端)提供基础设施的确定性视图,使它们不再从 compose 文件和清单中猜测。
针对 graph-go demo 的真实 Claude Code 会话:一个问题、graph-go 的工具,以及基于实时图构建的答案,包括那个没有任何写入的备份存储桶。
它通过 stdio 运行,并暴露三个只读工具:
| 工具 | 用途 |
|---|---|
get_topology | 存在什么、如何连接及其健康状况。过滤器:namespaces、types、health、name。超过 300 个节点时返回摘要(按命名空间和类型的计数,所有不健康或降级节点的完整信息),并说明如何缩小范围。 |
get_node | 一个节点及其所有入边或出边以及其邻居:“什么依赖这个 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 保持 stdin 打开以支持该协议;socket 标志与上文相同):
{
"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。
| 端口 | 用途 |
|---|---|
8080 | graph-go(UI + API + WebSocket — 生产环境) |
5173 | Vite 开发服务器(仅开发环境 — 参见 CONTRIBUTING.md) |
9001 | RustFS 控制台,位于 /rustfs/console/(仅演示栈) |
自动发现是首选方式。挂载 Docker socket 和/或运行在 Kubernetes 集群内 — graph-go 即可发现你的基础设施,无需任何配置文件。
仅当某些服务无法通过发现机制访问时(远程数据库、托管云服务、外部端点),才将 YAML 配置(conf/config.yaml)作为备用方案使用。完整 schema 参见 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 \
--group-add "$(stat -c %g /var/run/docker.sock)" \
-v $(pwd)/conf/config.yaml:/app/conf/config.yaml:ro \
ghcr.io/guilherme-grimm/graph-go:latest
仅限授权使用: graph-go 用于可视化你拥有或已获授权访问的基础设施。请勿将其指向未经授权的系统。