Higress 是阿里巴巴开源的 云原生 API 网关，对外宣称"三合一"：南北向流量网关 + 微服务网关 + AI 网关。底层架构是 Envoy 作数据面 + Istio Pilot 改造版作控制面 + Wasm 插件作扩展点。它原生支持 K8s Ingress、Gateway API、Knative、并扩展了 McpBridge / WasmPlugin / Http2Rpc 等 CRD。

核心卖点：配置热生效（不 reload）、丰富插件生态（60+ 官方插件）、对 LLM / MCP 友好。

Higress 控制面本质是裁剪魔改版 Istiod。证据：

• 仓库根目录有 istio/istio 子目录，是 Istio 源码的 vendored 副本。
• go.mod 用 replace 把 istio.io/istio 重定向到本地副本。
• pkg/bootstrap/server.go 大量 import "istio.io/istio/pilot/..."。

Higress 复用了 Istio 的 Pilot 配置聚合、xDS Server、Push 模型；去掉了 mTLS / CA / Sidecar Injector。

Higress 数据面是定制化 Envoy，集成了官方 Wasm HTTP Filter 和 Higress 自研的若干扩展（在 envoy/envoy 子模块、plugins/golang-filter 等位置）。运行时通过 gRPC ADS 从控制面拉取 LDS/RDS/CDS/EDS。所有"AI 网关能力"最终都跑在 Envoy filter chain 里，要么是 Wasm 沙箱，要么是 Go Filter。

┌─ Higress Console (前端 + Java/Spring) ────────────┐
│  用户图形化管理：路由、插件、AI、监控               │
└──────────────┬─────────────────────────────────────┘
               │ 调 K8s API (改 CRD)
               ▼
┌─ Higress Controller (本仓库 pkg/) ─────────────────┐
│  监听 CRD → 翻译成 Istio Config → xDS 推送         │
└──────────────┬─────────────────────────────────────┘
               │ gRPC ADS
               ▼
┌─ Higress Gateway (定制 Envoy) ─────────────────────┐
│  实际转发流量；加载 Wasm 插件                       │
└────────────────────────────────────────────────────┘

cmd/higress/    控制面唯一入口
pkg/            ★ 控制面核心 Go 代码
registry/       ★ 多注册中心适配
istio/          vendored 裁剪版 Istio
envoy/          Envoy 自定义构建材料
plugins/        ★ Wasm 插件（含 wasm-go SDK）
api/、client/   CRD schema 与 typed client
helm/           部署 chart
hgctl/          命令行工具
docker/、docs/、samples/、test/、tools/、release-notes/

Higress 的 go.mod 充满 replace 指令，把所有 istio.io/istio、istio.io/api、istio.io/client-go 等 import 路径重定向到本地的 ./istio/...。这让 Higress 可以独立修改 Istio 代码而不必等上游合并。

replace (
    istio.io/istio          => ./istio/istio
    istio.io/api            => ./istio/api
    istio.io/client-go      => ./istio/client-go
    ...
)

顶层有 3 个 Makefile：Makefile（入口）、Makefile.core.mk（核心目标）、Makefile.overrides.mk（覆盖钩子）。这套体系沿用了 Istio 的 build-common 模式。常用目标：

make build           # 编译 higress 二进制
make docker          # 构建镜像
make lint            # tools/linter
make test            # 单元测试
make gen             # 生成 CRD client / proto
make higress.tar     # 离线包

docker/ 下分别放 higress（控制面）、higress-gateway（数据面）、higress-pilot（裁剪 Istiod）等 Dockerfile。Higress 主镜像通常基于 distroless 或精简 Ubuntu，Gateway 镜像基于上游 envoyproxy/envoy 派生并打包 Wasm runtime。

helm/ 下分多个子 chart：core（CRD + controller）、higress（聚合）、console（前端）。安装时一句命令拉起完整集群形态：

helm install higress higress.cn/higress -n higress-system --create-namespace

• istio.io/istio：Pilot / xDS / ServiceRegistry 模型（vendored）
• k8s.io/client-go：K8s API 客户端
• github.com/envoyproxy/go-control-plane：Envoy proto + ADS 库
• github.com/tetratelabs/proxy-wasm-go-sdk：Wasm 插件 ABI
• github.com/nacos-group/nacos-sdk-go/v2、go-zookeeper/zk、hashicorp/consul/api 等注册中心客户端
• github.com/spf13/cobra：CLI
• google.golang.org/grpc：gRPC ADS server

Client
  │ HTTP/TLS
  ▼
Higress Gateway (Envoy)
  ├─ Listener Filter (TLS Inspector / SNI)
  ├─ HTTP Connection Manager
  │     ├─ Wasm Filter[ai-security-guard]
  │     ├─ Wasm Filter[jwt-auth]
  │     ├─ Wasm Filter[ai-token-ratelimit]
  │     ├─ Wasm Filter[ai-cache]
  │     ├─ Wasm Filter[ai-proxy]   ← 改写 path/body
  │     └─ Router → Cluster
  ▼
Upstream (K8s Service / Nacos 实例 / 大模型 API)

K8s API Server  +  Nacos/ZK/Consul/Eureka
       │                  │
       ▼                  ▼
   Informer        registry/* Watcher
       │                  │
       └───── IngressConfig ─────── ConfigAggregate
                            │
                            ▼
                  Pilot DiscoveryServer (xds)
                            │  gRPC ADS
                            ▼
                       Envoy 数据面

Higress 插件由两条路径加载：

• WasmPlugin CRD：声明式，最常用；插件以 .wasm 镜像形态从 OCI/HTTP 拉取，挂载到指定 phase + priority。
• Envoy Go Filter：plugins/golang-filter，需要重编 Envoy 镜像。

插件运行在 Envoy 的 Worker 线程内的 V8/WAVM 沙箱里，每个 worker 各自一份独立实例。

Higress 支持：

• 多 K8s 集群：每个集群一个 Ingress Controller 实例，由 common.AggregateController 聚合。
• 多注册中心：McpBridge 的 registries 是数组，可同时接入多个 Nacos/ZK/Consul/Eureka。

统一表示：所有外部服务都被翻译成 Istio ServiceEntry 注入 ServiceRegistry。

Higress 的 AI 网关能力不在控制面也不在 Envoy core，全部以 Wasm 插件形态存在于 plugins/wasm-go/extensions/ai-*：

• ai-proxy：协议归一化（统一 OpenAI 协议 → 各厂商）
• ai-cache、ai-rag、ai-history：上下文增强
• ai-security-guard、ai-token-ratelimit、ai-quota：治理
• ai-statistics、ai-load-balancer、ai-intent、ai-search：辅助

• 1.x：稳定 Ingress + 多注册中心 + Wasm 插件。
• 2.0：AI 网关首发，ai-proxy / ai-token-ratelimit 等大量插件入驻。
• 2.1+：MCP Server 托管、mcp-router 推出；与各 LLM 厂商对接扩展。

查看 release-notes/ 下按版本号组织的目录是最直接的"项目史读法"。

1. 纵向 1 条主线：跟一条 Ingress YAML 的命运，从 Informer → IngressConfig → VirtualService → Pilot xDS → Envoy（贯穿 02～05 期）。
2. 横向 1 条插件：选 ai-proxy，从 main.go 看到 provider 实现（贯穿 08~09 期）。
3. 横向 1 条注册中心：选 Nacos，从 McpBridge CRD 到 Endpoint 推送（07 期）。

这三条线覆盖 80% 的核心代码，剩下都是补充。