设置自托管 Supergraph

本教程将引导您使用GraphOS 和自托管 supergraph，使用 GraphOS Router。虽然您可以在 Apollo 计划的任何级别运行 Apollo Router Core，但将路由器连接到 GraphOS 需要 企业计划。如果您所在的组织目前没有企业计划，您可以通过注册一个免费的 企业试用版 来测试此功能。

Supergraph 概念

在我们开始之前，让我们快速了解一下什么是自托管 supergraph。

一个 supergraph将多个 GraphQL API 统一到一个 GraphQL 服务中。在 supergraph 中的单独 API 被称为 子图：

一个名为 路由器的独立服务位于您的 子图 之前，并为您的 supergraph 提供公开可访问的端点。客户端 查询 路由器，路由器将每个查询分配到适当的子图组合，并返回组合后的结果。

路由器使用一个特殊的 GraphQL 架构，称为 supergraph 架构。此架构包含每个 子图架构 中的类型和 字段，以及支持路由器正确分配查询到子图的元数据。

一个 自托管 supergraph是一个带有您的路由器 supergraph 和路由器，您在您自己的基础设施中托管和管理。这与使用由 Apollo 托管和管理的路由器 云 supergraph 形成对比。

我们将在下述步骤中更详细地介绍这些概念。

1. 设置 Apollo 工具

此快速入门使用了以下 Apollo 工具

• GraphOS Studio：这是 GraphOS 的主要 Web 界面。Studio 帮助您监视、管理和协作您的 supergraph。
• The Rover CLI：这是 GraphOS 的主要命令行界面。Rover 帮助您与您的图和其架构交互。

让我们首先设置这些。

创建 Apollo 帐户

要使用 GraphOS 管理我们的 supergraph，我们需要一个 Apollo 帐户。如果您还没有一个，请创建一个。

完成 开始使用 GraphOS（创建您的 Apollo 帐户），然后返回这里。

在 GraphOS Studio 中创建图

首次创建Apollo账户后，按照以下步骤在GraphOS Studio中创建您的第一个图：

1. 前往您组织的图选项卡，点击GraphOS Studio

2. 点击右上角的创建新图。

3. 在弹出的对话框中，指定您的图的组织和图标题。

4. 将图架构保留为默认的Supergraph (默认)。

5. 点击下一步。将出现以下模态框：

6. 将Supergraph Pipeline Track下拉菜单保留为默认值。

您的图已创建！

安装Rover CLI

Rover是Apollo管理所有图的CLI工具，包括子图和超图。在快速入门过程中，我们将使用它。

请使用适合您系统的适当命令安装最新版本的Rover：

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

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

安装后，运行rover在您的终端中不输入任何参数以确认安装成功。检查打印的版本号是否与最新完整版本（如果不符合，可能需要手动删除旧的安装）。

使用 GraphOS 验证 Rover

我们将使用Rover来发布我们的subgraph 模式到 GraphOS。为了做到这一点，我们首先需要使用 GraphOS 验证 Rover。

完成配置 Rover的前两步（获取 API 密钥并将 API 密钥提供给 Rover），然后返回这里。

2. 复制路由器项目模板

在这个快速入门教程中，我们将使用一些 Apollo 主办示例服务作为我们的subgraphs，并将 GraphOS 路由器设置在这些子图之前。路由器是一个高性能、预编译的 Rust 可执行文件，充当 supergraph 的路由器。

首先，让我们为您的router创建一个项目目录：

1. 打开这个 GitHub 模板。它提供了一个开箱即用的配置来通过 Dockerfile 部署和运行 router。
2. 在模板页面上，点击使用此模板 > 创建新存储库将模板复制到您的 GitHub 账户中的新存储库。
   • 如果您不使用 GitHub，您也可以通过代码菜单直接克隆模板。
3. 将您的新的存储库克隆到您的本地机器。

3. 使用 Docker 启动路由器

要在本地运行路由器，您需要一种构建和运行容器的方法。这里是一些流行的选项：

• Docker Desktop
• Rancher
• Podman

尝试构建和运行你的 router 容器：

docker build -t router .
docker run -it -p4000:4000 router

完成时，你将看到一个类似于以下内容的启动错误信息：

1
Apollo Router v1.18.0 // (c) Apollo Graph, Inc. // Licensed as ELv2 (https://go.apollo.dev/elv2)
2

3
⚠️  The Apollo Router requires a composed supergraph schema at startup. ⚠️
4

5
👉 DO ONE:
6

7
  * Pass a local schema file with the '--supergraph' option:
8

9
      $ ./router --supergraph <file_path>
10

11
  * Fetch a registered schema from GraphOS by setting
12
    these environment variables:
13

14
      $ APOLLO_KEY="..." APOLLO_GRAPH_REF="..." ./router
15

16
      For details, see the Apollo docs:
17
      https://apollo.graphql.net.cn/docs/router/managed-federation/setup
18

19
🔬 TESTING THINGS OUT?
20

21
  1. Download an example supergraph schema with Apollo-hosted subgraphs:
22

23
    $ curl -L https://supergraph.demo.starstuff.dev/ > starstuff.graphql
24

25
  2. Run the Apollo Router in development mode with the supergraph schema:
26

27
    $ ./router --dev --supergraph starstuff.graphql

那是因为我们目前没有向 router 提供一个 supergraph 模式！我们很快会解决这个问题。

4. 获取你的子图（subgraph）模式

1
extend schema
2
  @link(url: "https://specs.apollo.dev/federation/v2.0",
3
        import: ["@key"])
4

5
type Query {
6
  "The full list of locations presented by the Interplanetary Space Tourism department"
7
  locations: [Location!]!
8
  "The details of a specific location"
9
  location(id: ID!): Location
10
}
11

12
type Location @key(fields: "id"){
13
  id: ID!
14
  "The name of the location"
15
  name: String!
16
  "A short description about the location"
17
  description: String!
18
  "The location's main photo as a URL"
19
  photo: String!
20
}

1
extend schema
2
  @link(url: "https://specs.apollo.dev/federation/v2.0",
3
        import: ["@key"])
4

5
type Query {
6
  "The three latest reviews submitted for FlyBy's locations"
7
  latestReviews: [Review!]!
8
}
9

10
type Mutation {
11
  submitReview(locationReview: LocationReviewInput): SubmitReviewResponse
12
}
13

14
type Location @key(fields: "id") {
15
  id: ID!
16
  "The calculated overall rating based on all reviews"
17
  overallRating: Float
18
  "All submitted reviews about this location"
19
  reviewsForLocation: [Review]!
20
}
21

22
type Review {
23
  id: ID!
24
  "Written text"
25
  comment: String
26
  "A number from 1 - 5 with 1 being lowest and 5 being highest"
27
  rating: Int
28
  "The location the review is about"
29
  location: Location
30
}
31

32
input LocationReviewInput {
33
  "Written text"
34
  comment: String!
35
  "A number from 1 - 5 with 1 being lowest and 5 being highest"
36
  rating: Int!
37
  "Location Id"
38
  locationId: String!
39
}
40

41
type SubmitReviewResponse {
42
  "Similar to HTTP status code, represents the status of the mutation"
43
  code: Int!
44
  "Indicates whether the mutation was successful"
45
  success: Boolean!
46
  "Human-readable message for the UI"
47
  message: String!
48
  "Newly created review"
49
  locationReview: Review
50
}

为了为我们的 router 编写一个 supergraph schema， GraphOS 需要每个 subgraph 的以下信息：

• subgraph 的模式
• subgraph 的 GraphQL 端点 URL（该 URL 必须由 router 可访问）

幸运的是，我们拥有所有这些信息！让我们将其发送到 GraphOS。

5. 发布你的子图模式

因为我们已经配置了Rover CLI，现在我们可以使用它的subgraph publish命令来将我们的subgraph模式发布到GraphOS。

在GraphOS Studio，点击第一步中创建的graph。因为我们还没有向其发布任何模式，所以会出现以下对话框：

要发布我们的subgraph模式，我们首先使用Rover来分析运行的subgraph，然后传递获取的模式到subgraph publish。

1. 复制以下多行命令到您的终端中，但请先不要运行它——您需要先修改它。

   Bash

   rover subgraph introspect https://flyby-locations-sub.herokuapp.com/ | \
   rover subgraph publish --name locations \
   --routing-url https://flyby-locations-sub.herokuapp.com/ \
   --schema - <GRAPH_REF>

   复制

2. 在您的终端中，将最终的值<GRAPH_REF>替换为您graph的相应值。在上面的截图中，此值为MyGraph-1ncyus@current，但您的值可能不同。

   什么是graph ref？

   Graph ref唯一标识GraphOS中特定variant的特定graph。每个graph ref都是以下格式的字符串：

   graph-id@variant-name

   • 在@之前的值是您的graph在GraphOS中的唯一ID。
   • 在@之后的值是您与之交互的graph的variant的名称。

   每个graph的variant代表该graph运行的不同环境（如预发布和正式版）。对于此快速入门，您可以继续使用默认的建议variant名称，或者将其更改为您喜欢的任何其他名称（例如，quickstart）。只需确保在快速入门中的每个命令中都提供相同的graph ref即可！

   您在将模式发布到特定variant后，该variant的graph ref将始终在其README页面的顶部显示：

   

3. 运行修改后的命令。

   • 如果命令成功，您将看到以下输出

     文本

     1
     A new subgraph called 'locations' was created in 'docs-example-graph@main'
     2
     The supergraph schema for 'docs-example-graph@main' was updated, composed from the updated 'locations' subgraph

     复制

   • 如果命令失败，请确保您已使用GraphOS对Rover进行认证。与GraphOS交互的所有Rover命令都需要有效的API密钥。

   此时，如果您在Studio中打开您的graph的详细信息，您将在Schema页面看到locations子graph列出的类型和字段：

   

4. 为reviews子graph重复此操作，再次替换您的graph ref：

   Bash

   rover subgraph introspect https://flyby-reviews-sub.herokuapp.com/ | \
   rover subgraph publish --name reviews \
   --routing-url https://flyby-reviews-sub.herokuapp.com/ \
   --schema - <GRAPH_REF>

   复制

   您只需在第一次向特定变体发布子图架构时提供子图的 --routing-url 就可以了（除非以后需要更改该URL）。

   如果您在Studio中刷新Schema页面，现在您将看到 fields 和从 reviews 子图中的 fields。

我们每次发布子图架构，GraphOS都会自动将其所有子图架构组合成超级图架构！但是，我们的路由器尚未从Apollo获取该架构。我们将在下一阶段解决这个问题。

6. 连接到GraphOS的router

现在是时候启用我们的router，让它从GraphOS获取其超级图架构了。为此，我们需要一个 图形API密钥，并将其设置为环境变量的值。

1. 通过以下步骤获取您的Studio graph的graph API密钥：

   如何获取图形API密钥

   ⚠️ 注意

   API密钥是秘密凭证。切勿将其泄露给组织外部人员或在版本控制系统中提交。如果您怀疑API密钥受到损害，请将其删除并替换。

   1. 转到 studio.apollographql.com 并单击您要获取API密钥的graph。

   2. 如果出现 发布您的Schema 对话框，请复制示例代码块中 APOLLO_KEY= 后出现的受保护值（以 service: 开头），并设置完毕。

      否则，继续下一步。

   3. 打开您的graph设置页面并选择API密钥标签。点击 创建新密钥。为您的密钥命名，例如 生产。这有助于您跟踪每个API密钥的使用情况。

      ⓘ 注意

      如果您看不到API密钥标签，您没有足够的您的 graph 权限。只有拥有 组织管理员 或 graph管理员 角色的组织成员才能管理 graph API密钥。 了解成员角色的更多信息。

   4. 复制密钥的值。出于安全考虑，在创建后，您无法在Studio中查看API密钥的值。

   如果您有企业计划，请根据以下要求设置API密钥的角色：

   • 如果您的路由器将使用受保护变体，请选择图管理器。
   • 否则，请选择贡献者。

   💡 提示

   请确保将API密钥的值复制并粘贴到某个地方，以便您可以引用它。出于安全考虑，API密钥在创建后不会在工作室中可见。

2. 在您的路由器项目中创建一个名为.env的文件，并粘贴以下内容（将<API_KEY>替换为您的图API密钥，将<GRAPH_REF>替换为您的图引用):

   文本

   1
   APOLLO_KEY=<API_KEY>
   2
   APOLLO_GRAPH_REF=<GRAPH_REF>

   复制

   ⚠️ 注意

   API密钥是秘密凭证。永远不要在您的组织外部共享它们或将它们提交到版本控制。删除并更换您认为已泄露的API密钥。确保始终将.env文件添加到您的.gitignore文件。路由器模板项目已经这样做。

3. 将此命令粘贴到您的终端并运行它

   Bash

   docker run -it --env-file .env -p4000:4000 router

   复制

   这次没有错误，您将看到以下类似输出（省略了时间戳以节省空间）

   点击展开

   文本

   1
   INFO Apollo Router v1.18.0 // (c) Apollo Graph, Inc. // Licensed as ELv2 (https://go.apollo.dev/elv2)
   2
   INFO Anonymous usage data is gathered to inform Apollo product development.  See https://go.apollo.dev/o/privacy for more info.
   3
   INFO Running with *development* mode settings which facilitate development experience (for example, introspection enabled)
   4
   INFO GraphOS Studio usage reporting is enabled. See https://go.apollo.dev/o/data for details
   5
   INFO creating apollo exporter spaceport_endpoint=https://127.0.0.1:62894/
   6
   INFO creating apollo exporter spaceport_endpoint=https://127.0.0.1:62894/
   7
   INFO healthcheck endpoint exposed at http://127.0.0.1:8088/health
   8
   INFO GraphQL endpoint exposed at http://127.0.0.1:4001/ 🚀

   复制

   通过为路由器提供一个API密钥，您还自动启用了操作指标报告到GraphOS，使您能够可视化图形的性能。了解更多关于指标的信息。

现在我们的路由器正在运行，我们可以快速打开浏览器到localhost:4000来探索我们在Apollo沙盒中的组合架构

现在让我们对supergraph执行一些测试查询。我们将下一步查看这些测试查询的指标。

7. 查看操作和字段指标

因为我们的路由器连接到GraphOS，它将自动收集和报告传入的操作及其字段的指标。然后您可以在工作室中可视化这些指标。

返回到GraphOS工作室并转到您的supergraph变体的洞察页面，如下所示：

在前一个步骤中执行的测试查询将在几分钟内显示在这个页面上。洞察页面对于监控超级图在所有查询路由器的客户端中的性能至关重要。

了解更多关于可用的指标，请访问指标文档。展开下方的摘要表，以了解更多关于 Studio 中其他变体页面。

Studio 中的变体页面

第8节：部署路由器并连接客户端

现在，我们的路由器在开发环境中成功运行，我们可以将其部署到我们首选的平台（AWS、Google Cloud 等），以便客户端可以开始查询它！

部署路由器确切的细节取决于您使用哪个平台，但这些高阶步骤适用于大多数平台：

1. 在 CI 中构建 Docker 镜像并将其推送到容器注册库（一些提供商允许您跳过此步骤）。

2. 将镜像部署到您首选的平台（有关 Kubernetes 部署的额外资源）。

3. 在路由器的部署环境中设置APOLLO_KEY和APOLLO_GRAPH_REF环境变量，如同我们在此步骤本地做的那样。

   • 请记住，APOLLO_KEY是一个秘密，所以在您的部署环境中使用适当的机制来存储它。

4. 如果您平台希望 router 在特定的端口号上监听，请在此配置文件中设置该端口号：router.yaml（它是模板的一部分）。

   YAML

   router.yaml

   1
   supergraph:
   2
     # The socket address and port to listen on
   3
     listen: 127.0.0.1:4000
   4
     # OR if the port is specified via environment variable
   5
     listen: 127.0.0.1:${env.PORT}

   复制

   💡 提示

   了解更多关于 router 配置选项。

成功部署您的 router 后，它已准备好开始接收客户端 operations！如果您有现有的客户端应用程序直接连接到您的 GraphQL API，您可以更新它们的 GraphQL 端点 URL 为您的 router 的 URL。

类似地，所有新的客户端应用程序应使用您的 router 的 URL。

下一步

做得好！我们已经将两个 subgraph schema 在 GraphOS 上注册，并设置了一个 router 来检索其组成的 supergraph schema，以便可以在子图之间执行 operations。

如果我们现在发布对其中一个子图 schema 的更改，我们的正在运行的 router 会自动检索对应的超图 schema 的相应更改（假设 组合 成功）。

接下来，我们将介绍一些在您的新 supergraph 上执行的最常见和最重要的操作，包括：

• 更新 subgraph schema
• 添加另一个 subgraph
• 设置 schema 检查

转到下一步。