Envoy 核心术语详解Host、Listener、Cluster、Mesh 与 Runtime 配置在源码中的实现【免费下载链接】envoyCloud-native high-performance edge/middle/service proxy项目地址: https://gitcode.com/GitHub_Trending/en/envoy读完 Envoy 的架构文档前先要掌握一套贯穿全部文档与代码库的统一术语Host主机、Downstream/Upstream下游/上游、Listener监听器、Cluster集群、Mesh网格以及 Runtime configuration运行时配置。这些定义在行业内略有争议但 Envoy 的文档与源码严格遵循这套用法。本文以官方架构文档中的术语定义为骨架逐一展开每个概念在代码中的落地位置——从HostDescription接口、ListenerConfig到ClusterManager与Runtime::Snapshot帮助你在阅读文档、排查配置问题或编写集成代码时能够准确使用这些概念并快速定位对应的源码实现。术语总览术语一句话定义主要源码落点Host具备网络通信能力的实体手机上的应用、服务器等文档中是一个逻辑网络应用host_description.hDownstream连接 Envoy、发送请求并接收响应的主机网络接收方向见 listener.hUpstream接收来自 Envoy 的连接和请求、返回响应的主机cluster_manager.hListener下游客户端可连接的命名网络位置端口、Unix domain socket 等listener.h、listener_impl.hCluster一组逻辑相似的、Envoy 要连接的上游主机组cluster_manager.hMesh一组协同提供一致网络拓扑的主机Envoy mesh 即一组 Envoy 代理概念层跨实例协作Runtime configuration与 Envoy 并行部署的带外实时配置系统runtime.h这套术语的关系可以概括为Downstream 主机连接 Envoy 暴露的 ListenerEnvoy 根据路由规则将请求转发到 Cluster 中的某个 Upstream 主机多个 Envoy 实例可以组成 Mesh而 Runtime 配置提供一套不重启进程即可调整行为的带外开关。下文逐一深入。Host一个可被独立寻址的逻辑网络应用官方定义是Host 是具备网络通信能力的实体例如手机上的应用、服务器等。在 Envoy 文档中Host 是一个逻辑网络应用——一块物理硬件上可以同时运行多个 Host只要它们各自可以被独立寻址。这个逻辑定位在源码中体现得很清楚。上游主机的抽象由 envoy/upstream/host_description.h 中的HostDescription接口承担从该接口的方法签名可以看到一个 Host 在 Envoy 内部并不只是一个 IP而是一组与负载均衡、健康判断相关的属性canary()/canary(bool)该主机是否为金丝雀实例用于灰度流量的健康检查路径metadata()/metadataHash()主机关联的元数据及其缓存哈希元数据是 subset 负载均衡按标签路由到特定主机子集的数据基础cluster()返回该主机所属的ClusterInfo常量引用——从源码结构看Host 与其所属 Cluster 是强绑定的一个 Host 的描述必然引用它所在的集群priority相关的连接创建判断主机按优先级priority分组Envoy 可以据此决定是否为其建立连接。HostDescriptionConstSharedPtr这类共享指针别名using HostDescriptionConstSharedPtr std::shared_ptrconst HostDescription;表明上游主机对象在健康检查器、离群检测器见 outlier_detection.h等多个组件之间被共享引用这与Host 是逻辑实体而非线程私有对象的定义一致。Downstream 与 Upstream以 Envoy 为中心的流量方向这两个术语是相对 Envoy 而言的方向性是整个架构文档反复使用的前提Downstream下游连接 Envoy、发送请求、接收响应的主机。对 Envoy 而言downstream 流量从 Listener 进入。Upstream上游接收来自 Envoy 的连接与请求、返回响应的主机。upstream 主机是 Cluster 的成员由 Envoy 主动发起连接。这套方向约定贯穿配置与代码。例如 Listener 侧ListenerInfo接口envoy/network/listener.h通过direction()方法暴露TrafficDirection即相对于本地代理的流量方向上游侧则由 Cluster 与 ClusterManager 管理连接池与出站连接。阅读文档时注意出现 downstream 就指向客户端一侧出现 upstream 就指向服务端被代理一侧不要与网络拓扑中的上游/下游混淆。Listener下游可连接的命名网络位置官方定义Listener 是一个命名网络位置如端口、Unix domain socket下游客户端可以连接它Envoy 暴露一个或多个 Listener 供下游主机连接。在源码中Listener 的抽象分两层接口层envoy/network/listener.hListenerInfo描述监听器本身的元信息name()配置中设置的名称、metadata()/typedMetadata()关联的元数据、isQuic()是否为 QUIC 监听器、drainType()DEFAULT类型在监听器移除/修改、热重启以及/healthcheck/fail时排水MODIFY_ONLY则不响应后两种情况、shouldBypassOverloadManager()是否绕过过载管理器动作。ListenerConfig则承载每个新连接建立时需要的行为配置filterChainManager()/filterChainFactory()如何根据 SNI、地址等匹配过滤链、listenSocketFactories()创建监听 socket 的工厂对应端口或 Unix socket这一网络位置的落地、bindToPort()是否真正绑定端口——从注释可见不绑端口的 Listener 只能接收从其他 Listener 重定向过来的连接这支撑了use_original_dst场景下的连接交接、handOffRestoredDestinationConnections()恢复原始目标地址后是否把连接移交另一个 Listener、perConnectionBufferLimitBytes()每连接读写缓冲软限制、listenerFiltersTimeout()等待所有 Listener Filter 完成操作的超时时间超时后默认关闭被 accept 的 socket除非continueOnListenerFiltersTimeout()返回 true。实现层source/common/listener_manager/listener_manager_impl.h 中的ListenerManagerImpl负责 Listener 的生命周期管理创建、更新、排水移除。更完整的 Listener 行为说明可参见 listeners.rst 与 listener_filters.rst。Cluster逻辑相似的上游主机组官方定义Cluster 是一组逻辑相似的上游主机Envoy 连接它们Envoy 通过服务发现service discovery发现集群成员可选地通过主动健康检查active health checking判断成员健康最终由负载均衡策略决定把请求路由到哪个成员。定义中的三个能力分别对应独立的架构文档与子系统服务发现service_discovery.rst包括静态集群、DNS 集群、EDS 动态端点等方式主动健康检查health_checking.rst负载均衡load_balancing.rst包括 P2C、Ring Hash、Maglev 等策略。在源码层面集群的创建与更新由 envoy/upstream/cluster_manager.h 中的ClusterManager统一管理。其接口注释揭示了一个值得注意的两阶段初始化模型第一阶段初始化所有primary clusters例如承载 xDS 控制面的集群以便能成功部署其余动态配置第二阶段才初始化所有secondary clusters端点分配由 xDS 服务器提供并加载其余 xDS 配置。此外addOrUpdateCluster()的语义注释明确了动态更新的规则以配置哈希判断集群是否变化哈希相同则不做任何事并且静态定义的集群不能通过 API 更新。逻辑相似这一措辞也在实现中得到印证——同一 Cluster 内的 Host 共享同一套健康状态管理、负载均衡器与连接池前文HostDescription::cluster()返回所属ClusterInfo正是这种成员-集群从属关系。Mesh作为消息传递底座的 Envoy 代理群官方定义Mesh 是一组协同提供一致网络拓扑的主机。在 Envoy 文档语境下Envoy mesh 特指一组 Envoy 代理它们共同构成一个由众多不同服务与应用平台组成的分布式系统的消息传递底座message passing substrate。与 Host、Listener、Cluster 不同Mesh 是跨实例的概念——单个 Envoy 进程内部没有mesh对象它描述的是多个 Envoy 部署共同形成的整体网络形态典型如服务网格中每个服务前后各部署一个代理。Envoy 文档中与该主题直接相关的落地能力包括东西向service-to-service流量处理、内部监听器internal listener等例如仓库中的示例配置 internal_listener_proxy.yaml 就展示了用内部监听器在同一进程内串联多个代理角色的做法。Runtime configuration不重启即生效的带外配置官方定义Runtime configuration 是与 Envoy 并行部署的带外out of band实时配置系统其中的配置项可以在无需重启 Envoy、也无需修改主配置的情况下被修改并影响运行行为。源码实现位于 envoy/runtime/runtime.h。核心抽象是Runtime::Snapshot一个ThreadLocalObject派生类代表某一刻的运行时数据快照其中OverrideLayer运行时值的提供方注释写明一个或多个这样的层组合成快照的取值来源后层覆盖前层name()返回用户友好的层别名例如admin 或 disk——即通过 Admin 接口或磁盘 YAML 文件提供的覆盖值会分层生效featureEnabled()内置随机数生成器在 0–99 范围内取随机数与键值比较实现百分比分流代码注释特别提醒每次调用可能因新随机数而返回不同结果调用方不应假设同一快照上结果稳定稳定抽样需使用带random_value的变体或featureFlag一类接口deprecatedFeatureEnabled()/runtimeFeatureEnabled()注释解释了其工程目的——用于高风险变更时在新旧两条代码路径之间切换旧路径在 feature 默认为 true 后被弃用并计划在后续版本中移除。这正是 Envoy 用 runtime 机制做渐进式行为切换的典型模式。配套的文档讲解可参考 runtime.rst。理解这个术语的实用价值在于当你在 Envoy 文档或源码中看到某个行为受 runtime key 控制时意味着它可以通过 runtime 层disk/admin在不改主配置、不重启的前提下调整而不需要走 xDS 配置更新流程。术语与源码索引速查术语文档定义要点源码入口延伸阅读Host可独立寻址的逻辑网络应用envoy/upstream/host_description.hhost_description 完整接口Downstream / Upstream相对 Envoy 的请求进出方向envoy/network/listener.hintro.rstListener下游可连接的命名网络位置envoy/network/listener.h、listener_manager_impl.hlisteners.rstCluster逻辑相似的上游主机组envoy/upstream/cluster_manager.hcluster_manager.rst、load_balancing.rstMeshEnvoy 代理群构成的消息传递底座跨实例概念internal_listener_proxy.yamlRuntime configuration带外实时配置无需重启envoy/runtime/runtime.hruntime.rst术语体系还有一篇直接姊妹文档——线程模型threading_model.rst它解释 EventDispatcher、worker 线程与热重启如何协作理解了本文的 Host/Listener/Cluster 划分后再读线程模型会自然许多Listener 所在的事件调度器接收 downstream 连接worker 线程池上的连接池维护与 upstream 主机的通信而 runtime 快照作为线程本地对象在每次配置推送后向各线程广播。适用前提说明以上分析基于当前仓库版本xDS v3 API 世代的头文件接口HostDescription、ClusterManager等接口方法注释中的行为描述如 primary/secondary 集群两阶段初始化、静态集群不可经 API 更新以 envoy/upstream/cluster_manager.h 为准。术语定义本身源自官方架构文档 terminology.rst若未来版本调整接口建议以仓库最新代码注释为准。【免费下载链接】envoyCloud-native high-performance edge/middle/service proxy项目地址: https://gitcode.com/GitHub_Trending/en/envoy创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考