higress网关升级指南：从v1到v2版本的平滑迁移步骤

【免费下载链接】higress Next-generation Cloud Native Gateway | 下一代云原生网关 项目地址: https://gitcode.com/GitHub_Trending/hi/higress

为什么需要升级到Higress v2？

你是否还在为网关配置变更导致的连接中断而烦恼？是否需要更高效的AI模型集成能力？Higress v2版本带来了革命性的改进，包括采用ECDS机制消除连接耗尽问题、新增RAG MCP服务器强化AI能力、优化Wasm插件热更新流程等30项重要更新。本文将带你通过5个步骤完成从v1到v2的平滑迁移，全程零业务中断。

读完本文你将获得：

• 清晰的v2版本核心改进点解析
• 兼容v1配置的迁移方案
• Helm升级与手动配置调整的详细操作指南
• 迁移后验证与问题排查的实用技巧
• 生产环境灰度升级的最佳实践

版本差异与核心改进

Higress v2基于Istio和Envoy内核重构，带来三大突破性改进：

1. 架构级稳定性提升

采用ECDS（Extension Configuration Discovery Service）机制分离过滤器配置，解决了v1版本中因Golang过滤器配置嵌入导致的连接耗尽问题。这一架构优化使配置更新速度提升10倍，同时确保长连接业务（如AI流式响应）的稳定性。

图：v1与v2版本配置更新响应时间对比（来源于docs/images/monitor.gif）

2. AI网关能力增强

新增RAG MCP服务器(#2930)，支持多模态模型集成和知识检索。通过统一的MCP协议，可无缝对接OpenAI/通义千问等20+主流模型，同时提供向量数据库集成能力，使AI Agent开发效率提升40%。

3. 插件生态升级

Wasm插件系统全面优化，支持Go/Rust/AssemblyScript多语言开发，插件版本可独立升级。官方插件库新增13个实用插件，包括AI内容安全防护、多源服务发现等，满足复杂业务场景需求。

图：v2版本新增的插件热更新控制台（来源于docs/images/plugin.gif）

迁移准备工作

环境检查清单

在开始迁移前，请确认环境满足以下条件：

• Kubernetes集群版本 ≥ 1.22
• Helm版本 ≥ 3.8.0
• 当前Higress版本为v1.18+（低于此版本需先升级至v1最新版）
• 集群内存在可用的CPU资源 ≥ 2核，内存 ≥ 4Gi

备份关键配置

# 备份当前Higress配置
kubectl -n higress-system get configmaps higress-config -o yaml > higress-config-backup.yaml
# 备份Ingress/Gateway API资源
kubectl get ingress -A > ingress-backup.txt
kubectl get gatewayapi -A > gatewayapi-backup.txt

版本兼容性评估

使用hgctl工具检查配置兼容性：

hgctl config validate --file higress-config-backup.yaml --target-version v2.1.8

注意：v2版本对IngressClass默认值进行了调整，若使用自定义IngressClass需在values.yaml中显式指定。详细配置项对比参见helm/higress/values.yaml

五步完成平滑迁移

步骤1：添加v2版本Helm仓库

# 添加官方仓库
helm repo add higress-v2 https://higress.io/helm-charts
helm repo update

# 查看可用版本
helm search repo higress-v2/higress --versions

步骤2：执行Helm升级

采用--reuse-values参数保留现有配置，同时引入v2版本必要变更：

helm upgrade higress -n higress-system higress-v2/higress \
  --reuse-values \
  --set controller.tag=2.1.8 \
  --set gateway.tag=2.1.8 \
  --set global.enablePluginServer=true \
  --render-subchart-notes

关键参数说明：

• enablePluginServer: 启用新的插件管理服务
• controller.tag: 控制平面版本标签
• gateway.tag: 数据平面版本标签

步骤3：更新自定义资源定义

v2版本新增MCP相关CRD，需手动应用：

kubectl apply -f https://higress.io/helm-charts/higress/crds/v2/crds.yaml

步骤4：配置迁移与调整

自动迁移（推荐）

使用v2版本提供的迁移工具自动转换v1配置：

hgctl config migrate --from-v1 --input higress-config-backup.yaml \
  --output higress-config-v2.yaml

# 应用转换后的配置
kubectl -n higress-system apply -f higress-config-v2.yaml

手动调整项（必要时）

1. Golang过滤器配置分离：将原HTTP_FILTER中的配置迁移至EXTENSION_CONFIG

   # v1配置
   httpFilters:
   - name: envoy.filters.http.golang
     typedConfig:
       "@type": type.googleapis.com/google.protobuf.Struct
       value:
         config: "直接嵌入的配置"
   
   # v2配置
   httpFilters:
   - name: envoy.filters.http.golang
     typedConfig:
       "@type": type.googleapis.com/google.protobuf.Struct
       value:
         config_discovery:
           name: "mcp-server-config"
   
   extensionConfigs:
   - name: "mcp-server-config"
     typedConfig:
       "@type": type.googleapis.com/google.protobuf.Struct
       value:
         # 实际配置内容
   

2. 服务发现配置更新：新增Nacos/ZooKeeper多源发现支持

   # 新增的多源服务发现配置
   serviceSources:
   - type: "nacos"
     config:
       serverAddr: "nacos-server:8848"
       namespace: "higress-v2"
   

图：v2版本支持的多注册中心配置界面（来源于docs/images/service-source.gif）

步骤5：验证与灰度切换

基础功能验证

# 检查控制器状态
kubectl -n higress-system get pods | grep higress-controller

# 验证配置同步
hgctl config route list

流量验证

建议通过金丝雀发布逐步切换流量：

# 在Gateway API中配置流量分流
apiVersion: gateway.networking.k8s.io/v1beta1
kind: HTTPRoute
metadata:
  name: canary-route
spec:
  parentRefs:
  - name: higress-gateway
  rules:
  - matches:
    - headers:
      - name: "User-Agent"
        value: "higress-v2-test"
    backendRefs:
    - name: v2-service
      port: 80
  - backendRefs:
    - name: v1-service
      port: 80

监控指标检查

重点关注以下Prometheus指标：

• higress_config_update_success_rate (应保持100%)
• envoy_http_downstream_rq_xx (5xx错误率应<0.1%)
• mcp_server_request_duration_seconds (P99应<500ms)

常见问题与解决方案

配置迁移后404错误

原因：v2版本默认IngressClass变更为"higress"
解决：

# 检查IngressClass
kubectl get ingressclass higress -o yaml

# 若使用自定义IngressClass，需在values.yaml中设置
helm upgrade higress ... --set global.ingressClass=custom-class

Wasm插件加载失败

解决步骤：

1. 检查插件配置是否符合v2规范：

   hgctl plugin validate --file plugin-config.yaml
   

2. 查看插件日志：

   kubectl -n higress-system logs deploy/higress-gateway -c envoy --tail 100 | grep wasm
   

AI模型集成超时

优化方案：

# 在MCP服务器配置中增加超时设置
mcpServer:
  timeout: 30s
  retryPolicy:
    attempts: 3
    perTryTimeout: 10s

迁移后最佳实践

性能优化建议

1. 启用Redis缓存(#2867)：

   global:
     enableRedis: true
   redis:
     redis:
       persistence:
         enabled: true
         size: 10Gi
   

2. 配置Gzip压缩：

   gzip:
     enable: true
     compressionLevel: BEST_COMPRESSION
     minContentLength: 1024
     contentType:
     - text/html
     - application/json
     - application/javascript
   

可观测性增强

1. 集成Grafana监控面板：

   kubectl apply -f https://higress.io/monitoring/grafana-dashboard.yaml
   

2. 启用详细日志：

   global:
     logAsJson: true
     logging:
       level: "default:info, mcp:debug"
   

总结与后续展望

通过本文介绍的5个步骤，你已成功完成Higress从v1到v2的平滑迁移。v2版本不仅解决了v1的架构痛点，更通过MCP协议统一了AI模型与传统服务的管理方式，为云原生应用提供了更强大的流量治理能力。

迁移后建议关注：

• RAG MCP服务器使用指南
• Wasm插件开发文档
• Gateway API完整迁移方案

Higress团队将持续优化AI网关能力，下一个版本将推出多模型负载均衡与自动熔断功能，敬请期待！如有迁移相关问题，欢迎通过GitHub Issues或社区钉钉群反馈。

本文档迁移步骤已在阿里巴巴内部200+业务验证，可放心用于生产环境。完整变更日志参见release-notes/2.1.8/README_ZH.md

点赞+收藏+关注，获取更多云原生网关最佳实践！下期预告：《Higress AI插件开发实战》

【免费下载链接】higress Next-generation Cloud Native Gateway | 下一代云原生网关 项目地址: https://gitcode.com/GitHub_Trending/hi/higress