Envoy 项目全景导读：云原生边缘/中间/服务代理的架构、文档与开发路径

Envoy 是由 CNCF（云原生计算基金会）托管的云原生高性能边缘/中间/服务代理（edge/middle/service proxy），本仓库即其官方主仓库。本文以仓库根目录 README.md 为骨架，结合 what_is_envoy.rst 的架构阐述、REPO_LAYOUT.md 的目录导航与 CONTRIBUTING.md 的工程规范，系统梳理 Envoy 的核心能力、文档体系、仓库结构、安全机制与贡献路径，帮助你快速定位代码、配置与文档资源，建立对这套数据平面方案的完整认知。

项目定位：让网络对应用透明

Envoy 被定位为「Cloud-native high-performance edge/middle/service proxy」——一套既能充当南北向边缘网关、又能充当东西向服务间通信总线的高性能代理。它由 Cloud Native Computing Foundation（CNCF） 托管，项目诞生之初秉持一个核心信念：

网络应当对应用透明。当网络和应用问题发生时，应当能够轻松定位问题根源。

围绕这一目标，Envoy 选择了进程外（out of process）架构：它是一个自包含的独立进程，部署在每个应用服务器旁边；所有 Envoy 共同组成一张透明的通信网格，每个应用只与 localhost 通信，完全感知不到网络拓扑。相比传统「将通信逻辑做成库」的方式，这种架构带来两个显著收益：

• 语言无关：单一 Envoy 部署即可在 Java、C++、Go、PHP、Python 等语言服务之间搭起网格，透明地弥合多语言微服务架构的通信鸿沟；
• 升级解耦：库升级在大规模服务架构中极其痛苦，而 Envoy 可以在整个基础设施中快速、透明地部署和升级。

仓库当前开发版本为 1.40.0-dev（见 VERSION.txt），历史版本变更记录集中在 changelogs/，每份版本变更均按行为变更、缺陷修复、弃用、新特性等分类归档。

核心能力全景

结合 docs/root/intro/what_is_envoy.rst，Envoy 的核心能力可以概括为以下十一个方面：

L3/L4 过滤器架构

Envoy 本质上是一个 L3/L4 网络代理，通过可插拔的过滤器链机制（network filter chain）完成各种 TCP/UDP 代理任务。已实现的过滤器涵盖原始 TCP proxy、UDP proxy、HTTP proxy、TLS 客户端证书认证、Redis、MongoDB、Postgres 等协议，对应源码位于 source/extensions/filters/network/ 与 source/extensions/filters/listener/。

HTTP L7 过滤器架构

HTTP 在现代应用架构中至关重要，因此 Envoy 在 HTTP 连接管理（HTTP connection manager）子系统之上额外提供了一层 L7 过滤器架构。HTTP 过滤器可完成缓冲（buffering）、限流（rate limiting）、路由转发、DynamoDB 嗅探等任务，源码位于 source/extensions/filters/http/。

一等公民的 HTTP/2 与 HTTP/3

HTTP 模式下 Envoy 同时支持 HTTP/1.1 和 HTTP/2，且可在任意方向上透明互转，即任意 HTTP/1.1 与 HTTP/2 客户端/服务端的组合都能桥接。推荐的 service-to-service 配置是 Envoy 之间全部使用 HTTP/2，形成请求/响应多路复用的长连接网格。自 1.19.0 起，Envoy 还支持 HTTP/3（upstream 与 downstream 双向），可在 HTTP/1.1、HTTP/2、HTTP/3 任意组合间互译，相关文档见 docs/root/intro/arch_overview/http/http3.rst。

HTTP L7 路由

HTTP 模式下 Envoy 具备完整的路由子系统，可基于路径（path）、authority、content type、运行时（runtime）值等条件进行路由与重定向，是前端/边缘代理场景的核心能力，也被用于构建 service-to-service 网格。

gRPC 支持

gRPC 以 HTTP/2 为底层多路复用传输，Envoy 支持作为 gRPC 请求/响应路由与负载均衡底座所需的全部 HTTP/2 特性，两者高度互补。

服务发现与动态配置（xDS）

Envoy 可选地消费一套分层动态配置 API（xDS）实现集中化管理，可动态更新：后端集群内的主机、集群本身、HTTP 路由、监听 socket、加密材料。简单部署时，后端主机发现也可退化为 DNS 解析（strict DNS）甚至纯静态配置（static），见 configs/ads.yaml 与 api/ 下的数据平面 API 定义。

健康检查

构建 Envoy 网格的推荐方式是把服务发现视为最终一致的过程：Envoy 内置健康检查子系统，可对上游服务集群执行主动健康检查，并与服务发现信息取并集决定健康负载均衡目标；同时通过异常点检测（outlier detection）子系统支持被动健康检查。

高级负载均衡

由于是自包含代理而非库，Envoy 能在单一位置实现并被任意应用复用各种高级负载均衡技术：自动重试（automatic retries）、熔断（circuit breaking）、基于外部限流服务的全局限流、请求影子（request shadowing，即流量镜像）、异常点检测等，详见 docs/root/intro/arch_overview/upstream/load_balancing/。

前端/边缘代理支持

同一套软件用于边缘带来的收益（可观测性、管理、一致的服务发现与负载均衡算法）非常可观。Envoy 具备 TLS 终止、HTTP/1.1/2/3 支持与 L7 路由，适合绝大多数现代 Web 应用的边缘场景。

一流可观测性

Envoy 为所有子系统提供健壮的统计（statistics）支持，默认支持 statsd（及兼容 provider）作为统计 sink，并可通过**管理接口（admin interface）**直接查看统计；同时通过第三方 provider 支持分布式追踪（tracing）。相关文档见 docs/root/intro/arch_overview/observability/。

仓库布局导航

REPO_LAYOUT.md 给出了顶层目录的高层视图，这是进入代码前的第一张地图：

目录	职责
api/	Envoy 数据平面 API（proto 定义）
bazel/	Envoy 使用 Bazel 的构建配置
changelogs/	各版本的发布变更日志
ci/	CI 及 Docker 容器构建脚本
compat/	OpenSSL 兼容层
configs/	Envoy 示例配置（如 envoy-demo.yaml、admin-interface.yaml）
contrib/	非核心贡献扩展，布局镜像 source/extensions/，见 EXTENSION_POLICY.md
distribution/	打包与分发（Debian 包、Docker 镜像等）
docs/	面向最终用户的 Envoy 与数据平面 API 文档
envoy/	核心 Envoy 的「公共」接口头文件，绝大多数为 100% 抽象类
mobile/	Envoy Mobile：iOS / Android 平台库
restarter/	热重启（hot restart）包装 Python 脚本 hot-restarter.py
source/	核心 Envoy 及扩展的源码
test/	核心 Envoy 及扩展的测试代码
tools/	各类辅助工具

source/ 内部结构

source/ 下四个关键子目录：

• source/common/：核心代码（与扩展无关，也与独立 server 实现无关），理论上可被嵌入为库使用；
• source/exe/：构建最终生产 Envoy server 二进制（envoy-static）的专属代码；
• source/extensions/：核心 Envoy 的扩展；
• source/server/：以独立 server 方式运行 Envoy 的代码（配置、启动、worker 等）。

测试侧与之对应：test/common/、test/exe/、test/server/ 为单元测试，test/extensions/ 为扩展单元测试，test/integration/ 为使用真实 Envoy server 代码、fake 下游客户端与 fake 上游服务器的端到端集成测试，test/mocks/ 提供 envoy/ 中所有核心接口的 mock 实现。

扩展的命名空间纪律

仓库对扩展维护了非常严格的代码与命名空间布局，便于发现代码并支持在 CODEOWNERS 中指定扩展 owner。要点包括：

• 所有扩展注册在 source/extensions/all_extensions.bzl（不可从构建中移除）或 source/extensions/extensions_build_config.bzl（可按站点移除）；
• 顶层扩展目录与命名空间一一对应，例如 HTTP L7 过滤器使用 Envoy::Extensions::HttpFilters 命名空间、L4 网络过滤器使用 Envoy::Extensions::NetworkFilters、监听器过滤器使用 Envoy::Extensions::ListenerFilters；
• 每个扩展整体封闭在自己的命名空间中（如 Envoy::Extensions::NetworkFilters::Echo）；
• 多扩展共享的公共代码放在尽量靠近的 common/ 目录（如 source/extensions/filters/common/）。

文档体系：从 README 出发的阅读路径

README 将官方文档作为第一入口，仓库内的 docs/ 则以 reStructuredText（.rst）组织，围绕 docs/root/index.rst 展开，主要分支包括：

• intro/：入门与架构总览，核心是 what_is_envoy.rst、life_of_a_request.rst（一次请求的完整生命周期，含 life-of-a-request.yaml 示例）与 deployment_types/（前端代理、service-to-service、双重代理三种部署形态）；
• configuration/：面向运维的配置参考；
• operations/：运行时、热重启、动态配置、排空（draining）、过载管理等运维主题；
• extending/：如何扩展 Envoy；
• api-v3/：v3 API 参考；
• faq/：常见问题。

快速上手时，仓库 configs/ 目录提供了大量可直接阅读的示例配置（front-proxy、service-to-service、HTTP/3 上游/下游、gRPC 桥接、JWT 认证、UDP 隧道等），是理解配置语义的最佳配套材料。

相关项目生态

README 列出了三个紧密相关的姊妹仓库：

• data-plane-api：v2 API 定义的独立仓库，是 api/ 的只读镜像；
• envoy-perf：Envoy 性能测试框架；
• envoy-filter-example：演示如何新增过滤器并链接到主仓库的示例工程。

构建与开发支持

对开发者而言，README 指向了以下资源：

• Docker 快速构建/测试：见 ci/ 目录（ci#building-and-running-tests-as-a-developer），包含 do_ci.sh、build_setup.sh 等脚本；
• 开发者指南：DEVELOPER.md；
• 开发支持工具链：support/README.md，其中的 support/bootstrap 会安装 pre-commit / pre-push Git 钩子，自动化代码审查等环节的部分工作。

社区与联系方式

Envoy 维护了一套分层的邮件列表体系，按信息频率与受众严格区分：

列表	用途
envoy-announce	低频公告列表，仅发送公告
envoy-security-announce	仅发送安全相关公告
envoy-users	一般用户讨论
envoy-dev	开发者讨论（API、特性设计等）
envoy-maintainers	联系所有核心维护者

此外还有 Slack（envoyproxy.slack.com）与 Twitter。需要留意的是：Slack 上的用户问题回复属于「尽力而为」，如需「有保障」的回复，应按官方指引通过 envoy-users 邮件列表提问。

参与贡献：工程规范要点

CONTRIBUTING.md 详细规定了贡献流程，核心要点如下：

沟通先行

「重大特性」定义为改动超过 100 行（不含测试）或改变任何用户可见行为的变更。动手前必须先通过 GitHub、Slack、邮件等渠道沟通，确认无人重复工作，并开启 GitHub issue 讨论设计；新增扩展前务必先阅读 EXTENSION_POLICY.md。小补丁与缺陷修复则无需事先沟通。

编码风格与包容性语言

所有 PR 必须遵循 STYLE.md；同时社区有明确的包容性语言政策：禁止使用 whitelist（改用 allowlist）、blacklist（改用 denylist/blocklist）、master（改用 primary/main）、slave（改用 secondary/replica）。

破坏性变更（breaking change）政策

API 与实现稳定性对 Envoy 都至关重要：特性可随时在某个版本化 API 中标记弃用，但前提是 main 上已有替代实现与配置路径；弃用配置会在下一个大版本 API 中被删除。弃用节奏分两阶段：首个发布周期内使用弃用特性会产生警告日志并递增 runtime.deprecated_feature_use 统计；第二个发布周期则会导致配置加载失败，除非在 runtime 配置中显式覆盖（见 configs/using_deprecated_config.yaml 示例）或开启 envoy.features.enable_all_deprecated_features。所有弃用/破坏性变更都会清晰列在版本历史中，高危变更还会通过 envoy-announce 公告。

提交 PR 的流程

1. Fork 仓库，本地执行 ./support/bootstrap 安装 Git 钩子；
2. 新增代码必须附带覆盖测试，项目要求新增代码 100% 测试覆盖率；
3. 改变用户可见行为的 PR 必须在 docs/ 补文档，并在 changelogs/current/ 添加 release note 片段（命名形如 http__added-new-request-stat.rst，分区与区域见 changelogs/changelogs.yaml）；
4. 未通过测试的 PR 不会被合并；review 开始后请勿 rebase。

Runtime guarding（运行时护栏）

对高风险行为变更，Envoy 常用 runtime guard 双轨过渡：

if (Runtime::runtimeFeatureEnabled("envoy.reloadable_features.my_feature_name")) {
  // 新代码路径
} else {
  // 旧代码路径
}

以 envoy.reloadable_features. 前缀命名的特性必须允许在运行中的 Envoy 实例上安全翻转开关；所有 runtime 特性默认开启于 source/common/runtime/runtime_features.cc。行为类变更的旧代码路径在六个月无人提出异议后进入弃用流程，高风险重构类旧路径则在发布后清理。

DCO 签名与 AI 使用政策

Envoy 要求每个 commit 带 Developer Certificate of Origin 签名（Signed-off-by: 真实姓名 <邮箱>），support/bootstrap 钩子可在提交时自动补上；PR 失败时可交互式 squash 历史并 git push -f 修复 DCO。项目还明确了生成式 AI 使用政策：允许用 AI 辅助写代码与审查 PR，但提交者必须完全理解所提交的代码、对审查意见负责、在 PR 描述中透明披露 AI 使用，且所有生成代码须以与 Envoy 相同的许可证发布；不允许提交者本人不理解或未完全负责的 PR。

社区会议

Envoy 团队每两周在周二早 9 点（太平洋时间）召开社区例会，公共日历与会议纪要均公开。例会仅在存在议程项时举行，任何社区成员都可通过在会议纪要中添加议程来提议议题，维护者会在 24 小时内确认或取消会议。

安全机制

安全审计

项目开展过多次第三方安全审计：2018 年 Cure53 执行的安全审计（完整报告见 docs/security/），以及 2021 年 Ada Logics 对 fuzzing 基础设施的审计与改进建议。

漏洞报告

发现漏洞或潜在漏洞时，首选渠道是在 GitHub 上开启 Security Advisory，报告可直接在 GitHub 上分诊；也可邮件 [e-mail]。完整流程见 SECURITY.md。

OSS fuzzing 与架构支持边界

Envoy 长期参与 OSS-Fuzz 项目（状态徽章见 README）。需要特别留意安全政策边界：ppc64le 架构的构建不在 Envoy 安全政策覆盖范围内，该架构当前属于 best-effort、不由维护者维护；s390x 构建同样有独立的 CI 状态跟踪。

版本与发布

版本的发布流程细节见 RELEASES.md，回移植（backport）政策见 BACKPORTS.md。仓库 changelogs/ 完整保存了从 1.0.0 到当前版本的全部版本变更，changelogs/current/ 则按 behavior_changes、bug_fixes、deprecated、minor_behavior_changes、new_features、removed_config_or_runtime 六个分区持续累积待发布变更，是观察项目演进方向的最佳窗口。

小结

作为 Envoy 官方仓库的入口文档，README 将「文档、相关项目、联系渠道、贡献规范、社区会议、安全策略、发布流程」七条线串成一张完整的项目导航图。把它与 what_is_envoy.rst 的架构阐述、REPO_LAYOUT.md 的目录地图、CONTRIBUTING.md 的工程规范配合阅读，你便能在几分钟内建立对 Envoy 能力边界、代码位置与协作方式的全局认知——无论是作为使用者定位配置，还是作为开发者提交第一个 PR，这张地图都足够可靠。