3、Envoy超时配置详解：全局超时、路由超时、空闲超时、连接超时、重试超时等各类超时参数的含义与默认值

Envoy 的超时体系是流量治理中最容易引发“隐性故障”的环节。在回滚场景中，若上游服务已降级但 Envoy 仍按原超时策略等待响应，会导致客户端连接堆积、熔断器无法触发，最终使回滚护栏形同虚设。本节将逐一拆解 Envoy 中五类核心超时参数：全局超时、路由超时、空闲超时、连接超时与重试超时，并给出默认值与配置建议。

3.1 超时参数全景图

Envoy 的超时配置分布在 Cluster（集群）、Route（路由）和 Listener（监听器）三个层级。下图展示了各超时参数的作用位置与传递关系：

3.2 全局超时（Cluster Timeout）

全局超时定义在 Cluster 配置的 common_http_protocol_options 或 http_protocol_options 中，是 Envoy 等待上游 HTTP 响应的总时间上限。它从请求被转发到上游开始计时，直到收到完整响应头结束。

3.3 路由超时（Route Timeout）

路由超时定义在 RouteAction 的 timeout 字段中，是 Envoy 中优先级最高的超时参数。它会覆盖集群级别的全局超时，且对每个路由规则独立生效。

# 路由超时配置示例
routes:
- match:
    prefix: "/api/v1/rollback"
  route:
    cluster: rollback-service
    timeout: 5s                # 路由超时 5 秒
    retry_policy:
      retry_on: "5xx"
      num_retries: 3
      retry_timeout: 2s        # 重试超时 2 秒

3.4 空闲超时（Idle Timeout）

空闲超时控制连接在没有数据传输时的存活时间。Envoy 中有两个层级的空闲超时：

• 连接级空闲超时：定义在 Cluster.common_http_protocol_options.idle_timeout，仅对 HTTP/2 连接生效。默认无限制，但建议显式设置以防止连接泄漏。
• 流级空闲超时：定义在 RouteAction.idle_timeout，对单个 HTTP 流生效。若流在超时时间内未收到任何数据，Envoy 会主动关闭流。

3.5 连接超时（Connect Timeout）

连接超时控制 Envoy 与上游服务建立 TCP 连接的最大等待时间。它定义在 Cluster.connect_timeout 字段中，是网络层面的超时参数。

# 连接超时配置示例
clusters:
- name: rollback-service
  connect_timeout: 3s          # TCP 连接超时 3 秒
  per_connection_buffer_limit_bytes: 32768
  common_http_protocol_options:
    idle_timeout: 60s

3.6 重试超时（Retry Timeout）

重试超时是 Envoy 重试策略中的关键参数，控制单次重试请求的最大等待时间。它定义在 RouteAction.retry_policy.retry_timeout 中，与路由超时配合使用。

# 重试超时配置示例
retry_policy:
  retry_on: "5xx,gateway-error,connect-failure"
  num_retries: 3
  retry_timeout: 2s            # 每次重试最多等待 2 秒
  host_selection_retry_max_attempts: "5"

3.7 超时参数优先级与默认值汇总

下表汇总了所有超时参数的优先级顺序与默认值，方便在故障排查时快速定位：

3.8 超时配置检查清单

在排查回滚护栏失效问题时，请按以下清单逐一核对超时配置：

1. 路由超时是否被禁用？检查 timeout: 0 或 timeout: "0s"，禁用超时会绕过所有超时保护。
2. 重试超时是否继承路由超时？若未显式设置 retry_timeout，重试会使用路由超时，导致总等待时间 = 路由超时 × (重试次数 + 1)。
3. 连接超时是否大于路由超时？连接超时若大于路由超时，连接超时永远不会触发。
4. 空闲超时是否小于路由超时？对于长耗时回滚，空闲超时过小会导致连接提前关闭。
5. 全局超时是否被路由超时覆盖？确认路由超时是否显式设置，若未设置则使用全局超时。