Higress AI-Quota 插件加载失败问题深度解析

问题背景

在本地 Kubernetes 环境中部署 Higress 网关并尝试使用 ai-quota 插件为特定消费者配置限额时，发现插件未能正常工作。通过网关日志分析，发现 ai-quota 插件加载失败，导致请求配额验证功能无法使用。

现象分析

当用户尝试通过以下命令查询配额时：

curl http://gateway.local/gpt-4o/v1/chat/completions/quota\?consumer\=test-consumer-01

系统返回 404 错误，同时网关日志中显示以下关键信息：

1. Wasm HTTP 过滤器创建失败：

Unable to create Wasm HTTP filter higress-system.ai-quota-1.0.0

2. 请求被错误路由到 ai-proxy 插件：

[ai-proxy] [d7cedf82-8af4-4f41-8bec-79204d205cb2] [onHttpRequestHeader] unsupported path: /gpt-4o/v1/chat/completions/quota

根本原因

经过深入排查，发现问题主要由以下几个因素导致：

1. Redis 连接配置问题：ai-quota 插件依赖 Redis 服务进行配额管理，但 Redis 服务发现机制配置不当导致插件初始化失败。

2. 服务发现机制限制：Higress 网关中的 Envoy 插件不允许直接访问外部服务，必须通过 Envoy Cluster 进行访问。

3. 架构兼容性问题：在 ARM 架构环境下，WASM 模块加载存在兼容性问题，导致插件无法正常启动。

解决方案

1. 正确的 Redis 服务配置

对于云上 Redis 服务，应采用以下配置方式：

apiVersion: networking.higress.io/v1
kind: McpBridge
metadata:
  name: default
  namespace: higress-system
spec:
  registries:
  - domain: your-redis.cache.amazonaws.com
    name: redis
    type: dns
    port: 6379

然后在插件配置中引用：

admin_consumer: "gpt-4o-consumer-01"
admin_path: "/quota"
redis:
  service_name: redis.dns
  service_port: 6379
  timeout: 2000
redis_key_prefix: "chat_quota:"

2. Kubernetes 本地服务发现

对于 Kubernetes 集群内的 Redis 服务，需要确保：

1. 将 global.onlyPushRouteCluster 参数设置为 false，允许自动发现 Kubernetes Service
2. 或者通过 Ingress 路由绑定该服务

3. ARM 架构兼容性修复

最新版本已修复 ARM 架构下的 WASM 模块加载问题，重启网关即可获取修复后的插件版本。

排查技巧

当遇到插件加载问题时，可以通过以下方法进行诊断：

1. 检查 Envoy 配置：

curl localhost:15000/config_dump | grep -i quota

2. 查看集群服务发现状态：

curl localhost:15000/clusters | grep redis

3. 检查插件初始化日志：

kubectl logs -n higress-system <gateway-pod-name> | grep "Unable to create Wasm"

最佳实践建议

1. 服务发现统一管理：建议所有外部依赖服务都通过 McpBridge 进行统一注册和管理。

2. 环境隔离：开发、测试和生产环境应使用独立的 Redis 实例，避免配置冲突。

3. 监控告警：对插件初始化状态建立监控，及时发现加载失败的情况。

4. 版本兼容性检查：在 ARM 架构环境部署前，确认插件版本是否支持目标架构。

通过以上分析和解决方案，用户应能够顺利解决 Higress 中 ai-quota 插件加载失败的问题，并建立起完善的配额管理机制。