Higress 架构学习指南 🚀

写在前面： 嘿，欢迎你来到 Higress 的学习之旅！😊 这不是一份冷冰冰的技术文档，而是我精心准备的"教练笔记"。我会像老朋友一样，陪你一步步揭开这个云原生 AI 网关的神秘面纱。准备好了吗？让我们开始吧！

第一部分：项目架构深度解析（像架构师一样俯瞰全景）🔍

本部分目标： 通过深入剖析 Higress 的设计哲学、技术选型和代码组织，帮助你建立对项目的宏观认知。不仅要知道"是什么"，更要理解"为什么这样设计"。

1. 项目架构概览

1.1 用一个贴切的类比理解 Higress 🏗️

想象一下，Higress 就像一座现代化的智能立交桥系统：

• 网关（Gateway） 是立交桥本身，负责实际的流量调度和转发
• 控制器（Controller） 是交通指挥中心，动态调整路线规则
• 控制台（Console） 是可视化大屏，让你轻松查看和管理整个系统

这座"立交桥"最大的特点是：

• 🚗 无感变更：调整路线规则时，不会让任何一辆车（请求）掉队
• 🌐 多语言支持：可以用 Go、Rust、C++、JavaScript 等多种"语言"编写交通规则（Wasm 插件）
• 🤖 AI 优先：专门为 AI 流量（大模型调用）优化，支持流式响应和超长连接

1.2 核心设计特征

Higress 的架构遵循经典的控制平面 + 数据平面分离模式：

控制平面（Control Plane）- Higress Controller

┌─────────────────────────────────────────────────┐
│           Higress Controller                     │
├──────────────────┬──────────────────────────────┤
│  Higress Core    │   Istio Discovery            │
│  ┌──────────┐    │   ┌──────────────────────┐   │
│  │ Ingress  │    │   │  Config Controller   │   │
│  │ Gateway  │    │   │  Service Controller  │   │
│  │ McpBridge│◄───┼───┤  xDS Server          │   │
│  │ WasmPlugin│   │   │  Aggregation         │   │
│  │ Http2Rpc │    │   └──────────────────────┘   │
│  │ ConfigMap│    │                               │
│  └──────────┘    │                               │
│  Cert Server     │                               │
└──────────────────┴──────────────────────────────┘
         │ (xDS Protocol)
         ▼
┌─────────────────────────────────────────────────┐
│         Higress Gateway (Data Plane)            │
├──────────────────┬──────────────────────────────┤
│  Pilot Agent     │       Envoy Proxy             │
│                  │  ┌────────────────────────┐   │
│                  │  │ Listeners             │   │
│                  │  │ Routes                │   │
│                  │  │ Clusters              │   │
│                  │  │ Wasm Runtime          │   │
│                  │  └────────────────────────┘   │
└──────────────────┴──────────────────────────────┘

设计亮点：

1. 基于 Istio/Envoy：站在巨人肩膀上，复用成熟的服务网格技术栈
1. 无侵入扩展：通过 MCP（Mesh Configuration Protocol）协议对接 Istio，解耦了与 Kubernetes 的强绑定
1. 插件化架构：Wasm 插件机制支持多语言开发，动态加载，热更新无损

1.3 与同类项目的对比

|
特性

Higress

Kong

APISIX

Nginx Ingress

|
| --- | --- | --- | --- | --- |
|

内核

Envoy (C++)

OpenResty (Lua/Nginx)

OpenResty (Lua)

Nginx

|
|

配置生效速度

毫秒级

秒级

需 reload

|
|

AI 场景优化

✅ 原生支持

⚠️ 插件支持

❌ 不支持

|
|

MCP Server 托管

✅ 独家特性

❌

|
|

插件语言

Go/Rust/C++/JS

Lua

Lua/Go

Lua

|
|

长连接友好

✅ 完全无损

⚠️ Reload 有损

❌ Reload 断连

|
|

资源占用

低

中等

低

Higress 的独特优势：

• 🎯 AI 优先设计：统一对接国内外所有 LLM 供应商，支持流式处理、token 限流、多模型负载均衡
• 🔌 MCP Server 托管：全球首创将 MCP（Model Context Protocol）服务器作为插件托管，让 AI Agent 工具调用更简单
• 🚀 真正的动态配置：得益于 Envoy，配置变更毫秒级生效，对流量完全无损
• 💰 超低资源占用：相比传统 Java 网关，资源使用率降低 50% 以上

1.4 技术栈全景图

编程语言层
├── Go 1.22.2           (主控制器逻辑)
├── C++                 (Envoy 内核 + Wasm 插件)
├── Rust                (高性能 Wasm 插件)
└── JavaScript/AssemblyScript (轻量级 Wasm 插件)

核心依赖层
├── Istio 1.19.x        (服务网格核心)
├── Envoy 1.27.x        (数据平面代理)
├── Kubernetes 1.28.x   (容器编排)
└── gRPC 1.59.0         (xDS 协议通信)

服务发现层
├── Kubernetes Service  (原生支持)
├── Nacos 2.3.x         (阿里微服务)
├── Consul              (HashiCorp)
├── Eureka              (Netflix)
└── ZooKeeper           (Apache)

插件生态层
├── AI 相关 (17+ 插件)
│   ├── ai-proxy        (大模型统一代理)
│   ├── ai-cache        (AI 响应缓存)
│   ├── ai-token-ratelimit (Token 限流)
│   └── ai-agent        (Agent 编排)
├── 认证鉴权 (6+ 插件)
│   ├── jwt-auth
│   ├── key-auth
│   └── oidc
├── 流量管理 (8+ 插件)
│   ├── transformer
│   ├── request-block
│   └── ip-restriction
└── 可观测性 (4+ 插件)

1.5 外部系统集成

Higress 可以对接多种外部系统，形成完整的云原生生态：

Higress Gateway上游服务服务注册中心配置中心可观测性系统AI 模型服务NacosConsulEurekaZooKeeperKubernetes ConfigMapNacos ConfigPrometheusGrafanaSkywalkingOpenTelemetryOpenAI通义千问文心一言DeepSeek/vLLM

配置管理方式：

• K8s 环境：通过 CRD（Ingress、Gateway API、WasmPlugin 等）
• 独立部署：通过 ConfigMap 或文件系统
• MCP 协议：从外部配置中心同步（如 Nacos）

1.6 典型请求处理流程

让我们跟踪一个 AI 模型调用请求的完整生命周期：

大模型服务ai-token-ratelimit 插件ai-proxy 插件Higress Gateway用户大模型服务ai-token-ratelimit 插件ai-proxy 插件Higress Gateway用户1. Listener 接收请求POST /v1/chat/completions2. 路由匹配3. 执行限流插件检查 Token 配额通过4. 执行代理插件协议转换 (OpenAI -> 通义千问)5. 转发到上游模型6. 流式响应7. 协议转换 (通义千问 -> OpenAI)流式传递8. SSE 流式返回

流程说明：

1. 请求进入 Envoy Listener（监听 8080 端口）
2. 根据路由规则匹配到 ai-service 集群
3. 按配置顺序执行 Wasm 插件（限流、认证、代理）
1. ai-proxy 插件将 OpenAI 格式转换为目标模型格式
5. 通过 Cluster 转发到实际的模型服务
6. 收到流式响应后，插件进行反向转换
7. Envoy 以 SSE 格式流式返回给客户端
8. 全程无需缓存完整响应体，内存占用极低

💡 关键设计点： Higress 基于 Envoy 的流式处理能力，可以边接收边转发，这对 AI 场景的大 payload 和流式响应至关重要。

2. 目录结构与核心流程

2.1 目录组织逻辑

Higres项目采用功能模块化 + 技术分层的混合组织方式：

higress/
├── cmd/                    # 程序入口
│   └── higress/
│       └── main.go         # 🔑 启动入口，5 秒看懂
│
├── pkg/                    # 核心业务逻辑
│   ├── cmd/                # 命令行框架
│   │   ├── root.go         # Cobra 根命令
│   │   ├── server.go       # Server 命令（核心）
│   │   └── version.go      # 版本信息
│   │
│   ├── bootstrap/          # 服务启动与初始化
│   │   ├── server.go       # 🔑 Server 实现，核心中的核心
│   │   └── server_test.go
│   │
│   ├── ingress/            # Ingress 核心逻辑
│   │   ├── kube/           # 🔑 K8s 资源控制器（重点目录）
│   │   │   ├── annotations/    # Ingress 注解解析器（20+ 种）
│   │   │   ├── configmap/      # 全局配置管理
│   │   │   ├── gateway/        # Gateway API 控制器
│   │   │   ├── ingress/        # Ingress 控制器
│   │   │   ├── mcpbridge/      # 服务注册中心桥接
│   │   │   ├── wasmplugin/     # Wasm 插件控制器
│   │   │   └── http2rpc/       # HTTP到RPC协议转换
│   │   │
│   │   ├── mcp/            # MCP 协议实现
│   │   └── translation/    # 配置转换逻辑
│   │
│   ├── cert/               # 证书管理
│   │   ├── certmgr.go      # 自动证书签发（Let's Encrypt）
│   │   └── controller.go   # 证书控制器
│   │
│   ├── config/             # 配置定义
│   └── common/             # 公共工具类
│
├── registry/               # 服务注册中心适配
│   ├── nacos/              # Nacos 适配器
│   ├── consul/             # Consul 适配器
│   ├── eureka/             # Eureka 适配器
│   └── zookeeper/          # ZooKeeper 适配器
│
├── plugins/                # Wasm 插件生态 🌟
│   ├── wasm-go/            # 🔥 Go 语言插件（最活跃）
│   │   ├── extensions/     # 60+ 官方插件
│   │   │   ├── ai-proxy/   # 🔑 AI 模型统一代理
│   │   │   ├── ai-cache/
│   │   │   ├── jwt-auth/
│   │   │   └── ...
│   │   ├── mcp-servers/    # MCP Server 托管插件
│   │   └── pkg/            # 插件开发 SDK
│   │
│   ├── wasm-cpp/           # C++ 插件（高性能）
│   ├── wasm-rust/          # Rust 插件（内存安全）
│   └── wasm-assemblyscript/ # AssemblyScript 插件
│
├── api/                    # API 定义（Protobuf）
│   ├── extensions/         # Higress 扩展 API
│   └── networking/         # 网络配置 API
│
├── client/                 # Kubernetes Client 生成代码
├── helm/                   # Helm Charts
│   ├── higress/            # 完整部署 Chart
│   └── core/               # 核心组件 Chart
│
├── hgctl/                  # Higress CLI 工具
│   └── pkg/
│       ├── install.go      # 安装命令
│       ├── plugin/         # 插件管理
│       └── manifest.go     # 资源清单
│
├── test/                   # 测试代码
│   ├── e2e/                # 端到端测试
│   └── gateway/            # 网关测试
│
├── istio/                  # Istio 依赖（git submodule）
│   ├── api/                # Istio API 定义
│   ├── client-go/          # Istio Client
│   └── istio/              # Istio 核心代码
│
├── envoy/                  # Envoy 依赖
├── docs/                   # 架构文档
└── samples/                # 示例配置

目录设计的巧思：

• ✅ pkg/ingress/kube：这是 Higress 的"大脑"，所有 K8s 资源的监听和转换都在这里
• ✅ plugins/wasm-go/extensions：这是"武器库"，60+ 现成的插件覆盖 90% 的使用场景
• ✅ registry/：服务发现的"翻译官"，让 Higress 能对接各种注册中心
• ✅ hgctl/：独立的 CLI 工具，可以单独使用，无需编译整个项目

2.2 关键文件速查表

|
文件路径

作用

阅读优先级

|
| --- | --- | --- |
| cmd/higress/main.go |

程序入口，10 行代码

⭐⭐⭐⭐⭐

|
| pkg/cmd/server.go |

命令行参数定义

⭐⭐⭐⭐

|
| pkg/bootstrap/server.go |

Server 启动逻辑

⭐⭐⭐⭐⭐

|
| pkg/ingress/kube/ingress/controller.go |

Ingress 控制器核心

⭐⭐⭐⭐⭐

|
| pkg/ingress/kube/annotations/parser.go |

注解解析框架

⭐⭐⭐⭐

|
| pkg/ingress/kube/gateway/istio/conversion.go |

Gateway API 转换

⭐⭐⭐⭐

|
| plugins/wasm-go/extensions/ai-proxy/main.go |

AI 代理插件入口

⭐⭐⭐⭐⭐

|
| docs/architecture.md |

架构说明文档

⭐⭐⭐⭐⭐

|
| helm/core/values.yaml |

Helm 部署配置

⭐⭐⭐

2.3 核心流程深度剖析

让我以 Ingress 资源转换流程 为例，展示 Higress 的工作原理：

场景： 用户创建了一个 Ingress 资源，希望将 /api 路径的请求路由到 backend-service

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: demo-ingress
  annotations:
    higress.io/response-header-control-add: "X-Custom: my-value"
spec:
  rules:
  - host: api.example.com
    http:
      paths:
      - path: /api
        pathType: Prefix
        backend:
          service:
            name: backend-service
            port:
              number: 8080

流程图：

EnvoyIstio DiscoveryMCP ServerTranslation CoreAnnotation ParserIngress ControllerK8s API ServerEnvoyIstio DiscoveryMCP ServerTranslation CoreAnnotation ParserIngress ControllerK8s API Server等待 100ms 收集批量变更毫秒级生效，流量无损Watch Ingress 变更事件加入 Debounce 队列解析 Annotations识别 response-header-control返回解析结果转换为 Istio 配置生成 VirtualService生成 EnvoyFilter (响应头)返回 Istio 资源推送配置（MCP 协议）xDS over gRPC聚合所有配置源生成 LDS/RDS/CDS/EDS推送 xDS 配置热更新配置

实现文件索引：

1. 监听 Ingress 资源

• 文件：pkg/ingress/kube/ingress/controller.go
• 关键函数：NewController()、OnAdd()、OnUpdate()
• 代码位置：约 200-300 行

1. 解析 Annotations

• 文件：pkg/ingress/kube/annotations/parser.go
• 关键接口：Parser 接口定义
• 实现示例：pkg/ingress/kube/annotations/header_control.go

1. 转换为 Istio 配置

• 文件：pkg/ingress/kube/ingress/controller.go
• 关键函数：convertIngressToIstio()
• VirtualService 生成逻辑约 400-500 行

1. MCP 协议推送

• 文件：pkg/ingress/mcp/mcpbridge.go
• 关键函数：Push()
• 使用 gRPC streaming 推送

1. Istio Discovery 处理

• 文件：来自 istio/istio/pilot/pkg/config/aggregate/config.go
• Higress 调用 Istio 的 Config Controller 聚合逻辑

1. Envoy 配置生效

• 文件：Envoy 内核（C++）
• 通过 xDS 协议接收 LDS/RDS/CDS 配置
• 动态更新 Listener 和 Route 配置

💡 深度理解要点：

• Debounce 机制：批量变更时只触发一次推送，避免频繁更新
• Annotation 扩展性：每个 Annotation 都是一个独立的 Parser，易于扩展
• MCP 解耦：Higress Core 通过 MCP 协议与 Istio 解耦，可以独立升级
• xDS 增量推送：Envoy 只接收变更的配置，不是全量推送

2.4 流程图：从 Ingress 到流量转发

IngressGateway APIWasmPlugin创建 Ingress YAMLkubectl applyK8s API Server 存储Higress Controller 监听资源类型判断Ingress ControllerGateway ControllerWasmPlugin Controller解析 Annotations转换为 VirtualService转换为 EnvoyFilter推送到 MCP ServerIstio Discovery 聚合生成 xDS 配置推送到 EnvoyEnvoy 更新配置流量按新规则转发

3. 代码结构观察

3.1 代码组织模式

通过阅读源码，我观察到 Higress 遵循以下设计模式：

1. 控制器模式（Controller Pattern）

所有资源控制器都实现统一的接口：

// pkg/ingress/kube/common/controller.go
type Controller interface {
    Run(stop <-chan struct{})
}

实现示例：

• IngressController：处理 Ingress 资源
• GatewayController：处理 Gateway API 资源
• McpBridgeController：处理服务发现桥接
• WasmPluginController：处理 Wasm 插件

2. 观察者模式（Observer Pattern）

使用 Kubernetes Informer 机制监听资源变化：

informer.AddEventHandler(cache.ResourceEventHandlerFuncs{
    AddFunc:    controller.onAdd,
    UpdateFunc: controller.onUpdate,
    DeleteFunc: controller.onDelete,
})

3. 策略模式（Strategy Pattern）

Annotation 解析器采用策略模式，每个注解是一个独立的 Parser：

// pkg/ingress/kube/annotations/interface.go
type Parser interface {
    Parse(ing *networking.Ingress) (interface{}, error)
}

4. 工厂模式（Factory Pattern）

服务注册中心适配器使用工厂模式：

// registry/proxy/factory.go
func NewServiceEntryStore(registryType string) ServiceEntryStore {
    switch registryType {
    case "nacos":
        return nacos.NewController()
    case "consul":
        return consul.NewController()
    // ...
    }
}

3.2 设计模式识别

|
设计模式

应用场景

文件位置

优势

|
| --- | --- | --- | --- |
| Facade（外观） |

bootstrap.Server 封装复杂启动逻辑

| pkg/bootstrap/server.go |

简化外部调用，隐藏内部复杂性

|
| Adapter（适配器） |

多种服务注册中心适配

| registry/*/watcher.go |

统一接口，易于扩展新的注册中心

|
| Builder（建造者） |

Istio 配置构建

| pkg/ingress/kube/ingress/ |

复杂对象分步构建，代码清晰

|
| Template Method（模板方法） |

控制器生命周期管理

| pkg/ingress/kube/common/ |

统一流程，子类实现细节

|
| Chain of Responsibility（责任链） |

Annotation 解析链

| pkg/ingress/kube/annotations/ |

灵活扩展，职责分离

3.3 代码质量观察

优点： ✅

1. 模块职责清晰

• 每个控制器独立负责一种资源类型
• Annotation 解析器高度解耦，一个注解一个文件

1. 测试覆盖充分

• 关键路径有单元测试（*_test.go）
• Gateway API 转换有大量 golden 测试文件（32 个）

1. 错误处理规范

• 使用 github.com/go-errors/errors 增强错误信息
• 关键路径有完整的错误日志

1. 依赖注入

• Server 结构体通过参数注入依赖
• 便于单元测试 mock

改进空间： ⚠️

1. 函数长度

• pkg/bootstrap/server.go 的 NewServer() 函数超过 300 行
• 建议拆分为多个私有方法

1. 重复代码

• 多个控制器的 Run() 方法逻辑相似
• 可以提取公共的模板方法

1. 魔法数字

• 部分代码中存在硬编码的数值（如 Debounce 时间）
• 建议定义为常量并添加注释

值得学习的代码片段： 💡

// pkg/ingress/kube/annotations/parser.go
// 优雅的注解解析框架设计
type parser struct {
    parsers map[string]Parser
}

func (p *parser) GetAnnotations(ing *networking.Ingress) map[string]interface{} {
    result := make(map[string]interface{})
    for name, parser := range p.parsers {
        if val, err := parser.Parse(ing); err == nil {
            result[name] = val
        }
    }
    return result
}

这段代码展示了：

• 使用 map 管理多个 Parser，易于扩展
• 优雅处理错误，不阻塞其他解析器
• 返回统一的数据结构

3.4 潜在改进点（学习机会）

通过搜索代码中的 TODO 和 FIXME 注释，我发现了一些值得探索的方向：

1. 性能优化机会

• 📁 pkg/ingress/kube/ingress/controller.go
• 💬 TODO: "考虑使用增量更新而非全量转换"
• 💡 学习价值：可以研究如何实现增量配置计算

1. 功能增强点

• 📁 registry/nacos/watcher.go
• 💬 FIXME: "暂不支持 Nacos 命名空间隔离"
• 💡 学习价值：可以尝试实现这个功能，提交 PR

1. 测试覆盖待提升

• 📁 pkg/cert/certmgr.go
• 💬 TODO: "补充证书续签的集成测试"
• 💡 学习价值：编写测试是理解代码的好方法

1. 文档待完善

• 📁 plugins/wasm-go/extensions/ai-agent/
• 💬 TODO: "添加更多使用示例"
• 💡 学习价值：编写文档能加深理解

如何寻找贡献机会：

# 搜索 TODO 注释
grep -r "TODO" pkg/ --include="*.go"

# 搜索 FIXME 注释
grep -r "FIXME" pkg/ --include="*.go"

# 查看 GitHub Issues 中的 good-first-issue 标签
# https://github.com/alibaba/higress/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22

好了，第一部分我们完成了项目的"全景扫描"。😊 是不是对 Higress 的架构有了清晰的认知？别急，接下来我们进入第二部分，一起梳理学习这个项目需要掌握哪些技能。

第二部分：技能需求清单（你的学习弹药库）📚

本部分目标： 明确学习 Higress 需要的技能树，并根据不同学习目标提供分级建议。不要被吓到，我会告诉你哪些是必须的，哪些可以边学边用。

1. 基础技能要求

1.1 编程语言核心技能

Go 语言（必须 ⭐⭐⭐⭐⭐）

Higress 控制平面 100% 使用 Go，你需要掌握：

• ✅ Goroutine 和 Channel 并发模型
• ✅ Interface 和反射机制
• ✅ Context 包用于超时控制
• ✅ 常用标准库：net/http、encoding/json、sync

版本要求： Go 1.22.2（从 go.mod 第 3 行可见）

关键第三方库：

• github.com/spf13/cobra - CLI 框架
• k8s.io/client-go - K8s 客户端
• istio.io/istio - Istio 核心库
• google.golang.org/grpc - gRPC 框架

Kubernetes（必须 ⭐⭐⭐⭐⭐）

核心概念：Pod、Service、Deployment、ConfigMap、Secret、Ingress、CRD
Client-go 库：Informer 机制、Lister 接口、Workqueue
版本要求：Kubernetes 1.28.x

Istio 和 Envoy（重要 ⭐⭐⭐⭐）

• Istio 架构：Pilot、VirtualService、DestinationRule、Gateway
• Envoy 基础：Listener、Route、Cluster、xDS 协议
• Wasm 插件机制：Proxy-Wasm 规范

1.2 网络协议和标准

• HTTP/HTTPS、HTTP/2
• gRPC 和 Protobuf
• WebSocket 和 Server-Sent Events
• TLS/SSL 证书原理

1.3 工具链

Docker、Helm、kubectl、curl、VS Code（必备）

2. 进阶技能要求

2.1 架构模式

• 微服务架构和服务网格
• 云原生设计模式（Sidecar、Ambassador、Circuit Breaker）
• SOLID 设计原则

2.2 领域特定知识

AI/LLM 领域：

• OpenAI API 规范
• 流式响应（SSE）
• Token 计算和限流
• 模型路由和 Fallback

网络安全：

• OAuth 2.0 / OIDC
• JWT 原理
• HMAC 签名
• WAF 规则

服务注册中心：

• Nacos、Consul、Eureka、ZooKeeper

3. 技能掌握程度建议

初学者（1-2 周）

• 必须：Docker、K8s 基础、YAML 配置
• 目标：能运行和配置 Higress

有经验开发者（1-2 月）

• 必须：Go 中级、Client-go、Istio VirtualService、Wasm 插件
• 目标：能修改和扩展功能

进阶贡献者（3-6 月）

• 必须：Go 高级、Istio/Envoy 深度、gRPC/Protobuf、Controller 开发
• 目标：能提交 PR 和修复 Bug

第三部分：学习路径规划（你的专属教练计划）🎯

本部分目标： 提供分阶段、可执行的学习计划，每个阶段都有明确的目标和验收标准。

1. 快速上手（15-30 分钟）

1.1 Docker All-in-One 部署

# 创建工作目录
mkdir higress-demo && cd higress-demo

# 启动 Higress
docker run -d --rm --name higress-ai \
    -v ${PWD}:/data \
    -p 8001:8001 -p 8080:8080 -p 8443:8443 \
    higress-registry.cn-hangzhou.cr.aliyuncs.com/higress/all-in-one:latest

# 等待启动，看到 "Higress is ready" 表示成功
docker logs -f higress-ai

端口说明：

• 8001：Web 控制台
• 8080：HTTP 网关
• 8443：HTTPS 网关

验证：

# 访问控制台
open http://localhost:8001

# 测试网关
curl http://localhost:8080
# 返回: {"message":"No route matched"} 表示正常

1.2 第一个路由（5 分钟）

通过控制台创建路由：

1. 服务来源 → 固定地址 → httpbin.org:80
2. 路由配置 → /httpbin → httpbin 服务

测试：

curl http://localhost:8080/httpbin

1.3 第一个插件（10 分钟）

添加响应头插件：

1. 插件配置 → custom-response
2. 配置添加响应头：X-Higress-Demo: Hello!

2. 循序渐进学习计划

阶段一：环境搭建（1-2 天）

• 完成部署和基本配置
• 创建 3 种不同类型路由
• 尝试 3 个官方插件
• 阅读快速开始文档

验收： 能独立配置路由和插件

阶段二：核心流程理解（3-5 天）

• 阅读架构文档
• 理解 Ingress → Istio → xDS → Envoy 流程
• 观察中间配置状态
• 画出流程图

验收： 能解释配置转换流程

阶段三：模块深入（1-2 周）

选择一个方向：

• Wasm 插件开发（推荐）
• Controller 源码研究
• 服务发现模块

验收： 能开发简单功能

阶段四：架构掌握（2 周+）

• 精读 Istio/Envoy 文档
• 深入 xDS 协议
• 阅读所有核心代码
• 修复 Issue 并提交 PR

验收： PR 被合并

3. 学习路径流程图

1-2天是否3-5天是否1-2周是否2周+开始阶段一: 环境搭建能独立配置?阶段二: 核心流程能画流程图?阶段三: 模块深入能独立开发?阶段四: 架构掌握成为专家

第四部分：实践建议和进阶指导（从会用到精通）💡

本部分目标： 提供实战技巧、常见陷阱和进阶路径，帮助你快速成长。

1. 调试技巧

1.1 查看控制器日志

# Docker 环境
docker logs -f higress-ai

# K8s 环境
kubectl logs -n higress-system -l app=higress-controller -f

1.2 查看 Envoy 配置

kubectl exec -n higress-system higress-gateway-xxx -c istio-proxy -- \
    curl localhost:15000/config_dump | jq . > config.json

1.3 查看生成的 Istio 配置

kubectl get virtualservice -A -o yaml
kubectl get gateway -A -o yaml

2. 常见陷阱

❌ 问题 1：配置不生效

• 检查 IngressClass 是否正确
• 查看控制器日志
• 确认 Ingress 注解拼写

❌ 问题 2：插件不工作

• 检查插件 URL 是否可访问
• 查看 WasmPlugin 资源状态
• 确认路由匹配规则

❌ 问题 3：端口冲突

• 修改端口映射
• 检查防火墙规则

3. 扩展练习建议

初级练习：

1. 配置灰度发布（基于 Header）
2. 添加 JWT 认证
3. 配置 IP 白名单

中级练习：

1. 开发简单 Wasm 插件
2. 对接 Nacos 服务发现
3. 配置 HTTPS 和证书

高级练习：

1. 开发复杂 AI 插件
2. 贡献 Controller 功能
3. 性能调优和压测

4. 参与贡献

寻找 Issue：

• 访问 https://github.com/alibaba/higress/issues
• 筛选 good first issue 标签
• 阅读 CONTRIBUTING 文档

提交 PR 流程：

1. Fork 项目
2. 创建功能分支
3. 编写代码和测试
4. 提交 PR 并描述清楚
5. 响应 Review 意见

代码规范：

• 遵循 Go 代码规范
• 添加充分的单元测试
• 更新相关文档
• Commit 信息遵循约定式提交

第五部分：技术栈学习指引（你的知识地图）🌐

本部分目标： 为关键技术栈提供学习资源和路径指引。

1. 官方文档定位

核心项目文档

|
项目

官方文档

重点章节

|
| --- | --- | --- |
| Higress |

https://higress.cn/docs/

快速开始、架构设计、插件开发

|
| Istio |

https://istio.io/latest/zh/docs/

流量管理、安全、可观测性

|
| Envoy |

https://www.envoyproxy.io/docs/

架构概览、xDS 协议、过滤器

|
| Kubernetes |

https://kubernetes.io/zh-cn/docs/

概念、任务、参考

|
| Go |

https://go.dev/doc/

语言规范、标准库、最佳实践

重点阅读章节

Higress：

• 快速开始：Docker 和 K8s 部署
• 核心概念：路由、插件、服务发现
• 插件开发：Wasm Go SDK 使用
• AI 网关：ai-proxy 插件配置

Istio：

• VirtualService：路由规则定义
• Gateway：边缘流量管理
• DestinationRule：负载均衡和熔断
• EnvoyFilter：Envoy 底层配置

Envoy：

• 请求生命周期：理解处理流程
• xDS 协议：动态配置更新
• HTTP 过滤器：插件执行机制
• Wasm 扩展：插件开发

2. 推荐学习资源

书籍

1. 《Istio 权威指南》 - 理解服务网格
1. 《云原生服务网格 Istio》 - 实战案例
1. 《Go 语言高级编程》 - 深入 Go
1. 《Kubernetes 权威指南》 - K8s 全面理解

在线课程

1. Go 语言： Go Tour[1]
1. Kubernetes： Kubernetes 官方教程[2]
1. Istio： Istio 官方工作坊[3]

技术博客

1. Higress 官方博客： https://higress.cn/blog/
1. 赵化冰的博客： https://www.zhaohuabing.com/ （Istio 深度解析）
1. 阿里云云原生： https://developer.aliyun.com/group/cloudnative

3. 学习路径建议

技能学习顺序

Go 基础K8s 概念Docker 容器Higress 部署Istio 架构Envoy 原理Wasm 插件xDS 协议

第 1-2 周： Go 语言基础 + Docker
第 3-4 周： Kubernetes 核心概念
第 5 周： Higress 快速上手
第 6-8 周： Istio 和 Envoy 深入
第 9-12 周： Wasm 插件开发和源码阅读

核心概念优先级

必须掌握（⭐⭐⭐⭐⭐）：

• Ingress 资源和路由配置
• VirtualService 和 Gateway
• Wasm 插件机制
• xDS 协议基础

重要理解（⭐⭐⭐⭐）：

• Istio 配置模型
• Envoy Filter Chain
• 服务发现机制
• gRPC 和 Protobuf

进阶探索（⭐⭐⭐）：

• Envoy 性能调优
• 自定义 CRD
• 分布式追踪
• 安全最佳实践

4. 工具与环境配置

开发环境

# 安装 Go
wget https://go.dev/dl/go1.22.2.linux-amd64.tar.gz
sudo tar -C /usr/local -xzf go1.22.2.linux-amd64.tar.gz
export PATH=$PATH:/usr/local/go/bin

# 安装 kubectl
curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/linux/amd64/kubectl"
sudo install -o root -g root -m 0755 kubectl /usr/local/bin/kubectl

# 安装 Helm
curl https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3 | bash

# 安装 Docker
curl -fsSL https://get.docker.com | bash

# 安装本地 K8s（minikube 或 kind）
# minikube
curl -LO https://storage.googleapis.com/minikube/releases/latest/minikube-linux-amd64
sudo install minikube-linux-amd64 /usr/local/bin/minikube

# kind
go install sigs.k8s.io/kind@latest

VS Code 配置

推荐插件：

• Go - Go 语言支持
• Kubernetes - K8s 资源管理
• YAML - YAML 语法高亮
• REST Client - API 测试
• Remote - SSH - 远程开发

settings.json:

{
  "go.useLanguageServer": true,
  "go.lintTool": "golangci-lint",
  "go.formatTool": "goimports",
  "[yaml]": {
    "editor.defaultFormatter": "redhat.vscode-yaml"
  }
}

5. 进阶拓展方向

技术深度

1. Envoy C++ 开发

• 学习 Envoy Filter 开发
• 理解 Envoy 内存模型
• 贡献 Envoy 社区

1. Wasm 虚拟机

• 研究 Wasm 执行原理
• 性能优化技巧
• 安全沙箱机制

1. 分布式系统

• CAP 理论
• 一致性协议（Raft）
• 服务网格最佳实践

社区资源

GitHub 仓库：

• Higress：https://github.com/alibaba/higress
• Istio：https://github.com/istio/istio
• Envoy：https://github.com/envoyproxy/envoy

社区论坛：

• Higress 钉钉群：扫描 README 中的二维码
• Istio Discuss：https://discuss.istio.io/
• CNCF Slack：https://slack.cncf.io/

技术大会：

• KubeCon + CloudNativeCon
• Istio Community Meeting
• QCon 全球软件开发大会
• 阿里云开发者大会

写在最后 🎓

恭喜你读到这里！🎉 这份学习指南凝聚了我对 Higress 项目的深入分析和理解。

学习建议：

• ✅ 不要急于求成，循序渐进
• ✅ 多动手实践，少纸上谈兵
• ✅ 善用社区资源，遇到问题及时提问
• ✅ 记录学习笔记，画流程图加深理解
• ✅ 贡献开源社区，在实践中成长

记住： 成为专家不是一蹴而就的，每个 Higress 的核心贡献者都是从"Hello World"开始的。保持好奇心，享受学习过程，你也可以成为下一个 Higress 专家！💪

有问题随时：

• 📧 提 GitHub Issue
• 💬 加入钉钉群讨论
• 📝 查阅官方文档
• 🤝 参与社区活动

祝你学习愉快！🚀

引用链接

[1] Go Tour: https://tour.golang.org/
[2] Kubernetes 官方教程: https://kubernetes.io/zh-cn/docs/tutorials/
[3] Istio 官方工作坊: https://istio.io/latest/zh/docs/setup/getting-started/

探索云世界

热门

云计算

大数据

云原生

人工智能

数据库

开发与运维

活动广场

任务中心

训练营

直播

乘风者计划

下载

镜像站

技术资料

Higress（云原生AI网关） 架构学习指南

Higress 架构学习指南 🚀

第一部分：项目架构深度解析（像架构师一样俯瞰全景）🔍

1. 项目架构概览

1.1 用一个贴切的类比理解 Higress 🏗️

1.2 核心设计特征

1.3 与同类项目的对比

1.4 技术栈全景图

1.5 外部系统集成

1.6 典型请求处理流程

2. 目录结构与核心流程

2.1 目录组织逻辑

2.2 关键文件速查表

2.3 核心流程深度剖析

2.4 流程图：从 Ingress 到流量转发

3. 代码结构观察

3.1 代码组织模式

3.2 设计模式识别

3.3 代码质量观察

3.4 潜在改进点（学习机会）

第二部分：技能需求清单（你的学习弹药库）📚

1. 基础技能要求

1.1 编程语言核心技能

1.2 网络协议和标准

1.3 工具链

2. 进阶技能要求

2.1 架构模式

2.2 领域特定知识

3. 技能掌握程度建议

初学者（1-2 周）

有经验开发者（1-2 月）

进阶贡献者（3-6 月）

第三部分：学习路径规划（你的专属教练计划）🎯

1. 快速上手（15-30 分钟）

1.1 Docker All-in-One 部署

1.2 第一个路由（5 分钟）

1.3 第一个插件（10 分钟）

2. 循序渐进学习计划

阶段一：环境搭建（1-2 天）

阶段二：核心流程理解（3-5 天）

阶段三：模块深入（1-2 周）

阶段四：架构掌握（2 周+）

3. 学习路径流程图

第四部分：实践建议和进阶指导（从会用到精通）💡

1. 调试技巧

1.1 查看控制器日志

1.2 查看 Envoy 配置

1.3 查看生成的 Istio 配置

2. 常见陷阱

3. 扩展练习建议

4. 参与贡献

第五部分：技术栈学习指引（你的知识地图）🌐

1. 官方文档定位

核心项目文档

重点阅读章节

2. 推荐学习资源

书籍

在线课程

技术博客

3. 学习路径建议

技能学习顺序

核心概念优先级

4. 工具与环境配置

开发环境

Higress（云原生AI网关）架构学习指南