gRPC调用链路中出现UNAVAILABLE: io exception是一个高频且容易被误诊的问题。它通常表现为服务运行一段时间后，某些请求突然失败，日志里能看到类似io.grpc.StatusRuntimeException: UNAVAILABLE: io exception的堆栈，而过一会儿又自行恢复。这种间歇性失败大多不是服务真的不可用，而是底层TCP连接出了状况：连接被负载均衡器、NAT网关或者防火墙静默回收，客户端却还拿着一条已经死掉的连接继续发请求。解决思路主要有两条：一是通过Keepalive机制让连接保持活跃并及时探活，二是配合合理的重试策略兜底。
一、先搞清楚UNAVAILABLE到底意味着什么
gRPC的状态码语义里，UNAVAILABLE表示服务当前不可达，通常由网络层故障引起，而不是业务逻辑错误。触发这个状态码的场景包括：TCP连接被对端重置（收到RST包）、连接建立失败、正在使用的连接中途断开、以及底层抛出的IOException被gRPC框架包装后上抛。
一个典型的坑是这样的：客户端与服务端之间隔着防火墙或NAT设备，这些中间设备为了节省资源，会把空闲超过一定时间（常见的是几分钟到一小时不等）的会话表项直接清掉，并且不会通知两端。之后客户端再复用这条连接发请求，数据包发出去要么石沉大海，要么收到RST，gRPC就会抛出UNAVAILABLE。这就是为什么问题往往在低峰期或者业务空闲时段集中出现。
另一个常见诱因是HTTP/2的GOAWAY帧。服务端（尤其是经过了七层负载均衡器如Nginx、Envoy时）会主动关闭长时间存活或超过最大请求数的连接，先发GOAWAY再断开。如果客户端没有及时感知并新建连接，正处于传输中的请求就会失败。理解了这些成因，就能明白为什么单纯的try-catch重跑不能根治问题，必须从连接层面入手。
二、配置Keepalive：让连接活着，也让连接被探活
gRPC的Keepalive基于HTTP/2 PING帧实现，和TCP自带的keepalive不是一回事。客户端周期性发送PING，服务端应答PONG，这样既刷新了中间设备的会话表，又能在对端无响应时快速判定连接失效，触发重连。Java客户端的核心配置如下：
ManagedChannel channel = NettyChannelBuilder.forAddress("127.0.0.1", 9090)
// 客户端每30秒发一次PING探活
.keepAliveTime(30, TimeUnit.SECONDS)
// 发出PING后等待10秒没收到PONG就判定连接失效
.keepAliveTimeout(10, TimeUnit.SECONDS)
// 没有正在进行的请求时也允许发送PING
.permitKeepAliveWithoutCalls(true)
// 服务端允许的最小PING间隔，需小于等于服务端配置
.permitKeepAliveTime(20, TimeUnit.SECONDS)
.enableRetry()
.build();
Go语言的写法类似，通过grpc.WithKeepaliveParams设置：
conn, err := grpc.Dial("127.0.0.1:9090",
grpc.WithTransportCredentials(insecure.NewCredentials()),
grpc.WithKeepaliveParams(keepalive.ClientParameters{
Time: 30 * time.Second, // 探活间隔
Timeout: 10 * time.Second, // 探活超时
PermitWithoutStream: true, // 空闲时也发送PING
}),
)
这里有几个细节值得注意。第一，服务端默认会限制客户端PING的最小间隔（Go默认5分钟，可通过grpc.KeepaliveEnforcementPolicy调整），客户端PING得太频繁会被服务端以GOAWAY断开，反而加重问题。所以服务端也要显式配置，给客户端放行：
s := grpc.NewServer(
grpc.KeepaliveEnforcementPolicy(keepalive.EnforcementPolicy{
MinTime: 10 * time.Second, // 允许客户端最快每10秒PING一次
PermitWithoutStream: true,
}),
grpc.KeepaliveParams(keepalive.ServerParameters{
Time: 60 * time.Second, // 服务端主动探活间隔
Timeout: 20 * time.Second, // 超时后关闭连接
}),
)
第二，Keepalive间隔的取值要结合链路上的中间设备来定。如果中间是云厂商的NLB，空闲超时一般是350秒左右，Keepalive设置在30到60秒通常足够安全；如果是自建防火墙且超时时间更短，需要相应调小。原则是Keepalive间隔必须明显小于链路上最短的空闲超时时间，留足余量。
三、重试策略：给失败的请求一个兜底
Keepalive能大幅降低故障概率，但网络抖动、服务端发布重启仍然会造成瞬时不可用，重试是最后一道防线。gRPC内置了透明重试（对发送前连接失败且服务端未处理的请求自动重试一次）和服务配置重试两种机制。服务配置重试需要在服务端下发或客户端硬编码retry policy，Java客户端启用方式如下：
String retryConfig = "{\"methodConfig\":[{\"name\":[{\"service\":\"com.demo.OrderService\"}],"
+ "\"retryPolicy\":{\"maxAttempts\":3,"
+ "\"initialBackoff\":\"0.2s\",\"maxBackoff\":\"2s\",\"backoffMultiplier\":1.5,"
+ "\"retryableStatusCodes\":[\"UNAVAILABLE\"]}}]}";
ManagedChannel channel = NettyChannelBuilder.forAddress("127.0.0.1", 9090)
.defaultServiceConfig(JsonParser.parseString(retryConfig))
.enableRetry()
.build();
Go语言需要借助grpc.WithDefaultServiceConfig，写法类似。这里的关键点是retryableStatusCodes只应包含UNAVAILABLE，不要把INTERNAL、UNKNOWN这类可能代表业务或程序错误的码加进去，否则容易把同一个写操作重复执行造成脏数据。
这就引出重试必须面对的幂等问题。UNAVAILABLE存在模糊性：请求可能根本没被服务端处理，也可能已经处理完只是响应回不来。对于查询类接口，重试毫无风险；但对于下单、扣款这类写操作，盲目重试可能造成重复下单。稳妥的做法是在业务层引入幂等键（Idempotency Key），客户端生成唯一ID随请求携带，服务端根据该键去重。此外，重试务必搭配指数退避和抖动，避免服务端刚重启就被重试流量打出二次雪崩。重试次数建议控制在2到3次，总耗时要有上限，否则会拖垮上层调用的响应时间。
四、验证与排障建议
配置完成后，可以通过抓包确认Keepalive是否生效：在客户端机器上执行tcpdump -i any port 9090 -nn，正常情况下每隔Keepalive时间就能看到HTTP/2 PING/PONG帧（TYPE为0x6的帧）。如果看不到PING，多半是配置没生效或者客户端构建Channel的方式不对，比如用了过时的构建API。
如果问题依旧，建议按顺序排查：确认服务端是否因为PING过频回了GOAWAY（服务端日志会有too_many_pings相关记录）；检查中间链路的空闲超时配置，必要时让运维调大；确认客户端有没有禁用重连或者复用了已经shutdown的Channel；对经过Envoy或Nginx的场景，检查其HTTP/2的max_concurrent_streams和连接 draining 配置。最后，生产环境建议同时开启gRPC的健康检查服务（HealthChecking），让客户端在重连后先探健康再切流量，整体链路会更加健壮。
gRPC UNAVAILABLEKeepalivegRPC重试策略修改时间：2026-09-03 07:34:41