YARP HTTP 用戶端設定

簡介

每個叢集都有專用的 HttpMessageInvoker 實例，用來將要求轉送至其目的地。每個叢集會定義組態。在 YARP 啟動時，所有叢集都會取得新的 HttpMessageInvoker 實例，不過，如果稍後叢集組態變更， IForwarderHttpClientFactory 將會重新執行，並決定是否應該建立新的 HttpMessageInvoker 或繼續使用現有的實例。當 IForwarderHttpClientFactory 有變更時，預設HttpMessageInvoker實作會建立新的。

也可以設定指定叢集的傳出要求屬性。它們定義於 ForwarderRequestConfig 中。

如果您使用 IConfiguration 模型或程式代碼優先模型，則組態會以不同的方式表示。

IConfiguration（配置介面）

這些類型著重於定義可串行化的組態。程式代碼型組態模型的描述請參見下方的「程式配置」一節。

HttpClient

HTTP 用戶端組態是以 HttpClientConfig 為基礎，並以下列組態架構表示。如果您需要更細微的方法，請使用自訂實作的IForwarderHttpClientFactory。

"HttpClient": {
  "SslProtocols": [ "<protocol-names>" ],
  "MaxConnectionsPerServer": "<int>",
  "DangerousAcceptAnyServerCertificate": "<bool>",
  "RequestHeaderEncoding": "<encoding-name>",
  "ResponseHeaderEncoding": "<encoding-name>",
  "EnableMultipleHttp2Connections": "<bool>",
  "WebProxy": {
    "Address": "<url>",
    "BypassOnLocal": "<bool>",
    "UseDefaultCredentials": "<bool>"
  }
}

組態設定：

SslProtocols - 在指定的 HTTP 用戶端上啟用 SSL 通訊協定。通訊協定名稱會指定為字串數位。預設值為 None。

"SslProtocols": [
  "Tls11",
  "Tls12"
]

MaxConnectionsPerServer - 並行開啟至相同伺服器的 HTTP 1.1 連線數目上限。預設值為 int32。MaxValue。

"MaxConnectionsPerServer": "10"

DangerousAcceptAnyServerCertificate - 指出用戶端是否檢查伺服器的 SSL 憑證是否有效。將它設定為 true 完全停用驗證。預設值為 false。

"DangerousAcceptAnyServerCertificate": "true"

RequestHeaderEncoding - 允許傳出要求標頭使用非 ASCII 編碼。設定此值會利用 SocketsHttpHandler.RequestHeaderEncodingSelector，並將所選編碼用於所有標頭。然後使用Encoding.GetEncoding來剖析這些值，例如："utf-8"、"iso-8859-1"等。

"RequestHeaderEncoding": "utf-8"

啟用非 ASCII 編碼以處理來自代理伺服器將轉送的請求的傳入回應標頭。設定此值會利用 SocketsHttpHandler.ResponseHeaderEncodingSelector，並將所選編碼用於所有標頭。然後使用Encoding.GetEncoding來剖析這些值，例如："utf-8"、"iso-8859-1"等。

"ResponseHeaderEncoding": "utf-8"

請注意，如果您使用 ASCII 以外的編碼方式，您也需要將伺服器設定為接受這類標頭的要求和/或傳送回應。例如，當使用 Kestrel 作為伺服器時，請使用 KestrelServerOptions.RequestHeaderEncodingSelector / .ResponseHeaderEncodingSelector 來設定 Kestrel，以允許 Latin1 ("iso-8859-1") 標頭。

var builder = WebApplication.CreateBuilder(args);
builder.WebHost.ConfigureKestrel(kestrel =>
{
    kestrel.RequestHeaderEncodingSelector = _ => Encoding.Latin1;
    // and/or
    kestrel.ResponseHeaderEncodingSelector = _ => Encoding.Latin1;
});

EnableMultipleHttp2Connections - 當所有現有連線達到最大同時串流數量上限時，啟用與相同伺服器的其他 HTTP/2 連線。預設值為 true。請參閱 SocketsHttpHandler.EnableMultipleHttp2Connections

"EnableMultipleHttp2Connections": false

WebProxy - 允許透過輸出 HTTP Proxy 傳送要求以到達目的地。如需詳細資訊，請參閱 SocketsHttpHandler.Proxy。
- 位址 - 輸出 Proxy 的 URL 位址。
- BypassOnLocal - 布林值，指出本機位址的要求是否應該不經過外部代理。
- UseDefaultCredentials - 布爾值，指出目前的應用程式認證是否應該用來向輸出 Proxy 進行驗證。 ASP.NET Core 不會模擬已驗證的使用者進行輸出要求。

"WebProxy": {
  "Address": "http://myproxy:8080",
  "BypassOnLocal": "true",
  "UseDefaultCredentials": "false"
}

備註

預設值 ForwarderHttpClientFactory 設定 UseProxy 為 false。如果您想要使用預設系統 Proxy 而不是指定自訂 Proxy 位址，您可以設定 UseProxy 回 true 使用該 ConfigureHttpClient 方法。這在使用 Fiddler 等工具進行偵錯時很有用。如需範例，請參閱設定 http 用戶端一節。

HTTP請求

HTTP 要求組態是以 ForwarderRequestConfig 為基礎，並以下列組態架構表示。

"HttpRequest": {
  "ActivityTimeout": "<timespan>",
  "Version": "<string>",
  "VersionPolicy": ["RequestVersionOrLower", "RequestVersionOrHigher", "RequestVersionExact"],
  "AllowResponseBuffering": "<bool>"
}

組態設定：

ActivityTimeout - 設定一個請求在任何操作完成後允許保持閒置的時間，超過此時間後將被取消。預設值為100秒。逾時會在收到回應標頭或成功讀取或寫入任何要求、回應或串流數據（如 gRPC 或 WebSockets）後重設。 TCP keep-alives 和 HTTP/2 通訊協定 ping 不會重設逾時設定，但 WebSocket ping 將會重設。
版本 - 外發請求版本。目前支援的值是1.0、 1.12 與 3。預設值為 2。
VersionPolicy - 定義如何為傳出要求選取最終版本。請參閱 HttpRequestMessage.VersionPolicy。預設值是 RequestVersionOrLower。
AllowResponseBuffering - 如果裝載 YARP 的伺服器支援它，則允許在將回應傳回用戶端時使用寫入緩衝。注意：啟用它可能會中斷 SSE（伺服器端事件）情境。

設定範例

下列範例顯示 cluster1 和 cluster2 的 HTTP 用戶端和要求組態的 2 個範例。

{
  "Clusters": {
    "cluster1": {
      "LoadBalancingPolicy": "Random",
      "HttpClient": {
        "SslProtocols": [
          "Tls11",
          "Tls12"
        ],
        "MaxConnectionsPerServer": "10",
        "DangerousAcceptAnyServerCertificate": "true"
      },
      "HttpRequest": {
        "ActivityTimeout": "00:00:30"
      },
      "Destinations": {
        "cluster1/destination1": {
          "Address": "https://localhost:10000/"
        },
        "cluster1/destination2": {
          "Address": "http://localhost:10010/"
        }
      }
    },
    "cluster2": {
      "HttpClient": {
        "SslProtocols": [
          "Tls12"
        ]
      },
      "HttpRequest": {
        "Version": "1.1",
        "VersionPolicy": "RequestVersionExact"
      },
      "Destinations": {
        "cluster2/destination1": {
          "Address": "https://localhost:10001/"
        }
      }
    }
  }
}

程式碼設定

HTTP 用戶端組態會使用 HttpClientConfig 類型。

以下是使用HttpClientConfig組態的範例。將叢集陣列傳遞至 HttpClientConfig 方法之前，會將的實例指派給LoadFromMemory屬性。

var routes = new[]
{
    new RouteConfig()
    {
        RouteId = "route1",
        ClusterId = "cluster1",
        Match =
        {
            Path = "{**catch-all}"
        }
    }
};
var clusters = new[]
{
    new ClusterConfig()
    {
        ClusterId = "cluster1",
        Destinations =
        {
            { "destination1", new DestinationConfig() { Address = "https://localhost:10000" } }
        },
        HttpClient = new HttpClientConfig { MaxConnectionsPerServer = 10, SslProtocols = SslProtocols.Tls11 | SslProtocols.Tls12 }
    }
};

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

設定 HTTP 用戶端

ConfigureHttpClient 提供回呼來自訂 SocketsHttpHandler 設置，以用於代理請求。每次新增或變更叢集時，都會呼叫此專案。叢集設定會在回呼之前套用至處理程式。您可以在叢集元資料中提供自訂資料。此範例示範如何添加一個客戶端憑證，以驗證代理伺服器至目的地伺服器。

var clientCert = new X509Certificate2("path");
services.AddReverseProxy()
    .ConfigureHttpClient((context, handler) =>
    {
        handler.SslOptions.ClientCertificates.Add(clientCert);
    });

使用預設系統代理伺服器

預設 ForwarderHttpClientFactory 將 UseProxy 設定為 false，以避免代理伺服器偵測和設定的額外負荷。如果您需要使用預設系統 Proxy （例如，使用 Fiddler 或其他 Proxy 工具進行偵錯時），您可以設定 UseProxy 回 true：

services.AddReverseProxy()
    .ConfigureHttpClient((context, handler) =>
    {
        handler.UseProxy = true;
    });

此配置允許使用 HttpClient 系統的預設 Proxy 設定，而不必在配置中 WebProxy 手動指定 Proxy 位址。

自定義 IForwarderHttpClientFactory

如果需要直接控制 HTTP 用戶端建構，預設的 IForwarderHttpClientFactory 可以取代為自定義的 IForwarderHttpClientFactory 。對於某些自定義專案，您可以從預設 ForwarderHttpClientFactory 衍生，並重寫配置用戶端的方法。

建議任何自定義處理站將下列 SocketsHttpHandler 屬性設定為與默認處理站相同的值，以保留正確的反向 Proxy 行為，並避免不必要的額外負荷。

new SocketsHttpHandler
{
    UseProxy = false,
    AllowAutoRedirect = false,
    AutomaticDecompression = DecompressionMethods.None,
    UseCookies = false,
    EnableMultipleHttp2Connections = true,
    ActivityHeadersPropagator = new ReverseProxyPropagator(DistributedContextPropagator.Current),
    ConnectTimeout = TimeSpan.FromSeconds(15),
};

一律傳回 HttpMessageInvoker 實例，而不是衍生自 HttpMessageInvoker 的 HttpClient 實例。 HttpClient 預設會緩衝回應，這會中斷串流案例，並增加記憶體使用量和延遲。

您可以在叢集元資料中提供自訂資料。

以下是自定義 IForwarderHttpClientFactory 實作的範例。

public class CustomForwarderHttpClientFactory : IForwarderHttpClientFactory
{
    public HttpMessageInvoker CreateClient(ForwarderHttpClientContext context)
    {
        var handler = new SocketsHttpHandler
        {
            UseProxy = false,
            AllowAutoRedirect = false,
            AutomaticDecompression = DecompressionMethods.None,
            UseCookies = false,
            EnableMultipleHttp2Connections = true,
            ActivityHeadersPropagator = new ReverseProxyPropagator(DistributedContextPropagator.Current),
            ConnectTimeout = TimeSpan.FromSeconds(15),
        };

        return new HttpMessageInvoker(handler, disposeHandler: true);
    }
}

意見反應

此頁面對您有幫助嗎？

Last updated on 2025-11-08