📚 课程目录第4章 Envoy静态配置入门

4. Envoy 静态配置入门：静态配置 YAML 结构（node、static_resources、admin）、启动与验证

Envoy 的配置方式分为静态配置和动态配置（xDS）两种。本章聚焦于静态配置，即所有监听器、路由、集群等信息均在一个 YAML 文件中定义，不依赖外部控制面。静态配置是理解 Envoy 核心模型的最佳起点，也是小型部署或测试环境的首选方案。

4.1 静态配置顶层结构

一个完整的 Envoy 静态配置文件包含三个必选顶层字段：node、static_resources 和 admin。其结构如下：

  📌 核心要点： 静态配置 = 节点标识 + 资源定义 + 管理接口。三者缺一不可，否则 Envoy 启动时会报错。

字段	作用	是否必填	说明
`node`	标识当前 Envoy 实例的身份	是	包含 `id`、`cluster`、`metadata` 等子字段
`static_resources`	定义监听器、路由、集群等核心资源	是	包含 `listeners`、`clusters`、`secrets` 等子字段
`admin`	配置 Envoy 管理接口（HTTP）	是	用于查看配置、统计、日志级别等管理操作

4.2 字段详解

4.2.1 node：实例身份标识

node 字段用于在日志、统计和动态配置中唯一标识当前 Envoy 实例。其典型配置如下：

node:
  id: "ingress-gateway-1"        # 实例唯一 ID
  cluster: "prod-cluster"        # 所属集群名称
  metadata:                      # 自定义元数据（可选）
    role: "ingress"
    region: "cn-north-1"

💡 最佳实践： 在多租户场景中，node.cluster 可用于区分不同租户或环境（如 tenant-a-prod、tenant-b-staging），便于日志聚合和监控。

4.2.2 static_resources：核心资源定义

static_resources 是配置的主体，包含 listeners 和 clusters 两个核心子字段：

listeners：定义 Envoy 监听的端口、协议、过滤器链（FilterChain）以及路由行为。
clusters：定义上游服务集群的端点（Endpoint）、负载均衡策略、健康检查等。

一个最小可用的 static_resources 示例如下：

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
          route_config:
            name: local_route
            virtual_hosts:
            - name: backend
              domains: ["*"]
              routes:
              - match:
                  prefix: "/"
                route:
                  cluster: service_backend
          http_filters:
          - name: envoy.filters.http.router
  clusters:
  - name: service_backend
    type: STRICT_DNS
    lb_policy: ROUND_ROBIN
    load_assignment:
      cluster_name: service_backend
      endpoints:
      - lb_endpoints:
        - endpoint:
            address:
              socket_address:
                address: 10.0.0.1
                port_value: 8080

4.2.3 admin：管理接口

admin 字段配置 Envoy 内置的 HTTP 管理接口，用于运行时查看配置、统计、日志级别调整等。生产环境建议绑定到本地地址并限制访问：

admin:
  address:
    socket_address:
      address: 127.0.0.1
      port_value: 9901

常用管理端点：

/stats — 查看统计指标
/config_dump — 查看当前生效的配置
/logging — 动态调整日志级别
/quitquitquit — 优雅关闭 Envoy

4.3 静态配置完整示例

将上述三个字段组合，得到一个完整的静态配置文件 envoy-static.yaml：

node:
  id: "ingress-gateway-1"
  cluster: "prod-cluster"

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
          route_config:
            name: local_route
            virtual_hosts:
            - name: backend
              domains: ["*"]
              routes:
              - match:
                  prefix: "/"
                route:
                  cluster: service_backend
          http_filters:
          - name: envoy.filters.http.router
  clusters:
  - name: service_backend
    type: STRICT_DNS
    lb_policy: ROUND_ROBIN
    load_assignment:
      cluster_name: service_backend
      endpoints:
      - lb_endpoints:
        - endpoint:
            address:
              socket_address:
                address: 10.0.0.1
                port_value: 8080

admin:
  address:
    socket_address:
      address: 127.0.0.1
      port_value: 9901

4.4 启动与验证

4.4.1 启动 Envoy

使用以下命令启动 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

⚠️ 常见错误： 如果配置文件 YAML 格式错误（如缩进不一致、字段拼写错误），Envoy 会立即退出并打印详细的 JSON 错误信息。建议使用 yamlint 或 IDE 插件提前校验。

4.4.2 验证启动状态

Envoy 启动后，可通过以下方式验证：

检查进程：ps aux | grep envoy
访问管理接口：curl http://127.0.0.1:9901/config_dump，返回 JSON 格式的当前配置。
发送测试请求：curl http://localhost:10000/，观察是否转发到上游服务。
查看日志：启动时 Envoy 会输出 loading static configuration 和 all clusters initialized 等关键日志。

4.5 静态配置结构总览

下图展示了静态配置中 node、static_resources、admin 三个顶层字段及其子字段的层级关系：

4.6 静态配置 vs 动态配置

对比维度	静态配置	动态配置（xDS）
配置来源	本地 YAML 文件	远程控制面（如 Istiod）
变更方式	修改文件 + 重启 Envoy	热更新，无需重启
适用场景	测试、小型部署、边缘节点	大规模集群、服务网格
复杂度	低，适合入门	高，需控制面支持

💡 学习建议： 先通过静态配置掌握 Envoy 的监听器、路由、集群三大核心概念，再过渡到动态配置。静态配置是理解 xDS API 语义的基础。