在 YARP 反向代理中集成 Lets Encrypt 实现自动 HTTPSTLS 终结实战指南【免费下载链接】reverse-proxyA toolkit for developing high-performance HTTP reverse proxy applications.项目地址: https://gitcode.com/GitHub_Trending/re/reverse-proxy导读本指南基于仓库中的samples/ReverseProxy.LetsEncrypt.Sample示例讲解如何让 YARP 反向代理在面向客户端的一侧自动完成 TLS 终结TLS Termination通过集成开源的 LettuceEncrypt 库接入 Lets Encrypt 证书颁发机构CA以极少的配置即可为代理免费申请、续期 HTTPS 证书。读完本文你将掌握AddLettuceEncrypt()的注册方式、Kestrel 的 80/443 双端点配置、LettuceEncrypt 必需选项域名、邮箱、服务条款的含义以及 YARP 路由/集群如何与之协同工作并能够直接复刻出一套无需手动管理证书的 HTTPS 反向代理。一、为什么需要给 YARP 加一层自动 HTTPSYARPYet Another Reverse Proxy本质上是 ASP.NET Core 的一个组件代理服务器本身由 Kestrel 等 ASP.NET Core 服务器监听入站请求YARP 负责把请求按路由转发到后端的 destination。因此HTTPS 终结发生在 YARP 之前——即客户端与 YARP 之间的链路使用 HTTPS而 YARP 与后端之间可以使用 HTTP 或 HTTPS。按常规做法运维人员需要自己向 CA 购买/申请证书、定时续期、把证书文件挂载到 Kestrel 端点非常繁琐。该示例给出的方案是通过 LettuceEncrypt 库与 Lets Encrypt 集成。如示例文档所述Lets Encrypt 是一个免费提供 HTTPSSSL/TLS证书的证书颁发机构而本例展示了如何在 YARP 中以最小的配置实现客户端与 YARP 之间的 TLS 设置。整个示例只包含三块内容对应 samples/ReverseProxy.LetsEncrypt.Sample 目录Program.cs在服务注册阶段调用IServiceCollection.AddLettuceEncryptappsettings.json为 LettuceEncrypt 配置必需选项并同时配置 Kestrel 监听端点与 YARP 的 ReverseProxy 路由/集群ReverseProxy.LetsEncrypt.Sample.csproj通过 NuGet 引入 LettuceEncrypt 包。二、Program.cs三行注册开启自动证书示例的入口文件 Program.cs 完整代码如下已略去许可证头注释using Microsoft.AspNetCore.Builder; using Microsoft.Extensions.DependencyInjection; var builder WebApplication.CreateBuilder(args); builder.Services.AddLettuceEncrypt(); builder.Services.AddControllers(); // Add the reverse proxy capability to the server builder.Services.AddReverseProxy() // Initialize the reverse proxy from the ReverseProxy section of configuration .LoadFromConfig(builder.Configuration.GetSection(ReverseProxy)); var app builder.Build(); // Register the reverse proxy routes app.MapReverseProxy(); app.Run();关键点逐一拆解builder.Services.AddLettuceEncrypt()这是整个示例的核心。它为 ASP.NET Core 的 Kestrel 服务器接入 LettuceEncrypt使 Kestrel 的 HTTPS 端点能够在启动时自动向 Lets Encrypt 申请证书并在证书临近过期时自动续期。开发者无需在代码里接触 ACME 协议细节也无需手工放置.pfx证书文件。builder.Services.AddReverseProxy()将 YARP 反向代理能力注册进服务容器这与 BasicYarpSample 中的用法完全一致。.LoadFromConfig(builder.Configuration.GetSection(ReverseProxy))从配置文件appsettings.json的ReverseProxy节点加载路由与集群定义。app.MapReverseProxy()把 YARP 的路由注册进 ASP.NET Core 路由表让 Kestrel 收到的、与路由匹配的请求交给 YARP 转发处理。可以看到相比普通的 YARP 宿主程序这里唯一的差异就是多了一行AddLettuceEncrypt()其余都是 YARP 标准的三步式接入AddReverseProxy → LoadFromConfig → MapReverseProxy。三、appsettings.jsonKestrel 端点 LettuceEncrypt 选项 YARP 路由完整的 appsettings.json 包含三大部分分别对应 Kestrel 监听、Lets Encrypt 证书与 YARP 转发配置{ Kestrel: { Endpoints: { Http: { Url: http://*:80 }, Https: { Url: https://*:443 } } }, Logging: { LogLevel: { Default: Information, Microsoft: Information, Microsoft.Hosting.Lifetime: Information } }, AllowedHosts: *, ReverseProxy: { Routes: { route1: { ClusterId: cluster1, Match: { Path: {**catch-all} } } }, Clusters: { cluster1: { Destinations: { destination1: { Address: https://example.com/ } } } } }, LettuceEncrypt: { AcceptTermsOfService: true, DomainNames: [ example.com ], EmailAddress: it-adminexample.com } }3.1 Kestrel 端点让 80 与 443 同时监听Kestrel: { Endpoints: { Http: { Url: http://*:80 }, Https: { Url: https://*:443 } } }http://*:80提供 HTTP 监听。不要轻易移除它Lets Encrypt 默认使用 HTTP-01 挑战方式验证域名所有权CA 会通过 80 端口回访http://domain/.well-known/acme-challenge/...因此 80 端口必须可达且由当前进程监听。https://*:443提供 HTTPS 监听。LettuceEncrypt 会为这个端点自动装载申请到的证书。3.2 LettuceEncrypt 选项三个必需项LettuceEncrypt: { AcceptTermsOfService: true, DomainNames: [ example.com ], EmailAddress: it-adminexample.com }配置项类型是否必需含义与说明DomainNames字符串数组必需至少一个需要签发证书的域名列表。示例文档明确要求 at least one domain name is required。证书会覆盖这些域名因此域名必须已解析到本机公网 IP否则 ACME 验证无法通过。EmailAddress字符串必需用于向证书颁发机构注册的邮箱地址。示例文档要求 email address must be specified to register with the certificate authority。CA 会用该邮箱联系证书持有人例如证书即将过期提醒。AcceptTermsOfService布尔建议显式设置是否自动接受证书颁发机构的服务条款。配置注释说明得很清楚若不设置此项应用每次启动时都会要求你在控制台按y确认设置为true后可在无人值守环境容器、CI/CD中直接启动。这三项中DomainNames与EmailAddress是硬性必需项缺一不可AcceptTermsOfService关系到能否自动化运行。3.3 ReverseProxy 节点YARP 的转发目标示例沿用了 YARP 标准配置结构Routes.route1Match.Path为{**catch-all}即匹配所有路径的兜底路由绑定到cluster1Clusters.cluster1包含单个 destination地址为https://example.com/。在真实部署中应把Address替换为你的实际后端服务地址。如 BasicYarpSample/README.md 所强调的示例刻意使用 DNS 名称以便开箱即跑生产环境应写成带协议、IP 与端口的完整地址例如https://123.4.5.6:7890。四、项目文件与版本LettuceEncrypt 依赖从何而来ReverseProxy.LetsEncrypt.Sample.csproj 揭示了依赖关系Project SdkMicrosoft.NET.Sdk.Web PropertyGroup TargetFrameworks$(ReleaseTFMs)/TargetFrameworks LangVersionlatest/LangVersion /PropertyGroup ItemGroup PackageReference IncludeLettuceEncrypt Version$(LettuceEncryptVersion) / /ItemGroup ItemGroup ProjectReference Include..\..\src\ReverseProxy\Yarp.ReverseProxy.csproj / /ItemGroup /Project两点值得注意版本集中管理LettuceEncrypt的版本号不是写死的而是引用 MSBuild 属性$(LettuceEncryptVersion)。该属性定义在仓库根目录的 eng/Versions.props 中当前为1.3.0。这种集中管理的方式保证了仓库内各项目依赖版本的一致性。本地引用 YARP 源码通过ProjectReference直接引用 src/ReverseProxy/Yarp.ReverseProxy.csproj说明该示例是在仓库内与 YARP 源码一起构建的如果你要基于 NuGet 使用则改为引用Yarp.ReverseProxy包即可其余逻辑不变。五、运行与验证运行步骤确保已安装与仓库 global.json 指定版本匹配的 .NET SDK在仓库根目录执行dotnet run --project samples/ReverseProxy.LetsEncrypt.Sample程序启动时LettuceEncrypt 会读取配置中的域名向 Lets Encrypt 发起 ACME 注册与证书签发流程此过程需要公网可达、80 端口开放、域名 DNS 已解析证书签发成功后Kestrel 的 443 端点即启用 HTTPS。验证要点浏览器访问https://你的域名地址栏应显示有效证书不再有自签名告警证书到期前 LettuceEncrypt 会自动续期无需人工干预注意 Properties/launchSettings.json 中ASPNETCORE_ENVIRONMENT为Development本地调试时同样适用这套配置。六、工作原理一次 HTTPS 请求的完整链路结合源码与配置可以梳理出整体数据流客户端发起https://domain/...请求命中 Kestrel 的Https端点443Kestrel 使用 LettuceEncrypt 自动装载的 Lets Encrypt 证书完成 TLS 握手TLS 终结发生在 YARP 之前请求进入 ASP.NET Core 管道由MapReverseProxy()注册的 YARP 路由匹配本例为{**catch-all}兜底路由YARP 依据Routes.route1找到cluster1按负载均衡策略选出 destination本例仅一个https://example.com/请求被转发到后端后端响应再原路返回给客户端。在启动阶段LettuceEncrypt 还会处理两件看不见的事向 CA 注册邮箱对应的账户、验证域名所有权默认 HTTP-01 挑战这正解释了为何必须保留 80 端口端点、保存证书用于启动加载以及在证书接近过期时自动续期。七、注意事项与生产化建议结合示例配置注释与 YARP 使用习惯实践时需注意80 端口是自动签发的必要条件LettuceEncrypt 的 ACME HTTP-01 验证依赖 80 端口回访若网络环境中 80 端口不可达证书签发会失败。若你的架构只有 443 可用则需要改用其他验证方式如 TLS-ALPN-01 / DNS 验证需按 LettuceEncrypt 库的能力另行配置示例未涉及。域名必须真实指向本机DomainNames中的域名若未解析到运行实例的公网地址CA 无法完成验证示例配置中的example.com仅为演示必须替换为你自己的域名。邮箱与条款EmailAddress用于 CA 账户注册首次运行务必处理好AcceptTermsOfService否则交互式确认会阻塞自动化启动。后端仍可走 HTTPS示例中 destination 地址为https://example.com/说明 YARP 到后端的出站链路可以独立配置 TLS示例解决的是入站 TLS 终结这一环出站证书的管理属于另一套机制YARP 的 HttpClientConfig 与证书验证相关配置。证书选择与 SNI对于多域名、多证书的高级场景可参考仓库中 Kubernetes.Controller/Certificates 模块的CertificateHelper.cs、ServerCertificateSelector.cs等实现了解 YARP 在 Kubernetes 场景下如何按 SNI 选择服务器证书——这展示了 YARP 证书能力的延伸边界但本例的 LettuceEncrypt 集成并不需要这些。八、继续深入完整示例代码samples/ReverseProxy.LetsEncrypt.Sample无 TLS 的最小 YARP 示例对照samples/BasicYarpSample其中 README.md 说明了 YARP 路由→集群→destination 的基础转发模型YARP 核心库src/ReverseProxy其中 Yarp.ReverseProxy.csproj 是库的项目入口Configuration/HttpClientConfig.cs 与出站 HTTPS 相关版本集中定义eng/Versions.props含LettuceEncryptVersion证书相关能力延伸src/Kubernetes.Controller/Certificates本示例证明在 YARP 中启用生产级 HTTPS只需要引入一个 NuGet 包、调用一行AddLettuceEncrypt()、并在配置里填好域名与邮箱——自动申请、自动装载、自动续期的完整链路即告完成这正是以最小配置实现客户端与 YARP 之间 TLS的落地范本。【免费下载链接】reverse-proxyA toolkit for developing high-performance HTTP reverse proxy applications.项目地址: https://gitcode.com/GitHub_Trending/re/reverse-proxy创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
在 YARP 反向代理中集成 Let‘s Encrypt 实现自动 HTTPS（TLS 终结）实战指南
在 YARP 反向代理中集成 Lets Encrypt 实现自动 HTTPSTLS 终结实战指南【免费下载链接】reverse-proxyA toolkit for developing high-performance HTTP reverse proxy applications.项目地址: https://gitcode.com/GitHub_Trending/re/reverse-proxy导读本指南基于仓库中的samples/ReverseProxy.LetsEncrypt.Sample示例讲解如何让 YARP 反向代理在面向客户端的一侧自动完成 TLS 终结TLS Termination通过集成开源的 LettuceEncrypt 库接入 Lets Encrypt 证书颁发机构CA以极少的配置即可为代理免费申请、续期 HTTPS 证书。读完本文你将掌握AddLettuceEncrypt()的注册方式、Kestrel 的 80/443 双端点配置、LettuceEncrypt 必需选项域名、邮箱、服务条款的含义以及 YARP 路由/集群如何与之协同工作并能够直接复刻出一套无需手动管理证书的 HTTPS 反向代理。一、为什么需要给 YARP 加一层自动 HTTPSYARPYet Another Reverse Proxy本质上是 ASP.NET Core 的一个组件代理服务器本身由 Kestrel 等 ASP.NET Core 服务器监听入站请求YARP 负责把请求按路由转发到后端的 destination。因此HTTPS 终结发生在 YARP 之前——即客户端与 YARP 之间的链路使用 HTTPS而 YARP 与后端之间可以使用 HTTP 或 HTTPS。按常规做法运维人员需要自己向 CA 购买/申请证书、定时续期、把证书文件挂载到 Kestrel 端点非常繁琐。该示例给出的方案是通过 LettuceEncrypt 库与 Lets Encrypt 集成。如示例文档所述Lets Encrypt 是一个免费提供 HTTPSSSL/TLS证书的证书颁发机构而本例展示了如何在 YARP 中以最小的配置实现客户端与 YARP 之间的 TLS 设置。整个示例只包含三块内容对应 samples/ReverseProxy.LetsEncrypt.Sample 目录Program.cs在服务注册阶段调用IServiceCollection.AddLettuceEncryptappsettings.json为 LettuceEncrypt 配置必需选项并同时配置 Kestrel 监听端点与 YARP 的 ReverseProxy 路由/集群ReverseProxy.LetsEncrypt.Sample.csproj通过 NuGet 引入 LettuceEncrypt 包。二、Program.cs三行注册开启自动证书示例的入口文件 Program.cs 完整代码如下已略去许可证头注释using Microsoft.AspNetCore.Builder; using Microsoft.Extensions.DependencyInjection; var builder WebApplication.CreateBuilder(args); builder.Services.AddLettuceEncrypt(); builder.Services.AddControllers(); // Add the reverse proxy capability to the server builder.Services.AddReverseProxy() // Initialize the reverse proxy from the ReverseProxy section of configuration .LoadFromConfig(builder.Configuration.GetSection(ReverseProxy)); var app builder.Build(); // Register the reverse proxy routes app.MapReverseProxy(); app.Run();关键点逐一拆解builder.Services.AddLettuceEncrypt()这是整个示例的核心。它为 ASP.NET Core 的 Kestrel 服务器接入 LettuceEncrypt使 Kestrel 的 HTTPS 端点能够在启动时自动向 Lets Encrypt 申请证书并在证书临近过期时自动续期。开发者无需在代码里接触 ACME 协议细节也无需手工放置.pfx证书文件。builder.Services.AddReverseProxy()将 YARP 反向代理能力注册进服务容器这与 BasicYarpSample 中的用法完全一致。.LoadFromConfig(builder.Configuration.GetSection(ReverseProxy))从配置文件appsettings.json的ReverseProxy节点加载路由与集群定义。app.MapReverseProxy()把 YARP 的路由注册进 ASP.NET Core 路由表让 Kestrel 收到的、与路由匹配的请求交给 YARP 转发处理。可以看到相比普通的 YARP 宿主程序这里唯一的差异就是多了一行AddLettuceEncrypt()其余都是 YARP 标准的三步式接入AddReverseProxy → LoadFromConfig → MapReverseProxy。三、appsettings.jsonKestrel 端点 LettuceEncrypt 选项 YARP 路由完整的 appsettings.json 包含三大部分分别对应 Kestrel 监听、Lets Encrypt 证书与 YARP 转发配置{ Kestrel: { Endpoints: { Http: { Url: http://*:80 }, Https: { Url: https://*:443 } } }, Logging: { LogLevel: { Default: Information, Microsoft: Information, Microsoft.Hosting.Lifetime: Information } }, AllowedHosts: *, ReverseProxy: { Routes: { route1: { ClusterId: cluster1, Match: { Path: {**catch-all} } } }, Clusters: { cluster1: { Destinations: { destination1: { Address: https://example.com/ } } } } }, LettuceEncrypt: { AcceptTermsOfService: true, DomainNames: [ example.com ], EmailAddress: it-adminexample.com } }3.1 Kestrel 端点让 80 与 443 同时监听Kestrel: { Endpoints: { Http: { Url: http://*:80 }, Https: { Url: https://*:443 } } }http://*:80提供 HTTP 监听。不要轻易移除它Lets Encrypt 默认使用 HTTP-01 挑战方式验证域名所有权CA 会通过 80 端口回访http://domain/.well-known/acme-challenge/...因此 80 端口必须可达且由当前进程监听。https://*:443提供 HTTPS 监听。LettuceEncrypt 会为这个端点自动装载申请到的证书。3.2 LettuceEncrypt 选项三个必需项LettuceEncrypt: { AcceptTermsOfService: true, DomainNames: [ example.com ], EmailAddress: it-adminexample.com }配置项类型是否必需含义与说明DomainNames字符串数组必需至少一个需要签发证书的域名列表。示例文档明确要求 at least one domain name is required。证书会覆盖这些域名因此域名必须已解析到本机公网 IP否则 ACME 验证无法通过。EmailAddress字符串必需用于向证书颁发机构注册的邮箱地址。示例文档要求 email address must be specified to register with the certificate authority。CA 会用该邮箱联系证书持有人例如证书即将过期提醒。AcceptTermsOfService布尔建议显式设置是否自动接受证书颁发机构的服务条款。配置注释说明得很清楚若不设置此项应用每次启动时都会要求你在控制台按y确认设置为true后可在无人值守环境容器、CI/CD中直接启动。这三项中DomainNames与EmailAddress是硬性必需项缺一不可AcceptTermsOfService关系到能否自动化运行。3.3 ReverseProxy 节点YARP 的转发目标示例沿用了 YARP 标准配置结构Routes.route1Match.Path为{**catch-all}即匹配所有路径的兜底路由绑定到cluster1Clusters.cluster1包含单个 destination地址为https://example.com/。在真实部署中应把Address替换为你的实际后端服务地址。如 BasicYarpSample/README.md 所强调的示例刻意使用 DNS 名称以便开箱即跑生产环境应写成带协议、IP 与端口的完整地址例如https://123.4.5.6:7890。四、项目文件与版本LettuceEncrypt 依赖从何而来ReverseProxy.LetsEncrypt.Sample.csproj 揭示了依赖关系Project SdkMicrosoft.NET.Sdk.Web PropertyGroup TargetFrameworks$(ReleaseTFMs)/TargetFrameworks LangVersionlatest/LangVersion /PropertyGroup ItemGroup PackageReference IncludeLettuceEncrypt Version$(LettuceEncryptVersion) / /ItemGroup ItemGroup ProjectReference Include..\..\src\ReverseProxy\Yarp.ReverseProxy.csproj / /ItemGroup /Project两点值得注意版本集中管理LettuceEncrypt的版本号不是写死的而是引用 MSBuild 属性$(LettuceEncryptVersion)。该属性定义在仓库根目录的 eng/Versions.props 中当前为1.3.0。这种集中管理的方式保证了仓库内各项目依赖版本的一致性。本地引用 YARP 源码通过ProjectReference直接引用 src/ReverseProxy/Yarp.ReverseProxy.csproj说明该示例是在仓库内与 YARP 源码一起构建的如果你要基于 NuGet 使用则改为引用Yarp.ReverseProxy包即可其余逻辑不变。五、运行与验证运行步骤确保已安装与仓库 global.json 指定版本匹配的 .NET SDK在仓库根目录执行dotnet run --project samples/ReverseProxy.LetsEncrypt.Sample程序启动时LettuceEncrypt 会读取配置中的域名向 Lets Encrypt 发起 ACME 注册与证书签发流程此过程需要公网可达、80 端口开放、域名 DNS 已解析证书签发成功后Kestrel 的 443 端点即启用 HTTPS。验证要点浏览器访问https://你的域名地址栏应显示有效证书不再有自签名告警证书到期前 LettuceEncrypt 会自动续期无需人工干预注意 Properties/launchSettings.json 中ASPNETCORE_ENVIRONMENT为Development本地调试时同样适用这套配置。六、工作原理一次 HTTPS 请求的完整链路结合源码与配置可以梳理出整体数据流客户端发起https://domain/...请求命中 Kestrel 的Https端点443Kestrel 使用 LettuceEncrypt 自动装载的 Lets Encrypt 证书完成 TLS 握手TLS 终结发生在 YARP 之前请求进入 ASP.NET Core 管道由MapReverseProxy()注册的 YARP 路由匹配本例为{**catch-all}兜底路由YARP 依据Routes.route1找到cluster1按负载均衡策略选出 destination本例仅一个https://example.com/请求被转发到后端后端响应再原路返回给客户端。在启动阶段LettuceEncrypt 还会处理两件看不见的事向 CA 注册邮箱对应的账户、验证域名所有权默认 HTTP-01 挑战这正解释了为何必须保留 80 端口端点、保存证书用于启动加载以及在证书接近过期时自动续期。七、注意事项与生产化建议结合示例配置注释与 YARP 使用习惯实践时需注意80 端口是自动签发的必要条件LettuceEncrypt 的 ACME HTTP-01 验证依赖 80 端口回访若网络环境中 80 端口不可达证书签发会失败。若你的架构只有 443 可用则需要改用其他验证方式如 TLS-ALPN-01 / DNS 验证需按 LettuceEncrypt 库的能力另行配置示例未涉及。域名必须真实指向本机DomainNames中的域名若未解析到运行实例的公网地址CA 无法完成验证示例配置中的example.com仅为演示必须替换为你自己的域名。邮箱与条款EmailAddress用于 CA 账户注册首次运行务必处理好AcceptTermsOfService否则交互式确认会阻塞自动化启动。后端仍可走 HTTPS示例中 destination 地址为https://example.com/说明 YARP 到后端的出站链路可以独立配置 TLS示例解决的是入站 TLS 终结这一环出站证书的管理属于另一套机制YARP 的 HttpClientConfig 与证书验证相关配置。证书选择与 SNI对于多域名、多证书的高级场景可参考仓库中 Kubernetes.Controller/Certificates 模块的CertificateHelper.cs、ServerCertificateSelector.cs等实现了解 YARP 在 Kubernetes 场景下如何按 SNI 选择服务器证书——这展示了 YARP 证书能力的延伸边界但本例的 LettuceEncrypt 集成并不需要这些。八、继续深入完整示例代码samples/ReverseProxy.LetsEncrypt.Sample无 TLS 的最小 YARP 示例对照samples/BasicYarpSample其中 README.md 说明了 YARP 路由→集群→destination 的基础转发模型YARP 核心库src/ReverseProxy其中 Yarp.ReverseProxy.csproj 是库的项目入口Configuration/HttpClientConfig.cs 与出站 HTTPS 相关版本集中定义eng/Versions.props含LettuceEncryptVersion证书相关能力延伸src/Kubernetes.Controller/Certificates本示例证明在 YARP 中启用生产级 HTTPS只需要引入一个 NuGet 包、调用一行AddLettuceEncrypt()、并在配置里填好域名与邮箱——自动申请、自动装载、自动续期的完整链路即告完成这正是以最小配置实现客户端与 YARP 之间 TLS的落地范本。【免费下载链接】reverse-proxyA toolkit for developing high-performance HTTP reverse proxy applications.项目地址: https://gitcode.com/GitHub_Trending/re/reverse-proxy创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考