企业官网建设流程全解析

Envoy 运行实战：从 Demo 配置启动、--config-yaml 覆盖，到配置校验与日志控制

【免费下载链接】envoyCloud-native high-performance edge/middle/service proxy项目地址: https://gitcode.com/GitHub_Trending/en/envoy

本文以 Envoy 官方文档中的《Run Envoy》快速入门为核心，讲解如何将 Envoy 作为系统守护进程或 Docker 容器启动：如何使用-c/--config-path加载 demo 配置、如何用--config-yaml覆盖默认配置、如何用--mode validate做无网络副作用的配置校验，以及--log-path、--log-level、--component-log-level三类日志控制手段。读完本文，你可以独立跑通一个可代理真实流量的 Envoy 实例，并深入理解这些命令行参数在 source/server/options_impl.cc 中的实际解析逻辑。

两种运行形态：系统二进制与 Docker 镜像

安装完成 Envoy 后（系统二进制或 Docker 镜像两种形态），可以先确认版本信息：

系统形态：

$ envoy --version

Docker 形态：

$ docker run --rm \ envoyproxy/envoy:latest \ --version

通过--help可以查看全部命令行选项（系统形态执行envoy --help，Docker 形态将--version换成--help即可）。完整的选项定义可以在 source/server/options_impl.cc 中找到——该文件使用 TCLAP 逐一定义了--config-path、--config-yaml、--mode、--log-path、--log-level等参数。

用 demo 配置启动：-c/--config-path

-c或--config-path参数用于告诉 Envoy 初始配置文件的路径。Envoy 会根据文件扩展名解析配置内容。

系统形态：先获取 demo 配置（对应仓库中的 configs/envoy-demo.yaml），然后启动：

$ envoy -c envoy-demo.yaml

Docker 形态：不指定配置文件时，镜像会直接使用内置的 demo 配置：

$ docker run --rm -it \ -p 9901:9901 \ -p 10000:10000 \ envoyproxy/envoy:latest

要指定自定义配置，可将配置文件挂载进容器并用-c指定路径。假设当前目录下有一个名为envoy-custom.yaml的自定义配置：

$ docker run --rm -it \ -v $(pwd)/envoy-custom.yaml:/envoy-custom.yaml \ -p 9901:9901 \ -p 10000:10000 \ envoyproxy/envoy:latest \ -c /envoy-custom.yaml

启动后可通过以下命令验证代理是否生效：

$ curl -v localhost:10000

按Ctrl-c可以退出服务。

从源码看 Docker 镜像的默认配置

从 distribution/docker/Dockerfile-envoy 可以看到，镜像构建时将 configs/envoyproxy_io_proxy.yaml 打入镜像的/etc/envoy/envoy.yaml，并设置CMD ["envoy", "-c", "/etc/envoy/envoy.yaml"]，ENTRYPOINT指向 docker-entrypoint.sh：

ADD configs/envoyproxy_io_proxy.yaml /etc/envoy/envoy.yaml EXPOSE 10000 CMD ["envoy", "-c", "/etc/envoy/envoy.yaml"] ENTRYPOINT ["/docker-entrypoint.sh"]

因此“Docker 默认 demo 配置”实际来自 configs/envoyproxy_io_proxy.yaml。它与 configs/envoy-demo.yaml 结构几乎一致（admin 端口 9901、监听 10000、将流量转发到www.envoyproxy.io:443），差异在于：镜像内置配置额外包含connect_timeout: 30s与scheme_header_transformation: scheme_to_overwrite: https，且默认不带 stdout 访问日志。

demo 配置做了什么

configs/envoy-demo.yaml 是一份极简但完整的静态配置，值得逐段理解：

admin: address: socket_address: protocol: TCP address: 0.0.0.0 port_value: 9901 # Admin 接口，可用 curl 访问 /stats 等端点 static_resources: listeners: - name: listener_0 address: socket_address: protocol: TCP 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 access_log: - name: envoy.access_loggers.stdout typed_config: "@type": type.googleapis.com/envoy.extensions.access_loggers.stream.v3.StdoutAccessLog route_config: name: local_route virtual_hosts: - name: local_service domains: ["*"] # 匹配所有 Host routes: - match: prefix: "/" route: host_rewrite_literal: www.envoyproxy.io cluster: service_envoyproxy_io http_filters: - name: envoy.filters.http.router typed_config: "@type": type.googleapis.com/envoy.extensions.filters.http.router.v3.Router clusters: - name: service_envoyproxy_io type: LOGICAL_DNS dns_lookup_family: V4_ONLY # 注释掉可在 IPv6 环境测试 lb_policy: ROUND_ROBIN load_assignment: cluster_name: service_envoyproxy_io endpoints: - lb_endpoints: - endpoint: address: socket_address: address: www.envoyproxy.io port_value: 443 transport_socket: name: envoy.transport_sockets.tls typed_config: "@type": type.googleapis.com/envoy.extensions.transport_sockets.tls.v3.UpstreamTlsContext sni: www.envoyproxy.io

其工作链路为：0.0.0.0:10000的 HTTP 监听器 →http_connection_manager网络过滤器按local_route路由 → 匹配所有前缀的请求改写 Host 为www.envoyproxy.io并转发到上游集群service_envoyproxy_io（LOGICAL_DNS 集群，TLS + SNI）。这也解释了为什么curl localhost:10000能看到www.envoyproxy.io的响应。

用--config-yaml覆盖默认配置

--config-yaml参数可提供一个覆盖配置，它会与主配置进行合并。该参数只能指定一次。在 source/server/options_impl.cc 中的定义印证了这一点：

TCLAP::ValueArg<std::string> config_yaml( "", "config-yaml", "Inline YAML configuration, merges with the contents of --config-path", ...

将以下片段保存为envoy-override.yaml，把 admin 端口改为 9902：

admin: address: socket_address: address: 127.0.0.1 port_value: 9902

警告：如果在 Docker 容器内运行 Envoy，可能需要使用0.0.0.0。以这种方式暴露 admin 接口可能会带来非预期的控制权限，生产环境应谨慎。

启动方式：

系统形态（Linux/Mac）：

$ envoy -c envoy-demo.yaml --config-yaml "$(cat envoy-override.yaml)"

Docker 形态：

$ docker run --rm -it \ -p 9902:9902 \ -p 10000:10000 \ envoyproxy/envoy:latest \ -c /etc/envoy/envoy.yaml \ --config-yaml "$(cat envoy-override.yaml)"

此时 admin 接口应可在http://localhost:9902访问：

$ curl -v localhost:9902

合并语义的重要限制：合并 YAML 列表（如listeners或clusters）时，合并后的配置是**追加（append）**关系。因此你无法通过覆盖文件去修改此前已指定的 listener 或 cluster 的配置——覆盖配置只能追加新的条目或覆盖标量字段（如 admin 地址）。

校验配置：--mode validate

--mode validate让 Envoy 在不实际启动服务、不建立任何网络连接的前提下，验证配置是否能让 Envoy 正常启动：

• 配置有效：进程输出OK，返回码为0；
• 配置无效：进程输出错误信息，返回码为1。

系统形态：

$ envoy --mode validate -c my-envoy-config.yaml [2020-11-08 12:36:06.543][11][info][main] [source/server/server.cc:583] runtime: layers: - name: base static_layer: {} - name: admin admin_layer: {} [2020-11-08 12:36:06.543][11][info][config] [source/server/configuration_impl.cc:95] loading tracing configuration [2020-11-08 12:36:06.543][11][info][config] [source/server/configuration_impl.cc:70] loading 0 static secret(s) [2020-11-08 12:36:06.543][11][info][config] [source/server/configuration_impl.cc:76] loading 1 cluster(s) [2020-11-08 12:36:06.546][11][info][config] [source/server/configuration_impl.cc:80] loading 1 listener(s) [2020-11-08 12:36:06.549][11][info][config] [source/server/configuration_impl.cc:121] loading stats sink configuration configuration 'my-envoy-config.yaml' OK

Docker 形态（需先把配置挂载进容器）：

$ docker run --rm \ -v $(pwd)/my-envoy-config.yaml:/my-envoy-config.yaml \ envoyproxy/envoy:latest \ --mode validate \ -c my-envoy-config.yaml

从源码看，options_impl.cc 中--mode支持三个取值：serve（默认，校验配置后正常提供流量）、validate（校验后退出）和init_only，未知取值会抛出unknown mode错误。这一模式非常适合放进 CI 流水线做配置准入检查。

日志：系统日志与访问日志的分流

默认情况下，Envoy 的系统日志输出到/dev/stderr，可用--log-path覆盖为文件：

系统形态：

$ mkdir logs $ envoy -c envoy-demo.yaml --log-path logs/custom.log

Docker 形态（注意挂载目录权限，容器内的 envoy 是非 root 用户运行，需对挂载目录开放写权限）：

$ mkdir logs $ chmod go+rwx logs/ $ docker run --rm -it \ -p 10000:10000 \ -v $(pwd)/logs:/logs \ envoyproxy/envoy:latest \ -c /etc/envoy/envoy.yaml \ --log-path logs/custom.log

访问日志（access log）的路径可在 admin 接口与已配置的 listener 上设置。configs/envoy-demo.yaml 中就配置了一个将访问日志输出到/dev/stdout的监听器：

access_log: - name: envoy.access_loggers.stdout typed_config: "@type": type.googleapis.com/envoy.extensions.access_loggers.stream.v3.StdoutAccessLog

容器场景下，系统日志走/dev/stderr、访问日志走/dev/stdout是一个实用的分流方式：两类流可以分别采集，且无需额外挂载文件目录。此外，Envoy 的部分过滤器与扩展还具备额外的日志能力，并且可以配置不同的访问日志格式与输出目标（文件、stdout/err 之外还可以对接其他输出）。

网络配置：IPv4 / IPv6 与dns_lookup_family

默认情况下 Envoy 同时使用 IPv4 和 IPv6 网络。如果你的环境不支持 IPv6（例如非 Linux 宿主机上运行 Docker 时常见），应将其禁用。做法是在集群配置中将dns_lookup_family设为V4_ONLY，即 configs/envoy-demo.yaml 中的这一段：

- name: service_envoyproxy_io type: LOGICAL_DNS # Comment out the following line to test on v6 networks dns_lookup_family: V4_ONLY lb_policy: ROUND_ROBIN

注释掉该行即可在支持 IPv6 的环境中进行测试。

调试：日志级别与组件级细粒度控制

Envoy 系统日志级别通过-l或--log-level设置，可用级别包括：

• trace
• debug
• info
• warning/warn
• error
• critical
• off

默认级别为info（在 options_impl.cc 中，未显式指定--log-level时使用默认日志级别）。

还可以用--component-log-level对特定组件单独设置日志级别。下面的示例抑制了除upstream与connection之外的所有组件日志，并分别将它们设为debug与trace：

系统形态：

$ envoy -c envoy-demo.yaml -l off --component-log-level upstream:debug,connection:trace

Docker 形态：

$ docker run --rm -d \ -p 9901:9901 \ -p 10000:10000 \ envoyproxy/envoy:latest \ -c /etc/envoy/envoy.yaml \ -l off \ --component-log-level upstream:debug,connection:trace

提示：可用组件（logger）的完整清单见 source/common/common/logger.h 中的ALL_LOGGER_IDS宏定义，其中按字母序列出了admin、config、connection、http、upstream等全部 logger ID。

关键参数速查

以上所有命令行参数的定义与解析逻辑均可在 source/server/options_impl.cc 中查证；其中parseComponentLogLevels（options_impl.cc）负责把逗号分隔的组件:级别列表拆分为各组件的独立级别配置。配合 configs/envoy-demo.yaml 这份最小可运行配置，即可在本地快速搭建、调试并校验一个 Envoy 代理服务。

【免费下载链接】envoyCloud-native high-performance edge/middle/service proxy项目地址: https://gitcode.com/GitHub_Trending/en/envoy