【Envoy 数据面】生产排障：五条坐标系上的失败清单

「控制面显示已推送」与「客户端仍 503 / 旧路由 / 握手失败」可以同时为真。排障若从产品名或 Grafana 面板名起步，容易在 sidecar、网关与业务之间空转；若从第 1 篇的五条坐标系起步，多数故障会落进有限的几格。

本文是「Envoy / 数据面代理内核」系列第 15 篇：把常见生产症状映射到请求路径、线程快照、匹配改写、xDS 一致性、上游资源五轴，并给出可核对的 admin / 观测入口。不粘贴未执行的命令输出，不写跨引擎延迟排名。

本文是「Envoy / 数据面代理内核」系列第 15 篇（共 16 篇）。→ 系列目录

篇目核心内容

第 14 篇 · 可观测数据面 stats / access log / tracing 归因

第 15 篇 · 生产排障 症状 → 坐标系 → 核对清单

第 16 篇 · 选型收束机制排除树与系列开放问题

篇目	核心内容
第 14 篇 · 可观测数据面	stats / access log / tracing 归因
第 15 篇 · 生产排障	症状 → 坐标系 → 核对清单
第 16 篇 · 选型收束	机制排除树与系列开放问题

版本锚定：Envoy v1.39.0 admin、xDS、hot restart 与 HCM/Cluster 配置语义。清单是工程方法，不是厂商 runbook 全文。

一、先选轴，再动命令

请求路径轴：  卡在匹配 / 编解码 / filter / 路由 / 上游池？
线程快照轴：  Worker 读到的是哪一版 TLS 快照？
匹配改写轴：  FilterChain / SNI / original_dst 是否选错？
xDS 一致性轴：ACK 了吗？依赖 warming 完了吗？
上游资源轴：  连接池 / 熔断 / outlier / 健康检查卡死了吗？

flowchart TD
  symptom["Symptom: 5xx / stall / TLS fail"] --> axis["Pick coordinate axis"]
  axis --> path["Request path"]
  axis --> xds["xDS consistency"]
  axis --> up["Upstream resources"]
  axis --> match["Match / rewrite"]
  axis --> thr["Thread snapshot / restart"]
  path --> admin["Admin + access log flags"]
  xds --> dump["config_dump / clusters"]
  up --> stats["cluster.* stats"]

默认顺序（可裁剪）：

Access log / stats 定层（第 14 篇）。
/clusters、/config_dump 看「Worker 认为世界长什么样」。
对照控制面 version / nonce / ACK（第 10 篇）。
仍不一致 → warming / SDS / hot restart（第 11–12 篇）。

Admin 暴露配置与统计，也能执行破坏性操作；生产必须网络隔离或 allow_paths 收窄（Administration interface）。

二、无上游 / 503：路径轴 × 上游资源轴

症状：下游立即 503 或短超时；access log 常见与「无健康上游 / 溢出」相关的 RESPONSE_FLAGS（具体字母以当前版本文档表为准）。

核对	看什么	常见根因
Cluster 是否存在	`/config_dump` 中 CDS 名与 Route 引用是否一致	路由指向未下发的 cluster
Endpoint 是否为空	`/clusters` 主机列表、EDS	服务发现滞后、标签选空
健康与 outlier	`cluster.<name>.membership_`、`outlier_detection.`	全员被踢出、主动健康检查失败
熔断 / 池	`upstream_rq_pending_overflow`、`upstream_cx_overflow` 等	并发限额打满（第 8 篇）

排除树：Route 名对 → Cluster 在 dump 中存在 → 有 endpoint → 有健康主机 → 池未溢出。任一步断裂，就不要先怀疑「业务代码变慢」。

三、路由未生效：xDS 一致性轴

症状：控制面 UI / istioctl / 自研面板显示新路由已发布，流量仍走旧 cluster 或旧 prefix。

记住第 1 篇不变量：ACK ≠ 依赖已 warming ≠ 流量已切到新快照。

步骤	问题
1	ADS/xDS 流是否仍连接？NACK 是否在升？
2	Route 资源 version 是否出现在本机 `config_dump`？
3	Listener / VirtualHost / Route 命名是否指到预期 RDS？
4	是否仍有旧 listener 在服务（多 chain / 多 listener 端口）？
5	客户端是否打到另一条入口（节点网关 vs sidecar）？

SotW 全量与 Incremental 的「看见旧资源」窗口不同（第 10 篇）。排障时以数据面 dump 为准，不以控制面「已发送」文案为准。

四、证书与 SDS：一致性轴上的密钥路径

症状：TLS 握手失败、证书过期告警、或 SDS 更新后间歇性失败。

核对	说明
静态 secret vs SDS	dump 中 secret 来源；SDS 订阅是否活跃
Warming 中的 listener	新链等证书时，旧链是否仍在接（或反之造成空窗）
时钟与中间 CA	代理与客户端时钟偏移、bundle 是否缺链
热更新边界	仅轮转 secret 与整条 FilterChain 替换的失败面不同 → 第 11 篇

证书问题经常被误报成「上游挂了」：握手死在匹配轴 / 下游 TLS，upstream stats 可能几乎不动——用路径轴先分侧。

五、Warming 黑洞：一致性轴的空窗

症状：更新窗口内连接被拒或路由到无处；过后自愈或持续黑洞。

机制要点（与官方 warming 叙述一致，细节见第 11 篇）：

Listener / Cluster 可在依赖（Route、Endpoint、Secret）未就绪时处于 warming，不对流量「假装已切换」。
若旧资源已移除而新资源未就绪，就会出现可观测的空窗——这是一致性选择，不是随机丢包。

清单：

listener_manager / cluster warming 相关统计是否积压。
config_dump 是否同时存在 warming 与 active 视图（以实际 dump 字段为准）。
控制面是否在同一窗口删除了仍被引用的 EDS/CDS。
是否把「推送成功」当成「warming 完成」做发布门禁。

发布门禁应检查数据面就绪，而不是只检查 xDS ACK 计数。

六、Hot restart：线程快照轴上的排水

官方 Hot restart（v1.39.0）：新进程初始化并接管 listen socket 后，旧进程 drain；既有连接不迁移，必须在 drain 期内结束或被切断。父子经 UDS 交换计数；--drain-time-s 与 --parent-shutdown-time-s 独立，后者应更长。

症状	核对
发布后长连接突断	drain 是否短于业务最长请求；是否有未完成的流式 RPC
双进程残留	parent shutdown 是否到期；容器是否只杀子不杀父
统计「跳变」	热重启后 counter 继承与 gauge 清理语义；看 `server.hot_restart_generation`
并发变更	文档注明 concurrency 下降时 accept 队列连接可能丢失

Hot restart 解决的是「代码/完整配置重载且尽量保 listen」；它不是无感迁移所有连接的保证。LDS 热更新与进程级 hot restart 失败面不同——先分清发布打了哪一条路径（第 12 篇）。

七、连接泄漏与「池被吃光」

症状：upstream_cx_active / fd 用量只升不降；新请求 pending overflow；重启后暂时恢复。

方向	可能机制
下游不关连接	客户端或中间 LB 保活过量；idle timeout 未对准
上游半开	重试放大 + 连接不复用；outlier 抖动
过滤器持有	自定义/Wasm/ext_proc 长时间不结束流（第 13 篇）
健康检查	主动探测连接与业务池争用限额
限流/鉴权外呼	外置服务变慢导致下游连接堆积

对照：下游活跃连接 vs 上游活跃连接 vs pending 请求。三者同时高，先看超时与重试预算；仅上游高，查池与上游；仅下游高，查客户端与 idle 策略。

八、把清单收成一张表

症状	主轴	先看	系列回指
无健康上游 / 池溢出	上游资源	`/clusters`、`cluster.*`	07–08
路由仍旧	xDS 一致性	`config_dump`、ACK/NACK	09–11
TLS/证书	匹配 + xDS	SDS、warming listener	03、11
更新窗口黑洞	xDS warming	warming 统计与依赖删除次序	11
发布后长连断开	线程/重启	drain 参数、双进程	12
fd / 连接只增	路径 + 上游	cx_active、idle、重试	04、08、13
「慢」但码对	路径 + 观测	access log duration、trace	14

开放问题（系列级，选型篇继续）：大规模 EDS 抖动下，排障信号本身是否被控制面噪声淹没？Sidecar 数量上升后，admin 可达性与卡片爆炸如何治理？→ 第 16 篇。

九、参考资料

规范 / 官方文档（A）

Envoy Proxy v1.39.0，Administration interface（/stats、/clusters、/config_dump、安全边界）。
Envoy Proxy v1.39.0，xDS REST and gRPC protocol；Hot restart。
Envoy Proxy v1.39.0，Access log command operators / HTTP response flags 表。
Envoy Proxy v1.39.0，Cluster / Outlier detection / Circuit breakers 配置参考。

站内对照

实验台账

本篇为清单与语义；无本机故障注入输出。

十、小结

先定坐标系，再查 admin——避免在控制面文案与业务之间空转。
ACK、warming、流量切换是三件事；黑洞多落在中间那件。
无上游、证书、池耗尽、泄漏各有排除树；access log flags 与 cluster.* 是最短路径。
Hot restart 不迁移既有连接；drain 参数是发布风险，不是细节配置。

→ 上一篇：可观测数据面 · 系列目录 · 下一篇：选型收束

同主题继续阅读

把当前热点继续串成多页阅读，而不是停在单篇消费。

2026-08-10 · network / proxy