1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
| # 示例1：动态路由配置
def dynamic_routing():
"""
基于Higress实现动态路由配置
解决问题：根据请求头中的用户类型将流量分发到不同后端服务
"""
import json
# 模拟Higress路由规则配置
route_config = {
"name": "user-type-router",
"match": {
"headers": {
"X-User-Type": ["premium", "standard"] # 匹配用户类型
}
},
"route": {
"cluster": "user-service-cluster",
"timeout": "5s"
},
"request_headers_to_add": [
{"header": {"key": "X-Routed-By", "value": "Higress"}}
]
}
# 应用路由规则（实际需要调用Higress API）
print("应用动态路由规则:")
print(json.dumps(route_config, indent=2))
# 说明：这个示例展示了如何使用Higress实现基于请求头的动态路由，
# 常用于A/B测试、灰度发布或用户分级服务场景。
```python
def circuit_breaker():
"""
实现Higress熔断器配置
解决问题：防止下游服务故障导致雪崩效应
"""
import time
### 模拟熔断器状态
class CircuitBreaker:
def __init__(self, failure_threshold=5, timeout=60):
self.failure_count = 0
self.failure_threshold = failure_threshold
self.timeout = timeout
self.last_failure_time = None
self.state = "CLOSED" # CLOSED, OPEN, HALF_OPEN
def record_failure(self):
self.failure_count += 1
self.last_failure_time = time.time()
if self.failure_count >= self.failure_threshold:
self.state = "OPEN"
print("熔断器已打开！暂停请求转发")
def record_success(self):
self.failure_count = 0
self.state = "CLOSED"
def allow_request(self):
if self.state == "OPEN":
if time.time() - self.last_failure_time > self.timeout:
self.state = "HALF_OPEN"
print("熔断器进入半开状态，尝试恢复")
return True
return False
return True
cb = CircuitBreaker()
for i in range(7):
if cb.allow_request():
print(f"请求 {i+1} 通过")
if i > 4: # 模拟失败
cb.record_failure()
else:
print(f"请求 {i+1} 被熔断器拦截")
---
### Purpose and Scope
This document provides a comprehensive overview of Higress, an AI Native API Gateway built on Istio and Envoy. It covers the system's architecture, core components, and primary use cases. For detailed information about specific subsystems, refer to the Core Architecture (page 2), Build and Deployment (page 3), WASM Plugin System (page 4), AI Gateway Features (page 5), MCP System (page 6), and Development Guide (page 7) sections.
---
### What is Higress
Higress is a cloud-native API gateway that extends Istio and Envoy with WebAssembly (WASM) plugin capabilities. The system provides three core functions: AI gateway features for LLM applications, MCP server hosting for AI agent tool integration, and traditional API gateway capabilities including Kubernetes Ingress and microservice routing.
The architecture separates control plane (configuration management) from data plane (traffic processing). Configuration changes propagate through the xDS protocol with millisecond latency and no connection disruption, making it suitable for long-connection scenarios such as AI streaming responses.
**Primary Use Cases:**
Use Case| Description| Core Components
---|---|---
**AI Gateway**| Unified API for 30+ LLM providers with protocol translation, observability, caching, and security| `ai-proxy`, `ai-statistics`, `ai-cache`, `ai-security-guard` plugins
**MCP Server Hosting**| Host Model Context Protocol servers enabling AI agents to call tools and services| `mcp-router`, `jsonrpc-converter` filters + MCP server implementations (`quark-search`, `amap-tools`, `all-in-one`)
**Kubernetes Ingress**| Ingress controller with compatibility for nginx-ingress annotations| `higress-controller`, Ingress/Gateway API translation to Istio configs
**Microservice Gateway**| Service discovery from multiple registries (Nacos, Consul, ZooKeeper, Eureka)| `McpBridgeReconciler`, registry-specific watchers
**Production Validation:**
Higress originated at Alibaba to address Tengine reload issues affecting long-connection services and insufficient gRPC/Dubbo load balancing. Within Alibaba Cloud, it supports core AI applications including Tongyi Qianwen (通义千问), Tongyi Bailian model studio, and PAI platform. The system handles hundreds of thousands of requests per second with 99.99% availability guarantees.
Sources: [README.md30-52](https://github.com/alibaba/higress/blob/8deceb4d/README.md#L30-L52)
---
### Core Architecture
Higress implements a control plane and data plane separation derived from Istio's architecture. The control plane watches Kubernetes resources and generates Envoy configurations distributed via xDS protocol. The data plane processes traffic through Envoy proxies extended with WASM plugins.
### System Components and Binaries
**Component Deployment Diagram:**
**Binary and Process Mapping:**
Binary| Source Entry Point| Deployment Location| Primary Functions
---|---|---|---
`higress-controller`| [cmd/higress/main.go1-100](https://github.com/alibaba/higress/blob/8deceb4d/cmd/higress/main.go#L1-L100)| Single pod in `higress-system`| Resource watching, `IngressController`, `WasmPluginController`, `McpBridgeReconciler`, service discovery management
`pilot-discovery`| Istio upstream (patched)| Same pod as controller| xDS server implementation, configuration distribution on ports 15010 (gRPC), 15012 (gRPC-TLS), 15017 (webhook)
`higress-gateway`| Envoy binary + extensions| DaemonSet or Deployment| Data plane proxy, WASM VM (V8), HTTP/HTTPS listeners on ports 80/443, admin API on 15021
`hgctl`| [cmd/hgctl/main.go1-50](https://github.com/alibaba/higress/blob/8deceb4d/cmd/hgctl/main.go#L1-L50)| Local CLI tool| MCP server management, local development (`hgctl agent`, `hgctl mcp add`)
**Key Process Communication:**
The controller and pilot run in the same pod and communicate via localhost gRPC on port 15051. The controller implements multiple Kubernetes controllers (`pkg/ingress/kube/`) that watch different resource types and update an in-memory cache (`pkg/ingress/kube/common/cache.go`). The cache state is pushed to pilot, which converts it to xDS configurations (Listener Discovery Service, Route Discovery Service, Cluster Discovery Service, Endpoint Discovery Service) and streams them to all gateway instances.
Sources: [README.md32](https://github.com/alibaba/higress/blob/8deceb4d/README.md#L32-L32) Diagram 2 from provided architecture diagrams
### Configuration Flow and Controller Architecture
**Configuration Update Sequence:**
**Controller Registry and Responsibilities:**
The controller implements the informer pattern for multiple resource types:
Controller| Source Location| Watched Resource| Generated Configs
---|---|---|---
`IngressController`| [pkg/ingress/kube/ingress/ingress.go1-500](https://github.com/alibaba/higress/blob/8deceb4d/pkg/ingress/kube/ingress/ingress.go#L1-L500)| `Ingress` (v1)| `VirtualService`, `DestinationRule`, `Gateway`
`IngressController` (v1beta1)| [pkg/ingress/kube/ingress/ingressv1beta1.go1-400](https://github.com/alibaba/higress/blob/8deceb4d/pkg/ingress/kube/ingress/ingressv1beta1.go#L1-L400)| `Ingress` (v1beta1)| Legacy Ingress support
`KIngressController`| [pkg/ingress/kube/kingress/kingress.go1-300](https://github.com/alibaba/higress/blob/8deceb4d/pkg/ingress/kube/kingress/kingress.go#L1-L300)| Knative `Ingress`| Knative-specific routing
`WasmPluginController`| [pkg/ingress/kube/wasmplugin/wasmplugin.go1-400](https://github.com/alibaba/higress/blob/8deceb4d/pkg/ingress/kube/wasmplugin/wasmplugin.go#L1-L400)| `WasmPlugin` CRD| `EnvoyFilter` with WASM config
`McpBridgeReconciler`| [pkg/ingress/kube/mcpbridge/reconciler.go1-300](https://github.com/alibaba/higress/blob/8deceb4d/pkg/ingress/kube/mcpbridge/reconciler.go#L1-L300)| `McpBridge` CRD| Registry watcher lifecycle
`ConfigMapController`| [pkg/ingress/kube/configmap/1-100](https://github.com/alibaba/higress/blob/8deceb4d/pkg/ingress/kube/configmap/#L1-L100)| `higress-config` ConfigMap| `EnvoyFilter` for global settings
The central cache (`pkg/ingress/kube/common/cache.go`) maintains in-memory state for all Istio resources and provides atomic updates to prevent partial configuration states. Configuration changes propagate to pilot within milliseconds, significantly faster than nginx-ingress reload times (reported 10x improvement).
Sources: [README.md108-116](https://github.com/alibaba/higress/blob/8deceb4d/README.md#L108-L116) Diagram 2 from provided architecture diagrams
---
### Key Capabilities
### AI Gateway Features
AI gateway functionality is implemented through a pipeline of WASM plugins that process requests and responses for LLM providers. The plugins support protocol translation, observability, caching, and security.
**AI Plugin Pipeline:**
Plugin| Source Location| Request Phase| Response Phase
---|---|---|---
`ai-proxy`| [plugins/wasm-go/extensions/ai-proxy/main.go1-500](https://github.com/alibaba/higress/blob/8deceb4d/plugins/wasm-go/extensions/ai-proxy/main.go#L1-L500)| Protocol detection, provider selection, request transformation| Response transformation, SSE stream processing
`ai-statistics`| [plugins/wasm-go/extensions/ai-statistics/main.go1-400](https://github.com/alibaba/higress/blob/8deceb4d/plugins/wasm-go/extensions/ai-statistics/main.go#L1-L400)| Extract request attributes (user, model, tokens)| Extract response tokens, latency, write metrics/logs/traces
`ai-cache`| [plugins/wasm-go/extensions/ai-cache/main.go1-300](https://github.com/alibaba/higress/blob/8deceb4d/plugins/wasm-go/extensions/ai-cache/main.go#L1-L300)| Check cache (semantic search)| Store response in Redis
`ai-security-guard`| [plugins/wasm-go/ext
[...truncated...]
---
### 1. 技术架构深度剖析
Higress 的架构设计体现了“云原生+可扩展”的工程哲学，其核心在于**控制平面与数据平面的分离**以及**对 WASM（WebAssembly）的深度依赖**。
* **技术栈与架构模式**：
* **底层基石**：基于 **Envoy** 作为高性能数据平面，处理所有入站流量。Envoy 的 L3/L7 处理能力和 C++ 高性能特性是 Higress 性能的保障。
* **控制平面**：深度集成 **Istio**。Higress 复用了 Istio 的控制平面能力（如 xDS 协议下发），但对其进行了简化和增强，移除了 Sidecar 模式的复杂性，专注于 Gateway（Ingress）场景。
* **扩展机制**：核心亮点是 **WASM 插件系统**。它允许开发者使用 C/C++/Go/Rust 等语言编写插件，编译为 WASM 字节码后在 Envoy 中运行。这解决了传统 Lua 插件（如 OpenResty）在安全性、隔离性和性能上的痛点。
* **核心模块**：
* **Router (路由层)**：支持基于 HTTP Header、Path、权重等多种路由规则，特别针对 AI 场景优化了 SSE（Server-Sent Events）和长连接的路由稳定性。
* **WASM VM (沙箱)**：在 Envoy 中嵌入 WASM 虚拟机，实现插件的动态加载与热更新，无需重启网关。
* **MCP Server Host**：内置对 Model Context Protocol (MCP) 的支持，作为 AI Agent 的工具托管中心。
* **架构优势**：
* **毫秒级配置下发**：利用 xDS 协议的增量推送机制，配置变更可秒级生效且不断连。
* **极致性能**：数据平面无锁化设计，配合 WASM 的近原生执行速度。
---
### 2. 核心功能详细解读
Higress 不仅仅是一个流量网关，它正在演变为 AI 时代的基础设施层。
* **AI Gateway (LLM 优化)**：
* **解决的问题**：企业在对接 OpenAI、通义千问等 LLM 时，面临 Token 计费困难、Prompt 注入风险、超时处理复杂以及多模型切换成本高的问题。
* **核心功能**：提供统一的 LLM 标准化接口。用户只需调用 Higress，Higress 后端可路由至不同的模型提供商。支持 **Token 统计与限流**（精确到 Input/Output Token）、**Prompt 装饰**（自动注入 System Prompt）以及**结果后处理**。
* **流式处理**：完美支持 LLM 的流式响应（SSE），确保在网关层不断开长连接，这对 AI 交互体验至关重要。
* **MCP (Model Context Protocol) 支持**：
* **解决的问题**：AI Agent 需要调用外部工具（如搜索、数据库查询），传统方式需要为每个工具编写独立接口。
* **实现**：Higress 可以作为 MCP Server 的托管网关，允许 LLM 客户端通过标准协议发现并调用由 Higress 暴露的工具能力，极大简化了 Agent 的工具链集成。
* **与传统网关的对比**：
* **vs Nginx/OpenResty**：Higress 拥有更强大的控制平面（Kubernetes 原生），配置管理更自动化；WASM 插件比 Lua 插件更安全、多语言支持更好。
* **vs Kong/APISIX**：Higress 与 Istio 生态结合更紧密，且在 AI 场景（如 SSE 转发、Token 计费）上有开箱即用的增强，而传统网关通常需要编写复杂脚本才能实现。
---
### 3. 技术实现细节
* **WASM 插件机制**：
* **原理**：Higress 实现了 `Proxy-WASM` ABI 标准。当流量匹配特定规则时，Envoy 会将请求上下文传入 WASM 虚拟机。
* **关键技术**：使用 **http_filter** 在 Envoy 的 Filter Chain 中插入 WASM 过滤器。通过 `on_request_headers`、`on_body`、`on_response_headers` 等钩子函数实现无侵入式逻辑修改。
* **难点解决**：WASM 的内存管理是难点。Higress 通过优化宿主与 WASM 之间的数据拷贝（利用 Shared Memory 技术），降低了延迟开销。
* **配置热更新**：
* **xDS 协议**：Higress Console 将配置写入数据库，控制平面监听变化，将其转换为 Envoy 的 Listener/Route/Cluster 配置，通过 gRPC 流式推送给数据平面。
* **动态路由**：避免传统的 reload 进程模式（会导致 TCP 连接中断），实现了配置变更的无感切换。
* **性能优化**：
* **零拷贝**：在处理 SSE 流时，尽量减少 Buffer 的拷贝。
* **连接池**：针对后端 LLM 服务建立 HTTP/2 连接池，复用连接以减少握手开销。
---
### 4. 适用场景分析
* **最适合的场景**：
1. **AI 应用中台**：企业内部统一管理对各大 LLM 厂商的 API 调用，实现统一的鉴权、限流和计费。
2. **Kubernetes 微服务网关**：替代 Ingress Nginx，作为云原生架构的统一流量入口，特别是需要复杂插件扩展能力的场景。
3. **多模型 SaaS 平台**：需要根据用户等级动态切换底层模型（如从 GPT-3.5 切换到 GPT-4），对用户屏蔽底层细节。
* **不适合的场景**：
1. **极边缘计算**：Envoy + WASM 相比纯 Nginx 仍然有较高的内存占用，不适合资源极度受限的嵌入式设备。
2. **简单的静态文件托管**：杀鸡焉用牛刀，Nginx 或 Caddy 更轻量。
* **集成建议**：
* 在 Kubernetes 环境中，推荐通过 Helm Chart 部署。
* 利用 Ingress Class 标识将 Higress 作为特定 HTTPRoute 的处理网关。
---
### 5. 发展趋势展望
* **从流量网关向 AI 网关演进**：Higress 正在重新定义 API 网关。未来的网关不仅要懂“协议”，还要懂“语义”。我们可能会看到 Higress 集成更多向量检索能力或 RAG（检索增强生成）相关的处理逻辑。
* **MCP 协议的普及**：随着 Anthropic 的 MCP 协议成为 AI Agent 连接工具的标准，Higress 作为 MCP Server 的托管者，将成为连接企业内部数据与 AI 模型的关键枢纽。
* **WASM 生态的爆发**：随着 WASM 标准的成熟，未来会有更多第三方开发者编写通用的 Wasm 插件（如 SQL 防火墙、数据脱敏），Higress 将成为一个插件市场。
---
### 6. 学习建议
* **适合人群**：具备 Kubernetes 基础、了解微服务架构、对 Go 语言有一定了解的后端工程师或运维专家。
* **学习路径**：
1. **前置知识**：理解 Envoy 的基本概念和 Istio 的架构。
2. **上手部署**：使用 Docker 或 Kind 在本地搭建 Higress，跑通一个简单的路由转发。
3. **插件开发**：阅读官方的 Go SDK 文档，尝试编写一个简单的 WASM 插件（例如：给 Response Header 加上一个自定义字段），并在控制台配置加载。
4. **AI 实战**：配置一个 LLM 插件，实现将 OpenAI 的请求转发至通义千问，并体验 Prompt 模板功能。
---
### 7. 最佳实践建议
* **资源隔离**：在生产环境中，建议将 AI Gateway（处理 LLM 流量）与传统 API Gateway（处理普通业务流量）分开部署，因为 LLM 流量通常具有长连接、高延时的特点，可能会占用过多连接池。
* **插件开发规范**：
* **避免阻塞**：WASM 插件中严禁进行长时间的同步 I/O 操作（如直接调用第三方 HTTP API），这会阻塞 Envoy 的事件循环。如有必要，应使用异步调用或在 Go Control Plane 中处理复杂逻辑。
* **错误处理**：插件必须做好异常捕获，防止一个插件的 Bug 导致整个网关 Crash。
* **配置管理**：利用 GitOps 理念管理 Higress 的 Ingress 配置，避免直接在控制台手动修改生产环境配置。
---
### 8. 哲学与方法论：第一性原理与权衡
* **抽象层的转移**：
* Higress 将**流量控制的复杂性**从业务代码（微服务内部）转移到了**基础设施层**（网关侧）。
* 它将**协议处理的复杂性**从 Nginx C 模块转移到了**WASM 虚拟机**。这使得扩展网关不再需要掌握 C++ 和 Envoy 源码，只需掌握通用编程语言和 WASM 接口。
* **价值取向与代价**：
* **取向**：**可扩展性** 和 **标准化**。它极度推崇云原生标准，倾向于通过配置和插件解决问题，而不是修改核心代码。
* **代价**：**复杂度**。引入 Istio 和 Envoy 意味着运维门槛的显著提升。相比 Nginx 的简单配置，Higress 的故障排查需要理解 Control Plane、Data Plane、xDS 协议以及 WASM 生命周期。
* **工程哲学**：
* Higress 的范式是**“插件化基础设施”**。它认为网关不应该是一个静态的路由器，而是一个可编程的运行时。
* **误用风险**：最容易误用的是 **WASM 插件的性能边界**。开发者容易将其当作普通业务服务来写，忽略了它运行在请求的热路径上，极其消耗 CPU 资源。
* **可证伪的判断**：
1. **性能指标**：在启用 WASM 插件的情况下，Higress 的长连接并发处理能力相比原生 Envoy 下降幅度应控制在 10% 以内（验证 WASM 虚拟机的开销）。
2. **AI 稳定性**：在处理 1000 个并发的 SSE（流式）请求时，网关不应出现内存溢出或连接非正常断开（验证对 AI 场景的适配性）。
3. **配置延迟**：修改路由规则后，端到端的流量生效延迟应低于 500ms（验证控制平面与数据平面的同步效率）。
|