Higress AI 网关部署指南

概述

本文档详细介绍如何在已有 ingress-nginx 的 Kubernetes 集群中部署 Higress AI 网关。Higress 是一个基于 Istio 和 Envoy 的云原生网关，特别适合 AI 服务场景。

前置条件

已有 Kubernetes 集群
已部署 ingress-nginx 作为外部流量入口
已安装 Helm 3
具备基本的 Kubernetes 操作知识

部署架构

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   外部流量       │    │   Higress        │    │   应用服务       │
│                 │    │   网关           │    │                 │
│  ingress-nginx   │───▶│  higress-core   │───▶│   AI Services   │
│                 │    │  higress-console│    │                 │
└─────────────────┘    └─────────────────┘    └─────────────────┘

1. 部署 Higress 核心

1.1 创建配置文件

首先创建 Higress 的 values 配置文件 higress-values.yaml：

# ==============================================
# Higress AI 网关配置
# ==============================================

# ----------------------------------------------
# 全局配置
# ----------------------------------------------
global:
  # 重要：Higress 使用的 IngressClass 名称
  # 这里填 "higress" 表示 Higress 会管理 IngressClass 为 "higress" 的资源
  # 注意：这不是 nginx-ingress 的配置，不会影响现有流量入口
  ingressClass: "higress"
  
  # 避免 Higress 修改现有 Ingress 的状态
  enableStatus: false
  
  # 部署环境（false = 生产环境）
  local: false
  
  # 不安装监控套件（如需监控可改为 true）
  o11y:
    enabled: true

# ----------------------------------------------
# Higress 核心组件配置（数据面 + 控制面）
# ----------------------------------------------
higress-core:
  # 网关配置（数据面）
  gateway:
    # 服务类型：ClusterIP 表示不直接对外暴露
    service:
      type: ClusterIP
      ports:
        - name: http
          port: 80
          targetPort: 8080
        - name: https
          port: 443
          targetPort: 8443
    
    # 网关副本数（可根据流量调整）
    replicas: 1
    
    # 资源限制
    resources:
      requests:
        cpu: 200m
        memory: 512Mi
      limits:
        cpu: 1000m
        memory: 1Gi
  
  # 控制器配置（控制面）
  controller:
    replicas: 1
    resources:
      requests:
        cpu: 200m
        memory: 256Mi
      limits:
        cpu: 500m
        memory: 512Mi

# ----------------------------------------------
# Higress 控制台配置（管理界面）
# ----------------------------------------------
higress-console:
  # 副本数
  replicaCount: 1
  
  # 服务配置
  service:
    type: ClusterIP
    port: 8080
  
  # 通过 Ingress 暴露控制台
  # 注意：如果 enabled=true，会由 Higress 自身处理，而不是 ingress-nginx
  # 在本部署方案中，我们设置为 false，通过单独的 ingress-nginx Ingress 来暴露
  ingress:
    enabled: false
    # 控制台访问域名（请修改为你自己的域名）
    domain: higress-console.domain.com
    paths:
      - path: /
        pathType: Prefix
  
  # 资源限制
  resources:
    requests:
      cpu: 250m
      memory: 512Mi
    limits:
      cpu: 500m
      memory: 1Gi
  
  # 管理员初始配置
  admin:
    username: admin
    # 如不设置密码，首次访问需要初始化
    password: "higress12345"
  
  # 登录页提示
  web:
    login:
      prompt: ""

1.2 部署 Higress

# 添加 Higress Helm 仓库
helm repo add higress.io https://higress.io/helm-charts

# 更新 Helm 仓库
helm repo update

# 部署 Higress
helm install higress higress.io/higress \
  --namespace higress-system \
  --create-namespace \
  --version 2.2.0 \
  -f higress-values.yaml

2. 创建外部访问 Ingress

由于集群已使用 ingress-nginx，我们需要为 Higress 创建单独的 Ingress 资源。

2.1 Higress 控制台 Ingress

创建 higress-console-ingress.yaml：

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: higress-console
  namespace: higress-system
  annotations:
    kubernetes.io/ingress.class: nginx
    nginx.ingress.kubernetes.io/rewrite-target: /
spec:
  ingressClassName: nginx
  tls:
  - hosts:
    - higress-console.yourdomain.com
    #secretName: #若不指定，使用ingress-nginx配置的默认证书
  rules:
  - host: higress-console.yourdomain.com
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: higress-console
            port:
              number: 8080

2.2 AI 网关 Ingress

创建 ai-gateway-ingress.yaml：

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: ai-gateway
  namespace: higress-system
  annotations:
    kubernetes.io/ingress.class: nginx
    # AI 服务需要更大的请求体大小限制
    nginx.ingress.kubernetes.io/proxy-body-size: "10m"
    # AI 服务需要更长的超时时间
    nginx.ingress.kubernetes.io/proxy-read-timeout: "300"
    nginx.ingress.kubernetes.io/proxy-send-timeout: "300"
    # 启用 CORS 支持
    nginx.ingress.kubernetes.io/enable-cors: "true"
    nginx.ingress.kubernetes.io/cors-allow-credentials: "true"
    nginx.ingress.kubernetes.io/cors-allow-headers: "DNT,X-CustomHeader,Keep-Alive,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type,Authorization,Accept,Origin,X-Mx-ReqToken,X-Data-Type,X-Auth-Token,X-Requested-With"
    nginx.ingress.kubernetes.io/cors-allow-methods: "GET,POST,PUT,DELETE,OPTIONS"
    nginx.ingress.kubernetes.io/cors-allow-origin: "*"
spec:
  ingressClassName: nginx
  tls:
  - hosts:
    - ai.yourdomain.com
    #secretName: #若不指定，使用ingress-nginx配置的默认证书
  rules:
  - host: ai.yourdomain.com
    http:
      paths:
      - path: /v1/chat/completions
        pathType: Exact
        backend:
          service:
            name: higress-gateway
            port:
              number: 80
      - path: /v1
        pathType: Prefix
        backend:
          service:
            name: higress-gateway
            port:
              number: 80

2.3 应用 Ingress 配置

# 应用控制台 Ingress
kubectl apply -f higress-console-ingress.yaml

# 应用 AI 网关 Ingress
kubectl apply -f ai-gateway-ingress.yaml

3. 验证部署

3.1 检查 Higress 组件状态

# 检查命名空间
kubectl get namespace higress-system

# 检查 Pod 状态
kubectl get pods -n higress-system

# 检查服务状态
kubectl get svc -n higress-system

3.2 验证控制台访问

# 检查控制台 Ingress
kubectl get ingress higress-console -n higress-system

# 访问控制台
# http://higress-console.yourdomain.com
# 用户名: admin
# 密码: higress12345

3.3 验证 AI 网关访问

# 检查 AI 网关 Ingress
kubectl get ingress ai-gateway -n higress-system

# 测试 AI 网关连通性
curl -X POST http://ai.yourdomain.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-3.5-turbo",
    "messages": [{"role": "user", "content": "Hello"}]
  }'

4. 监控和日志

5.1 启用监控

如果需要启用监控，修改 higress-values.yaml 中的 o11y.enabled 为 true：

o11y:
  enabled: true

然后重新部署：

helm upgrade --install higress higress.io/higress \
  --namespace higress-system \
  --create-namespace \
  --version 2.2.0 \
  -f higress-values.yaml

5.2 查看日志

# 查看 Higress 控制器日志
kubectl logs -n higress-system deployment/higress-controller

# 查看 Higress 网关日志
kubectl logs -n higress-system deployment/higress-gateway -c higress-gateway

6. 常见问题

6.1 Ingress 无法访问

检查 ingress-nginx 控制器日志：

kubectl logs -n ingress-nginx deployment/ingress-nginx-controller-xxxxx

6.2 Higress 服务无法启动

检查 Higress Pod 状态和事件：

kubectl describe pods -n higress-system -l app=higress

6.3 AI 网关超时

调整 AI 网关 Ingress 的超时配置：

nginx.ingress.kubernetes.io/proxy-read-timeout: "600"
nginx.ingress.kubernetes.io/proxy-send-timeout: "600"

7. 清理部署

# 删除 Ingress 资源
kubectl delete ingress higress-console -n higress-system
kubectl delete ingress ai-gateway -n higress-system

# 删除 Higress
helm uninstall higress-system -n higress-system

# 删除命名空间
kubectl delete namespace higress-system

8. 参考资料

9. 总结

通过本文档，您应该能够成功在已有 ingress-nginx 的 Kubernetes 集群中部署 Higress AI 网关。Higress 提供了强大的网关功能，特别适合 AI 服务的流量管理和路由需求。配置完成后，您可以通过控制台管理网关规则，并通过 AI 网关 Ingress 为您的 AI 服务提供外部访问。

posted @ 2026-03-10 16:15 怀恋小时候阅读(320) 评论(0) 收藏举报

刷新页面返回顶部

怀恋小时候

Higress AI 网关部署指南

Higress AI 网关部署指南

概述

前置条件

部署架构

1. 部署 Higress 核心

1.1 创建配置文件

1.2 部署 Higress

2. 创建外部访问 Ingress

2.1 Higress 控制台 Ingress

2.2 AI 网关 Ingress

2.3 应用 Ingress 配置

3. 验证部署

3.1 检查 Higress 组件状态

3.2 验证控制台访问

3.3 验证 AI 网关访问

4. 监控和日志

5.1 启用监控

5.2 查看日志

6. 常见问题

6.1 Ingress 无法访问

6.2 Higress 服务无法启动

6.3 AI 网关超时

7. 清理部署

8. 参考资料

9. 总结

公告