rover

Apollo Rover CLI 指南

Rover 是 Apollo GraphOS 的官方 CLI。它可帮助你管理 schema、在本地运行组合、发布到 GraphOS，并在本地计算机上开发 supergraph。

快速入门

步骤 1：安装

# macOS/Linux
curl -sSL https://rover.apollo.dev/nix/latest | sh

# npm (cross-platform)
npm install -g @apollo/rover

# Windows PowerShell
iwr 'https://rover.apollo.dev/win/latest' | iex

步骤 2：进行身份验证

# OAuth login via browser (recommended for local dev)
rover auth login

# Or interactive API key entry
rover config auth

# Or set environment variable (recommended for CI/CD)
export APOLLO_KEY=your-api-key

步骤 3：验证安装

rover --version
rover auth whoami    # OAuth identity
rover config whoami  # API key identity

步骤 4：初始化项目（可选）

# Create a new federated graph project
rover init

# Create a project with MCP server
rover init --mcp

探索图的 schema（schema 相关问题从这里开始）

要回答“这个图里有什么？”，查找字段，或针对 GraphOS 图编写查询，请获取 API schema 并通过管道传递给 rover schema——这样 SDL 不会进入你的上下文，只会返回你需要的内容：

# What can I query? (compact overview)
rover graph fetch <graph@variant> | rover schema describe -

# Find a field by concept/keyword (returns the path from a root operation)
rover graph fetch <graph@variant> | rover schema search - "<keyword>"

# Zoom into one type or field
rover graph fetch <graph@variant> | rover schema describe - --coord <Type.field> --depth 1

遵循以下三条规则，确保操作正确：

• 使用 rover graph fetch（API schema），不要使用 rover supergraph fetch（它会返回包含 join__/link__ 等 Federation 内部细节的组合 SDL）。
• 使用管道——不要单独运行 rover graph fetch 并读取原始 SDL（大型 schema 会淹没你的上下文；rover schema 正是为避免此问题而设计的）。
• schema 命令读取的是通过管道传入的 SDL，而不是图引用——rover schema describe <graph@variant> 会失败；你必须先获取 schema，再通过管道传入。

完整参考、排序规则和仅保存一次的模式：Schema 探索 和 references/schema.md。

核心命令概览

命令	说明	使用场景
rover init	初始化新的联邦图项目	新项目设置、MCP 服务设置
rover subgraph publish	将子图 schema 发布到 GraphOS	CI/CD、schema 更新
rover subgraph check	验证 schema 更改	PR 检查、部署前检查
rover subgraph fetch	下载子图 schema	本地开发
rover supergraph compose	在本地组合 supergraph	本地测试
rover dev	本地 supergraph 开发	开发工作流
rover graph publish	发布单体图 schema	非联邦图
rover schema describe	按坐标探索 schema；通过 stdin/文件接收 SDL，而非图引用——通过管道从 rover graph fetch 传入	Agent schema 发现
rover schema search	按关键词搜索 schema；通过 stdin/文件接收 SDL，而非图引用——通过管道从 rover graph fetch 传入	Agent schema 发现
rover connector	使用 Apollo Connectors（运行、测试、列出）	Connector 开发
rover contract	管理 contract 变体（描述、预览、发布）	API 表面筛选
rover persisted-queries	生成并发布持久化查询清单（别名：pq）	安全、性能
rover client check	根据图 schema 验证客户端操作	客户端 CI
rover auth login	通过 OAuth 浏览器流程进行身份验证	本地开发身份验证
rover api-key	创建、列出、删除、重命名和轮换 API 密钥	密钥管理
rover readme	获取或发布图变体 README	图文档
rover template	列出并使用项目模板	项目脚手架

图引用格式

大多数命令都需要使用以下格式的图引用：

<GRAPH_ID>@<VARIANT>

示例：

• my-graph@production
• my-graph@staging
• my-graph@current（默认变体）

设置为环境变量：

export APOLLO_GRAPH_REF=my-graph@production

子图工作流

发布子图

# From schema file
rover subgraph publish my-graph@production \
  --name products \
  --schema ./schema.graphql \
  --routing-url https://products.example.com/graphql

# From running server (introspection)
rover subgraph publish my-graph@production \
  --name products \
  --schema <(rover subgraph introspect http://localhost:4001/graphql) \
  --routing-url https://products.example.com/graphql

检查 schema 更改

# Check against production traffic
rover subgraph check my-graph@production \
  --name products \
  --schema ./schema.graphql

获取 schema

# Fetch from GraphOS
rover subgraph fetch my-graph@production --name products

# Introspect running server
rover subgraph introspect http://localhost:4001/graphql

Supergraph 组合

本地组合

创建 supergraph.yaml：

federation_version: =2.9.0
subgraphs:
  products:
    routing_url: http://localhost:4001/graphql
    schema:
      file: ./products/schema.graphql
  reviews:
    routing_url: http://localhost:4002/graphql
    schema:
      subgraph_url: http://localhost:4002/graphql

这里的 federation_version 是组合版本——它只需大于或等于每个子图的 @link 下限，因此固定为较低版本的子图也能顺利组合。如果子图服务端在启动时抛出 UNKNOWN_FEDERATION_LINK_VERSION，那是客户端库版本滞后，而不是组合问题。请参阅 apollo-federation 技能中的 Federation 版本。

组合：

rover supergraph compose --config supergraph.yaml > supergraph.graphql

获取组合后的 Supergraph

rover supergraph fetch my-graph@production

这会返回 supergraph SDL（联邦指令和 join__/link__ 内部内容）——用于组合器/路由器相关工作。若要探索可查询的内容或编写操作，请改用 rover graph fetch（API 架构）——参见探索 Graph 的架构。

使用 rover dev 进行本地开发

启动一个可自动组合架构的本地 Router：

# Start with supergraph config
rover dev --supergraph-config supergraph.yaml

# Start with GraphOS variant as base
rover dev --graph-ref my-graph@staging --supergraph-config local.yaml

集成 MCP

# Start with MCP server enabled
rover dev --supergraph-config supergraph.yaml --mcp

架构探索（适用于 Agent）

rover schema describe 和 rover schema search 可让 Agent 探索架构，而无需将完整 SDL 加载到上下文中——这正是这些命令的全部意义。

⚠️ 切勿将原始 SDL 读入上下文。 单独运行 rover graph fetch <ref>（或 rover graph introspect <url>）会将整个架构直接输出到上下文中——从数百行到数万行不等，这会让这些命令失去意义。务必将 fetch 的输出传入 rover schema describe/search：SDL 会通过 stdin 流转，只有精简的概览/结果会传给你。（如果用户确实需要 SDL，获取到文件中即可。）

这些命令也接受来自 stdin 或文件的 SDL，而不是 graph ref——不能向它们传入 graph@variant。请先获取，再通过管道传入：

❌ rover schema describe my-graph@current             # 错误：会查找名为该内容的文件
❌ rover graph fetch my-graph@current                 # 将完整 SDL 倒入上下文
✅ rover graph fetch my-graph@current | rover schema describe -

若要在 GraphOS 中探索 graph，请获取其架构并通过管道传入。若要探索“我可以查询什么？”，请使用 rover graph fetch（API 架构）——它不会包含联邦内部内容。只有在需要组合详情（join__/link__ 类型、子图结构）时，才使用 rover supergraph fetch：

# Overview of a GraphOS graph
rover graph fetch my-graph@current | rover schema describe -

# Find fields by keyword (results include paths from root operations)
rover graph fetch my-graph@current | rover schema search - "playback"

# Zoom into a coordinate, expanding referenced types one level
rover graph fetch my-graph@current | rover schema describe - --coord <Type.field> --depth 1

Coordinate 格式： --coord 接受类型（User）、字段（User.posts）、字段参数（Type.field(arg:)）或指令（@deprecated）——不传入时会显示概览。

search 与 describe 的区别： 当你要匹配概念或关键词、但还不知道字段名时，优先使用 rover schema search——它能找到嵌套字段，并显示从根操作开始的路径。describe 概览只会列出根字段，因此要定位更深层的字段，应使用 search。若要查看概览，或在已知类型/字段 coordinate 时，则使用 describe。

这样就能形成一个闭环工作流——搜索 → 描述 → 编写查询——无需设置 MCP 服务。完整的命令参考、排序规则以及大型架构的仅保存一次模式，请参见架构探索。

运行生成的操作： Rover 不会执行查询——它只管理和检查架构。要实际运行生成的查询，你需要 graph 的端点：

• 单子图 graph： rover subgraph list <graph@variant> 会输出 Routing Url——用 curl 向该地址发送查询。
• 多子图/联邦 graph： 客户端端点是 router URL（可在 GraphOS Studio 中找到），而不是各个子图的 routing URL。
• 不要尝试通过 GraphOS Platform API 查找端点——Rover 会将 API 密钥保存在其配置文件/钥匙串中，而不是 $APOLLO_KEY，因此临时 API 调用会因未通过身份验证而失败。

参考文件

特定主题的详细文档：

• 初始化 - rover init 项目初始化和 MCP 服务设置
• 子图 - 获取、发布、检查、Lint、内省、删除
• 图 - 单体图命令（非联邦）
• 超图 - 组合、获取、配置格式
• 开发 - 用于本地开发的 rover dev
• Schema 探索 - describe、search、Agent schema 发现工作流
• 连接器 - rover connector 的 run、test、list、analyze、generate
• Contracts - contract 变体的 describe、preview、publish
• 持久化查询 - 生成并发布持久化查询清单
• 客户端操作 - 验证客户端操作、提取 GraphQL 文档
• 配置 - 安装、身份验证、环境变量、配置文件、OAuth 登录
• 其他命令 - template、readme、api-key、plugin、license、graph-artifact、completion、explain、docs

常见模式

CI/CD 流水线

# 1. Check schema changes
rover subgraph check $APOLLO_GRAPH_REF \
  --name $SUBGRAPH_NAME \
  --schema ./schema.graphql

# 2. If check passes, publish
rover subgraph publish $APOLLO_GRAPH_REF \
  --name $SUBGRAPH_NAME \
  --schema ./schema.graphql \
  --routing-url $ROUTING_URL

Schema Lint

# Lint against GraphOS rules
rover subgraph lint --name products ./schema.graphql

# Lint monograph
rover graph lint my-graph@production ./schema.graphql

输出格式

# JSON output for scripting
rover subgraph fetch my-graph@production --name products --format json

# Plain output (default)
rover subgraph fetch my-graph@production --name products --format plain

基本规则

• 使用 GraphOS 命令前，始终先完成身份验证（rover auth login、rover config auth 或 APOLLO_KEY）
• 始终使用正确的图引用格式：graph@variant
• 在 CI/CD 中，优先在 rover subgraph publish 之前运行 rover subgraph check
• 使用 rover dev 进行本地超图开发，而不要手动运行 Router
• 使用 rover init 搭建新的图项目，而不要手动设置
• 绝不将 APOLLO_KEY 或 APOLLO_CLIENT_SECRET 提交到版本控制中；请使用环境变量
• 以编程方式解析输出时，使用 --format json
• 在 supergraph.yaml 中明确指定 federation_version，以确保可复现性
• 使用 rover subgraph introspect 从运行中的服务提取 schema
• 使用 rover schema search / rover schema describe（从 fetch 管道传入）来探索大型 schema，而不要将完整 SDL 加载到上下文中
• 绝不要仅为探索 schema 就将完整 schema 获取到上下文中——将 rover graph fetch/introspect 的输出通过管道传入 rover schema describe/search（只有在用户需要 SDL 文件本身时才直接使用 fetch）
• 部署客户端变更前，使用 rover client check 验证客户端操作
• 使用 rover persisted-queries publish 注册操作，以启用持久化查询强制执行