ASP.NET Core Web API Docker环境HTTPS访问Swagger报错及配置疑问

你的当前配置属于过度设计——TLS握手回调仅适用于多证书/复杂SNI场景，而你的场景（单证书适配localhost和host.docker.internal）完全可以用更简洁的标准方案解决。

核心问题原因 #

报错“检测到向未启用TLS的端点发起TLS握手”本质是Kestrel未正确绑定HTTPS端点或证书配置缺失，导致TLS握手无法正常触发。你用的TlsHandshakeCallbackOptions是为多域名多证书的复杂场景设计的，而你两个域名共用同一张证书，完全不需要自定义握手逻辑。

简化方案 #

方案1：通过appsettings.json配置（推荐） #

直接在appsettings.json中添加Kestrel端点配置，无需编写复杂代码：

{
  "Kestrel": {
    "Endpoints": {
      "Https": {
        "Url": "https://*:443",
        "Protocols": "Http1AndHttp2",
        "Certificate": {
          "Path": "/root/.aspnet/https/webapi.pfx",
          "Password": "password"
        }
      }
    }
  }
}

Kestrel会自动加载该配置，绑定443端口并启用TLS，自动处理localhost和host.docker.internal的SNI请求（只要证书包含这两个域名的SAN条目）。

方案2：代码简洁配置 #

如果必须通过代码配置，可简化为：

builder.WebHost.ConfigureKestrel(options =>
{
    options.ListenAnyIP(443, listenOptions =>
    {
        listenOptions.Protocols = HttpProtocols.Http1AndHttp2;
        listenOptions.UseHttps("/root/.aspnet/https/webapi.pfx", "password");
    });
});

这段代码直接绑定443端口并启用HTTPS，Kestrel默认逻辑会自动处理TLS握手和SNI匹配，无需自定义回调。

Docker环境补充注意事项 #

• 确保证书文件通过Docker Compose的volumes正确挂载到容器的/root/.aspnet/https/目录
• 开发环境下，可挂载宿主机的ASP.NET Core开发证书（路径通常为~/.aspnet/https/）到容器对应目录
• 证书需包含localhost和host.docker.internal的SAN条目，否则浏览器会出现证书警告（但不影响连接）

内容的提问来源于stack exchange，提问作者Dr. Strangelove