密钥轮换后的连接池失效处理:Java HttpClient连接重建最佳实践

文章导读
密钥轮换(证书或 JWT 签名密钥)后,服务端会停止信任旧密钥对应的 TLS 会话或认证状态。但客户端这边,HttpClient 连接池中的连接不会自动感知这一点,已经复用的连接会继续发请求,直到收到异常或超时。这里记录一下我清理连接池时用到的判断方法和操作顺序,供遇到类似问题的同学参考。
📋 目录
  1. Ⅰ 判断连接池是否真的失效
  2. Ⅱ 重建连接池的操作路径
  3. Ⅲ 重建时的压力边界
  4. Ⅳ 验证连接是否真的重建了
  5. Ⅴ 容易忽略的两个坑
A A

密钥轮换(证书或 JWT 签名密钥)后,服务端会停止信任旧密钥对应的 TLS 会话或认证状态。但客户端这边,HttpClient 连接池中的连接不会自动感知这一点,已经复用的连接会继续发请求,直到收到异常或超时。这里记录一下我清理连接池时用到的判断方法和操作顺序,供遇到类似问题的同学参考。

判断连接池是否真的失效

密钥轮换后,连接池中的连接不会自动感知服务端证书或密钥的变化。已建立的 TLS 会话在客户端侧的状态仍然是可复用,但服务端可能已经停止信任该会话对应的密钥。典型的判断依据是:密钥轮换后的首个请求收到非预期的 401 或 403,或出现 TLS 握手异常,而同密钥轮换前的请求完全正常。另一种情况是连接被服务端重置,日志里能看到 Connection reset 或 SSLHandshakeException。但不能仅凭响应码判断,因为有些服务会将旧密钥连接静默断开,表现为超时。所以需要结合服务端轮换时间点来排查。

这里要注意,不能用响应码一票定论。如果服务端在轮换后立即关闭了旧连接,那客户端会收到 Connection reset;但如果服务端只是对旧密钥的请求拒绝,连接本身还保持,则可能是 401/403。更麻烦的是某些网关会静默丢弃,表现为超时。所以第一步是确认服务端轮换的时间点,并把客户端日志和这个时间点对齐。如果轮换前后都有正常请求,只有指定时间后的请求异常,那基本可以判断是连接池里的旧连接导致。

重建连接池的操作路径

最简单可靠的重建方式是让连接池整体失效。对于 Apache HttpClient,可以在密钥轮换完成后调用 PoolingHttpClientConnectionManager.closeIdleConnections(0, TimeUnit.MILLISECONDS),将空闲连接全部关闭,同时调用 closeExpiredConnections() 清理过期连接。如果活跃连接中还可能持有旧证书,需要调用 closeLeasedConnections(),但它依赖连接管理器内部跟踪,且会中断正在使用的连接,应当先停止接收新请求或等待租约归还。对于 Java 11 内置的 HttpClient,直接重新创建 HttpClient 实例并替换引用即可,因为旧实例的内部连接池无法单独清空。

以 Apache HttpClient 为例,常见写法是在轮换通知里调用连接管理器清理空闲连接:

密钥轮换后的连接池失效处理:Java HttpClient连接重建最佳实践
PoolingHttpClientConnectionManager cm = httpClient.getConnectionManager();
cm.closeIdleConnections(0, TimeUnit.MILLISECONDS);
cm.closeExpiredConnections();

这里 closeIdleConnections(0, ...) 表示把所有空闲连接立即关闭。如果连接池中还有正在使用的连接(即被租约占用的连接),但那些连接可能也持有旧证书,此时可以调用 closeLeasedConnections()。这个方法会中断活跃请求,所以必须在确认没有新请求进来或已经拿到服务端允许中断的窗口时再调用。更稳妥的方式是先用一个 boolean 开关停止从 HttpClient 获取新连接,然后等活跃请求自然结束,最后再清理。如果用的是 Java 11 自带的 java.net.http.HttpClient,没有暴露连接池操作接口,最简单的办法就是持有当前实例的原子引用,轮换后替换成新实例:

private volatile HttpClient httpClient = HttpClient.newBuilder()
        .connectTimeout(Duration.ofSeconds(10))
        .build();

// 密钥轮换后调用
httpClient = HttpClient.newBuilder()
        .connectTimeout(Duration.ofSeconds(10))
        .build();

旧实例如果不再被引用,内部的连接池会随对象一起回收。但这里有个关键点:替换引用前一定要确保所有业务代码都通过这个 volatile 引用获取 HttpClient,不要有人把旧实例缓存到局部变量里。否则旧连接还是会被用到。另外,如果 HttpClient 上有自定义的 Cookie 或认证头,新实例也需要重新设置,不能只换连接池。

重建时的压力边界

连接重建不能盲目暴力。如果在密钥轮换的一瞬间清空整个连接池,所有并发请求会同时触发新连接建立,可能造成服务端瞬时压力,尤其在 TPS 较高时形成连接风暴。合理做法是先通过连接管理器统计空闲连接数,然后在低峰期或轮换完成后分片清理,比如每次关闭一半空闲连接,等待新连接建立成功后再清理下一批。此外,连接池重建不等同于应用重启,HttpClient 实例上的配置、超时、重试策略等都应保留,避免在重建过程中覆盖这些参数。

所以在实际执行时,建议先查看连接池的空闲连接数。Apache HttpClient 的 PoolingHttpClientConnectionManager 有 getTotalStats() 方法,返回可用的连接统计。可以配合一个定时任务或者手动脚本,在轮换后的低峰期分批关闭。例如:

密钥轮换后的连接池失效处理:Java HttpClient连接重建最佳实践
PoolStats stats = cm.getTotalStats();
int idleToClose = stats.getAvailable() / 2;
cm.closeIdleConnections(0, TimeUnit.MILLISECONDS);

但这个示例只看总数,没有区分到底是空闲还是已分配。更细的做法是循环调用,每次关闭一部分,等待几秒让新连接建立,再继续。注意不要只依赖数字,因为关闭后新连接可能立刻被占满,所以还要观察请求错误率。如果发现重建过程中大量请求失败,要停止分批清理,等整体负载下降后再操作。

验证连接是否真的重建了

关闭连接后,不能只看请求恢复就说成功了。要确认新连接确实用了新密钥。对于 Apache HttpClient,可以检查连接管理器统计,观察空闲数是否降为零,然后发起新请求后已分配数增加。对于 Java 11 HttpClient,可以通过调试参数 javax.net.debug=ssl 来观察握手过程中的证书信息,但生产环境开启会打印大量日志,建议只在测试环境或临时开启。更直接的验证方式是用一个只有新密钥才能访问的测试接口,如果新连接能正常通过,说明连接重建成功。如果服务端只信任新证书,而新连接还是用的旧证书,那问题就不在连接池,而在客户端的密钥加载逻辑。

容易忽略的两个坑

清理连接池时,最常见的坑是只调用 closeExpiredConnections()。这个方法只会关闭超过 validateAfterInactivity 配置或系统默认过期时间的连接,而密钥轮换后,很多连接在客户端眼里还没过期,所以不会真正释放。另一个坑是,如果客户端在复用连接时不会重新走 TLS 握手,那么服务端就算用新密钥校验旧连接上的认证头,也只会拒绝当前请求,而连接本身仍然被保留,导致下一个请求继续复用,连续失败。这种情况必须显式清空连接池,而不能等待自然失效。

最后,连接池重建不是一次性的,如果服务端有定期轮换策略,建议把连接池清理动作挂到轮换通知的消费者里,而不是靠人工在出问题时再执行。同时,HttpClient 上的超时、重试、连接池大小等配置不应该在重建时被覆盖,最好把构建 HttpClient 实例的代码收敛到一个方法里,方便统一管理和复用。