4. Envoy 静态配置入门：静态配置文件结构

Envoy 的静态配置是学习其代理模型的基础。在变更门禁场景中，静态配置常用于固定边车代理的初始启动参数，确保在动态控制面尚未就绪时，代理仍能按预设规则转发流量。本章将拆解静态配置文件的三大核心块：listeners、clusters 和 admin，并掌握 YAML 语法要点与启动命令。

4.1 静态配置文件整体结构

Envoy 的静态配置是一个 YAML 文件，顶层包含三个必需字段和一个可选字段：

顶层字段 是否必需 作用描述
listeners 是 定义监听端口、协议、过滤器链，决定如何接收入站流量
clusters 是 定义上游服务端点、负载均衡策略、健康检查，决定流量转发目标
admin 是 暴露管理接口（如 /stats、/config_dump），用于运行时监控与调试
static_resources 否 包裹 listeners 和 clusters 的父级容器，静态配置中必须使用此字段
关键记忆点： 静态配置的 YAML 根节点必须是 static_resources，其下嵌套 listeners 和 clusters；admin 与 static_resources 平级。

4.2 YAML 语法基础与避坑指南

Envoy 配置对 YAML 缩进和类型敏感，以下是最容易出错的三个规则：

  • 缩进一致性： 使用空格（禁止 Tab），同一层级必须对齐。Envoy 通常使用 2 空格缩进。
  • 字符串引号： 包含冒号、特殊字符或数字开头的值必须加双引号，例如 "127.0.0.1:8080"。
  • 列表与映射： 列表项以 - 开头，映射键值对以 key: value 形式书写，冒号后必须有一个空格。
常见错误示例：
# 错误：缩进不一致，冒号后无空格
listeners:
- name: my_listener
  address:
    socket_address:
      address: 0.0.0.0
      port_value:10000  # 缺少空格
# 正确写法
listeners:
- name: my_listener
  address:
    socket_address:
      address: "0.0.0.0"
      port_value: 10000

4.3 Listeners 详解：流量入口

Listener 定义了 Envoy 如何监听端口、解析协议以及应用过滤器。一个最小可用的 Listener 包含以下结构：

static_resources:
  listeners:
  - name: ingress_listener
    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: backend_cluster
          http_filters:
          - name: envoy.filters.http.router

核心字段说明：

  • address.socket_address： 绑定 IP 和端口，0.0.0.0 表示监听所有网络接口。
  • filter_chains： 过滤器链，至少包含一个网络过滤器。HTTP 场景下使用 http_connection_manager。
  • route_config： 定义虚拟主机和路由规则，将请求映射到目标 cluster。

4.4 Clusters 详解：流量出口

Cluster 定义了一组提供相同服务的上游端点。Envoy 根据负载均衡策略将请求分发到这些端点。

  clusters:
  - name: backend_cluster
    connect_timeout: "0.25s"
    type: STRICT_DNS
    dns_lookup_family: V4_ONLY
    lb_policy: ROUND_ROBIN
    load_assignment:
      cluster_name: backend_cluster
      endpoints:
      - lb_endpoints:
        - endpoint:
            address:
              socket_address:
                address: "10.0.0.1"
                port_value: 8080
        - endpoint:
            address:
              socket_address:
                address: "10.0.0.2"
                port_value: 8080
字段 说明 常用值
type 端点发现方式 STRICT_DNS（DNS 解析）、STATIC（静态 IP）、EDS（动态）
lb_policy 负载均衡算法 ROUND_ROBIN、LEAST_REQUEST、RING_HASH
connect_timeout 与上游建立连接的超时时间 "0.25s"、"1s"
load_assignment 静态端点列表（type=STATIC 或 STRICT_DNS 时使用） 包含 lb_endpoints 数组

4.5 Admin 接口：运行时调试入口

Admin 模块为运维人员提供 HTTP 管理端点，用于查看配置、统计、日志级别调整等。变更门禁调试中，/config_dump 和 /stats 是最常用的两个端点。

admin:
  address:
    socket_address:
      address: "0.0.0.0"
      port_value: 9901

启动后可通过 curl http://127.0.0.1:9901/stats 查看实时指标，或通过 curl http://127.0.0.1:9901/config_dump 导出当前生效配置。

安全提示： 生产环境中 admin 端口不应暴露到公网，建议绑定到 127.0.0.1 或通过防火墙限制访问。

4.6 启动 Envoy 实例

将上述配置保存为 envoy-static.yaml，使用以下命令启动 Envoy：

# 使用 docker 运行（推荐）
docker run --rm -v $(pwd)/envoy-static.yaml:/etc/envoy/envoy.yaml \
  -p 10000:10000 -p 9901:9901 \
  envoyproxy/envoy:v1.28-latest \
  -c /etc/envoy/envoy.yaml

# 或直接使用本地二进制
envoy -c envoy-static.yaml --log-level info

启动后验证：

  • 访问 http://localhost:9901/stats 确认 admin 接口正常。
  • 访问 http://localhost:10000 测试流量是否被代理到上游端点。

4.7 静态配置整体架构图

下图展示了静态配置中 Listener、Cluster 和 Admin 三者的关系，以及请求从入站到转发的完整路径：

Envoy 静态配置架构图 Envoy 静态配置核心组件与请求流 外部客户端 Listener 0.0.0.0:10000 HTTP Connection Manager Cluster backend_cluster STRICT_DNS / ROUND_ROBIN 上游 Admin 接口 0.0.0.0:9901 运维人员 说明： 1. 外部客户端请求到达 Listener（端口 10000），经过 HTTP 过滤器链。 2. Listener 根据路由规则将请求转发到 Cluster（backend_cluster）。 3. Cluster 按负载均衡策略将请求分发到上游端点；Admin 接口（9901）独立于数据面。

4.8 完整静态配置示例

将上述 Listener、Cluster 和 Admin 合并为一个完整的 envoy-static.yaml：

static_resources:
  listeners:
  - name: ingress_listener
    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: backend_cluster
          http_filters:
          - name: envoy.filters.http.router
  clusters:
  - name: backend_cluster
    connect_timeout: "0.25s"
    type: STRICT_DNS
    dns_lookup_family: V4_ONLY
    lb_policy: ROUND_ROBIN
    load_assignment:
      cluster_name: backend_cluster
      endpoints:
      - lb_endpoints:
        - endpoint:
            address:
              socket_address:
                address: "10.0.0.1"
                port_value: 8080
        - endpoint:
            address:
              socket_address:
                address: "10.0.0.2"
                port_value: 8080
admin:
  address:
    socket_address:
      address: "0.0.0.0"
      port_value: 9901
快速验证： 将上述配置保存后启动 Envoy，然后执行 curl -v http://localhost:10000/，观察是否返回上游服务的响应。若未部署上游服务，可先启动一个简单的 HTTP 服务器（如 python3 -m http.server 8080）作为测试端点。
← 上一章 📖 返回目录 下一章 →