Higress 路由配置 - 我的博客

NOTE
路由是网关的核心能力。Higress 兼容 K8s Ingress 和 Gateway API 标准，同时提供丰富的扩展注解。

路由配置方式对比#

方式	标准	复杂度	功能	推荐场景
Ingress	K8s 原生	⭐⭐	基础路由 + 注解扩展	兼容现有 Ingress
Gateway API	K8s 新一代	⭐⭐⭐	功能更强、角色分离	新项目、复杂路由
Higress Console	Web UI	⭐	可视化配置	快速上手、运维

方式一：Ingress 路由#

基础路由（域名 + 路径）#

1
apiVersion: networking.k8s.io/v1
2
kind: Ingress
3
metadata:
4
  name: demo-ingress
5
  namespace: default
6
  annotations:
7
    higress.io/destination: "httpbin.default.svc.cluster.local:80"
8
spec:
9
  ingressClassName: higress
10
  rules:
11
    - host: demo.example.com
12
      http:
13
        paths:
14
          - path: /api
15
            pathType: Prefix
16
            backend:
17
              service:
18
                name: httpbin
19
                port:
20
                  number: 80

测试：

1
curl -H "Host: demo.example.com" http://<gateway-ip>/api/get

路径匹配类型#

pathType	说明	示例
Exact	精确匹配	`/api/v1/users` 只匹配该路径
Prefix	前缀匹配	`/api` 匹配 `/api`、`/api/v1`、`/api/v2`
ImplementationSpecific	实现相关	Higress 支持正则（见下文）

正则路径匹配（Higress 扩展）#

1
metadata:
2
  annotations:
3
    higress.io/use-regex: "true"
4
    higress.io/rewrite-target: /$1
5
spec:
6
  rules:
7
    - host: api.example.com
8
      http:
9
        paths:
10
          - path: /api/(.*)
11
            pathType: ImplementationSpecific
12
            backend:
13
              service:
14
                name: api-service
15
                port:
16
                  number: 8080

效果：

/api/users → 转发到 /users
/api/orders/123 → 转发到 /orders/123

1
metadata:
2
  annotations:
3
    higress.io/header-match: "X-Env:gray"
4
spec:
5
  rules:
6
    - host: api.example.com
7
      http:
8
        paths:
9
          - path: /api
10
            pathType: Prefix
11
            backend:
12
              service:
13
                name: api-gray
14
                port:
15
                  number: 8080

效果：只有 X-Env: gray 的请求才路由到 gray 服务。

Query 参数匹配#

1
metadata:
2
  annotations:
3
    higress.io/query-match: "version:v2"
4
spec:
5
  rules:
6
    - host: api.example.com
7
      http:
8
        paths:
9
          - path: /api
10
            pathType: Prefix
11
            backend:
12
              service:
13
                name: api-v2
14
                port:
15
                  number: 8080

效果：/api?version=v2 路由到 v2 服务。

方式二：Gateway API 路由#

Gateway + HTTPRoute#

1
# 1. 定义 Gateway（监听端口）
2
apiVersion: gateway.networking.k8s.io/v1
3
kind: Gateway
4
metadata:
5
  name: demo-gateway
6
  namespace: higress-system
7
spec:
8
  gatewayClassName: higress
9
  listeners:
10
    - name: http
11
      protocol: HTTP
12
      port: 80
13
      allowedRoutes:
14
        namespaces:
15
          from: All
16

17
---
18
# 2. 定义 HTTPRoute（路由规则）
19
apiVersion: gateway.networking.k8s.io/v1
20
kind: HTTPRoute
21
metadata:
22
  name: demo-route
23
  namespace: default
24
spec:
25
  parentRefs:
26
    - name: demo-gateway
27
      namespace: higress-system
28
  hostnames:
29
    - "api.example.com"
30
  rules:
31
    - matches:
32
        - path:
33
            type: PathPrefix
34
            value: /api/v1
35
          headers:
36
            - name: X-Env
37
              value: prod
38
      filters:
39
        - type: RequestHeaderModifier
40
          requestHeaderModifier:
41
            add:
42
              - name: X-Routed-By
43
                value: higress
44
        - type: URLRewrite
45
          urlRewrite:
46
            path:
47
              type: ReplacePrefixMatch
48
              replacePrefixMatch: /v1
49
      backendRefs:
50
        - name: api-service
51
          port: 8080
52
          weight: 90
53
        - name: api-service-canary
54
          port: 8080
55
          weight: 10

Gateway API 优势：

角色分离：平台工程师管 Gateway，开发管 HTTPRoute
功能更强：原生支持 Header/Query 匹配、权重、Filter
标准化：K8s 官方推荐，未来替代 Ingress

高级路由功能#

权重路由（灰度发布）#

1
metadata:
2
  annotations:
3
    higress.io/canary: "true"
4
    higress.io/canary-weight: "20"
5
spec:
6
  rules:
7
    - host: api.example.com
8
      http:
9
        paths:
10
          - path: /api
11
            pathType: Prefix
12
            backend:
13
              service:
14
                name: api-canary
15
                port:
16
                  number: 8080

效果：20% 流量到 canary 服务，80% 到稳定服务。

路径改写#

1
metadata:
2
  annotations:
3
    higress.io/rewrite-target: /v2/$1
4
spec:
5
  rules:
6
    - host: api.example.com
7
      http:
8
        paths:
9
          - path: /api/(.*)
10
            pathType: ImplementationSpecific
11
            backend:
12
              service:
13
                name: api-service
14
                port:
15
                  number: 8080

效果：/api/users → 转发到 /v2/users

重定向#

1
metadata:
2
  annotations:
3
    higress.io/permanent-redirect: "https://new.example.com$request_uri"
4
spec:
5
  rules:
6
    - host: old.example.com
7
      http:
8
        paths:
9
          - path: /
10
            pathType: Prefix
11
            backend:
12
              service:
13
                name: placeholder
14
                port:
15
                  number: 80

效果：所有 old.example.com 请求 301 重定向到 new.example.com

超时配置#

1
metadata:
2
  annotations:
3
    higress.io/upstream-vhost: "api.example.com"
4
    higress.io/request-timeout: "30s"
5
    higress.io/connect-timeout: "5s"
6
spec:
7
  rules:
8
    - host: api.example.com
9
      http:
10
        paths:
11
          - path: /api
12
            pathType: Prefix
13
            backend:
14
              service:
15
                name: api-service
16
                port:
17
                  number: 8080

重试策略#

1
metadata:
2
  annotations:
3
    higress.io/retry-count: "3"
4
    higress.io/retry-timeout: "10s"
5
    higress.io/retry-on: "5xx,reset,connect-failure"
6
spec:
7
  rules:
8
    - host: api.example.com
9
      http:
10
        paths:
11
          - path: /api
12
            pathType: Prefix
13
            backend:
14
              service:
15
                name: api-service
16
                port:
17
                  number: 8080

重试条件：

5xx：上游返回 5xx
reset：连接被重置
connect-failure：连接失败
retriable-4xx：可重试的 4xx（如 409）

CORS 跨域#

1
metadata:
2
  annotations:
3
    higress.io/enable-cors: "true"
4
    higress.io/cors-allow-origin: "https://web.example.com"
5
    higress.io/cors-allow-methods: "GET,POST,PUT,DELETE"
6
    higress.io/cors-allow-headers: "Authorization,Content-Type"
7
    higress.io/cors-max-age: "86400"
8
spec:
9
  rules:
10
    - host: api.example.com
11
      http:
12
        paths:
13
          - path: /api
14
            pathType: Prefix
15
            backend:
16
              service:
17
                name: api-service
18
                port:
19
                  number: 8080

路由优先级#

1
匹配顺序（从高到低）：
2
1. 精确路径（Exact）
3
2. 最长前缀（Prefix，/api/v1 > /api）
4
3. 正则路径（ImplementationSpecific）
5
4. Header/Query 匹配（更具体的优先）
6
5. 权重路由（按比例分配）
7

8
示例：
9
/api/v1/users     → 匹配 /api/v1（最长前缀）
10
/api/v1           → 匹配 /api/v1
11
/api/v2/orders    → 匹配 /api（前缀）
12
/api              → 匹配 /api
13
/health           → 无匹配，返回 404

实战案例#

案例 1：多环境路由#

1
# 开发环境
2
apiVersion: networking.k8s.io/v1
3
kind: Ingress
4
metadata:
5
  name: api-dev
6
  annotations:
7
    higress.io/header-match: "X-Env:dev"
8
spec:
9
  ingressClassName: higress
10
  rules:
11
    - host: api.example.com
12
      http:
13
        paths:
14
          - path: /api
15
            pathType: Prefix
16
            backend:
17
              service:
18
                name: api-dev
19
                port:
20
                  number: 8080
21

22
---
23
# 生产环境
24
apiVersion: networking.k8s.io/v1
25
kind: Ingress
26
metadata:
27
  name: api-prod
28
spec:
29
  ingressClassName: higress
30
  rules:
31
    - host: api.example.com
32
      http:
33
        paths:
34
          - path: /api
35
            pathType: Prefix
36
            backend:
37
              service:
38
                name: api-prod
39
                port:
40
                  number: 8080

案例 2：A/B 测试#

1
# 版本 A（80%）
2
apiVersion: networking.k8s.io/v1
3
kind: Ingress
4
metadata:
5
  name: ab-test-a
6
  annotations:
7
    higress.io/canary: "true"
8
    higress.io/canary-weight: "80"
9
spec:
10
  ingressClassName: higress
11
  rules:
12
    - host: api.example.com
13
      http:
14
        paths:
15
          - path: /api
16
            pathType: Prefix
17
            backend:
18
              service:
19
                name: api-version-a
20
                port:
21
                  number: 8080
22

23
---
24
# 版本 B（20%）
25
apiVersion: networking.k8s.io/v1
26
kind: Ingress
27
metadata:
28
  name: ab-test-b
29
  annotations:
30
    higress.io/canary: "true"
31
    higress.io/canary-weight: "20"
32
spec:
33
  ingressClassName: higress
34
  rules:
35
    - host: api.example.com
36
      http:
37
        paths:
38
          - path: /api
39
            pathType: Prefix
40
            backend:
41
              service:
42
                name: api-version-b
43
                port:
44
                  number: 8080

案例 3：API 版本管理#

1
# v1 API（旧版本，兼容）
2
apiVersion: networking.k8s.io/v1
3
kind: Ingress
4
metadata:
5
  name: api-v1
6
  annotations:
7
    higress.io/rewrite-target: /$1
8
spec:
9
  ingressClassName: higress
10
  rules:
11
    - host: api.example.com
12
      http:
13
        paths:
14
          - path: /v1/(.*)
15
            pathType: ImplementationSpecific
16
            backend:
17
              service:
18
                name: api-legacy
19
                port:
20
                  number: 8080
21

22
---
23
# v2 API（新版本）
24
apiVersion: networking.k8s.io/v1
25
kind: Ingress
26
metadata:
27
  name: api-v2
28
  annotations:
29
    higress.io/rewrite-target: /$1
30
spec:
31
  ingressClassName: higress
32
  rules:
33
    - host: api.example.com
34
      http:
35
        paths:
36
          - path: /v2/(.*)
37
            pathType: ImplementationSpecific
38
            backend:
39
              service:
40
                name: api-new
41
                port:
42
                  number: 8080

常见问题#

Q1: Ingress 配置不生效#

1
# 1. 检查 Ingress 状态
2
kubectl get ingress -n default
3
kubectl describe ingress demo-ingress -n default
4

5
# 2. 检查 Higress Controller 日志
6
kubectl logs -n higress-system deploy/higress-controller
7

8
# 3. 确认 ingressClassName
9
spec:
10
  ingressClassName: higress   # 必须是 higress
11

12
# 4. 确认 Service 存在且 Endpoint 正常
13
kubectl get svc httpbin -n default
14
kubectl get endpoints httpbin -n default

Q2: 路由匹配顺序混乱#

1
# 查看 Envoy 实际路由配置
2
kubectl exec -n higress-system deploy/higress-gateway -- \
3
  curl -s localhost:15000/config_dump | jq '.configs[] | select(.["@type"]=="type.googleapis.com/envoy.admin.v3.RoutesConfigDump")'
4

5
# 简化排查：用 curl -v 看响应头
6
curl -v -H "Host: api.example.com" http://<gateway-ip>/api/v1/users
7
# 查看 X-Envoy-Upstream-Service-Time 等 Header 确认路由到了哪个服务

Q3: 正则路径不生效#

1
# 必须加注解
2
annotations:
3
  higress.io/use-regex: "true"
4

5
# pathType 必须是 ImplementationSpecific
6
pathType: ImplementationSpecific
7

8
# 路径用正则语法
9
path: /api/(.*)

复习卡片#

TIP
快速复习清单

两种路由标准：Ingress（兼容）、Gateway API（推荐新项目）

路径匹配：Exact（精确）、Prefix（前缀）、ImplementationSpecific（正则）

高级匹配：Header（higress.io/header-match）、Query（higress.io/query-match）

权重路由：higress.io/canary-weight: "20"（灰度发布）

路径改写：higress.io/rewrite-target: /v2/$1

重定向：higress.io/permanent-redirect（301）/ temporal-redirect（302）

超时重试：request-timeout、retry-count、retry-on: 5xx,reset

CORS：enable-cors、cors-allow-origin/methods/headers

优先级：精确 > 最长前缀 > 正则 > Header/Query > 权重

TIP
下一篇：服务发现将讲解如何对接 K8s/Nacos/Consul/Eureka/DNS/静态服务，实现动态服务发现。
返回 Higress 学习路线总览 | 合集页

路由配置方式对比#

方式一：Ingress 路由#

基础路由（域名 + 路径）#

路径匹配类型#

正则路径匹配（Higress 扩展）#

Header 匹配#

Query 参数匹配#

方式二：Gateway API 路由#

Gateway + HTTPRoute#

高级路由功能#

权重路由（灰度发布）#

路径改写#

重定向#

超时配置#

重试策略#

CORS 跨域#

路由优先级#

实战案例#

案例 1：多环境路由#

案例 2：A/B 测试#

案例 3：API 版本管理#

常见问题#

Q1: Ingress 配置不生效#

Q2: 路由匹配顺序混乱#

Q3: 正则路径不生效#

复习卡片#