Day 01 / 共 20 天 · 第 1 周架构与线程

项目全景：云原生代理

欢迎来到 Envoy。这是 higress-group 系列的第一个、也是最底层的项目。第一天建立全局地图：Envoy 是什么、"代理"是什么、目录怎么组织、六大核心术语，以及它在整个 higress 生态里的位置。

📍 你在整门课的位置（这条链贯穿 20 天，每天开头点亮你所在的格子）

Day 1 全景→ W1 架构与线程（D2-5）→ W2 过滤器与请求（D6-10）→ W3 xDS 与上游（D11-15）→ W4 扩展/可观测/构建（D16-20）

L01

Envoy 是什么

🤔 痛点：没有 Envoy 这层，你的业务代码要背多少锅？假设你写了个订单服务。突然要求：后端要部署 5 台做负载均衡、每分钟限流 1000 次、所有流量走 HTTPS、每个请求记延迟、某台后端挂了自动摘除……这些和"下订单"没半点关系，却全得塞进你的业务代码里，每个服务重写一遍——又累又容易出错。

💡 本质：把"网络治理"从业务里剥出来，交给一个专职中间人 Envoy 就像小区的门卫兼前台：所有进出的人（网络请求）都先经过它，由它统一负责登记（可观测）、查名单放行（路由）、拦不速之客（认证限流）、指路（转发到哪台后端）。业主（你的业务代码）只管在屋里干活，这些杂事一概不用操心。本课后面所有概念，都是这个"门卫"的不同零件。

Envoy 是 CNCF 毕业的云原生高性能边缘/服务代理，C++ 编写，由 Lyft 开源。它是 Istio 服务网格、Higress 网关等的数据面内核——真正扛流量、做转发的那一层。

一句话：Envoy = "超级智能的流量中转站" 所有进出你服务的网络请求，都先经过 Envoy。它负责：路由（这个请求该转发到哪）、负载均衡（后端有多台，选哪台）、限流、认证、可观测（记录延迟/错误率）、故障注入、TLS 加解密等。你的业务代码只管写业务，把这些"网络治理"的脏活累活全交给 Envoy。而且它极快（C++ + 精心设计的线程模型），能扛百万级并发连接。本周你会看到它快的秘密。

L02

"代理"是什么

代理 = "中间人" 客户端不直接连你的服务，而是先连"代理"，代理再转发给真正的服务。好比公司前台：访客不直接冲进办公室，而是先到前台，前台帮忙转达、登记、拦截不速之客。Envoy 做的就是这件事，只不过对象是网络请求。下游（downstream）= 连进来的客户端侧；上游（upstream）= Envoy 转发去的后端侧。请求从下游进、被 Envoy 处理、转发到上游、拿回响应、再返回下游。记住"下游=客户端、上游=后端"这个方向，看源码不会晕。

⚠️ 常见误解：很多人凭"上=前、下=后"直觉，误以为"上游=客户端"。其实反了——这里的"上/下游"是按数据流的源头说的：水从客户端"流下来"（下游 downstream），Envoy 把它推向后端这个"上游 upstream"。把 Envoy 想成河中间的水闸：河水从上游后端放出、经水闸流向下游用户——记"后端在上、用户在下"就不会晕。

L03

顶层目录地图

权威依据 REPO_LAYOUT.md：

目录	作用
`api/`	数据面 API，全是 Protobuf（`.proto`）——你写的所有配置的 schema
`envoy/`	核心接口头文件，几乎 100% 纯虚抽象类（interface）
`source/`	核心 + 扩展的真正 C++ 实现
`test/`	测试，镜像 source/ 布局
`bazel/ ci/ configs/`	构建、CI、示例配置

"接口"和"实现"分两个目录（关键设计）注意 envoy/（接口）和 source/（实现）物理分离：envoy/ 里全是"约定"（纯虚类，定义"应该有哪些方法"但不写怎么做），source/ 里才是"干活的代码"。这就是我们在每个框架都见到的"接口/实现分离"，Envoy 用目录结构把它落到了极致。好处：上层代码只依赖接口，实现可替换（比如换个负载均衡算法）。读源码时，想知道"某能力的约定"看 envoy/，想知道"怎么实现"看 source/。

L04

source 内部

目录	内容
`source/common/`	与"独立 server"无关的核心代码（event/、network/、http/、router/、thread_local/），可当库复用
`source/exe/`	生产二进制的入口，真正的 `main()`
`source/server/`	以 standalone server 运行的代码：配置加载、启动、worker 线程
`source/extensions/`	所有可插拔扩展（filters/http 64 个、clusters、tracers…）

读法：common=引擎核心、exe=入口、server=服务器骨架、extensions=可插拔功能。extensions/ 按类别组织（Day 16 详讲），是 Envoy 功能丰富的秘密。

L05

六大术语

术语	大白话
Listener 监听器	Envoy 对外暴露的端口（下游客户端连它）
Cluster 集群	一组等价的上游后端（转发目的地）
Route 路由	"什么请求转发到哪个 Cluster"的规则
Filter 过滤器	可插拔的请求处理单元（L4 字节 / L7 HTTP）
Upstream/Downstream	上游=后端侧，下游=客户端侧
xDS	动态配置发现（LDS/CDS/RDS/EDS，Day 11 详讲）

读法：这六个词是 Envoy 世界的"基本词汇"。一个请求的一生就是：进 Listener → 走 Filter 链 → 按 Route 选 Cluster → 负载均衡到某 Upstream 后端。xDS 让这一切配置能动态热更新。

图注：六大术语不是孤立名词，而是一个请求依次经过的六个"关卡"。记住这条链，后面每天钻进其中一关。

📝 举个例子：一次真实访问怎么走完这条链客户端发 GET https://shop.com/api/order → 撞上 443 端口的 Listener（大门）→ 过 Filter 链（TLS 解密、查 JWT 认证、限流）→ Route 按 /api/ 前缀命中规则，指向 order-cluster → 从这个 Cluster 的 3 台后端里负载均衡选中 10.0.0.7 这台 Upstream → 转发、拿回响应 → 原路返回客户端。

🚶 第一人称：现在你就是那个请求 "我是一个 HTTP 请求。我先撞到大门（Listener），门卫让我排队走安检流水线（Filter 链）——第一关验我的身份证（认证），第二关看我今天来太多次没（限流）。过关后，门卫查访客名单（Route）说'你找订单部，在 order-cluster'。到了那层楼有 3 个服务窗口（Cluster 里的 Upstream 主机），前台挑了个最闲的窗口把我送进去。办完事，我沿原路出来。"记住这套"门卫—安检—名单—窗口"的世界观，后面天天用。

L06

在 higress-group 的角色

Envoy 是整个 higress 生态的地基：
• Envoy（本项目） = 数据面，真正转发流量的"发动机"
• Istio（本系列后面） = 控制面，生成配置并通过 xDS 下发给 Envoy 的"控制器"
• Higress = 基于 Envoy + Istio 的云原生网关，做了增强 + Wasm 插件生态
• wasm-go = 用 Go 写 Higress/Envoy 的 Wasm 插件的 SDK
所以先学 Envoy（最底层）→ 再学 Istio（控制它）→ 再学 Higress（增强它）→ 最后 wasm-go（扩展它）。层层向上，理解一个完整的云原生网关是怎么搭起来的。这个 fork 里有很多 #if defined(HIGRESS) 分支，是 Higress 对上游 Envoy 的定制，教程中会标注。

L07

20 天路线

第 1 周（架构与线程）：全景 → 启动 → 线程模型 → 事件循环 → 请求入口。
第 2 周（过滤器与请求）：L4 过滤器 → HCM → L7 过滤器 → Router → Codec。
第 3 周（xDS 与上游）：xDS → 配置订阅 → 集群管理 → 负载均衡 → 健康检查。
第 4 周（扩展/可观测/构建）：扩展机制 → Wasm → 可观测 → Buffer/Bazel → 收官。

读法：由底向上：先懂"引擎怎么跑、为何快"（W1），再懂"请求怎么被处理"（W2），再懂"配置怎么动态下发、后端怎么选"（W3），最后"怎么扩展、观测、构建"（W4）。

L08

今日小结 + 动手

                🧠 今天你应该能回答
                Envoy 是什么？它在服务架构里扮演什么角色？
"代理"是什么？上游/下游怎么区分？
envoy/ 和 source/ 为什么物理分离？
六大术语各是什么？一个请求的一生怎么走？
Envoy/Istio/Higress/wasm-go 的关系？

            

✋ 动手

cd /Users/bitmart/work/codes/github/higress-group/envoy
cat REPO_LAYOUT.md | head -50
ls source/ envoy/ api/
cat docs/root/intro/arch_overview/intro/terminology.rst 2>/dev/null | head -30

明天预告 · Day 02：启动路径——envoy 进程怎么 boot：main.cc → MainCommon → Server::InstanceImpl → 主线程事件循环 dispatcher_->run(Block)。

← 总目录 Day 02 · 启动路径 →