YARP 可扩展性：配置提供程序

2025-04-17

介绍

基本 Yarp 示例显示从 appsettings.json 加载的代理配置。相反，可以从选择的源以编程方式加载代理配置。可以通过提供几个实现 IProxyConfigProvider 和 IProxyConfig 的类来实现这一点。

有关自定义配置提供程序的示例，请参阅 ReverseProxy.Code.Sample。

在加载序列期间，可以使用配置筛选器修改配置。

结构

IProxyConfigProvider 具有单个方法 GetConfig()，该方法返回 IProxyConfig 实例。 IProxyConfig 包含当前路由和群集的列表，以及一个 IChangeToken，用于在此信息过期并应重新加载时通知代理，这将导致再次调用 GetConfig()。

路由

路由部分是命名路由的无序集合。路由包含匹配项及其关联的配置。路由至少需要以下字段：

RouteId - 唯一名称
ClusterId - 指群集部分中的条目名称。
匹配 - 包含主机数组或路径模式字符串。路径是一个 ASP.NET Core 路由模板，可定义为如所述，详见。

Headers、Authorization、CORS 以及其他基于路由的策略都可以在每个路由表项上配置。有关其他字段，请参阅 RouteConfig。

代理将应用给定的匹配条件和策略，然后将请求传递给指定的群集。

群集

群集部分是一个由多个命名群集组成的无序集合。群集主要包含命名目标的集合及其地址，其中任何一个都被视为能够处理给定路由的请求。代理将根据路由和群集配置处理请求，以选择目标。

有关其他字段，请参阅 ClusterConfig。

在内存配置中

InMemoryConfigProvider 实现 IProxyConfigProvider，并通过调用 LoadFromMemory 直接在代码中指定路由和群集。

services.AddReverseProxy().LoadFromMemory(routes, clusters);

若要稍后更新配置，请从服务容器解析 InMemoryConfigProvider，并使用新的路由和群集列表调用 Update。

httpContext.RequestServices.GetRequiredService<InMemoryConfigProvider>().Update(routes, clusters);

生命周期

初创公司

IProxyConfigProvider 作为单一实例在 DI 容器中注册。启动时，代理将解析此实例并调用 GetConfig()。在此首次调用时，提供程序可以选择：

如果提供程序因任何原因无法生成有效的代理配置，则引发异常。这会阻止应用程序启动。
在加载配置时同步阻止。这将阻止应用程序启动，直到有效的路由数据可用。
或者，它可以选择在后台加载配置时返回一个空的 IProxyConfig 实例。当配置可用时，提供程序需要触发 IChangeToken。

代理将验证给定的配置，如果配置无效，将引发异常，阻止应用程序启动。提供程序可以使用 IConfigValidator 来预先验证路由和群集，并采取任何其认为适当的措施，例如剔除无效条目。

原子性

提供给代理的配置对象和集合应是只读的，一旦通过 GetConfig() 将其传递给代理，就不能修改。

重新加载

如果 IChangeToken 支持 ActiveChangeCallbacks，则代理处理初始配置集后，它将使用此令牌注册一个回调。如果服务提供程序不支持回调，则每 5 分钟轮询一次 HasChanged。

当提供程序想要向代理提供新配置时，它应：

在后台加载该配置。
- 路由和群集对象是不可变的，因此必须为任何新数据创建新实例。
- 未更改的路由和群集的对象可以重复使用，也可以创建新的实例，通过区分它们可以检测更改。
（可选）使用 IConfigValidator 验证配置，只有在此之后，才向之前的 IProxyConfig 实例发出IChangeToken信号，以告知新数据可用。代理将再次调用 GetConfig() 以检索新数据。

重新加载配置与第一次加载配置有重要区别。

新配置将与当前配置不同，只有修改后的路由或群集才会更新。更新将以原子方式应用，并且只会影响新请求，而不会影响当前正在进行的请求。
重新加载过程中的任何错误都将被记录并抑制。应用程序将继续使用最后一个已知良好的配置。
如果引发 GetConfig()，代理将无法侦听未来的更改，因为 IChangeToken 是一次性的。

一旦新的配置被验证和应用，代理将向新的 IChangeToken 注册一个回调。请注意，如果连续发出多个重载信号，代理可能会跳过某些重载，并在准备就绪后立即加载下一个可用配置。每个 IProxyConfig 都包含完整的配置状态，因此不会丢失任何内容。

多个配置源

从 1.1 起，YARP 支持从多个源加载代理配置。多个 IProxyConfigProvider 可以注册为单例服务，并且所有这些服务都将被解析和合并。这些源可以是相同或不同的类型，例如 IConfiguration 或 InMemory。路由可以引用来自其他源的群集。请注意：不支持合并来自给定路由或群集的不同源的部分配置。

    services.AddReverseProxy()
        .LoadFromConfig(Configuration.GetSection("ReverseProxy1"))
        .LoadFromConfig(Configuration.GetSection("ReverseProxy2"));

或

    services.AddReverseProxy()
        .LoadFromMemory(routes, clusters)
        .LoadFromConfig(Configuration.GetSection("ReverseProxy"));

示例

InMemoryConfigProvider 给出了一个 IProxyConfigProvider 的示例，其中手动加载了路由和群集。