.NET core 中的Kestrel 服务器

什么是Kestrel？

Kestrel 是一个跨平台的Web服务器，会默认在ASP.NET Core 项目模板中对其进行配置。未使用 IIS 托管时，ASP.NET Core 项目模板默认使用 Kestrel。

Kestrel 的功能包括：

跨平台：Kestrel 是可在 Windows、Linux 和 macOS 上运行的跨平台 Web 服务器。
高性能：Kestrel 经过优化，可有效处理大量并发连接。
轻量级：它经过优化，可在资源受限的环境（如容器和边缘设备）中运行。
强化了安全性：Kestrel支持 HTTPS 并经过强化可抵御 Web 服务器漏洞。
宽协议支持：Kestrel 支持常见的 Web 协议，包括：
- HTTP/1.1、HTTP/2 和 HTTP/3
- WebSockets
与 ASP.NET Core 集成：与其他 ASP.NET Core 组件（例如中间件管道、依赖项注入和配置系统）无缝集成。
灵活工作负载：Kestrel 支持许多工作负载：
- ASP.NET 应用框架，例如最小 API、MVC、Razor 页、SignalR、Blazor 和 gRPC。
- 使用 YARP 生成反向代理。
扩展性：通过配置、中间件和自定义传输自定义 Kestrel。
性能诊断：Kestrel 提供内置的性能诊断功能，例如日志记录和指标。

在下面的模板生成的 Program.cs 中，WebApplication.CreateBuilder 方法在内部调用 UseKestrel：

var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();

app.MapGet("/", () => "Hello World!");

app.Run();

一、终结点配置

ASP.NET Core 项目配置为绑定到 5000-5300 之间的随机 HTTP 端口和 7000-7300 之间的随机 HTTPS 端口。所选端口存储在生成的 Properties/launchSettings.json 文件中，开发人员可以对其进行修改。 launchSetting.json 文件仅用于本地开发。

如果没有终结点配置，则 Kestrel 绑定到 http://localhost:5000。

在 appsettings.json 中配置终结点

Kestrel 可以从 IConfiguration 实例加载终结点。默认情况下，Kestrel 配置从 Kestrel 部分加载，终结点在 Kestrel:Endpoints 中配置：

{
  "Kestrel": {
    "Endpoints": {
      "MyHttpEndpoint": {
        "Url": "http://localhost:8080"
      }
    }
  }
}

上面的示例：

使用 appsettings.json 作为配置源。但是，可以使用任何 IConfiguration 源。
在端口 8080 上添加名为 MyHttpEndpoint 的终结点。

在代码中配置终结点

KestrelServerOptions 提供用于在代码中配置终结点的方法：

Listen
ListenLocalhost
ListenAnyIP
ListenUnixSocket
ListenNamedPipe

如果同时使用 Listen 和 UseUrls API，Listen 终结点将覆盖 UseUrls 终结点。

Listen、ListenLocalhost 和 ListenAnyIP 方法绑定到 TCP 套接字：

var builder = WebApplication.CreateBuilder(args);

builder.WebHost.ConfigureKestrel((context, serverOptions) =>
{
    serverOptions.Listen(IPAddress.Loopback, 5000);
    serverOptions.Listen(IPAddress.Loopback, 5001, listenOptions =>
    {
        listenOptions.UseHttps("testCert.pfx", "testPassword");
    });
});

上面的示例：

配置侦听端口 5000 和 5001 的终结点。
使用 ListenOptions 上的 UseHttps 扩展方法为终结点配置 HTTPS。有关详细信息，请参阅在代码中配置 HTTPS。

在 Windows 上，可以使用 New-SelfSignedCertificate PowerShell cmdlet 创建自签名证书。有关不受支持的示例，请参阅 UpdateIISExpressSSLForChrome.ps1。

在 macOS、Linux 和 Windows 上，可以使用 OpenSSL 创建证书。

二、配置 HTTPS

Kestrel 支持使用 HTTPS 保护终结点。通过 HTTPS 发送的数据使用传输层安全性 (TLS) 进行加密，以提高在客户端和服务器之间传输的数据的安全性。

HTTPS 需要 TLS 证书。 TLS 证书存储在服务器上，并将 Kestrel 配置为使用该证书。应用可以在本地开发环境中使用 ASP.NET Core HTTPS 开发证书。开发证书未安装在非开发环境中。在生产环境中，必须显式配置 TLS 证书。至少必须提供默认证书。

配置 HTTPS 和 TLS 证书的方式取决于终结点的配置方式：

如果 URL 前缀或仅指定端口用于定义终结点，则仅当 HTTPS 终结点配置中提供了默认证书时，才能使用 HTTPS。可以使用以下选项之一配置默认证书：
在 appsettings.json 中配置 HTTPS
在代码中配置 HTTPS

在 appsettings.json 中配置 HTTPS

Kestrel 可以使用默认 HTTPS 应用设置配置架构。从磁盘上的文件或从证书存储中配置多个终结点，包括要使用的 URL 和证书。

任何未指定证书的 HTTPS 终结点（下例中的 HttpsDefaultCert）会回退至在 Certificates:Default 下定义的证书或开发证书。

以下示例适用于 appsettings.json，但可以使用任何配置源：

{
  "Kestrel": {
    "Endpoints": {
      "Http": {
        "Url": "http://localhost:5000"
      },
      "HttpsDefaultCert": {
        "Url": "https://localhost:5004"
      }
    }
  }
}

在代码中配置 HTTPS

上面已经介绍过，使用 Listen API 时，ListenOptions 上的 UseHttps 扩展方法可用于配置 HTTPS。

var builder = WebApplication.CreateBuilder(args);

builder.WebHost.ConfigureKestrel((context, serverOptions) =>
{
    serverOptions.Listen(IPAddress.Loopback, 5000);
    serverOptions.Listen(IPAddress.Loopback, 5001, listenOptions =>
    {
        listenOptions.UseHttps("testCert.pfx", "testPassword");
    });
});

ListenOptions.UseHttps 参数：

filename 是证书文件的路径和文件名，关联包含应用内容文件的目录。
password 是访问 X.509 证书数据所需的密码。
configureOptions 是配置 HttpsConnectionAdapterOptions 的 Action。返回 ListenOptions。
storeName 是从中加载证书的证书存储。
subject 是证书的主题名称。
allowInvalid 指示是否存在需要留意的无效证书，例如自签名证书。
location 是从中加载证书的存储位置。
serverCertificate 是 X.509 证书。

有关 UseHttps 重载的完整列表，请参阅 UseHttps。

三、为Kestrel 服务器配置选项

上面介绍过，要配置 Kestrel 配置选项，可以在 Program.cs 中调用 ConfigureKestrel：

var builder = WebApplication.CreateBuilder(args);

builder.WebHost.ConfigureKestrel(serverOptions =>
{
    // ...
});

还可以从 appsettings.json 或 appsettings.{Environment}.json 文件配置 Kestrel ：

{
  "Kestrel": {
    "Limits": {
      "MaxConcurrentConnections": 100,
      "MaxConcurrentUpgradedConnections": 100
    },
    "DisableStringReuse": true
  }
}

常用配置：

保持活动状态超时

KeepAliveTimeout 获取或设置保持活动状态超时：

builder.WebHost.ConfigureKestrel(serverOptions =>
{
    serverOptions.Limits.KeepAliveTimeout = TimeSpan.FromMinutes(2);
});

将调试器附加到 Kestrel 进程时，不会强制实施此超时限制。

客户端最大连接数

MaxConcurrentConnections 获取或设置最大打开的连接数：

builder.WebHost.ConfigureKestrel(serverOptions =>
{
    serverOptions.Limits.MaxConcurrentConnections = 100;
});

MaxConcurrentUpgradedConnections 获取或设置最大打开、升级的连接数：

builder.WebHost.ConfigureKestrel(serverOptions =>
{
    serverOptions.Limits.MaxConcurrentUpgradedConnections = 100;
});

升级的连接是已从 HTTP 切换到另一个协议（如 WebSocket）的连接。连接升级后，不会计入 MaxConcurrentConnections 限制。

请求正文最大大小

MaxRequestBodySize 获取或设置允许的请求正文的最大大小（以字节为单位）。

以下示例为所有请求配置 MaxRequestBodySize：

builder.WebHost.ConfigureKestrel(serverOptions =>
{
    serverOptions.Limits.MaxRequestBodySize = 100_000_000;
});

在 ASP.NET Core MVC 应用中替代限制的推荐方法是在操作方法上使用 RequestSizeLimitAttribute 属性：

[RequestSizeLimit(100_000_000)]
public IActionResult Get()

以下示例在一个自定义中间件中使用 IHttpMaxRequestBodySizeFeature 为特定请求配置 MaxRequestBodySize：

app.Use(async (context, next) =>
{
    var httpMaxRequestBodySizeFeature = context.Features.Get<IHttpMaxRequestBodySizeFeature>();

    if (httpMaxRequestBodySizeFeature is not null)
        httpMaxRequestBodySizeFeature.MaxRequestBodySize = 10 * 1024;

    // ...

    await next(context);
});

如果应用在开始读取请求后尝试配置请求的限制，则会引发异常。使用 IHttpMaxRequestBodySizeFeature.IsReadOnly 属性检查设置 MaxRequestBodySize 属性是否安全。

请求正文最小数据速率

Kestrel 每秒检查一次数据是否以指定的速率（字节/秒）传入。如果速率低于最小值，则连接超时。宽限期是 Kestrel 允许客户端将其发送速率提升到最小值的时间量。在此期间不会检查速率。宽限期有助于避免最初由于 TCP 慢启动而以较慢速率发送数据的连接中断。最小速率也适用于响应。

MinRequestBodyDataRate 获取或设置请求正文的最小数据速率（以字节/秒为单位）。 MinResponseDataRate 获取或设置响应最小数据速率（以字节/秒为单位）。

以下示例为所有请求配置 MinRequestBodyDataRate 和 MinResponseDataRate：

builder.WebHost.ConfigureKestrel(serverOptions =>
{
    serverOptions.Limits.MinRequestBodyDataRate = new MinDataRate(
        bytesPerSecond: 100, gracePeriod: TimeSpan.FromSeconds(10));
    serverOptions.Limits.MinResponseDataRate = new MinDataRate(
        bytesPerSecond: 100, gracePeriod: TimeSpan.FromSeconds(10));
});

请求标头超时

RequestHeadersTimeout 获取或设置服务器接收请求头所需的最大时间量：

builder.WebHost.ConfigureKestrel(serverOptions =>
{
    serverOptions.Limits.RequestHeadersTimeout = TimeSpan.FromMinutes(1);
});

HTTP/2 限制

该部分中的限制在 KestrelServerLimits.Http2 上设置。

每个连接的最大流

MaxStreamsPerConnection 限制每个 HTTP/2 连接的并发请求流的数量。拒绝过多的流：

builder.WebHost.ConfigureKestrel(serverOptions =>
{
    serverOptions.Limits.Http2.MaxStreamsPerConnection = 100;
});

标题表大小

HeaderTableSize 限制了服务器上 HPACK 编码器与解码器可以使用的标头压缩表的大小（以八进制数表示）。 HPACK 解码器为 HTTP/2 连接解压缩 HTTP 标头：

builder.WebHost.ConfigureKestrel(serverOptions =>
{
    serverOptions.Limits.Http2.HeaderTableSize = 4096;
});

最大帧大小

MaxFrameSize 指示允许接收的最大帧有效负载的大小（以八进制数表示）：

builder.WebHost.ConfigureKestrel(serverOptions =>
{
    serverOptions.Limits.Http2.MaxFrameSize = 16_384;
});

最大请求标头大小

MaxRequestHeaderFieldSize 指示请求头字段序列的最大允许大小。此限制适用于名称和值序列的压缩和未压缩表示形式：

builder.WebHost.ConfigureKestrel(serverOptions =>
{
    serverOptions.Limits.Http2.MaxRequestHeaderFieldSize = 8192;
});

初始连接窗口大小

InitialConnectionWindowSize 表示服务器一次愿意接收和缓冲多少请求正文数据，这些数据在每个连接的所有请求（流）中汇总：

builder.WebHost.ConfigureKestrel(serverOptions =>
{
    serverOptions.Limits.Http2.InitialConnectionWindowSize = 131_072;
});

请求也受 InitialStreamWindowSize 限制。

初始流窗口大小

InitialStreamWindowSize 表示服务器愿意为每个流一次接收和缓冲多少请求正文数据：

builder.WebHost.ConfigureKestrel(serverOptions =>
{
    serverOptions.Limits.Http2.InitialStreamWindowSize = 98_304;
});

请求也受 InitialConnectionWindowSize 限制。