Higress 详细笔记

Kubernetes 环境下的 Higress 入门与部署实践

- [1. 背景：为什么要学习 Higress？](#1. 背景：为什么要学习 Higress？)
- [2. Higress 是什么？](#2. Higress 是什么？)
- [3. Higress 和之前见过的 KServe 有什么关系？](#3. Higress 和之前见过的 KServe 有什么关系？)
- [4. Higress 的核心组件](#4. Higress 的核心组件)
- - [4.1 higress-controller：控制平面](#4.1 higress-controller：控制平面)
  - [4.2 higress-gateway：数据平面](#4.2 higress-gateway：数据平面)
  - [4.3 Ingress / Gateway API：路由声明](#4.3 Ingress / Gateway API：路由声明)
- [5. 本地实验环境](#5. 本地实验环境)
- [6. 安装 Higress](#6. 安装 Higress)
- - [6.1 检查 Kubernetes 集群状态](#6.1 检查 Kubernetes 集群状态)
  - [6.2 添加 Higress Helm 仓库](#6.2 添加 Higress Helm 仓库)
  - [6.3 安装 Higress](#6.3 安装 Higress)
  - [6.4 查看 Higress 组件](#6.4 查看 Higress 组件)
- [7. 部署一个测试服务](#7. 部署一个测试服务)
- [8. 创建 Higress 路由](#8. 创建 Higress 路由)
- [9. 本地访问验证](#9. 本地访问验证)
- [10. Higress 后续项目开发应该学什么？](#10. Higress 后续项目开发应该学什么？)
- - [10.1 路由能力](#10.1 路由能力)
  - [10.2 插件能力](#10.2 插件能力)
  - [10.3 Go Wasm 插件开发](#10.3 Go Wasm 插件开发)
  - [10.4 和 KServe / vLLM 结合](#10.4 和 KServe / vLLM 结合)
- [11. 总结](#11. 总结)

1. 背景：为什么要学习 Higress？

一段 AI 推理，或者普通的请求，访问是这样的：

text 复制代码

用户请求 → 进入集群 → 转发到模型服务 → 返回推理结果

但是这里还有一个关键问题：

text 复制代码

请求到底是怎么进入 Kubernetes 集群的？

之前博客提到的 KServe ，关注的是部署模型服务本身，如 InferenceService、Predictor、Runtime、Pod、Service、HPA 等；

而 Higress 要解决的就是更靠前的一层问题：集群入口流量如何接入、路由、治理、安全控制，以及未来如何面向 AI 服务做统一网关。

所以：

text 复制代码

KServe：负责把模型服务跑起来
Volcano：负责 AI 任务和资源调度
Higress：负责外部流量进入集群后的网关治理

对于 AI Infra / 智算云开发来说，Higress 不是一个孤立组件，而是整个模型服务平台入口层的重要组成部分。

2. Higress 是什么？

Higress 是一个基于 Istio + Envoy 的云原生 API 网关，可以作为 Kubernetes Ingress 网关、微服务网关，也可以作为 AI 网关使用。

更直白一点：

text 复制代码

Higress = 入口流量管理 + 路由转发 + 插件扩展 + 安全治理 + AI 网关能力

它可以帮我们做这些事情：

把外部 HTTP / HTTPS 请求转发到 Kubernetes 内部服务；
根据域名、路径、Header 等规则做路由；
对请求做鉴权、限流、灰度、跨域、安全防护；
通过插件机制扩展网关能力；
在 AI 场景下统一管理大模型 API、模型调用、限流、观测和降级。

但此刻只为入门，可以先不要把 Higress 想复杂。第一阶段只需要记住：

text 复制代码

Higress 就是 Kubernetes 集群入口处的高级网关。

3. Higress 和之前见过的 KServe 有什么关系？

之前学习 KServe 时，核心是：

text 复制代码

InferenceService → 自动创建底层 Deployment / Service / HPA → 对外提供模型服务

但是模型服务真正对外暴露时，通常还需要一个入口网关。

所以未来在 AI 推理平台里，一个比较完整的链路可能是：

text 复制代码

用户 / 前端 / API 调用方
        ↓
Higress 网关
        ↓
KServe InferenceService
        ↓
vLLM / Triton / sklearn server / 模型运行时
        ↓
模型推理结果

也就是说：

text 复制代码

KServe 更偏模型服务管理；
Higress 更偏流量入口治理。

两者不是替代关系，而是上下游关系。

在实际项目中，Higress 可能会负责统一入口，例如：

text 复制代码

/api/v1/chat       → 转发到大模型服务
/api/v1/embedding  → 转发到向量模型服务
/api/v1/rerank     → 转发到重排序模型服务
/api/v1/admin      → 转发到后端管理服务

这样平台对外只有一个统一入口，内部可以挂很多服务。

4. Higress 的核心组件

使用 Helm 安装 Higress 后，主要会看到两个核心组件：

text 复制代码

higress-controller
higress-gateway

4.1 higress-controller：控制平面

higress-controller 负责监听 Kubernetes 里的配置变化，比如 Ingress、Service、Endpoint 等资源。

当我们创建一个 Ingress 资源时，controller 会把这份路由配置转换成网关可以理解的配置，并下发给数据面。

它更像是：

text 复制代码

配置管理者

4.2 higress-gateway：数据平面

higress-gateway 负责真正处理请求流量。

用户请求进入集群后，会先经过 gateway，再由 gateway 根据路由规则转发到后端服务。

它更像是：

text 复制代码

真实处理流量的网关入口

4.3 Ingress / Gateway API：路由声明

Higress 可以通过 Kubernetes 原生的 Ingress 资源来配置路由。

比如：

yaml 复制代码

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: foo
spec:
  ingressClassName: higress
  rules:
  - host: foo.bar.com
    http:
      paths:
      - pathType: Prefix
        path: "/foo"
        backend:
          service:
            name: foo-service
            port:
              number: 5678

这段配置表达的意思是：

text 复制代码

访问 foo.bar.com/foo 的请求，转发到 foo-service:5678

这和之前学习 Kubernetes Service、Ingress 的知识是可以直接串起来的。

5. 本地实验环境

这是我当前的实验环境，你需要至少等于或高于这个：

text 复制代码

本机系统：Windows
虚拟化环境：VMware
K8s 环境：Ubuntu + kubeadm
集群形态：本地 Kubernetes 测试集群
已有基础：kubectl、Helm、KServe、Volcano 入门
GPU 情况：没有真实 NVIDIA GPU，只有 VMware 虚拟显卡

因为 Higress 本质上是网关组件，所以这次实验不需要真实 GPU。

也就是说，即使当前无法跑大模型 GPU 推理，也完全可以先把 Higress 的网关链路跑通。

本次目标是：

text 复制代码

在本地 Kubernetes 集群中安装 Higress；
部署一个简单 HTTP 服务；
通过 Higress Ingress 路由访问这个服务；
完成本地 curl 验证。

6. 安装 Higress

6.1 检查 Kubernetes 集群状态

先确认当前集群正常：

bash 复制代码

kubectl get nodes

正常情况下应该看到 master / worker 节点处于 Ready 状态：

bash 复制代码

NAME          STATUS   ROLES           AGE   VERSION
master-k8s    Ready    control-plane   ...
worker-1      Ready    <none>          ...
worker-2      Ready    <none>          ...

再确认 Helm 可用：

bash 复制代码

helm version

6.2 添加 Higress Helm 仓库

bash 复制代码

helm repo add higress.io https://higress.io/helm-charts
helm repo update

6.3 安装 Higress

由于我是在本地 VMware / kubeadm 环境里做测试，不是云厂商 ACK、EKS、GKE 那种带 LoadBalancer 的托管集群，所以这里使用本地测试参数：

bash 复制代码

helm install higress higress.io/higress \
  -n higress-system \
  --create-namespace \
  --render-subchart-notes \
  --set global.local=true \
  --set global.o11y.enabled=false

这里几个参数的含义：

text 复制代码

-n higress-system
表示安装到 higress-system 命名空间。

--create-namespace
如果命名空间不存在，则自动创建。

--set global.local=true
表示当前是本地 K8s 测试环境。

--set global.o11y.enabled=false
暂时不安装内置观测套件，降低本地资源压力。

对于我的 VMware 环境来说，先不要一上来就打开 Prometheus、Grafana、Loki 这些组件，因为当前重点是先跑通网关访问链路。

6.4 查看 Higress 组件

安装完成后查看 Pod：

bash 复制代码

kubectl get pods -n higress-system

预期能看到类似组件：

text 复制代码

higress-controller-xxx
higress-gateway-xxx
higress-console-xxx

再查看 Service：

bash 复制代码

kubectl get svc -n higress-system

重点关注：

text 复制代码

higress-gateway

它就是后面负责接收外部请求的网关入口。

7. 部署一个测试服务

为了验证 Higress 是否能正常转发请求，先部署一个最简单的 HTTP echo 服务。

新建文件：

bash 复制代码

vim foo.yaml

写入：

yaml 复制代码

apiVersion: v1
kind: Pod
metadata:
  name: foo-app
  labels:
    app: foo
spec:
  containers:
  - name: foo-app
    image: higress-registry.cn-hangzhou.cr.aliyuncs.com/higress/http-echo:0.2.4-alpine
    args:
    - "-text=foo"
---
apiVersion: v1
kind: Service
metadata:
  name: foo-service
spec:
  selector:
    app: foo
  ports:
  - port: 5678
    targetPort: 5678

应用配置：

bash 复制代码

kubectl apply -f foo.yaml

查看 Pod 和 Service：

bash 复制代码

kubectl get pod
kubectl get svc

确认 foo-app 正常 Running：

bash 复制代码

kubectl get pod foo-app

8. 创建 Higress 路由

接下来创建一个 Ingress，把外部请求转发到 foo-service。

新建文件：

bash 复制代码

vim foo-ingress.yaml

写入：

yaml 复制代码

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: foo
spec:
  ingressClassName: higress
  rules:
  - host: foo.bar.com
    http:
      paths:
      - pathType: Prefix
        path: "/foo"
        backend:
          service:
            name: foo-service
            port:
              number: 5678

应用：

bash 复制代码

kubectl apply -f foo-ingress.yaml

查看 Ingress：

bash 复制代码

kubectl get ingress

这里最关键的是：

yaml 复制代码

ingressClassName: higress

它告诉 Kubernetes：

text 复制代码

这个 Ingress 资源交给 Higress 来处理。

如果这里写错，Higress 就不会接管这条路由。

9. 本地访问验证

在云厂商 Kubernetes 里，网关通常可以通过 LoadBalancer 暴露公网 IP。

但我的环境是 VMware 本地 kubeadm 集群，一般没有云厂商 LoadBalancer，所以这里用 port-forward 做本地测试。

执行：

bash 复制代码

kubectl port-forward service/higress-gateway -n higress-system 8080:80

保持这个终端不要关闭。

然后新开一个终端，执行：

bash 复制代码

curl http://127.0.0.1:8080/foo -H "Host: foo.bar.com"

如果返回：

text 复制代码

foo

说明链路已经跑通：

text 复制代码

curl 请求
  → 本机 8080
  → port-forward 到 higress-gateway:80
  → Higress 根据 Host + Path 匹配路由
  → 转发到 foo-service:5678
  → foo-app 返回 foo

这一步非常关键，因为它证明 Higress 已经可以作为 Kubernetes 集群入口网关工作。

10. Higress 后续项目开发应该学什么？

Higress 入门不是只会安装就结束了。

如果后面要开始接触项目开发，我认为应该按下面几个方向继续学。

10.1 路由能力

先掌握最基础的路由配置：

text 复制代码

按域名路由
按路径路由
按 Header 路由
HTTP / HTTPS 转发
服务发现
后端服务配置

对应到 Kubernetes 里，就是熟悉：

text 复制代码

Ingress
Service
Endpoint
Gateway API

对于我现在的基础来说，先把 Ingress 方式学熟，再逐步看 Gateway API 会更稳。

10.2 插件能力

Higress 的一个重要能力是插件扩展。

插件可以做很多事情：

text 复制代码

鉴权
限流
Header 改写
请求拦截
安全防护
AI 请求治理
模型调用统计

这和后端开发关系很大。

比如以后做一个 AI 平台，可能需要限制每个用户每分钟最多调用多少次模型服务，这就属于网关层限流。

10.3 Go Wasm 插件开发

因为我的技术路线里包含 Go 后端，所以后面可以重点关注 Higress 的 Go Wasm 插件开发。

可以把它理解成：

text 复制代码

用 Go 写一段网关逻辑，然后挂到 Higress 上，在请求进入业务服务之前执行。

例如写一个简单插件：

text 复制代码

请求进入 Higress
  → 插件读取 Header
  → 校验 token
  → 校验通过则继续转发
  → 校验失败则直接返回 401

这类能力非常接近真实项目开发。

后续可以从三个小 Demo 入手：

text 复制代码

Demo 1：给请求自动添加 Header
Demo 2：拦截没有 token 的请求
Demo 3：根据用户 ID 做简单限流

10.4 和 KServe / vLLM 结合

当 Higress 基础路由跑通后，就可以和之前学的 KServe 结合起来。

比如未来可以做这样的实验：

text 复制代码

部署一个 KServe sklearn-iris 服务
        ↓
通过 Higress 暴露访问入口
        ↓
使用 curl 通过 Higress 调用模型预测接口

再往后升级：

text 复制代码

部署 vLLM OpenAI-compatible API
        ↓
通过 KServe 或普通 Deployment 管理
        ↓
通过 Higress 暴露 /v1/chat/completions
        ↓
在 Higress 层做鉴权、限流、日志、模型路由

这样就从普通网关学习，逐步过渡到了 AI Gateway 场景。

11. 总结

所以说，Higress 是 Kubernetes 集群入口处的云原生 API 网关，负责把外部请求安全、稳定、可治理地转发到集群内部服务。

Higress 的价值在于，它不是一个单独的工具，而是 AI 云原生平台入口层的重要组成部分。

text 复制代码

KServe 解决模型服务怎么跑；
Volcano 解决 AI 任务怎么调度；
Higress 解决外部流量怎么进来、怎么治理、怎么安全地访问模型服务。

本篇博客所做的部署实验：

text 复制代码

1. Helm 安装 Higress；
2. 部署测试 HTTP 服务；
3. 创建 Ingress 路由；
4. 使用 port-forward 暴露本地访问；
5. 使用 curl 验证请求成功转发。