gRPC客户端retryPolicy在h2c多路复用场景下失效问题排查

核心场景与问题 #

我们生产环境采用Ahmet风格的h2c多路复用方案，在同一TCP端口同时运行gRPC服务器和grpc-gateway（暴露HTTP API）。此前运行正常，但为所有gRPC客户端添加retryPolicy后，该策略完全失效：

• 测试用例：服务器前3次请求返回可重试错误，第4次返回成功
• 现象：客户端首次请求失败后直接终止，无重试触发；Go和Python客户端均存在此问题
• 对比：切换到cmux多路复用方案时，retryPolicy可正常工作

可能的原因与排查方向 #

1. h2c协议升级请求的重试兼容性 #

Ahmet的方案依赖HTTP/1.1到HTTP/2的Upgrade: h2c升级流程，部分gRPC客户端实现对这类升级请求的重试逻辑有特殊限制：

• 部分客户端默认不会重试协议升级类请求，即使配置了retryPolicy，首次升级请求失败后也不会触发重试
• 验证方式：
  • 抓包确认客户端首次失败后是否发送了二次请求
  • 开启客户端gRPC debug日志，查看是否有重试相关的限制提示

2. 多路复用层的错误透传不匹配 #

前置的http.Server可能将gRPC错误转化为了非标准HTTP错误码，导致客户端retryPolicy不匹配：

• 服务器返回的gRPC可重试错误（如UNAVAILABLE）被HTTP层转化为HTTP 502/503等，客户端的retryPolicy只针对gRPC标准错误码，因此不触发重试
• 验证步骤：
  • 服务器端打印返回的gRPC错误码，确认是retryPolicy中配置的类型（如UNAVAILABLE）
  • 客户端捕获错误，检查错误的类型和代码是否与配置匹配

3. h2c连接生命周期的限制 #

h2c需要先完成HTTP/1.1到HTTP/2的升级，才能复用连接发送后续请求：

• 如果首次请求失败时连接尚未完成升级，客户端可能直接判定连接不可用并关闭，不会重试请求
• 对比cmux方案：cmux直接基于流量分流，gRPC请求走原生HTTP/2连接，无需升级流程，重试逻辑可作用于每个请求
• 验证方式：让服务器首次请求成功，确认h2c升级完成后，后续请求的retryPolicy是否正常触发

4. 客户端retryPolicy配置的有效性 #

确认retryPolicy是否正确应用到了h2c客户端连接：

• Go客户端：检查是否为不安全连接（insecure.NewCredentials()）正确配置了grpc.WithDefaultServiceConfig()，且service config的JSON格式无误：

  serviceConfig := `{
    "retryPolicy": {
      "maxAttempts": 4,
      "retryableStatusCodes": ["UNAVAILABLE"]
    }
  }`
  conn, err := grpc.Dial(address, grpc.WithTransportCredentials(insecure.NewCredentials()), grpc.WithDefaultServiceConfig(serviceConfig))
  

• Python客户端：检查是否通过grpc.insecure_channel的options参数正确传递了service config：

  channel = grpc.insecure_channel(
      address,
      options=[
          ("grpc.service_config", '{"retryPolicy": {"maxAttempts": 4, "retryableStatusCodes": ["UNAVAILABLE"]}}')
      ]
  )
  

实操排查步骤 #

1. 抓包分析：用tcpdump或Wireshark捕获流量，确认首次失败后是否有重试请求，以及请求是否为h2c升级类型
2. 日志调试：
   • 服务器端：打印每个请求的连接状态、返回的gRPC错误码
   • 客户端：开启gRPC debug日志（Go：GRPC_GO_LOG_VERBOSITY_LEVEL=99 GRPC_GO_LOG_SEVERITY_LEVEL=info；Python：GRPC_VERBOSITY=debug），查看重试相关日志
3. 最小化测试：
   • 移除grpc-gateway，仅保留h2c gRPC服务器，测试retryPolicy是否生效
   • 修改多路复用逻辑，通过路径前缀直接转发gRPC请求（绕过h2c升级），验证重试是否正常
4. 错误码验证：修改服务器返回的错误码为retryPolicy中明确配置的类型，确认客户端是否触发重试

内容的提问来源于stack exchange，提问作者jdi