API网关 – HDUO Lab

排查某业务线核心 API 网关间歇性 503 告警时，发现了一个极其经典的防御性配置失效案例。结论先行：网关层的 Token Bucket（令牌桶）限流算法中，burst（桶容量）配置过大，导致毫秒级微突发流量直接穿透网关，瞬间击垮下游服务线程池。更要命的是，熔断器配置缺乏防抖逻辑，导致在“熔断-半开-放行-再次击垮”之间形成了高频震荡（Thrashing）。

解决思路很简单：将 burst 值严格限制在下游最大并发承载能力之内，或者针对这种重计算型下游改用 Leaky Bucket（漏桶）算法进行流量整形（Traffic Shaping），同时为熔断器加入指数退避冷却时间。

案发现场与指标异常

监控大盘上的表象非常诡异。网关层统计的平均 QPS 稳定在 2,000 左右，并未达到设定的 3,000 QPS 报警水位。但下游订单服务的 P99 延迟却会毫无规律地从 50ms 飙升至 5,000ms 以上，随后伴随大量的 context deadline exceeded 报错。

查看下游宿主机的 Node Exporter 指标，Load Average 在几秒内冲高到正常核心数的 4 倍，CPU 软中断（si）陡增。

抓取网关层的 Envoy（或基于 Go 自研的网关）日志，看到大量 503 状态码以及频繁的熔断状态切换：

[gw-error] downstream_connection_error: upstream_reset_before_response_started
[circuit_breaker] state changed: CLOSED -> OPEN, reason: 5xx_rate_exceeded
[circuit_breaker] state changed: OPEN -> HALF_OPEN
[circuit_breaker] state changed: HALF_OPEN -> CLOSED
[circuit_breaker] state changed: CLOSED -> OPEN, reason: 5xx_rate_exceeded

愚蠢的配置与技术逻辑剖析

直接调出网关的限流配置片段，问题一目了然：

# 某网关 Token Bucket 限流配置片段
rate_limit:
  token_bucket:
    max_tokens: 15000       # 桶的总容量 (Burst)
    tokens_per_fill: 3000   # 每次填充的令牌数
    fill_interval: 1s       # 填充间隔

写出这段配置的研发可能对限流算法有什么误解。他认为“平时流量 2,000，限制在 3,000，为了防止大促时的流量尖刺，把 max_tokens 设成 15,000 留足缓冲”。

这是毫无系统边界意识的典型表现。 Token Bucket 的核心特性是允许一定程度的突发流量。当业务处于低谷时，令牌桶会很快被填满（15,000 个令牌）。此时如果客户端利用并发压测工具或因为重试风暴，在 10 毫秒内打过来 10,000 个请求，网关会认为“桶里有足够的令牌”，瞬间全部放行。

下游订单服务是个典型的 Java Spring Boot 配合 Tomcat 的同步阻塞架构，Tomcat 最大线程数才配置了 800，数据库连接池 200。这 10,000 个并发砸下去，直接导致：

Tomcat 线程池瞬间打满，后续请求全部进入 Accept 队列。
数据库连接池耗尽，获取 Connection 发生等待。
线程疯狂上下文切换，CPU 资源被内耗殆尽。

网关层的限流不仅没有保护下游，反而成了帮凶。你以为的“缓冲”，其实是积攒了一发核弹交给了客户端。

熔断震荡（Circuit Breaker Thrashing）的雪上加霜

下游瘫痪后，网关的熔断器（Circuit Breaker）触发了 OPEN 状态，切断流量，下游开始缓慢恢复。但随后的恢复过程暴露了熔断器设计的另一个缺陷。

现有的熔断半开（HALF_OPEN）策略是：等待 5 秒后，放行 10 个请求，如果全成功，则关闭熔断器（CLOSED）。因为这 10 个探路请求下去时，下游服务刚刚喘过气，处理极快。熔断器一看，非常健康，瞬间切回 CLOSED。结果桶里早就又攒满了 15,000 个令牌，下一波微突发（Micro-burst）再次穿透，下游再次暴毙。

这种简单的状态机没有考虑到下游服务的冷启动缓冲和并发水位线，导致系统在可用与不可用之间剧烈震荡，P99 延迟曲线变成了梳子状。

避坑指南与底层调优

解决这类问题，必须摒弃“一厢情愿”的配置，回归到底层容量规划上来：

1. 重新校准 Token Bucket，或者改用 Leaky Bucket 如果下游服务对瞬间并发极度敏感（如涉及复杂事务、慢 SQL 的 DB 操作），首选 Leaky Bucket（漏桶）。漏桶就像一个队列，强行将请求以恒定速率滴漏给下游（Traffic Shaping），完全抹平突发。如果必须用 Token Bucket，max_tokens（Burst）的绝对上限，必须小于下游服务能够承受的最大瞬时并发数（通常是 线程池大小 + 队列长度的小部分）。

修正后的配置：

rate_limit:
  token_bucket:
    max_tokens: 800         # 严格卡住瞬间并发上限
    tokens_per_fill: 3000
    fill_interval: 1s

(注：如果使用 Go 的 golang.org/x/time/rate，Limit 控制速率，Burst 就是这个 max_tokens，务必小心设置。)

2. 引入滑动窗口与指数退避熔断 放弃拍脑袋的连续错误计数熔断，改用基于时间滑动窗口（Sliding Window）的错误率熔断。半开状态的探测必须具备平滑放量能力，而不是简单的“成功 10 个就完全放开”。冷却时间必须使用指数退避（Exponential Backoff，如 5s -> 10s -> 20s），并引入 Jitter（随机抖动）防止探路请求形成新的微并发。

3. 监控维度的降维打击：从秒级到毫秒级 只看秒级（QPS）的监控，永远抓不到微突发。在排查阶段，通过抓包或高频采样，将吞吐量统计粒度降到 10ms 或 100ms，你会清楚地看到流量的尖刺。

排查清单（同类问题速查）

核对 Burst/Capacity 配置：检查网关限流器中代表突发容量的字段（如 burst, max_tokens），其值是否远大于下游服务的可用线程数/连接池数。
区分流量整形需求：评估下游是否能处理突发。如果不能，立刻将 Token Bucket 替换为 Leaky Bucket，或在 Nginx 中严格使用 limit_req 且不加 burst（或者加 nodelay 时严格控制大小）。
检查熔断震荡日志：在日志系统中聚合分析 CLOSED -> OPEN -> HALF_OPEN -> CLOSED 的时间差。如果发生频率在秒级切换，说明探路策略过于激进，需增大退避时间和放量步长。
排查毫秒级微突发：如果 1s 内的 QPS 正常但 P99 飙升，使用 Prometheus 的 rate(metric[1m]) 是看不出来的，必须拉取网关 Access Log 按照 100ms 粒度做 count 聚合分析。

结论先行：网关层单一使用 Token Bucket 限流，极易因 burst（突发）参数配置过大导致下游在流量毛刺下被击穿。某次排查发现，瞬间高并发耗尽令牌桶后直接透传，打挂了后端服务，进而引发 Envoy v1.27.0 熔断器（Outlier Detection）频繁弹射健康节点，触发 Panic 路由机制导致全局雪崩。核心解法：引入 Leaky Bucket 平滑流量，并精确调优 Envoy 驱逐窗口与熔断阈值。

案发现场：P99 飙升与诡异的 503 UO 报错

排查某核心交易链路问题时，监控大盘显示网关入口 QPS 平稳维持在 3000 左右，但 P99 延迟却在某些瞬间飙升至 4000ms 以上。紧接着，下游服务开始大面积报警，CPU 使用率出现锯齿状波动，Load Average 瞬间飙升至宿主机核心数的 3 倍。

抓取入口网关与 Sidecar 的日志，发现海量的 503 报错。提取关键的 Envoy (v1.27.0) Access Log：

{
  "response_code": "503",
  "response_flags": "UO",
  "upstream_cluster": "outbound|8080||order-svc",
  "duration": "2",
  "upstream_service_time": null
}

注意这里的 Response Flag UO (Upstream Overflow)。在 Envoy 的语义中，UO 意味着请求不仅没有到达后端应用代码，甚至连连接池都没建起来，直接被 Envoy 的 Circuit Breaker 拦截了。但进一步看，日志中还夹杂着大量 UC (Upstream Connection Termination) 和 503 URX (Upstream Retry Limit Exceeded)。

这就很有意思了：流量大盘是平稳的，网关层配置了 5000 QPS 的全局限流，按理说后端集群（20个 Pod，单 Pod 容量 300 QPS）完全吃得消，为什么会被打出 UO 和 UC？

为什么 Token Bucket 算法无法应对瞬间毛刺流量？

排查网关层的分布式限流实现，发现业务研发基于 Redis + Lua 实现了一个标准的 Token Bucket（令牌桶）算法。核心 Lua 脚本片段如下：

-- KEYS[1]: rate_limit_key
-- ARGV[1]: capacity (桶容量)
-- ARGV[2]: rate (每秒生成令牌数)
-- ARGV[3]: current_timestamp (当前时间戳)
local capacity = tonumber(ARGV[1])
local rate = tonumber(ARGV[2])
local now = tonumber(ARGV[3])

local last_time = tonumber(redis.call('hget', KEYS[1], 'last_time') or '0')
local current_tokens = tonumber(redis.call('hget', KEYS[1], 'tokens') or capacity)

-- 计算这期间生成的令牌
local delta_tokens = math.floor((now - last_time) * rate)
local tokens = math.min(capacity, current_tokens + delta_tokens)

if tokens > 0 then
    redis.call('hset', KEYS[1], 'tokens', tokens - 1)
    redis.call('hset', KEYS[1], 'last_time', now)
    return 1 -- 放行
else
    return 0 -- 限流
end

当时的配置是：capacity = 2000，rate = 1000。这就是典型的防御盲区。Token Bucket 的核心特性是允许突发流量（Burst）。如果系统在过去 2 秒内极其空闲，桶里积攒了 2000 个令牌。此时一个瞬间的流量毛刺（Microburst）打过来，这 2000 个请求会在 10 毫秒 内全部被网关放行，直接砸向后端。

对于后端来说，这不是 1000 QPS，这是瞬时 2000 / 0.01s = 200,000 QPS 的冲击。微服务的连接池瞬间被打满，TCP Accept Queue 溢出，导致部分请求超时（产生 504/503）。

如果是 Leaky Bucket（漏桶） 算法，由于其恒定速率流出的特性（类似 Nginx 的 limit_req 且不带 nodelay），这 2000 个请求会被强制在队列中排队，以绝对平滑的 1000 QPS 速率向后端转发，起到真正的削峰填谷作用。

Envoy 熔断器（Outlier Detection）的雪崩效应

流量毛刺击穿网关后，真正的灾难在 Envoy 代理层爆发。微服务由于瞬时过载，部分 Pod 开始返回 5xx 错误或连接超时。Envoy 的 Outlier Detection（异常点检测）机制被触发。

当时配置的 DestinationRule 如下：

apiVersion: networking.istio.io/v1alpha3
kind: DestinationRule
metadata:
  name: order-svc-dr
spec:
  host: order-svc
  trafficPolicy:
    connectionPool:
      http:
        http1MaxPendingRequests: 1024
        maxRequestsPerConnection: 100
    outlierDetection:
      consecutive5xxErrors: 3
      interval: 10s
      baseEjectionTime: 30s
      maxEjectionPercent: 50

当突发流量导致某几个 Pod 连续返回 3 个 5xx 时，Envoy 毫不犹豫地将它们拉黑（Eject）30 秒。随着被拉黑的 Pod 越来越多（很快达到了 maxEjectionPercent: 50% 的上限），剩余 50% 的 Pod 必须承受全部流量，瞬间雪崩。

更致命的是，当 Envoy 发现健康后端节点比例低于 Panic Threshold（默认 50%）时，会触发恐慌路由（Panic Routing）。Envoy 会认为：“既然健康检查机制可能出错了，那我就无视驱逐状态，把流量均匀分发给所有节点”。于是，处于假死状态的 Pod 再次迎来海量流量，彻底 OOM，Envoy 连接池爆满，最终向上游网关抛出开篇看到的 503 UO 和 503 UC。

体系化修复与架构加固

为了彻底根治这种“毛刺流量 -> 网关击穿 -> 熔断驱逐 -> 恐慌路由 -> 全局雪崩”的连环雷，我们从网关层和 Mesh 层做了以下防御性调整：

1. 网关层：平滑限流（Leaky Bucket 变体）替代纯令牌桶

废弃了原有的自研 Lua 纯令牌桶，在 Nginx/OpenResty 入口层启用基于共享内存的严格限流。即使保留一定的并发度，也必须通过 delay 参数强制平滑：

# 定义 1000r/s 的速率，桶容量为 500
limit_req_zone $binary_remote_addr zone=api_limit:10m rate=1000r/s;

# burst=500 允许一定突发，但 delay=200 表示超过 200 的突发流量将被严格按速率排队延迟，拒绝瞬间砸穿后端
limit_req zone=api_limit burst=500 delay=200;

2. Mesh 层：压制重试风暴与调优熔断参数

调整 Envoy 的 Outlier Detection 与连接池控制，防止误杀：

放大连续错误阈值：将 consecutive5xxErrors 从 3 调整为 15。在高并发微服务中，3 个连续 5xx 极易被网络抖动误触发。
细化驱逐条件：启用 splitExternalLocalOriginErrors，明确区分应用自身抛出的 5xx（如 500 业务报错）和本地网络/Envoy 产生的 5xx（如 503 连接超时）。只对真正的网络连接异常进行物理节点驱逐。
调整恐慌阈值：在 Envoy Cluster 配置中，通过 EnvoyFilter 将 Panic Threshold 从 50% 降低至 20%（如果 80% 节点都挂了，再开启无差别盲发请求）。

# EnvoyFilter 局部核心配置片段
name: envoy.filters.network.http_connection_manager
typed_config:
  "@type": type.googleapis.com/envoy.extensions.filters.network.http_connection_manager.v3.HttpConnectionManager
  common_http_protocol_options:
    idle_timeout: 60s
  route_config:
    virtual_hosts:
    - name: order_route
      routes:
      - match: { prefix: "/" }
        route:
          cluster: outbound|8080||order-svc
          max_stream_duration:
            max_stream_duration: 3s # 强制设置全局绝对超时

常见问题 (FAQ)

Q1：Token Bucket 和 Leaky Bucket 在真实网关选型时究竟怎么选？ 面对对外网关（防刷、防爬），首选 Leaky Bucket（或者带强排队机制的令牌桶变体），这能把刺猬一样的流量彻底削平。面对内部微服务间的限流（RPC 调用），由于内部流量更可控且对 RT 敏感，通常使用 Token Bucket 以容忍短时间的并发调用，但必须严格限制 burst 上限，burst 绝对不能超过目标服务连接池容量的 1/3。

Q2：分布式限流用 Redis + Lua 有什么性能隐患？ 最大的隐患是单点网络瓶颈和 Redis CPU 阻塞。Lua 脚本在 Redis 中是单线程原子执行的，如果网关单机并发极高，所有请求都在等待 Redis 响应，会导致网关 Worker 进程被严重阻塞。对于 10万+ QPS 的限流，千万别用纯 Redis 强一致限流，必须退化为本地内存限流为主，Redis 异步同步配额为辅的架构（类似 Sentinel 的集群限流机制）。

Q3：Envoy 的 Circuit Breaker 和 Outlier Detection 有什么本质区别？ 这是个极度容易混淆的概念。Envoy 的 Circuit Breaker 本质上是“连接池限制”，比如 max_requests: 1000，超出了直接本地决断拦截返回 503（抛出 UO）。它防御的是“我（Client）发出的并发太多了”。而 Outlier Detection 才是传统意义上的熔断（类似 Netflix Hystrix），它通过统计后端节点返回 5xx 的频率，将坏节点剔除出负载均衡池。它防御的是“他（Server）坏了，我不要再把请求发给他”。排查时必须严格区分这两种动作产生的不同报错标识。

标签： API网关

深入 API 网关限流陷阱排查：Token Bucket 容量失控引发的微突发穿透与熔断震荡实战