遇到 API 网关鉴权超时返回 504，最直接的止损方式是适当调大网关的上游超时配置，但长期优化必须聚焦在鉴权服务本身的响应速度和缓存策略上。
先说结论：504 错误表明网关在等待鉴权服务响应时超出了预设时间，临时调参可恢复业务，但根治需要降低鉴权耗时。
- 先确认：网关日志中的上游响应耗时是否接近 timeout 阈值
- 先处理：修正网关超时配置单位并排查鉴权服务数据库或网络瓶颈
- 再验证：调整后的请求成功率及鉴权接口 P99 延迟
快速处理思路
不同网关配置方式不同，但核心逻辑一致。以下是常见网关的超时配置位置及单位对照，请根据实际环境修改：
| 网关类型 | 配置项 | 单位 | 示例值 |
|---|---|---|---|
| Nginx | proxy_read_timeout | 秒 (s) | 60s |
| Kong | config.read_timeout | 秒 (s) | 60 |
| APISIX | timeout.read | 秒 (s) | 60s |
# Nginx 示例
proxy_read_timeout 60s;# Kong 网关示例 (Route 配置)
# 注意：Kong 该配置单位为秒，切勿填入毫秒数
config.read_timeout: 60# APISIX 示例 (Upstream 配置)
timeout:read: 60s
注意：修改配置后通常需要重载或热更新，不要直接重启生产服务，避免流量中断。
为什么会这样
HTTP 504 Gateway Timeout 状态码的定义是网关作为代理时，未能及时从上游服务器收到响应。在鉴权场景下，网关通常需要在转发业务请求前，先调用内部的鉴权服务（Auth Service）验证 Token 或签名。
如果鉴权服务因为数据库慢查询、外部依赖超时、Full GC 或网络抖动导致处理时间超过了网关设定的等待时间，网关就会主动断开连接并向客户端返回 504。这通常不是网关本身的问题，而是上游鉴权链路出现了性能瓶颈或不稳定。
分步处理
1. 查看网关访问日志
确认 504 错误发生时的上游响应时间。大多数网关日志会记录 upstream_response_time 或类似字段。
# Nginx 日志示例字段
$upstream_response_time# 快速 grep 查看接近超时的请求 (假设超时阈值为 5 秒)
grep "504" access.log | awk '$10 > 4.9 {print $0}'
如果该时间非常接近你的 timeout 设置，说明确实是超时导致的。
2. 临时调整网关超时配置
根据当前观测到的最大耗时，适当增加超时阈值。例如当前设置为 3 秒，最大耗时达到 2.8 秒，可临时调整为 5 秒或 10 秒。这只是止血手段，防止用户请求被误杀。
3. 排查鉴权服务性能
登录鉴权服务服务器，检查应用监控和数据库慢查询日志。常见原因及排查命令如下：
- 数据库慢查询：检查是否缺少索引，导致查询 Token 有效性时全表扫描。
-- 查看当前正在执行的语句 SHOW PROCESSLIST;-- 查看慢查询日志配置 SHOW VARIABLES LIKE 'slow_query_log'; - 链路过长：鉴权服务调用了其他微服务（如用户信息服务），需梳理调用链。
- 垃圾回收（GC）停顿：检查 JVM 状态。
# 查看 GC 频率和时间 (pid 为进程 ID) jstat -gcutil <pid> 1000
引入网关层缓存
如果使用的是 JWT 等无状态令牌，可以在网关层缓存公钥或令牌状态，减少穿透到鉴权服务的请求。以下是 Kong 网关 JWT 插件开启缓存的配置示例：
# Kong JWT Plugin 配置
plugins:- name: jwtconfig:key_claim_name: kidsecret_is_base64: falsecache_ttl: 300 # 缓存验证结果 300 秒
开启后可显著降低上游压力，但需注意缓存失效时间与权限变更的平衡。
熔断降级配置
盲目调大超时时间可能掩盖上游服务故障，建议配合熔断策略。当鉴权服务连续失败达到阈值时，快速失败或降级，而不是让用户等待直到超时。以下是 APISIX 熔断器配置示例：
# APISIX Circuit Breaker 插件配置
plugins:- name: circuit-breakerconfig:unhealthy.http_statuses:- 504- 502unhealthy.failures: 5 # 连续 5 次失败触发熔断healthy.http_statuses:- 200healthy.successes: 5 # 连续 5 次成功恢复
怎么验证是否生效
1. 使用 curl 命令测试
通过命令行发送请求并查看耗时，确认不再返回 504。首先创建格式化文件 curl-format.txt：
time_namelookup: %{time_namelookup}\n
time_connect: %{time_connect}\n
time_appconnect: %{time_appconnect}\n
time_pretransfer: %{time_pretransfer}\n
time_redirect: %{time_redirect}\n
time_starttransfer: %{time_starttransfer}\n
----------\n
time_total: %{time_total}\n
http_code: %{http_code}\n
然后执行请求：
curl -w "@curl-format.txt" -o /dev/null -s "https://your-api.com/endpoint"
关注 time_total 和 http_code 是否为 200。
2. 观察监控面板
查看网关的 HTTP 状态码分布图，504 曲线应明显下降。同时观察鉴权服务的 P99 延迟，确认是否稳定在超时阈值以内。
3. 检查错误日志
持续观察网关错误日志，确认没有新的 504 记录产生。如果有，记录发生的时间点，对比鉴权服务的负载情况。
常见坑
1. 超时时间设置过大
不要盲目将超时设置为几分钟。过长的超时会导致网关工作进程长时间占用，并发能力下降，可能引发雪崩。具体数值需根据业务 SLA 决定，通常建议设置在 3-5 秒以内，避免长时间占用连接。
2. 忽略鉴权服务健康检查
如果鉴权服务已经宕机或严重拥堵，单纯增加超时时间无效。应配置网关的上游健康检查，当鉴权服务不可用时快速失败或降级，而不是让用户等待直到超时。
3. 缓存策略不当
在网关缓存 Token 状态时，要注意失效时间（TTL）。如果用户权限在后台被变更，网关缓存未过期，可能导致权限回收不及时。需确保缓存 TTL 小于权限变更的允许延迟。
4. 掩盖上游故障
仅增加超时时间而不解决根本性能问题，会导致故障排查窗口被压缩。建议配合熔断器和报警机制，确保超时增加期间能感知到上游异常。
原文链接：https://www.zjcp.cc/ask/11364.html