Envoy 这个词第一次出现在我工作流里时，我的第一反应是“又一个负载均衡器”。但真正把一个请求从客户端打进 Envoy、再打到后端，然后看着访问日志和指标一点点还原出它内部的执行路径之后，我才意识到：这玩意儿和传统代理完全不是一个物种。它把“监听端口”“四层转发”“七层路由”“限流熔断”这些能力全部抽象成了一层层可以编排的过滤器，连接一进来，就像零件上了流水线。这篇东西我准备了很久，想清楚把 L4/L7 代理能力、Filter 链模型、线程模型和性能调优这四块拆开揉碎讲明白，适合那些已经跑通过 Envoy、但还想真正理解它内部机制的开发者。
1. 骨架先行：Listener、Worker 与连接流向
1.1 主线程与 Worker 线程各自的分工
Envoy 是一个单进程多线程的程序。启动之后你会看到几个线程：一个主线程，剩下是数据面线程，官方叫法一般是 main thread 和 worker threads。
主线程负责的是“不碰流量”的杂活：加载并热更新配置、处理 xDS 动态下发的资源、DNS 解析、证书轮换、统计信息聚合、admin 接口的维护。它不参与具体请求的收发，但所有配置变更都会先经过它，再被推送到 worker 上。这样做的核心好处是：你在运行时改了 cluster 列表，数据面不用重启，请求也不会被中断。
每个 worker 线程则是一个完全独立的事件循环，有自己的 dispatcher、自己的连接表、自己的连接池、自己的定时器和自己的统计计数器。默认情况下 worker 数量等于机器的硬件并发数，也就是--concurrency参数。
这个“每 worker 一套完整副本”的设计是理解 Envoy 一切行为的关键。正因为每个 worker 之间几乎没有共享的可变状态，数据面在处理连接时才不需要频繁抢锁。代价也显而易见：worker 越多，内存占用越大。后面讲性能调优时会再回到这一点。
1.2 连接到达后会发生什么
一个 TCP 连接进来以后，第一步不是路由器转发，也不是某个 filter 开始工作，而是先要决定“这个连接归哪个 worker 管”。Envoy 有两种路径来完成这件事。
第一种是主线程统一 accept，再把 fd 通过内部队列交给某个 worker。这种模式下主线程是所有新连接的入口，连接量非常大的时候，accept 本身可能成为瓶颈，而且每次转发都多一次线程间通信。
第二种是开启SO_REUSEPORT。每个 worker 直接在自己的事件循环里监听同一个端口，内核在三次握手完成后基于四元组哈希把连接分配到某个 worker 的 socket 队列上。没有主线程转发，没有跨线程传递 fd，accept 的压力被天然分散到所有 worker 上。这是 Envoy 在高并发接入场景下最推荐的做法。
连接归到某个 worker 后，剩下的一切——listener filter、network filter、HTTP filter 的执行，上游连接的建立，超时计时——都发生在该 worker 线程内部。一个连接从生到死不会反复跨线程迁移，这也避免了锁竞争和缓存抖动。
1.3 线程模型对后续所有特性意味着什么
理解了上面的模型，你就能看懂 Envoy 配置里很多看似奇怪的限制。比如为什么per_connection_buffer_limit_bytes是 per-listener 级别的，因为每个 worker 都要为这个连接预留独立的读写缓冲；为什么熔断指标里有upstream_cx_active，因为连接池是按 worker 各自维护的；为什么你在压测时看到某个 worker CPU 飙高而其他 worker 很闲，原因也往往出在连接分配层。
我在实际项目里排查过一个现象：明明开了SO_REUSEPORT，流量还是倾斜到同一个 worker。查询了统计之后发现，压测客户端只用了少量长连接，而内核哈希在连接数少时不会自动做均衡。这不是程序 bug，而是连接粒度哈希的固有特性。想让流量更均匀，要么增加并发连接数，要么把一些场景切到 HTTP/2 多路复用，让单连接内承载更多请求。
线程模型不是一个可以“大致理解”的架构细节，它直接决定了你写的每个 filter 在什么执行上下文里跑，也决定了性能调优时该动哪些旋钮。
2. L4/L7 双层代理：一条连接里两种面目
2.1 L4 阶段：从字节到可以“动手”的信息
L4 代理的经典形态是 tcp_proxy：你在 listener 里配一个envoy.filters.network.tcp_proxy，指定 upstream cluster，Envoy 就把客户端连接和上游连接做双向搬运。此时它不关心字节流里是什么协议，只做事字节转发、连接管理和访问日志。这套能力适合 RPC 透传、数据库访问代理、纯 TCP 网关。
但真正让 Envoy 在 L4 层显得“聪明”的，是一类叫做 listener filter 的组件。它们在连接建立后的第一时间执行，能读取连接元数据，为后续路由提供决策依据。
tls_inspector：不终止 TLS，只窥探 ClientHello 里的 SNI 和 ALPN，产生TLSProperties元数据。基于它，同一个端口上可以把不同域名的 TLS 流量分到不同 filter chain。original_dst：读取内核为透明代理场景保留的原始目标地址，配合 iptables 的 REDIRECT 规则，让 Envoy 在自己不知道目标端口的前提下把流量转到正确后端。proxy_protocol：解析 HAProxy PROXY Protocol，拿到真实客户端 IP，解决多层代理后面源地址丢失的问题。
这些 listener filter 的执行发生在任何 network filter 之前，所以它们提取的信息可以被后续 filter chain 的filter_chain_match条件使用。比如你可以按 SNI 分流到不同的 filter chain，有一部分走四层直通，另一部分走七层网关。
2.2 进入 L7 之后：协议解析与路由决策
L7 代理的入口是envoy.filters.network.http_connection_manager，通常缩写为 HCM。它是 network filter 链里最特殊的一个角色：它不再是简单地把字节搬来搬去，而是把原始字节流解析成 HTTP/1.1、HTTP/2、HTTP/3 的协议帧，再向上一层暴露统一的 HTTP filter API。
HCM 的职责非常多：解析请求行、请求头和请求体，管理 keepalive 和连接多路复用，处理 100-continue，生成和传播 trace 上下文，注入请求 ID，处理 WebSocket upgrade，支持 gRPC 流量，以及最终把请求交给 HTTP filter 链处理。
HTTP filter 链的终点通常是 router filter，它根据虚拟主机和路由规则做最后的决策：选 route、选 cluster、执行负载均衡、发起重试、计算超时、判断熔断。所以你看到的 L7 路由能力，其实是一整条 HTTP filter 链在 HCM 框架下协作的结果，不是某一个独立模块单独干出来的。
2.3 L4/L7 混合编排的典型生产姿势
很多人在配置里只用 filter chain 做简单的 SNI 路由，其实还可以在同一套 listener 里混排四层和七层能力。比如下面这个配置就很典型：同样的 443 端口，internal.example.com走 L4 tcp_proxy 直通到内部后端，api.example.com走 HCM 做完整的七层路由。
static_resources: listeners: - name: ingress address: socket_address: address: 0.0.0.0 port_value: 443 listener_filters: - name: tls_inspector typed_config: "@type": type.googleapis.com/envoy.extensions.filters.listener.tls_inspector.v3.TlsInspector filter_chains: - filter_chain_match: server_names: ["internal.example.com"] filters: - name: tcp_proxy typed_config: "@type": type.googleapis.com/envoy.extensions.filters.network.tcp_proxy.v3.TcpProxy stat_prefix: internal_tcp cluster: internal_backend - filter_chain_match: server_names: ["api.example.com"] filters: - name: http_connection_manager typed_config: "@type": type.googleapis.com/envoy.extensions.filters.network.http_connection_manager.v3.HttpConnectionManager stat_prefix: api_http route_config: name: api_route virtual_hosts: - name: api_vh domains: ["api.example.com"] routes: - match: prefix: "/" route: cluster: api_backend http_filters: - name: router typed_config: "@type": type.googleapis.com/envoy.extensions.filters.http.router.v3.Router这样一套配置，等于让 Envoy 同时干了一个四层网关和一个七层网关的活。四层链路因为不解析协议，延迟和吞吐特征是“近乎裸转发的”；七层链路则能拿到 URL、Header、方法等完整语义去做限流、鉴权、灰度。
选择哪种模式的核心依据是：你是不是需要读取和改写请求内容。不需要，就尽量留在 L4；需要路由规则、超时重试、灰度分流，再升到 L7。这不是能力炫耀的问题，而是每一层都有成本。
3. Filter 链模型：请求在流水线上被逐级加工
3.1 Downstream/Upstream 两条链的走向
Filter 链模型是 Envoy 最核心的抽象，没有之一。理解它之前，先记住一条总原则：一切流量处理都发生在 filter 链里，每条链由若干 filter 按顺序串起来。
从配置位置看，至少有两类链。一类是 listener 里的filter_chains，里面挂的是 network filter，负责处理下游连接上的原始字节；另一类是 HCM 内部的http_filters，负责处理已经被解析成 HTTP 语义的流。前者在连接粒度执行，后者在请求流粒度执行。
从数据流方向看，也存在“下游链”和“上游链”两个概念。大多数场景里我们主要配置的是下游方向的 filter 链：客户端流量进入 listener，逐级经过 network filter 和 HTTP filter，最后 router filter 决定上游 cluster，再经过连接池发出。新版本 Envoy 也支持在 cluster 上挂 upstream filter，用于在数据发出之前对出站方向做二次加工，比如在正向代理或出口网关场景下插入自定义处理逻辑。
需要注意，配置位置和数据方向不是一回事：你通常把 HTTP filters 写在 HCM 里，但它们既处理请求（downstream -> upstream），也处理响应（upstream -> downstream）。
3.2 Decode 与 Encode：方向陷阱
HTTP filter 的 API 里面有四个高频出现的关键词：decodeHeaders、decodeData、decodeTrailers，还有对应的encodeHeaders、encodeData、encodeTrailers。
decode 系列负责请求方向，也就是从下游收到流量、向上游转发之前的过程。encode 系列负责响应方向，也就是从上游拿到响应、向下游返回之前的过程。
很多刚接触 Envoy 的人会误以为 Filter 链只处理请求。事实上，你去写一个自定义 HTTP filter，大概率要同时实现两套回调：请求进来时在 decodeHeaders 里做点事，响应回来时在 encodeHeaders 里做点事。如果只实现 decode 而忽略 encode，那么响应路径上的修改（比如给响应头加自定义字段）永远不生效。
更微妙的是执行顺序：HTTP filter 链按配置顺序处理请求，但处理响应时是逆序的。假设你配置了 A、B、C 三个 filter，请求会先经过 A 再 B 再 C，响应则先经过 C 再 B 再 A。这是一个很符合直觉的对折模型，但实际配置时特别容易忽略。
3.3 过滤器执行顺序和迭代器机制
每个 HTTP filter 并不是“看完就交给下一个”这么简单。它需要明确告诉 Envoy 自己的处理状态：
Continue：立即把控制权交给链上的下一个 filter。StopIteration：暂停链的继续推进，等当前 filter 完成一个异步动作，比如调用外部认证服务、做权限检查或者读缓存，之后再调用continueDecoding()或continueEncoding()恢复链条。StopIterationAndBuffer：暂停链条并缓冲当前数据，适合那些必须攒齐完整请求体才能做决定的 filter，比如签名校验。StopIterationAndWatermark：缓冲的同时触达水位限制，防止缓冲无限制增长。
这套迭代器机制决定了 filter 的执行不总是顺序完成。你可以把它想象成一条多人协作的产线：每个工人干完自己的活，要么拍拍下一个工人的肩膀让他继续，要么举手表决“先停一下，我等外部结果”，等到外部结果返回，再拍下一个人。
有经验的开发者踩过最典型的坑就是：在自定义 filter 里调用了异步 HTTP 请求，但忘了调用continueDecoding()，导致请求链条永远停在自己这里，客户端等了几十秒后超时。排查时看日志只能看到请求进来，但转发迟迟没发生。缺的就是那一句显式的继续调用。
3.4 用两类实际场景体会链条性质
第一个场景是请求体缓冲。你在 router 前面挂了 buffer filter，它会试图把整个请求体都缓存下来。这样做的动机是：某些场景里你希望请求体完整到达后再做路由或鉴权。如果 buffer filter 在链上位置靠后，前面的 filter 可能已经读到部分 body 并做了判断，这会导致行为不一致。配置顺序本质上是“谁先接触数据”的决定权。
第二个场景是响应路径。假设你配置了 gzip filter，又配置了一个自定义的审计 filter，你想在响应里看到“原始未压缩”的内容，还是“压缩后的内容”？因为响应按逆序处理，配置顺序决定了审计 filter 看到的数据形态。这种问题在文档里几乎找不到直接答案，只能通过实际抓包或者日志验证。
Filter 链的顺序不是一个风格问题，它是一个功能正确性问题。
4. 性能优势的内部机制：为什么多核可以撑住高并发
4.1 每个线程一个事件循环的核心设计
Envoy 的性能底座是“单进程多线程 + 每线程事件循环”。每个 worker 内部有一个基于 epoll 的事件驱动循环，所有连接事件都在这个循环里被批量取出、批量处理，而不是一个请求起一个线程。
这种设计在并发模型上有一个巨大优势：绝大多数连接处理的代码路径都不需要加锁。因为连接被绑定到某个 worker 之后，该连接上的所有状态——读缓冲、写缓冲、filter 状态、定时器、连接池里的可用连接——都只被这个 worker 访问。
同样处理大量连接，传统多线程阻塞 I/O 模型在连接数升高后会有大量线程上下文切换；而 Envoy 的每个 worker 线程在事件循环里只做非阻塞的处理，线程数不随连接数增长，连接再多也只是在事件循环里多注册几个 fd。
事件循环还有一层容易被忽略的优化：批量处理。每次从 epoll 拿一批就绪事件，在同一轮里连续处理，能显著减少系统调用次数。这也是为什么很多压测场景下，Envoy 的 CPU 曲线不是“一个请求一波动”，而是相对平滑的持续推进。
4.2 连接分配的两种路径与权衡
前面提到过连接分配有两条路径，这里把它们的取舍摊开说。
| 分配方式 | 工作路径 | 优点 | 风险 |
|---|---|---|---|
| 主线程 accept | 主线程 accept 后把 fd 转给 worker | 可精确控制连接在 worker 间的分配，便于二次负载均衡 | 高并发 accept 时主线程容易成为瓶颈 |
| SO_REUSEPORT | 每个 worker 独立 accept 端口 | 无主线程转发，内核做哈希均衡，吞吐上限最高 | 哈希粒度是四元组，短连接占比低时可能出现单 worker 热点 |
我在线上见过的主线程 accept 模式，连接峰值大概到每秒 5 到 8 万个就开始出现 accept 队列堆积。切到 reuse_port 之后，同样配置下峰值能再往上顶一大截，而且实现成本只是 listener 上的一个 socket option。所以如果没有特殊理由，生产环境务必把 reuse_port 打开。
但打开不代表万事大吉。内核哈希只保证协议层面的分布，不保证业务流量完全均匀。遇到“少连接、大流量”的场景，还是要靠监控 worker 粒度的 CPU 和连接数来判断是否需要做进一步调整。
4.3 连接池与内存的“空间换时间”
Envoy 的上游连接池是分成 worker 隔离的。每个 worker 都有自己的连接池、TLS 会话缓存和读缓冲。这么做的好处是：worker 内的连接复用可以完全无锁。HTTP/2 多路复用场景下，一个 worker 可能只维持少量上游连接，却承载了大量并发流。
代价也很清晰：连接池、缓存、缓冲区全部按 worker 复制一份，--concurrency设得越大，内存占用增长越明显。如果机器是 64 核甚至 128 核的高配，又没调整并发数，你可能会在压测时发现内存被 Envoy 吃掉了大半，实际上很多副本是同一个连接池在不同 worker 里的镜像。
这不是 bug，而是内存换性能的设计取向。生产上调优的其中一个核心决策，就是在“足够的事件循环并发能力”和“可接受的内存占用”之间找到平衡点。
4.4 性能上线的关键参数与实测思路
影响 Envoy 性能的变量很多，我使用中觉得优先级最高的是下面几个：
--concurrency：不要永远保持“等于 CPU 核数”。超线程环境下建议从物理核数的一半开始压测，看吞吐曲线和内存曲线，找到拐点。- 连接缓冲：HCM 里可以设置
per_connection_buffer_limit_bytes，太小会导致大包被反复拆分，太大则内存容易被拖垮。 - HTTP/2 流量控制：
initial_stream_window_size和initial_connection_window_size默认值偏保守，传输大对象时吞吐会受限。我见过上传场景一直只跑满 30% 带宽，调大窗口后立刻恢复。 - 上游连接复用：HTTP/2 天然多路复用，不需要额外配置；HTTP/1.1 则要注意 keepalive 与
max_requests_per_connection的组合，避免频繁重建连接。 - 熔断阈值：
circuit breakers的默认阈值比较保守，流量上涨时容易先撞到熔断而非真实系统瓶颈。压测前先调大一倍观察指标变化。
实测时不要只看 QPS。关注upstream_rq_time、listener.downstream_cx_active、cluster.upstream_cx_active、cluster.upstream_rq_pending、每个 worker 的 CPU 使用率和内存占用，这些指标才能帮你判断瓶颈是在连接分配层、协议层还是连接池层。
5. 从默认配置到生产调优：那些文档里不会明说的细节
5.1 最先要校准的参数清单
不少团队把 Envoy 拿到手，配置一跑通就上了生产，等到流量大了才被动调参。我更推荐在第一天就把下面这张表过一遍：
| 配置位置 | 参数 | 作用 | 建议 |
|---|---|---|---|
| 启动参数 | --concurrency | worker 数量 | 从物理核数的一半起步，压测后再定 |
| listener | reuse_port | 是否开启内核级均衡 | 默认关闭时注意改开 |
| listener | per_connection_buffer_limit_bytes | 单连接读写缓冲上限 | 结合最大请求体和并发数推算 |
| HCM | initial_stream_window_size | HTTP/2 流窗口 | 大对象传输场景调大 |
| HCM | max_concurrent_streams | 单连接并发流数 | 太高时注意下游连接数收益递减 |
| cluster | connect_timeout | 上游建连超时 | 根据实际网络 RTT 设置，过小会误杀 |
| cluster | idle_timeout | 空闲连接回收 | 避免连接池堆积 |
| cluster | max_requests_per_connection | 单上游连接最大请求数 | HTTP/1.1 keepalive 场景常用 |
| 熔断 | max_connections/max_requests/max_retries | 主动保护阈值 | 通常需要压测校准，不建议直接默认 |
这些参数之间不是独立关系。比方说你把initial_connection_window_size调大，但per_connection_buffer_limit_bytes还停留在默认值，大窗口反而可能撑爆缓冲区。每调一个数字，都要顺着数据路径把上下游全部检查一遍。
5.2 filter 顺序踩坑的真实复盘
我这个项目经历过一次很有代表性的故障。当时在 HCM 里配了一个外部鉴权 filter，做了 JWT 校验，另外加了一个自定义 response header 注入 filter。配置大概是先写鉴权，再写自定义 filter，最后写 router。按我当时的理解，请求进来自定义 filter 会先给响应头注入一个内部标记，鉴权 filter 再检查令牌。
结果上线后发现问题正好反着来：响应头里确实有这个标记，但鉴权 filter 对某些需要豁免的路径失效了。排查日志发现，自定义的响应头过滤器和鉴权过滤器在 encode 方向是逆序执行的，而且外部鉴权 filter 对某些路径返回了直接响应，绕过了 router，导致我预期在 router 之后注入 header 的逻辑在新路径上根本没机会执行。
这个故障表面看是“filter 顺序问题”，实质是三个问题叠加：一是没有理解响应方向逆序执行；二是没有预期到 filter 可以直接短路返回响应；三是不了解直接响应会绕过后续 filter 链。后来我把整个链路打了出来，对比了正常路由和直接响应两种场景的 filter 执行轨迹，才把所有分支理清楚。
调试 filter 链有个笨但有效的方法：在关键 filter 里加日志，在 decode 和 encode 两个方向各打一次，看顺序和执行的 filter 集合。不要凭直觉猜顺序，把执行路径拉出来看。
5.3 调优后如何验证效果
每次调优都要有可量化的验证方法，不然就是玄学。
配置层面，先用envoy --mode validate -c config.yaml做静态校验，这个必须养成习惯。它会帮你发现很多层级、字段、类型上的低级错误。
运行层面，Envoy 的 admin 接口信息量非常大：/stats能拉出所有计数器、仪表盘值、直方图，/config_dump能看到运行时实际生效的配置，/clusters能实时观察每个 cluster 的健康状态和连接池占用情况。这些是排查问题最顺手的入口。
压测层面，我常用的组合是 wrk 做 HTTP/1.1 短连接压测，h2load 做 HTTP/2 多路复用压测，代码里面再配合 perf 或内置的 CPU profiler 看热点函数。压测时不能只测 QPS，还要同步采集 Envoy 进程的 CPU、内存、连接数，把“压测结果”和“资源占用”对应起来看，才能真正判断参数调整是变好还是变坏。
调优这事的终点不是“参数调得多好看”，而是你能够回答以下几个问题：瓶颈在哪一层？参数调整改变了哪个指标？这个改变在多大流量下会反过来变成风险？
我在实际使用中还有一个体会：Envoy 持续优化的思路不是抓住某一个配置猛调，而是把“监听层—过滤链—连接池—熔断”看成一个整体系统。每次只动一个变量，记录数据，再动下一个。等你把每个变量的影响都摸过一遍，再遇到线上问题，光看指标就能大致猜到是哪一层出了问题。这种能力，比任何一份“最佳实践清单”都值钱。
