自1.25.0

使用持久查询进行白名单

在减低请求延迟的同时保障您的图安全

该功能仅适用于 GraphOS 企业计划.
您可以通过免费企业试用版.

通过 GraphOS 企业版，您可以通过维护 supergraph 的持久查询列表 (PQL) 来增强您的 GraphOS Router 的安全性。为了创建和更新 PQL，第三方应用程序将在构建时向 PQL 附加受信任操作。

ⓘ 注意

客户端可以向 PQL 注册任何类型的操作，包括查询、突变和订阅。

在运行时，路由器会对照 PQL 来检查传入的请求，这可以作为操作白名单，具体取决于您的路由器配置。

您的路由器可以使用其持久化查询列表（PQL），既可以保护您的 supergraph，也可以加快客户端的操作速度：

当您启用 白名单 时，您的路由器会拒绝任何未在 PQL 中注册的操作。
客户端应用程序可以通过提供其 PQL 指定的 ID 而不是整个操作字符串来执行操作。
- 按 ID 请求可以显著减少大型操作字符串的延迟和网络使用。
- 您的路由器可以要求客户端通过 ID 提供操作，并拒绝完整的操作字符串——甚至完整的 PQL 操作字符串。

与自动持久化查询的区别

Apollo 路由器核心 cũng hỗ trợ một tính năng liên quan gọi là automatic persisted queries (APQ)。 Với APQ，khách hàng có thể thực hiện một GraphQL operation bằng cách gửi hash SHA256 của chuỗi hoạt động thay vì chuỗi hoạt động nguyên bản. APQ không hỗ trợ chức năng white-listing vì router sẽ cập nhật bộ nhớ cache APQ của nó theo thời gian với bất kỳ operations nó nhận được.

Để biết thêm về sự khác nhau giữa APQ và tính năng này, xem tài liệu GraphOS persisted queries。

Triển khai

Sự kiện projectile để kích hoạt operation white-listing có một số bước:

Tạo và liên kết PQL
Cấu hình Router
Registration operation
Cập nhật phiên bản khách

Bài viết này chi tiết về bước cấu hình router. Để biết thêm thông tin về các khía cạnh cấu hình khác, xem tài liệu GraphOS persisted queries。

Cấu hình router

Khi một biến thể graph variant đã liên kết PQL-connected, bạn có thể cấu hình các instance router để tải và sử dụng PQL bằng cách làm theo các bước sau:

Đảm bảo các instance router của bạn sẵn sàng làm việc với PQLs：
- 确保您使用的是版本 v1.32.0 或更高版本的路由器。（该功能在版本 v1.25.0 的预览中发布，并在 v1.32.0 中提供通用功能。）
- 确保您的路由器实例已连接到您的 GraphOS Enterprise 组织，并且与您 PQL 流量关联的版本。
在路由器的 YAML 配置文件中设置您希望的安全级别。有关支持选项，请参阅路由器安全级别。在初次实施持久查询时，最好从审核（模拟运行）模式开始。
部署更新后的路由器实例以开始使用您的 PQL。

一旦您组织中的 PQL 已注册您所有客户的操作，且您已确保客户端应用程序仅发送已注册的操作，您可以将路由器配置更新为安全列表安全级别。

路由器安全级别

GraphOS 路由器支持以下安全级别，按限制程度递增：

允许操作 ID：客户端可以选择执行操作，通过提供操作 PQL指定的 ID。
- 所有其他级别也提供此核心功能。
- 此级别不提供安全列表功能。
审核模式：通过提供 PQL 指定的 ID 执行操作仍然是可选的，但路由器也会记录任何未注册的操作。
- 此级别可以作为模拟运行，帮助您在启用安全列表之前识别出您可能仍需注册的操作。
安全列表：路由器拒绝所有不在其 PQL 中的操作。请求可以使用 ID 或操作字符串。
- 在此安全级别之前切换，请确保所有客户端操作都包含在您的 PQL 中。
仅 ID 的安全列表：路由器拒绝任何自由形式的 GraphQL 操作。客户端只能通过提供它们的 PQL 指定的 ID 来执行操作。
- 在此安全级别之前切换，请确保所有客户端通过提供它们的 PQL 指定的 ID 执行操作。

在采用持久查询时，您应该从较宽松的安全级别开始，如审核模式。然后，在团队更新所有客户端后，您可以启用日趋严格的安全级别。

以下是每个级别的示例 YAML 配置。请参考路由器配置选项以获取选项的详细信息。

ⓘ 注意

从版本1.25.0到1.32.0，persisted_queries配置选项被命名为preview_persisted_queries。将您的router升级到版本1.32.0或更高版本，以使用以下特性的一般可用版本和示例配置片段。

允许操作ID

为了仅使用持久化查询以减少网络带宽和延迟（不是为了列入白名单），请添加以下最小配置：

router.yaml

1
persisted_queries:
2
  enabled: true

ⓘ 注意

您可以使用此安全级别Whether启用或禁用自动持久化查询。

此模式允许客户端通过提供他们的PQL指定的ID来执行操作，而不是完整的操作字符串。您的router也继续接受完整的操作字符串，即使对于不包含在其PQL中的操作也是如此。

审计模式（干燥运行）

打开日志记录对于评估您的客户端应用程序的列入白名单准备情况至关重要。日志记录可以确定您需要将哪些操作添加到您的PQL中，或阻止您的客户端应用程序执行的操作。

要启用未注册查询的日志记录，请启用log_unknown属性：

router.yaml

1
persisted_queries:
2
  enabled: true
3
  log_unknown: true

ⓘ 注意

您可以使用审计模式是否启用自动持久化查询。

未注册操作将显示在您的router的日志中。

例如

1
2023-08-02T11:51:59.833534Z  WARN [trace_id=5006cef73e985810eb086e5900945807] unknown operation operation_body="query ExampleQuery {\n  me {\n    id\n  }\n}\n"

如果您的router收到在PQL中注册的操作，则不会输出日志消息。

您可以使用这些router日志来审计发送到您的router的操作，并要求客户端团队添加新的操作到您的PQL中（如果需要）。

列入白名单

⚠️ 注意

在应用此配置之前，请确保您的PQL包含所有GraphQL操作，这些操作都在您的客户端应用的当前活跃版本中执行。如果未确保此操作而启用列入白名单，则您的router将拒绝所有未发布的客户端操作。

使用以下配置，您的路由器仅允许其中的GraphQL操作，并拒绝所有其他操作：

router.yaml

1
persisted_queries:
2
  enabled: true
3
  log_unknown: true
4
  safelist:
5
    enabled: true
6
    require_id: false
7
apq:
8
  enabled: false # APQ must be turned off

ⓘ 注意

要启用安全列表，您必须关闭自动持久查询（APQs）。APQs允许客户端在运行时注册任意操作，而安全列表则将操作限制为已明确注册的那些。

要执行一个操作，客户端可以提供其 PQL指定的ID或完整的操作字符串。路由器拒绝未注册的操作，如果log_unknown为true，则那些操作将在您的路由器日志中显示。

💡 小贴士

采用安全列表时，最佳做法是保持log_unknown为true，这样您可以监控路由器拒绝的操作。一旦您确信所有客户端都已正确配置，您可以将它关闭以提高日志的清晰度。

仅使用ID的安全列表

⚠️ 注意

不要从此配置开始。它要求所有客户端通过提供其PQL指定的ID来执行操作。如果任何客户端仍然提供完整的操作字符串，路由器将拒绝这些操作，即使它们包含在安全列表中。

使用以下配置，您的路由器拒绝所有操作字符串，仅接受注册的操作ID：

router.yaml

1
persisted_queries:
2
  enabled: true
3
  log_unknown: true
4
  safelist:
5
    enabled: true
6
    require_id: true 
7
apq:
8
  enabled: false # APQ must be turned off

ⓘ 注意

要启用安全列表，您必须关闭自动持久查询（APQs）。APQs允许客户端在运行时注册任意操作，而安全列表则将操作限制为已明确注册的那些。

如果您想使用此安全级别，您应该首先设置允许操作字符串的安全列表。仅ID的安全列表要求所有您的客户端通过PQL指定的ID而不是操作字符串来执行操作。在执行这些必需的更改时，您可以在路由器中使用更宽松的安全列表模式。

将log_unknown设置为true时，路由器会记录所有被拒绝的操作，包括那些已注册到您的PQL但使用了完整的操作字符串而不是PQL指定的ID的操作。

ⓘ 注意

配置选项

路由器提供四种配置选项，您可以组合使用这些选项来创建推荐的安全级别。本节详细说明了每个配置选项。有关推荐组合，请参阅安全级别部分。

ⓘ 注意

从版本 1.25.0 到 1.32.0，配置选项 persisted_queries 的名称改为 preview_persisted_queries。将您的路由器升级到版本 1.32.0 或更高版本以使用该功能的通用版以及下面的示例配置片段。

`persisted_queries`

此基本配置启用该功能。所有其他配置选项都是基于此配置进行构建的。

router.yaml

1
persisted_queries:
2
  enabled: true

`log_unknown`

将 log_unknown: true 添加到 persisted_queries 配置，使路由器将任何未注册到 PQL 的操作记录下来。

router.yaml

1
persisted_queries:
2
  enabled: true
3
  log_unknown: true

如果与 safelist 选项一起使用，路由器将记录未注册和拒绝的操作。禁用 safelist.required_id 时，只有未注册的操作会被拒绝。如果启用 safelist.required_id，即使操作已注册，也可能因使用操作 ID 而不是操作字符串而被拒绝。

`experimental_prewarm_query_plan_cache`

此功能为实验性。您的疑问和反馈非常重要——请及时与您的 Apollo 联系人联系.

将 experimental_prewarm_query_plan_cache: true 添加到 persisted_queries 配置，使路由器在启动时使用持久化查询列表预热查询计划缓存。所有后续请求都将从预热的缓存中受益，从而降低延迟并提高性能。

router.yaml

1
persisted_queries:
2
  enabled: true
3
  experimental_prewarm_query_plan_cache: true # default: false

`experimental_local_manifests`

此功能为实验性。您的疑问和反馈非常重要——请及时与您的 Apollo 联系人联系.

将 experimental_local_manifests 添加到您的 persisted-queries 配置，您可以使用本地的持久化查询清单而不是托管 Uplink 版本。这对于使用离线 Enterprise license 且无法使用 Uplink 情况有所帮助。使用 experimental_local_manifests，路由器不会从文件系统重新加载清单，因此您需要重新启动路由器以应用更改。

router.yaml

1
persisted_queries:
2
  enabled: true
3
  experimental_local_manifests: 
4
    - ./path/to/persisted-query-manifest.json

您可以从 GraphOS Studio 中下载您的清单版本以本地使用。通过点击左边图形名称旁边的 转到持久化查询列表，打开 PQL 页。然后，单击操作列下的 ••• 菜单，以将 PQL 的清单作为 JSON 文件下载。将此文件保存在本地，并使用文件路径更新您的 experimental_local_manifests 配置。

`白名单`

将 safelist: true 添加到 persisted_queries，将导致 router 丢弃任何未注册到您的 PQL 的操作。

router.yaml

1
persisted_queries:
2
  enabled: true
3
  safelist:
4
    enabled: true
5
apq:
6
  enabled: false

ⓘ 注意

要启用白名单，您必须关闭自动持久化查询 (APQs)。APQs 允许客户端在运行时注册任意操作，而白名单将限制操作为显式注册的操作。

默认情况下，require_id 子选项为 false，这意味着只要操作已注册，router 就接受操作 ID 和操作字符串。

`require_id`

将 require_id: true 添加到 safelist 选项会导致 router 丢弃任何以下操作：

未注册到您的 PQL
使用完整的操作字符串而不是操作 ID

router.yaml

1
persisted_queries:
2
  enabled: true
3
  safelist:
4
    enabled: true
5
    require_id: true
6
apq:
7
  enabled: false

ⓘ 注意

要启用白名单，您必须关闭自动持久化查询 (APQs)。APQs 允许客户端在运行时注册任意操作，而白名单将限制操作为显式注册的操作。

限制条件

不支持离线许可证。使用 GraphOS Router 的离线企业许可证无法使用持久化查询的白名单功能。此功能依赖于 Apollo Uplink 来检索持久化查询清单，因此当 router 与 Uplink 断开连接时，该功能不能按设计工作。

操作限制

需求控制