分享一个APISIX网关返回502的典型案例

分享一个APISIX网关返回502的典型案例

💡 原文中文,约1500字,阅读约需4分钟。
📝

内容提要

APISIX网关默认keepalive会话保持60秒,而上游Gunicorn+FastAPI服务keepalive仅5秒,导致上游先关闭连接,网关复用旧连接转发请求时报502。解决办法是将上游keepalive超时设为60秒以上,或关闭网关keepalive;作者选择前者后问题消失,并建议业务运维注意此典型问题。

🔎

延伸解读

keepalive 超时错配是 502 的根因

APISIX 默认保持连接 60 秒,而上游 Gunicorn+FastAPI 默认仅 5 秒。上游先关闭空闲连接后,网关仍复用旧连接转发新请求,导致读取响应头时连接已被关闭,从而返回 502。这种超时不一致是反向代理场景下的典型问题,Nginx 等同样存在。

两种修复思路的取舍

文章给出两种方案:关闭网关 keepalive,或让上游 keepalive 超时超过 60 秒。作者选择后者,因为保留网关 keepalive 有利于性能。这提示运维人员,在享受连接复用带来的性能收益时,必须确保上下游超时配置匹配,否则会引入隐蔽的 502 错误。

APISIX 不会无条件重试

作者曾向社区反馈为何此场景下 APISIX 不自动重试。社区指出 APISIX 的重试有条件限制,并非无脑重试。这意味着遇到类似 502 时,不能依赖网关自动恢复,而应从连接生命周期配置入手排查,避免误判为偶发故障。

❓

Q&A

APISIX网关返回502,但后端服务日志显示没有收到请求,可能是什么原因?

可能是网关与上游服务的keepalive超时不一致导致的。APISIX默认keepalive会话保持60秒,而上游服务(如Gunicorn+FastAPI)默认keepalive仅5秒,上游先关闭连接后,网关复用旧连接转发请求时就会报502,错误日志通常为“upstream prematurely closed connection while reading response header from upstream”。

如何解决APISIX因keepalive超时不一致导致的502错误?

有两种解决办法:一是关闭网关的keepalive特性;二是将上游服务的keepalive超时时间设置为大于60秒(例如60秒以上)。作者选择了后者,修改后问题不再出现。

APISIX的keepalive默认超时时间是多少?

APISIX默认开启keepalive特性,预设会话保持时长为60秒。

Gunicorn+FastAPI服务的keepalive默认超时时间是多少?

Gunicorn+FastAPI开发框架默认开启keepalive,会话保持默认设置为5秒。

APISIX在遇到上游连接被关闭时会不会自动重试?

APISIX并不会无脑重试,重试是有条件限制的。具体可参考OpenResty和Nginx的相关文档。

除了APISIX,还有哪些场景会出现类似的keepalive超时问题?

这个问题在Nginx等反向代理场景下同样存在,是一个很典型的Case。

🏷️

标签

➡️

继续阅读