Higress 架构与设计思想

QianXun · 2026-06-16T04:53:49+00:00

花了半天时间对 AgentScope/HiClaw 项目做了深度研究，核心发现如下。 ## 这是什么阿里云 Higress 团队做的开源多 Agent 协作平台。思路不复杂：一个 Manager Agent 管一群 Worker Agent，在同一个 Matrix 聊天室里干活——人类全程看得到、随时可打断。它不自己实现 Agent 逻辑，只管编排。打个比方：OpenClaw 像 Docker——跑一个 Agent。HiClaw 像 Kubernetes——把一群 Agent 编排成团队。 ## 架构最聪明的地方：凭证零暴露 Worker 永远不持有真实 API Key 或 GitHub PAT——只有一个消费者令牌。真实凭证全部锁在 Higress 网关里。这意味着： - 即使 Worker 装了 skills.sh 上 80000+ 个社区技能中的恶意 Skill，它也偷不到任何真实凭证 - 权限撤销快——把 Consumer 从 allowedConsumers 列表踢掉，WASM 热更新几秒生效在当前的几十个开源多 Agent 项目里，没有第二家做到这一点。

> 本文档基于 Higress 源码（v2.2.2）与仓库内文档深度整理，旨在系统阐述项目的整体架构、核心设计原则与实现思想。更详细的组件原理可参考 architecture.md，用户与开发文档见 higress.cn。

---

1. 项目定位与设计哲学 2. 整体架构 3. 控制面：Higress Controller 4. 数据面：Higress Gateway 5. 管理面：Console 与 hgctl 6. 配置流转与中间表示 7. 插件与扩展体系 8. 服务发现与注册中心集成 9. 核心设计模式 10. 代码仓库结构 11. 技术栈与依赖关系 12. 演进方向与架构取舍 13. 参考资料

---

1. 项目定位与设计哲学

1.1 是什么

Higress 是一款 AI Native 云原生 API 网关，内核基于 Istio 与 Envoy 二次定制，是 CNCF Sandbox 项目。它从阿里巴巴内部为解决 Tengine reload 对长连接业务的损害、gRPC/Dubbo 负载均衡能力不足等生产痛点而诞生，已在阿里内部及大量企业环境中验证。

当前 Higress 承担多重角色：

角色	核心能力
AI Gateway	统一对接国内外 LLM 提供商，多模型负载均衡、Token 限流、缓存、AI 可观测
MCP Gateway	通过 Wasm / Golang Filter 托管 MCP Server，统一认证、限流、审计
Kubernetes Ingress Controller	兼容 nginx-ingress 大量注解，支持 Gateway API
微服务网关	对接 Nacos / Eureka / Consul / ZooKeeper，深度集成 Dubbo
安全网关	WAF、key-auth / hmac-auth / jwt-auth / oidc 等

1.2 设计哲学

Higress 的架构决策围绕以下核心思想展开：

#### 站在巨人肩上，而非重复造轮子

Higress 不重新实现网关数据面，而是深度复用 Envoy 的高性能代理能力与 Istio Pilot 的配置分发机制。控制面的增量工作集中在 Ingress/Gateway API 到 Istio IR 的翻译层 与 Higress 特有 CRD 的处理，避免维护一套独立的 xDS 控制面。

#### 标准优先，降低迁移成本

路由配置遵循 Kubernetes Ingress API 与 Gateway API 标准
兼容 nginx-ingress 注解，支持从 nginx-ingress 平滑迁移
插件配置通过 CRD（WasmPlugin 等） 声明式管理，与 K8s 生态一致

#### 扩展性通过沙箱隔离实现

网关的业务逻辑扩展走 Envoy Proxy-Wasm 沙箱路径，而非修改 C++ 内核或重启进程。Wasm 插件支持 Go / Rust / C++ / JS 等多语言，可独立版本升级，实现 流量无损热更新。

#### 生产级可靠性与 AI 场景友好

配置变更毫秒级生效，彻底摆脱 Nginx reload 引起的连接抖动
完整流式处理（SSE 等），对大带宽 AI 场景显著降低内存开销
阿里内部验证：每秒数十万级请求 的大规模场景

#### 开放与社区驱动

项目遵循 CNCF 治理模型，强调 Openness、Fairness、Community First。完整治理说明见 GOVERNANCE.md。

---

2. 整体架构

Higress 由三大运行时组件构成（Console 为独立仓库）：

┌─────────────────────────────────────────────────────────────────┐
│              Higress Console（higress-console 独立仓库）          │
│         路由 / 插件 / 域名 / 证书管理 UI + Higress Admin SDK      │
└────────────────────────────┬────────────────────────────────────┘
                             │ K8s API / Admin SDK
┌────────────────────────────▼────────────────────────────────────┐
│                   Higress Controller（本仓库）                    │
│  ┌──────────────────────┐    ┌───────────────────────────────┐  │
│  │  Discovery           │    │       Higress Core            │  │
│  │  (Istio Pilot)       │◄───│  Ingress Config + Cert Server  │  │
│  │  Config Controller   │    │  (6+ K8s Controllers)         │  │
│  │  Service Controller  │    │  MCP over xDS 配置来源          │  │
│  └──────────┬───────────┘    └───────────────────────────────┘  │
│             │ gRPC xDS (:15051)                                  │
└─────────────┼────────────────────────────────────────────────────┘
              ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Higress Gateway（数据面）                      │
│       Pilot Agent + Envoy（UDS xDS: LDS/RDS/CDS/EDS/SDS）         │
│       Wasm 插件在 HTTP Filter 链中执行                            │
└────────────────────────────┬────────────────────────────────────┘
                             ▼
              上游业务服务 / LLM API / MCP Backend / 注册中心服务

请求处理路径（简化）：

客户端 → Envoy Listener → HTTP Router → Wasm Filter 链 → 上游 Cluster → 后端服务
                ↑                              ↑
           LDS/RDS (xDS)                  WasmPlugin CRD

---

3. 控制面：Higress Controller

控制面是本仓库（cmd/ + pkg/）的核心，通过 higress serve 启动。

3.1 启动链路

cmd/higress/main.go
    └── pkg/cmd/server.go          (cobra: higress serve)
            └── pkg/bootstrap/server.go   (NewServer)
                    ├── initKubeClient
                    ├── initXdsServer          # Istio DiscoveryServer + MCP Generators
                    ├── initHttpServer         # /ready, /debug
                    ├── initConfigController   # IngressTranslation 作为 ConfigStore
                    ├── initRegistryEventHandlers
                    ├── initAuthenticators
                    └── initAutomaticHttps     # Let's Encrypt 自动证书

默认监听端口：

端口	用途
15051	gRPC xDS（控制面 ↔ 数据面）
8888	HTTP debug / ready
8889	自动 HTTPS 证书 HTTP 挑战

3.2 Discovery 子组件（Istio Pilot-Discovery）

Discovery 负责 服务发现、配置聚合、xDS 推送，是 Istio 控制面的核心。Higress 复用其以下能力：

#### Config Controller

管理多种配置来源，Higress 的关键集成点是 MCP over xDS：

Higress Core 实现 MCP Server，作为 Discovery 的 Istio 配置来源之一
higress-config ConfigMap 中 configSources 同时指向本地 xDS 与 K8s：

configSources:
- address: xds://127.0.0.1:15051   # Higress Core (MCP)
- address: k8s://                 # K8s 原生 Istio CRD

#### Service Controller

对接 Kubernetes Service / Endpoint，提供服务发现数据（EDS）。

3.3 Higress Core 子组件

Higress Core 是 Higress 相对 Istio 的 核心增量，位于 pkg/ingress/。

#### Ingress Config（虚拟 ConfigStore）

IngressConfig（pkg/ingress/config/ingress_config.go）实现 Istio 的 ConfigStoreController 接口，是一个 只读、Pull 式 的虚拟配置存储：

不将转换结果写回 Kubernetes
在 xDS List(GVK) 被调用时 按需转换 Ingress/Gateway/CRD 为 Istio 中间表示（IR）
支持的 IR 类型（pkg/ingress/kube/common/schema.go）：

Gateway · VirtualService · DestinationRule · ServiceEntry · EnvoyFilter · WasmPlugin

#### 六大控制器

控制器	路径	职责
Ingress Controller	`kube/ingress/`, `kube/ingressv1/`	K8s Ingress → Gateway / VS / DR
Gateway Controller	`kube/gateway/`	Gateway API → Istio IR（基于 Istio krt）
McpBridge Controller	`kube/mcpbridge/`	外部注册中心 → ServiceEntry
Http2Rpc Controller	`kube/http2rpc/`	HTTP → Dubbo/gRPC RPC 转换
WasmPlugin Controller	`kube/wasmplugin/`	Higress WasmPlugin → Istio WasmPlugin
ConfigMap Controller	`kube/configmap/`	全局 gzip / tracing / mcpServer 等 → EnvoyFilter

另有 Secret Controller（kube/secret/）管理 TLS 证书，KIngress 支持（Knative Ingress 并行处理）。

#### Cert Server

pkg/cert/ 提供 Let's Encrypt 自动签发与续签，监听 higress-https ConfigMap，管理 TLS Secret。

---

4. 数据面：Higress Gateway

数据面由 Pilot Agent + Envoy 组成，镜像来自 Istio/Envoy submodule 构建。

4.1 组件职责

Pilot Agent：Envoy 生命周期管理，代理 xDS 请求到 Discovery（gRPC → UDS）
Envoy：高性能 L7 代理，执行路由、负载均衡、TLS 终止、Wasm 插件

4.2 Envoy 核心概念

概念	说明	发现服务
Listener	监听下游连接的网络地址（IP:Port / UDS）	LDS
Router	根据路径、Header 等将请求路由到 Cluster	RDS
Cluster	逻辑相似的上游服务集合	CDS
Endpoint	Cluster 中的具体实例（IP:Port）	EDS
Secret	TLS 证书、私钥等	SDS

4.3 HTTP Filter 链

Envoy 的请求处理经过 HTTP Connection Manager 中的 Filter 链。Higress 通过 WasmPlugin 和 EnvoyFilter 在此链中注入：

Wasm HTTP Filter：通用插件（认证、限流、AI 代理等）
Golang Native Filter：MCP Server 等需要原生性能的场景
EnvoyFilter：Http2Rpc 等协议转换

---

5. 管理面：Console 与 hgctl

5.1 Higress Console（独立仓库）

higress-console 提供 Web UI，功能包括：

路由、域名、证书、插件、服务来源管理
内置或可对接自建 Grafana / Prometheus 可观测

Higress Admin SDK 从 Console 剥离，提供 Java（JDK 17+）API，便于外部系统对接配置管理。

5.2 hgctl CLI（本仓库 `hgctl/`）

独立 Go module 的命令行工具：

命令组	功能
`install` / `upgrade` / `uninstall`	Helm 部署管理
`config`	查看数据面 route / listener 等配置
`plugin`	Wasm 插件脚手架、构建、安装
`profile` / `manifest` / `dashboard`	配置导出与监控
`agent` / `mcp`	AI Agent 与 MCP 工具

---

6. 配置流转与中间表示

6.1 完整数据流

① 用户提交配置
   ├── K8s Ingress + higress/nginx 注解
   ├── Gateway API (Gateway / HTTPRoute / GRPCRoute / ...)
   ├── Higress CRD (WasmPlugin / McpBridge / Http2Rpc)
   └── ConfigMap (higress-config: 全局配置)

② Informer 同步到本地 Cache
   └── Work Queue.onEvent → 触发 xDS PushRequest

③ xDS DiscoveryServer 收到 Push
   └── MCP Generator.Generate() → Environment.List(GVK)

④ IngressConfig.List(GVK)  [Pull 式转换]
   ├── listFromIngressControllers()
   │     ├── 读取 Ingress → 解析注解 → 转换 IR
   │     └── convertGateway / VirtualService / DestinationRule / ...
   └── listFromGatewayControllers()
         └── GatewayController.List() → krt 已转换的 IR

⑤ MCP Generator 序列化为 xDS MCP Resource
   └── gRPC ADS → Envoy Gateway 应用配置

6.2 Pull 式转换 vs 传统 Reconcile

Higress 控制面 不采用 典型的 Operator Reconcile（读 CR → 转换 → 写回 Status）模式来处理路由配置。其设计是：

1. K8s 资源变更 → 仅触发 xDS Push 信号 2. 实际 Ingress → VirtualService 转换在 xDS List() 调用时按需执行 3. 使用 istio.io/always-push: "true" 标签，跳过 config diff，确保每次事件触发 full push

这种 Event-driven Push + Pull 式 Virtual ConfigStore 模式与 Istio Pilot 原生架构一致，避免了维护转换结果副本的一致性问题。

6.3 Ingress 注解系统

注解处理采用 策略模式 + 责任链，位于 pkg/ingress/kube/annotations/：

AnnotationHandlerManager
├── Parser[]              → 解析注解到 Ingress 结构体
├── GatewayHandler[]      → 应用到 Gateway（如下游 TLS）
├── RouteHandler[]        → 应用到 HTTPRoute（重写、CORS、限流等）
└── TrafficPolicyHandler[]→ 应用到 DestinationRule（负载均衡、上游 TLS）

支持的注解能力包括：金丝雀发布、CORS、重写/重定向、超时/重试、负载均衡、本地限流、认证、镜像流量、Http2Rpc、MCP Server 等。

IngressClass 过滤逻辑：

IngressClass 值	行为
`higress`（默认）	仅 watch higress class 的 Ingress
`nginx`	兼容模式：watch nginx class 或无 class 的 Ingress
空字符串	watch 集群内全部 Ingress

---

7. 插件与扩展体系

Higress 的差异化能力很大程度来自其 双轨插件架构。

7.1 架构总览

                    ┌─────────────────────────────────┐
                    │         控制面 CRD               │
                    │  WasmPlugin / ConfigMap / CRD   │
                    └───────────────┬─────────────────┘
                                    │
              ┌─────────────────────┼─────────────────────┐
              ▼                     ▼                     ▼
     Istio WasmPlugin          EnvoyFilter           ServiceEntry
              │                     │                     │
              ▼                     ▼                     ▼
     ┌────────────────┐   ┌─────────────────┐   ┌──────────────┐
     │ Proxy-Wasm     │   │ Golang Filter   │   │ Http2Rpc     │
     │ HTTP Filter    │   │ (MCP Server)    │   │ 协议转换      │
     └────────────────┘   └─────────────────┘   └──────────────┘
              │                     │
              ▼                     ▼
     plugins/wasm-go/       plugins/golang-filter/
     plugins/wasm-cpp/      plugins/golang-filter/mcp-server/
     plugins/wasm-rust/

7.2 WasmPlugin CRD

API Group： extensions.higress.io/v1alpha1

Higress WasmPlugin 在 Istio WasmPlugin 基础上扩展：

字段	说明
`url`	OCI 镜像 / 本地 file / HTTP 远程 Wasm 模块
`pluginConfig`	插件配置（JSON）
`matchRules`	按 domain / ingress / service 粒度匹配
`phase`	插件执行阶段（AUTHN / AUTHZ / STATS 等）
`priority`	同阶段内优先级
`failStrategy`	插件失败策略

控制面转换链：

WasmPlugin CR → CommonController (Informer)
  → IngressConfig.convertIstioWasmPlugin()
  → Istio WasmPlugin IR
  → WasmPluginGenerator → xDS MCP → Envoy Proxy-Wasm

7.3 插件实现目录（`plugins/`）

目录	语言/运行时	代表插件
`wasm-go/extensions/`	Go → Wasm	ai-proxy, jwt-auth, waf, model-router, ai-cache
`wasm-go/mcp-servers/`	Go → Wasm	预置 MCP Server（天气、文档转换等）
`wasm-cpp/extensions/`	C++ → Wasm	basic_auth, key_auth, oauth, bot_detect
`wasm-rust/extensions/`	Rust → Wasm	ai-data-masking, ai-intent
`golang-filter/`	Envoy Golang Filter	MCP Server, MCP Session

AI 相关插件集群（战略重点）：

ai-proxy：统一 LLM API 代理，支持 30+ 国内外模型 Provider
ai-token-ratelimit / ai-quota：Token 级流控
ai-cache / response-cache：AI 响应缓存
ai-statistics / ai-load-balancer：AI 可观测与多模型负载均衡
mcp-server / mcp-router：MCP 协议托管与路由

7.4 Http2Rpc（EnvoyFilter 路径）

Http2Rpc CRD（networking.higress.io/v1）将 HTTP 请求映射为 Dubbo / gRPC RPC 调用，控制面生成专用 EnvoyFilter（constructHttp2RpcEnvoyFilter），不走 WasmPlugin 路径。适用于将遗留 RPC 服务以 HTTP 接口暴露。

7.5 插件设计原则

1. 沙箱隔离：Wasm 插件在 Proxy-Wasm VM 中运行，内存安全，崩溃不影响 Envoy 主进程 2. 热更新无损：OCI 镜像更新后，Envoy 动态加载新模块，长连接不中断 3. 流式友好：SDK 支持完整流式 Body 处理，适配 SSE / AI 流式响应 4. 粒度可控：全局 / 域名 / 路由 / 服务四级 matchRules

---

8. 服务发现与注册中心集成

8.1 McpBridge CRD

API Group： networking.higress.io/v1

声明外部注册中心连接信息，支持：

类型	实现
Nacos	`registry/nacos/`, `registry/nacos/v2/`
Eureka	`registry/eureka/`
Consul	`registry/consul/`
ZooKeeper	`registry/zookeeper/`
DNS / Static	`registry/direct/`

8.2 Registry Reconciler

registry/reconcile/reconcile.go 采用 Level-triggered Reconcile 模式：

McpBridge CR (desired state)
    → diff vs watchers map (actual state)
    → Create / Update / Delete registry watcher
    → 产出 ServiceEntry + DestinationRule + WasmPlugin
    → 触发 xDS Push

这与 Ingress 控制器的 Event-driven Push 模式不同，Registry Reconciler 是典型的 desired/actual diff + apply 模式，适合管理有生命周期的外部连接（Watcher）。

---

9. 核心设计模式

模式	应用位置	说明
Virtual ConfigStore	`IngressConfig`	只读 Pull 式配置存储，实现 Istio 接口但不写 K8s
Informer + Work Queue	所有 Kube 控制器	Istio `controllers.Queue`，限速重试
Generic Controller	`CommonController[T]`	泛型复用 CRD Watch 逻辑（WasmPlugin 等）
Strategy / Chain	`AnnotationHandlerManager`	注解解析与应用解耦
Facade	`IngressTranslation`	统一 Ingress + KIngress 两路输入
Aggregate ConfigStore	`bootstrap/server.go`	Istio `configaggregate.MakeCache` 合并多 Store
Event-driven Push	xDS 更新	资源变更 → PushRequest → Debounce → Push
Reactive Collections (krt)	Gateway API	Istio 声明式依赖图，增量重算
Level-triggered Reconcile	`RegistryReconciler`	McpBridge desired/actual diff
Resource Generator	`pkg/ingress/mcp/`	自定义 xDS MCP Generator

9.1 关键接口

// 核心控制器 — pkg/ingress/kube/common/controller.go
type IngressController interface {
    RegisterEventHandler(kind, handler)
    List() []config.Config
    ConvertGateway / ConvertHTTPRoute / ConvertTrafficPolicy(...)
    Run(stop) / HasSynced()
}

type GatewayController interface {
    model.ConfigStoreController   // 直接提供转换后的 Istio IR
}

// xDS 集成 — pkg/ingress/mcp/
type XdsResourceGenerator interface {
    Generate(proxy, watchedResource, pushRequest) (Resources, ...)
}

---

10. 代码仓库结构

higress/
├── api/                  # Higress CRD Protobuf 定义 → Cue → CRD YAML
├── client/               # CRD 的 client-go Informer/Lister 生成代码
├── cmd/higress/          # Controller 入口 (higress serve)
├── pkg/
│   ├── bootstrap/        # 服务编排与启动
│   ├── cert/             # 自动 HTTPS 证书
│   ├── cmd/              # Cobra CLI
│   ├── config/           # 全局配置常量
│   ├── ingress/          # ★ 核心：配置翻译 + K8s 控制器 + xDS 生成
│   └── kube/             # 扩展 K8s Client（Higress CRD Informer）
├── registry/             # 外部注册中心 Watcher + Reconciler
├── plugins/              # Wasm 插件 + Golang Filter 源码
├── hgctl/                # CLI 工具（独立 Go module）
├── helm/                 # Helm Charts（controller / gateway / plugin-server）
├── docker/               # Controller 镜像 Dockerfile
├── samples/              # 示例 YAML
├── test/                 # E2E 一致性测试
├── istio/                # Git Submodule：定制 Istio 1.27
├── envoy/                # Git Submodule：定制 Envoy 1.36
└── docs/                 # 仓库内文档

独立关联仓库

仓库	用途
higress-console	Web 管理控制台
higress-standalone	单机 Docker 部署
plugin-server	插件管理服务
wasm-go	Wasm Go SDK

---

11. 技术栈与依赖关系

层次	技术	版本
控制面语言	Go	1.24.4
数据面	Envoy	1.36（submodule）
控制面框架	Istio Pilot	1.27（submodule）
配置协议	xDS / MCP / gRPC	—
K8s 集成	client-go, Gateway API	v0.34 / v1.4
插件运行时	Proxy-Wasm, Golang Filter	—
证书	certmagic / acmez (Let's Encrypt)	—
部署	Helm, Docker All-in-One	—
许可证	Apache 2.0	—

Submodule 与构建：

Istio 与 Envoy 以 Git Submodule 形式 vendored，构建时 go.mod 通过 replace 指向 ./external/*。这允许 Higress 在 Istio/Envoy 上游基础上做必要 fork 而不脱离社区版本节奏。

---

12. 演进方向与架构取舍

12.1 从 Ingress 网关到 AI Gateway

Higress 的架构演进体现了明确的战略路径：

1. 第一阶段：替代 Nginx Ingress — 注解兼容、配置热更新、资源开销降低 2. 第二阶段：微服务网关 — McpBridge 多注册中心、Dubbo 集成、Http2Rpc 3. 第三阶段（当前重点）：AI Gateway + MCP Gateway — ai-proxy 插件族、MCP Server 托管、统一 LLM/MCP API 管理

架构上，AI 与 MCP 能力 并未引入新的控制面组件，而是通过 Wasm 插件 + CRD 扩展 在现有 Envoy Filter 链上叠加，体现了「扩展而非重写」的设计哲学。

12.2 关键架构取舍

取舍	选择	理由
控制面	复用 Istio Pilot 而非自研	成熟的 xDS 分发、Debounce、Push 机制
数据面	复用 Envoy 而非自研	生产级性能、Wasm 生态、流式支持
配置转换	Pull 式 Virtual ConfigStore	与 Istio 架构一致，避免双写一致性问题
插件	Wasm 为主、Native Filter 为辅	安全隔离 + 热更新；Native 用于 MCP 等性能敏感场景
Console	独立仓库	解耦 UI 迭代与核心控制面发布节奏
服务网格	不做 Sidecar 模式	专注 Gateway 场景，保持轻量

12.3 未来可扩展方向

Gateway API 支持持续增强（InferencePool 等 AI 相关 API）
MCP Generator Delta xDS 实现（当前 TODO）
多集群 / 多 Revision 配置隔离
更丰富的 AI 插件生态（RAG、Agent Workflow 等）

---

13. 参考资料

仓库内文档

architecture.md — 核心组件与原理（含架构图）
README_ZH.md — 项目介绍与使用场景
GOVERNANCE.md — CNCF 治理模型
CONTRIBUTING_CN.md — 贡献指南
plugins/wasm-go/README_EN.md — Wasm Go 插件开发

官方在线文档

上游项目

---

*文档版本：基于 Higress v2.2.2 源码整理*