在IIS上以OutOfProcess运行ASP.NET Core gRPC服务报502.3错误

OutOfProcess托管模式下，IIS以反向代理形式运行，请求会先进入IIS工作进程（w3wp.exe），再转发到后台独立运行的Kestrel进程处理。和InProcess模式直接在w3wp进程内运行服务逻辑不同，该跨进程转发链路对协议、端口、证书、头信息的要求更高，出现502.3错误的核心原因是IIS无法和后端Kestrel进程建立有效的HTTP/2连接，常见触发场景如下：

• IIS版本低于10，不支持HTTP/2协议转发，无法兼容gRPC的底层协议要求
• Kestrel未显式配置HTTP/2协议支持，或监听的端口、证书配置和IIS转发规则不匹配
• 未配置转发头中间件，Kestrel拒绝处理来自IIS反向代理的请求
• IIS请求过滤规则拦截了gRPC依赖的Trailer响应头，导致链路中断
• Kestrel进程启动失败（端口占用、证书不可信、依赖缺失等），IIS无法将请求转发到有效节点

• 确认IIS版本符合要求
  必须使用Windows Server 2016/Windows 10及以上系统自带的IIS 10及以上版本，低版本IIS不支持HTTP/2，无法托管gRPC服务的OutOfProcess模式。
• 显式配置Kestrel的协议与监听规则
  在Program.cs中显式指定Kestrel开启HTTP/2支持，生产环境配置和IIS站点绑定一致的可信证书：

  using Microsoft.AspNetCore.Server.Kestrel.Core;
  
  var builder = WebApplication.CreateBuilder(args);
  
  builder.WebHost.UseKestrel(options =>
  {
      // 若无需固定端口可省略Listen配置，Kestrel会自动使用ASPNETCORE_PORT环境变量指定的端口（由IIS自动传递）
      options.ListenAnyIP(0, listenOptions =>
      {
          listenOptions.Protocols = HttpProtocols.Http2;
          // 生产环境替换为实际证书路径和密码
          listenOptions.UseHttps("grpc-cert.pfx", "your-cert-password");
      });
  });
  

• 配置转发头中间件
  在所有中间件注册之前添加转发头配置，信任来自IIS的代理请求：

  var app = builder.Build();
  
  // 必须放在所有中间件的最前面
  app.UseForwardedHeaders(new ForwardedHeadersOptions
  {
      ForwardedHeaders = Microsoft.AspNetCore.HttpOverrides.ForwardedHeaders.XForwardedFor | Microsoft.AspNetCore.HttpOverrides.ForwardedHeaders.XForwardedProto
  });
  
  // 后续注册gRPC等其他中间件
  app.MapGrpcService<YourGrpcServiceImpl>();
  

• 修正web.config配置
  确保使用AspNetCoreModuleV2托管，开启gRPC所需的头放行规则，示例配置如下：

  <?xml version="1.0" encoding="utf-8"?>
  <configuration>
    <location path="." inheritInChildApplications="false">
      <system.webServer>
        <handlers>
          <add name="aspNetCore" path="*" verb="*" modules="AspNetCoreModuleV2" resourceType="Unspecified" />
        </handlers>
        <aspNetCore processPath="dotnet" arguments=".\你的gRPC服务程序集名.dll" hostingModel="OutOfProcess" stdoutLogEnabled="false" stdoutLogFile=".\logs\stdout" />
        <security>
          <requestFiltering allowUnlistedHeaders="true">
            <requestLimits maxAllowedContentLength="4294967295" />
          </requestFiltering>
        </security>
      </system.webServer>
    </location>
  </configuration>
  

• 日志排查定位具体问题
  若以上配置后仍报错，将web.config中stdoutLogEnabled设为true，在服务根目录创建logs文件夹，重启站点后查看生成的日志，可直接定位Kestrel启动失败、证书无效、端口占用等具体错误原因。

内容的提问来源于stack exchange，提问作者Hadi Fooladi Talari