3. Envoy 配置入门：静态配置与动态配置（xDS）、Listener 与 Cluster 基础配置、HTTP 连接管理器（HCM）配置

Envoy 的配置体系是理解其行为与排障能力的基础。本章将系统讲解 Envoy 的两种配置模式——静态配置与动态配置（xDS），并深入剖析核心组件 Listener、Cluster 以及 HTTP 连接管理器（HCM）的基础配置方法。掌握这些内容后，你将能够独立搭建一个具备基本路由与代理能力的 Envoy 实例，并为后续缓存命中故障排查打下坚实的配置基础。

3.1 静态配置 vs 动态配置（xDS）

Envoy 支持两种配置加载方式：静态配置和动态配置。静态配置在启动时通过一个 YAML 或 JSON 文件一次性加载，所有代理规则在进程生命周期内固定不变；动态配置则通过 xDS（Discovery Service）协议从外部控制平面实时获取配置更新，实现零重启热更新。

特性 静态配置 动态配置（xDS）
配置来源 本地文件（bootstrap.yaml） 远程控制平面（如 Istio Pilot、Go Control Plane）
更新方式 需重启 Envoy 进程 热更新，无需重启
适用场景 测试环境、边缘节点、固定路由 生产环境、服务网格、频繁变更
配置复杂度 低，单文件管理 高，需部署控制平面
排障难度 低，配置可完整导出 中，需结合 xDS 日志与快照
排障要点：在缓存命中故障排查中，若使用静态配置，应首先检查 bootstrap 文件中 Listener 与 Cluster 的完整定义；若使用动态配置，则需通过 config_dump 管理端点（/config_dump）获取当前生效的 xDS 资源快照，对比预期配置与实际配置的差异。

3.2 Listener 与 Cluster 基础配置

Listener 和 Cluster 是 Envoy 代理架构中最核心的两个抽象概念。Listener 负责监听入站流量，Cluster 负责定义上游服务端点。理解它们的配置结构是进行任何流量管理的前提。

3.2.1 Listener 配置

Listener 定义了 Envoy 在哪个 IP 地址和端口上接收来自下游的请求。一个 Envoy 实例可以配置多个 Listener，每个 Listener 可以绑定不同的协议（TCP、UDP）和过滤器链。

static_resources:
  listeners:
  - name: listener_http
    address:
      socket_address:
        address: 0.0.0.0
        port_value: 10000
    filter_chains:
    - filters:
      - name: envoy.filters.network.http_connection_manager
        typed_config:
          "@type": type.googleapis.com/envoy.extensions.filters.network.http_connection_manager.v3.HttpConnectionManager
          stat_prefix: ingress_http
          codec_type: AUTO
          route_config:
            name: local_route
            virtual_hosts:
            - name: backend
              domains: ["*"]
              routes:
              - match:
                  prefix: "/"
                route:
                  cluster: service_cluster
          http_filters:
          - name: envoy.filters.http.router
            typed_config:
              "@type": type.googleapis.com/envoy.extensions.filters.http.router.v3.Router
配置要点：Listener 的 address 字段必须与容器网络命名空间内的实际 IP 和端口匹配。在 Kubernetes 环境中，通常绑定 0.0.0.0 以监听所有网络接口。端口号应避免与主机上其他进程冲突。

3.2.2 Cluster 配置

Cluster 定义了 Envoy 将请求转发到的上游服务集合。每个 Cluster 可以包含一个或多个端点（endpoint），并支持负载均衡策略、健康检查、连接池等高级特性。

static_resources:
  clusters:
  - name: service_cluster
    connect_timeout: 0.25s
    type: STRICT_DNS
    dns_lookup_family: V4_ONLY
    lb_policy: ROUND_ROBIN
    load_assignment:
      cluster_name: service_cluster
      endpoints:
      - lb_endpoints:
        - endpoint:
            address:
              socket_address:
                address: service-backend.default.svc.cluster.local
                port_value: 8080
    health_checks:
    - timeout: 1s
      interval: 10s
      unhealthy_threshold: 3
      healthy_threshold: 2
      http_health_check:
        path: "/health"
Cluster 字段 说明 常见取值
type 端点发现方式 STRICT_DNS、LOGICAL_DNS、STATIC、EDS
lb_policy 负载均衡算法 ROUND_ROBIN、LEAST_REQUEST、RING_HASH、MAGLEV
connect_timeout 与上游建立连接的超时时间 0.25s、1s
health_checks 主动健康检查配置 HTTP、TCP、gRPC 检查
常见排障陷阱：Cluster 的 type 配置错误是导致缓存命中失败或请求超时的常见原因。例如，在 Kubernetes 中使用 STRICT_DNS 时，DNS 解析结果必须与 Service 的 Endpoints 一致；若使用 STATIC 类型，则需确保端点 IP 在容器生命周期内不会变化。

3.3 HTTP 连接管理器（HCM）配置

HTTP 连接管理器（HCM）是 Envoy 中最核心的网络过滤器，负责处理 HTTP/1.1、HTTP/2 以及 HTTP/3 协议的解析、路由和过滤。HCM 配置在 Listener 的 filter_chains 中，是连接下游请求与上游 Cluster 的桥梁。

3.3.1 HCM 核心配置结构

typed_config:
  "@type": type.googleapis.com/envoy.extensions.filters.network.http_connection_manager.v3.HttpConnectionManager
  stat_prefix: ingress_http
  codec_type: AUTO
  route_config:
    name: local_route
    virtual_hosts:
    - name: backend
      domains: ["*"]
      routes:
      - match:
          prefix: "/api"
        route:
          cluster: api_cluster
      - match:
          prefix: "/static"
        route:
          cluster: static_cluster
          timeout: 30s
  http_filters:
  - name: envoy.filters.http.router
    typed_config:
      "@type": type.googleapis.com/envoy.extensions.filters.http.router.v3.Router

3.3.2 HCM 关键参数说明

参数 作用 缓存排障关联
codec_type 协议编解码类型（AUTO/HTTP1/HTTP2） HTTP/2 多路复用可能影响缓存键生成
route_config 路由表定义，决定请求转发目标 路由规则错误会导致缓存 miss 或请求到错误 Cluster
http_filters HTTP 过滤器链，顺序执行 缓存过滤器（如本地缓存、外部缓存）必须位于 Router 之前
stat_prefix 统计指标前缀 用于区分不同 Listener 的缓存命中统计
request_timeout 完整请求超时时间 超时过短可能导致缓存未填充完成即被中断
缓存排障关键检查点：在 HCM 配置中，http_filters 的顺序至关重要。如果缓存过滤器（如 envoy.filters.http.cache）被放置在 envoy.filters.http.router 之后，缓存逻辑将永远不会生效，因为 Router 过滤器会直接将请求转发到上游，不再经过后续过滤器。正确的顺序应为：
缓存过滤器 → 其他过滤器 → Router 过滤器

3.4 静态配置与动态配置的架构对比

下图展示了静态配置与动态配置（xDS）在 Envoy 中的整体架构差异。静态配置中所有资源定义在本地 bootstrap 文件中；动态配置中 Envoy 通过 gRPC 流从控制平面订阅 LDS、RDS、CDS、EDS 等资源更新。

静态配置 vs 动态配置（xDS）架构对比 静态配置 bootstrap.yaml（本地文件） Envoy 进程启动时加载 Listener / Cluster / Route 固定 变更需重启 Envoy 进程 动态配置（xDS） 控制平面（xDS Server） gRPC 流推送 LDS/RDS/CDS/EDS Envoy 热更新配置 零重启，配置实时生效

3.5 本章小结

本章涵盖了 Envoy 配置的三大基础模块：

  • 静态配置 vs 动态配置（xDS）：理解两种模式的适用场景与排障差异，掌握 config_dump 的使用方法。
  • Listener 与 Cluster 基础配置：Listener 定义入站流量入口，Cluster 定义上游服务端点，两者共同构成 Envoy 代理的核心骨架。
  • HTTP 连接管理器（HCM）配置：HCM 是 HTTP 流量的处理中枢，其过滤器顺序直接影响缓存逻辑是否生效。
实践建议：在开始缓存命中故障排查之前，建议先使用静态配置搭建一个最小可用的 Envoy 实例，验证 Listener 和 Cluster 的连通性，再逐步引入 HCM 和缓存过滤器。这样可以在出现问题时快速定位是配置错误还是缓存逻辑本身的问题。
← 上一章 📖 返回目录 下一章 →