3. 静态配置入门：使用静态YAML配置启动Envoy，实现一个最简单的TCP代理
Envoy 的配置方式分为静态配置和动态配置（xDS）。对于初学者或固定拓扑场景，静态配置是最直接、最可控的入门方式。本章将使用一个纯静态 YAML 配置文件，启动 Envoy 并实现一个最简单的 TCP 代理——将客户端的 TCP 流量透明转发到上游服务。
3.1 核心概念：Listener、Filter、Cluster
在编写配置之前，需要理解 Envoy 代理的三个核心抽象层。它们构成了 Envoy 数据平面的基本骨架。
| 组件 | 角色 | 类比 |
|---|---|---|
| Listener | 定义 Envoy 在哪个 IP:Port 上监听入站连接 | 大门（入口） |
| Filter | 对经过 Listener 的流量进行匹配、处理或转发决策 | 门卫（检查与路由） |
| Cluster | 定义上游服务（目标后端）的地址、端口、负载均衡策略 | 目的地列表（地址簿） |
关键理解： 在 TCP 代理场景中，Filter 的作用是“匹配所有 TCP 连接，并将其转发到指定的 Cluster”。不需要 HTTP 协议解析，因此使用
envoy.filters.network.tcp_proxy 过滤器。
3.2 静态配置结构总览
一个完整的 Envoy 静态配置文件是一个 YAML 文档，顶层包含 admin、static_resources 等关键字段。下面是最简 TCP 代理的配置骨架：
admin:
address:
socket_address:
address: 0.0.0.0
port_value: 9901
static_resources:
listeners:
- name: listener_0
address:
socket_address:
address: 0.0.0.0
port_value: 10000
filter_chains:
- filters:
- name: envoy.filters.network.tcp_proxy
typed_config:
"@type": type.googleapis.com/envoy.extensions.filters.network.tcp_proxy.v3.TcpProxy
stat_prefix: tcp_proxy
cluster: backend_service
clusters:
- name: backend_service
type: STRICT_DNS
lb_policy: ROUND_ROBIN
load_assignment:
cluster_name: backend_service
endpoints:
- lb_endpoints:
- endpoint:
address:
socket_address:
address: 127.0.0.1
port_value: 8080
配置要点：
- admin：暴露 Envoy 管理接口（端口 9901），用于健康检查和指标采集。
- listeners：监听 0.0.0.0:10000，接收所有 TCP 连接。
- filter_chains：使用
tcp_proxy过滤器，将流量转发到名为backend_service的 Cluster。 - clusters：定义上游为 127.0.0.1:8080，使用 STRICT_DNS 类型和轮询负载均衡。
3.3 流量路径与组件交互
下图展示了客户端请求经过 Envoy TCP 代理到达后端服务的完整数据流：
3.4 启动与验证步骤
按照以下步骤启动 Envoy 并验证 TCP 代理是否正常工作：
- 准备后端服务：使用
nc或python启动一个简单的 TCP 回显服务监听 8080 端口。 - 编写配置文件：将上述 YAML 保存为
envoy-tcp.yaml。 - 启动 Envoy：
envoy -c envoy-tcp.yaml --log-level info - 验证管理接口：
curl http://localhost:9901/server_info - 测试 TCP 代理：
echo "Hello Envoy" | nc localhost 10000
常见问题：
- 如果 Envoy 启动失败，检查 YAML 缩进是否正确（Envoy 对缩进敏感）。
- 确保后端服务先于 Envoy 启动，否则 Envoy 会报告 Cluster 无健康端点。
- 管理接口端口 9901 不要与业务端口 10000 冲突。
3.5 配置参数详解
下表对 TCP 代理配置中的关键参数进行说明：
| 参数路径 | 值示例 | 说明 |
|---|---|---|
listeners[].address.socket_address.port_value |
10000 | Envoy 监听的端口，客户端连接的目标端口 |
filter_chains[].filters[].typed_config.cluster |
backend_service | 指定流量转发到的 Cluster 名称，必须与 clusters 中定义一致 |
clusters[].type |
STRICT_DNS | Cluster 发现类型：STATIC（静态IP）、STRICT_DNS（DNS解析）、LOGICAL_DNS |
clusters[].lb_policy |
ROUND_ROBIN | 负载均衡策略：ROUND_ROBIN、LEAST_REQUEST、RING_HASH 等 |
load_assignment.endpoints[].lb_endpoints[].endpoint.address.socket_address |
127.0.0.1:8080 | 上游服务的实际 IP 和端口 |
3.6 进阶：多端点与负载均衡
静态配置同样支持定义多个上游端点，Envoy 会自动进行负载均衡。下面是一个包含两个后端实例的 Cluster 配置片段：
clusters:
- name: backend_service
type: STATIC
lb_policy: ROUND_ROBIN
load_assignment:
cluster_name: backend_service
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
生产建议： 在开发环境使用
STATIC 类型直接写死 IP；在测试环境使用 STRICT_DNS 配合 DNS 轮询；生产环境推荐使用动态 xDS 实现服务发现。