grafbase/grafbase · 上手攻略

  • 仓库：grafbase/grafbase
  • 链接：https://github.com/grafbase/grafbase
  • 分类：ai
  • 作者：Tom
  • 更新：2026-08-23

它是什么

Grafbase 是一个用 Rust 编写的自托管 GraphQL Federation 网关，用于将多个微服务、遗留系统或第三方 API 统一成单一 GraphQL 端点。它曾是 The Guild 商业产品的开源核心，2024 年被 The Guild 收购后逐步转型。

⚠️ 重要声明（2026-05 动态）：Grafbase 平台本身（Dashboard / app.grafbase.com）已于近期停运退役（sunsetted）。CLI 与 Gateway 目前处于维护模式（maintenance mode），仅接收高危安全修复，将于 2026 年 5 月底正式归档（archive）。如需生产级 Federation 路由，推荐迁移至 Hive Router 或 Hive Gateway。

本攻略聚焦 Grafbase 历史功能文档，帮助理解其架构设计思想，供技术选型参考。

解决什么问题

在 Grafbase 出现之前，团队通常需要手写胶水代码将多个 GraphQL 微服务拼在一起，维护成本极高。Grafbase 通过 Apollo Federation v2 规范实现了：

痛点 Grafbase 方案
多服务 schema 拼接 Federation 自动组合各 subgraph schema
跨服务授权 Gateway 层统一鉴权，不用改下游服务
高延迟 Rust 引擎比 Apollo 官方网关快 40%
接入 AI 能力 内置 MCP（Model Context Protocol）服务器，可将 GraphQL API 暴露为 MCP server
协议扩展 支持 REST、gRPC、Postgres、Kafka 等非 GraphQL 数据源

快速安装

# macOS / Linux
curl -fsSL https://grafbase.com/install.sh | bash

# Windows (PowerShell)
irm https://grafbase.com/install.ps1 | iex

# 验证安装
grafbase --version

# 初始化项目
grafbase init my-project
cd my-project

核心用法

1. 启动本地 Gateway

# 方式一：直接启动（需要一个 .grafbase 配置文件）
grafbase dev

# 方式二：使用 Docker（推荐用于生产）
docker run -p 4000:4000 \
  -e GRAFBASE_API_URL=https://your-subgraph-url.com/graphql \
  grafbase/grafbase:v0.100.0

⚠️ 上述 Docker 镜像是最后已知可用的版本（v0.100.0 附近），具体最新 tag 建议查阅 GitHub Releases 页面确认。

2. 配置 Federation subgraph

创建 grafbase.config.ts：

import { graph, connector } from '@grafbase/sdk'

const g = graph()

// 连接一个 REST 数据源作为 subgraph
g.datasource('REST-api').url('https://api.example.com/graphql')

// 定义 schema
g.type('User') {
  g.field('id').type('ID!')
  g.field('name').type('String!')
}

export default g

3. WebAssembly 扩展（高级）

Grafbase 支持用 WASM 自定义鉴权、授权和解析逻辑：

# 初始化一个 authentication extension
grafbase extension init --type authentication auth-guard
cd auth-guard

# 编译并安装
grafbase extension build
grafbase extension install

常见的 WASM 扩展场景：

场景 说明
JWT 验证 自定义 token 校验逻辑
字段级权限 动态决定哪些字段对哪些用户可见
任意数据源 将非 GraphQL API（如 REST、gRPC）接入 Federation
速率限制 基于用户或 IP 的请求限流

4. MCP 集成（AI 原生特性）

Grafbase 是首个内置 MCP 服务器支持的 GraphQL 网关，可将现有 GraphQL API 直接暴露给 AI Agent：

# 启用 MCP（配置文件中设置）
# grafbase.config.ts
g.mcp({ enabled: true, port: 3001 })

典型适用场景

场景 适用程度 说明
微服务统一 ✅ 强烈推荐 多个 GraphQL 微服务一键联邦
REST/gRPC 集成 ✅ 适用 通过 Federation 接入非 GraphQL 服务
AI Agent 上下文 ✅ 适用 MCP 集成让 Agent 直接查询 GraphQL
快速原型验证 ⚠️ 注意 平台已停运，不建议新建生产项目
Schema 治理 ✅ 仍可用 CLI 和 composition checks 仍有效

坑与注意

  1. 平台已死，CLI 仍可用：Dashboard、Schema Registry 等云端功能已不可用，但本地 grafbase dev / grafbase deploy 的 self-hosted 模式在归档前仍可工作。

  2. 迁移路径：The Guild 推荐迁移至 Hive，这是 Hive Console（schema registry）+ Hive Router（federation gateway）的组合。Hive Router 与 Grafbase Gateway 功能高度重叠，但由原班团队维护。

  3. NPM 包名变更：之前包名是 @grafbase/sdk，收购后部分 API 有调整，文档以官网最新为准。

  4. 性能数据：README 中声称"40% faster than Apollo"，来自 Grafbase 官方博客基准测试，未有第三方独立验证，⚠️ 标注。

  5. 归档时间临近：预计 2026-05 底归档，如有依赖建议尽快制定迁移计划。

与同类对比

特性 Grafbase Apollo Router Hive Router Cosmo Router
引擎 Rust Rust Rust Rust
Federation v2 ✅ 原生 ✅ ✅ ✅
WASM 扩展 ✅ ✅ ✅ ✅
MCP 集成 ✅ ❌ ❌ ❌
平台状态 🔴 停运/归档中 🟢 活跃 🟢 活跃 🟡 一般
Schema Registry ❌（平台已关） ✅ Apollo Studio ✅ Hive Console ✅

一句话结论

Grafbase 架构设计优秀（Rust + Federation v2 + MCP），但平台已停运、即将归档——新项目请直接选 Hive Router；学习 Federation 架构思想仍可参考本仓库文档。