Higress 生产级调优手册

一、流量分级定档

根据峰值 QPS 、路由规则数 、后端服务数三个维度确定档位，取三者中最高档。

维度	S 档	M 档	L 档	XL 档
峰值 QPS	< 1K	1K -- 5K	5K -- 20K	> 20K
路由规则数	< 100	100 -- 500	500 -- 2K	> 2K
后端服务数	< 30	30 -- 150	150 -- 500	> 500
典型场景	内部工具	中型业务	核心业务线	全站入口

二、各档资源配额

所有组件 request = limit（Guaranteed QoS），避免 Burstable 调度抖动。

Gateway（数据面）

参数	S 档	M 档	L 档	XL 档
replicas	2	3	4 -- 6	6 -- 20 + HPA
cpu	1000m	2000m	4000m	8000m
memory	1Gi	2Gi	4Gi	8Gi
autoscaling	关闭	关闭	开启（4--12）	开启（6--20）
HPA targetCPU	-	-	70%	65%

Controller（控制面）

参数	S 档	M 档	L 档	XL 档
replicas	1	2	2	3
cpu	500m	1000m	2000m	4000m
memory	1Gi	2Gi	4Gi	8Gi

Pilot（xDS 下发引擎）

参数	S 档	M 档	L 档	XL 档
cpu	500m	1000m	2000m	4000m
memory	1Gi	2Gi	4Gi	8Gi

Prometheus

参数	S 档	M 档	L 档	XL 档
storage	10Gi	50Gi	100Gi	200Gi
memory limit	2Gi	4Gi	8Gi	16Gi

三、每档完整 Helm Values

S 档（< 1K QPS）

YAML 复制代码

global:
  onlyPushRouteCluster: true
  defaultUpstreamConcurrencyThreshold: 5000
  o11y:
    enabled: true

higress-core:
  gateway:
    replicas: 2
    resources:
      requests: { cpu: 1000m, memory: 1Gi }
      limits:   { cpu: 1000m, memory: 1Gi }
    rollingMaxSurge: "50%"
    rollingMaxUnavailable: "0"
    service:
      type: LoadBalancer
      externalTrafficPolicy: Local

  controller:
    replicas: 1
    resources:
      requests: { cpu: 500m, memory: 1Gi }
      limits:   { cpu: 500m, memory: 1Gi }

  pilot:
    traceSampling: 0.1
    resources:
      requests: { cpu: 500m, memory: 1Gi }

higress-console:
  o11y:
    prometheus:
      storage: 10Gi
      resources:
        limits: { cpu: 500m, memory: 2Gi }
    grafana:
      storage: 5Gi

M 档（1K -- 5K QPS）

YAML 复制代码

global:
  onlyPushRouteCluster: true
  defaultUpstreamConcurrencyThreshold: 10000
  o11y:
    enabled: true

higress-core:
  gateway:
    replicas: 3
    resources:
      requests: { cpu: 2000m, memory: 2Gi }
      limits:   { cpu: 2000m, memory: 2Gi }
    rollingMaxSurge: "50%"
    rollingMaxUnavailable: "0"
    service:
      type: LoadBalancer
      externalTrafficPolicy: Local

  controller:
    replicas: 2
    resources:
      requests: { cpu: 1000m, memory: 2Gi }
      limits:   { cpu: 1000m, memory: 2Gi }

  pilot:
    traceSampling: 0.05
    keepaliveMaxServerConnectionAge: 30m
    resources:
      requests: { cpu: 1000m, memory: 2Gi }

higress-console:
  o11y:
    prometheus:
      storage: 50Gi
      resources:
        limits: { cpu: 1000m, memory: 4Gi }
    grafana:
      storage: 10Gi

L 档（5K -- 20K QPS）

YAML 复制代码

global:
  onlyPushRouteCluster: true
  defaultUpstreamConcurrencyThreshold: 20000
  o11y:
    enabled: true

higress-core:
  gateway:
    replicas: 4
    resources:
      requests: { cpu: 4000m, memory: 4Gi }
      limits:   { cpu: 4000m, memory: 4Gi }
    autoscaling:
      enabled: true
      minReplicas: 4
      maxReplicas: 12
      targetCPUUtilizationPercentage: 70
    rollingMaxSurge: "25%"
    rollingMaxUnavailable: "0"
    service:
      type: LoadBalancer
      externalTrafficPolicy: Local
    affinity:
      podAntiAffinity:
        requiredDuringSchedulingIgnoredDuringExecution:
          - labelSelector:
              matchLabels:
                app: higress-gateway
            topologyKey: kubernetes.io/hostname

  controller:
    replicas: 2
    resources:
      requests: { cpu: 2000m, memory: 4Gi }
      limits:   { cpu: 2000m, memory: 4Gi }

  pilot:
    traceSampling: 0.01
    keepaliveMaxServerConnectionAge: 20m
    resources:
      requests: { cpu: 2000m, memory: 4Gi }

  skywalking:
    enabled: true
    service:
      address: skywalking-oap.observability.svc
      port: 11800

higress-console:
  o11y:
    prometheus:
      storage: 100Gi
      resources:
        limits: { cpu: 2000m, memory: 8Gi }
    grafana:
      storage: 20Gi

XL 档（> 20K QPS）

YAML 复制代码

global:
  onlyPushRouteCluster: true
  defaultUpstreamConcurrencyThreshold: 30000
  o11y:
    enabled: true

higress-core:
  gateway:
    replicas: 6
    resources:
      requests: { cpu: 8000m, memory: 8Gi }
      limits:   { cpu: 8000m, memory: 8Gi }
    autoscaling:
      enabled: true
      minReplicas: 6
      maxReplicas: 20
      targetCPUUtilizationPercentage: 65
    rollingMaxSurge: "20%"
    rollingMaxUnavailable: "0"
    service:
      type: LoadBalancer
      externalTrafficPolicy: Local
    affinity:
      podAntiAffinity:
        requiredDuringSchedulingIgnoredDuringExecution:
          - labelSelector:
              matchLabels:
                app: higress-gateway
            topologyKey: topology.kubernetes.io/zone
          - labelSelector:
              matchLabels:
                app: higress-gateway
            topologyKey: kubernetes.io/hostname

  controller:
    replicas: 3
    resources:
      requests: { cpu: 4000m, memory: 8Gi }
      limits:   { cpu: 4000m, memory: 8Gi }

  pilot:
    traceSampling: 0.005
    keepaliveMaxServerConnectionAge: 15m
    resources:
      requests: { cpu: 4000m, memory: 8Gi }
    env:
      PILOT_SCOPE_GATEWAY_TO_NAMESPACE: false

  skywalking:
    enabled: true
    service:
      address: skywalking-oap.observability.svc
      port: 11800

higress-console:
  o11y:
    prometheus:
      storage: 200Gi
      resources:
        limits: { cpu: 4000m, memory: 16Gi }
    grafana:
      storage: 30Gi

四、连接与并发参数按档调优

参数	S 档	M 档	L 档	XL 档	说明
`defaultUpstreamConcurrencyThreshold`	5000	10000	20000	30000	单 Pod → 单服务最大并发
`route-limit-rps`（Ingress 级）	500	2000	8000	30000	单机限流，× 副本数 ≈ 全局
`route-limit-burst-multiplier`	5	5	3	2	高流量降低突发因子防过载
`proxy-next-upstream-tries`	3	2	1	1	高流量减少重试防雪崩
`higress.io/timeout`（秒）	30	15	10	5	高流量收窄超时快速释放连接
`keepaliveMaxServerConnectionAge`	30m	30m	20m	15m	缩短连接生命周期均衡 Controller
`traceSampling`	0.1	0.05	0.01	0.005	采样率随流量反比降低

五、核心监控指标与告警阈值

指标速查

指标	正常	Warning	Critical
5xx 错误率	< 0.1%	≥ 1%	≥ 5%
P99 延迟	< 200ms	≥ 500ms	≥ 2s
Gateway CPU 使用率	< 60%	≥ 75%	≥ 90%
Envoy 内存使用	< 60% limit	≥ 75% limit	≥ 85% limit
活跃连接数	< 60% 阈值	≥ 80% 阈值	≥ 95% 阈值
上游连接失败	0/min	> 5/min	> 50/min

告警规则清单

HigressHighErrorRate（Warning，持续 5m）

Plain 复制代码

sum(rate(envoy_cluster_upstream_rq_xx{response_code_class="5"}[5m]))
/ sum(rate(envoy_cluster_upstream_rq_total[5m]))
> 0.01

HigressCriticalErrorRate（Critical，持续 2m）

Plain 复制代码

sum(rate(envoy_cluster_upstream_rq_xx{response_code_class="5"}[5m]))
/ sum(rate(envoy_cluster_upstream_rq_total[5m]))
> 0.05

HigressHighLatency（Warning，持续 5m）

Plain 复制代码

histogram_quantile(0.99,
  sum(rate(envoy_cluster_upstream_rq_time_bucket[5m])) by (le)
) > 2000

HigressHighCPU（Warning，持续 10m）

Plain 复制代码

rate(container_cpu_usage_seconds_total{container="higress-gateway"}[5m])
/ on() kube_pod_container_resource_limits{resource="cpu"}
> 0.8

HigressMemoryPressure（Critical，持续 5m）

Plain 复制代码

container_memory_working_set_bytes{container="higress-gateway"}
/ on() kube_pod_container_resource_limits{resource="memory"}
> 0.85

HigressUpstreamConnectFail（Critical，持续 1m）

Plain 复制代码

sum(rate(envoy_cluster_upstream_cx_connect_fail[1m])) by (cluster)
> 50

HigressConfigPushSlow（Warning，持续 5m）

Plain 复制代码

pilot_proxy_convergence_time_bucket{le="5000"}
/ pilot_proxy_convergence_time_bucket{le="+Inf"}
< 0.95

HigressControllerDown（Critical，持续 1m）

Plain 复制代码

kube_pod_status_ready{namespace="higress-system",pod=~"higress-controller.*"} == 0

六、容量规划公式

Gateway 副本数估算

Plain 复制代码

replicas = ceil(peak_QPS / per_pod_QPS)

经验值：
  2000m CPU ≈ 3K QPS（HTTP）
  4000m CPU ≈ 6K QPS（HTTP）
  8000m CPU ≈ 10K QPS（HTTP）
  HTTPS 场景打 7 折（TLS 握手消耗 CPU）
  gRPC 场景打 8 折（长连接复用效率高）

内存预估

Plain 复制代码

mem = base + (routes × 2KB) + (conns × 50KB)

base ≈ 200MB
routes = 路由规则数
conns = 活跃连接数

示例：500 条路由 + 5000 并发连接
  = 200MB + 1MB + 244MB ≈ 445MB → 配 2Gi 足够

Prometheus 存储预估

Plain 复制代码

storage = samples_per_sec × 16bytes × retention_days × 86400 × 1.5

samples_per_sec ≈ 路由规则数 × 3 + 服务数 × 10
1.5 = WAL + compaction 开销系数

示例：1000 条路由 × 3 + 200 服务 × 10 = 5000 samples/s
  = 5000 × 16 × 30 × 86400 × 1.5 ≈ 311GB → 配 100Gi + Thanos 远端存储

限流阈值换算

Plain 复制代码

global_rps = per_pod_rps × gateway_replicas

示例：Ingress 配 route-limit-rps=100，6 副本
  全局限流 ≈ 600 rps（单机限流有误差，不精确）

HPA 扩缩容时副本数变化，全局阈值自动变化
需要精确全局限流 → 使用商业版 MSE Ingress（基于 Redis）

HPA 伸缩计算

Plain 复制代码

desired_replicas = ceil(current_replicas × (current_cpu / target_cpu))

scale-up 延迟 ≈ 3 min（默认 stabilization window）
scale-down 稳定窗口 ≈ 5 min

示例：当前 4 副本，CPU 90%，目标 70%
  = ceil(4 × 90/70) = ceil(5.14) = 6

突发流量缓冲

Plain 复制代码

burst_capacity = rps × burst_multiplier

默认 burst_multiplier = 5
100 rps 配置 → 瞬时可扛 500 请求

高流量场景建议降至 2~3，避免瞬时过载压垮后端

七、排障决策树

5xx 飙升

Plain 复制代码

看 upstream_cx_connect_fail
├─ > 0 → 后端 Pod 不健康
│        → kubectl get endpoints 确认
│        → 检查 readinessProbe
│        → 检查后端是否 OOM/CrashLoop
│
└─ = 0 → 看 upstream_rq_time
         ├─ 延迟过高 → 后端处理慢
         │            → 检查 higress.io/timeout 是否过短
         │            → 排查后端服务自身瓶颈
         │
         └─ 延迟正常 → 看 response_flag
                      ├─ UH → 无健康主机（熔断触发）
                      ├─ UF → 上游连接失败
                      ├─ UT → 上游超时
                      └─ UC → 上游连接关闭

延迟突增

Plain 复制代码

看 Gateway CPU
├─ > 80% → 扩副本或升配
│          → 检查是否有路由规则批量变更导致 xDS 推送风暴
│          → 检查 Envoy access log 中是否有慢路由
│
└─ 正常 → 看 upstream_rq_time
          ├─ 后端慢 → 非网关问题，排查后端
          │
          └─ 后端正常 → 看 downstream_cx_active
                       └─ 连接数打满 → 增大 defaultUpstreamConcurrencyThreshold

配置不生效

Plain 复制代码

Ingress Annotation 变更
  ↓
Controller 是否 watch 到？
  → kubectl logs -f higress-controller --tail=100
  → 常见：ingressClassName 不匹配
  ↓
Pilot 是否生成 xDS？
  → Controller 日志中有 "pushing xDS" 字样
  ↓
Gateway 是否收到 push？
  → Envoy admin /config_dump 确认
  → 常见：Canary Ingress 缺少 canary: "true"
         正则路径语法错误
         多个 Ingress 优先级冲突

OOM Killed

Plain 复制代码

看 envoy_server_memory_allocated 趋势
├─ 持续增长 → 内存泄漏或配置膨胀
│            → 开启 onlyPushRouteCluster: true（默认已开）
│            → 减少不需要的路由规则
│            → 检查是否有 Wasm 插件内存泄漏
│
├─ 突发增长 → 短时大量连接涌入
│            → 增大 resources.limits.memory（留 50% 余量）
│            → 降低 defaultUpstreamConcurrencyThreshold
│
└─ 稳定但接近 limit → 正常增长超出配额
                      → 线性升配 memory
                      → memory = base + routes×2KB + conns×50KB

灰度比例不准

Plain 复制代码

同一路由是否同时配了多种灰度方式？
├─ 是 → 优先级覆盖：Header > Cookie > 权重
│       → 删除不需要的高优先级灰度方式
│
└─ 否 → 仅权重灰度
        ├─ 样本不够 → 至少观察 10K 请求再判断
        └─ canary-weight-total 被自定义
           → 确认总权重计算正确
           → 正式服务权重 = total - Σ灰度权重

八、常见调优场景速查

场景 1：Gateway CPU 持续 > 80%

症状： 路由规则 > 1000 条，xDS 推送频繁

操作：

确认 onlyPushRouteCluster: true（默认已开启）
Gateway 升配至 4000m CPU 或扩副本
合并相似路由规则，使用 pathType: Prefix 通配符
删除不再使用的 Canary Ingress 减少配置量

场景 2：后端连接被拒绝（503）

症状： upstream_cx_connect_fail 持续 > 0

操作：

检查后端 Pod readinessProbe 是否通过
检查 defaultUpstreamConcurrencyThreshold 是否打满
检查后端服务自身的连接数限制
将负载均衡算法从 round_robin 切为 least_conn

场景 3：滚动更新丢请求

症状： 发布期间出现短暂 502/50

操作：

设置 rollingMaxUnavailable: "0"
设置 rollingMaxSurge: "25%"
后端 Pod 配置 preStop hook：sleep 10
Gateway 的 terminationGracePeriodSeconds ≥ 30

场景 4：限流不够精确

症状： 单机限流 × 副本数 ≠ 期望全局限流值

操作：

单机限流是近似值，rps_per_pod × replicas ≈ global_rps
HPA 自动伸缩时副本数变化，全局阈值自动变化
精确全局限流 → 商业版 MSE Ingress（基于 Redis）
临时方案：固定 Gateway 副本数，关闭 HPA

场景 5：Prometheus 存储写满

症状： Prometheus Pod OOM 或 PVC 满

操作：

降低 traceSampling（如 0.01 → 0.005）
设置 Prometheus retention: 15d
远端存储用 Thanos / Cortex 长期归档
调大 PVC 和 memory limit

场景 6：跨域请求被浏览器拦截

症状： OPTIONS 预检返回 403 或缺少 CORS 响应头

操作：

确认 higress.io/enable-cors: "true" 已设置
cors-allow-origin 不能是 * 当 cors-allow-credentials: "true"
浏览器 DevTools 检查 OPTIONS 响应头
cors-max-age 设为 86400 减少预检频率

九、上线前检查清单

#	检查项	验证方法	通过标准
1	Gateway 副本数 ≥ 2	`kubectl get pods -l app=higress-gateway`	Running 且分布在不同节点
2	Guaranteed QoS	requests == limits	所有核心组件
3	零停机更新	`rollingMaxUnavailable: "0"`	更新期间无 5xx
4	超时已配置	`kubectl get ingress -o yaml	grep timeout`
5	限流已配置	`kubectl get ingress -o yaml	grep route-limit`
6	HTTPS 已开启	`curl -I http://... → 301`	HTTP 自动跳转 HTTPS
7	监控面板就绪	Grafana Dashboard 已导入	核心指标有可视化
8	告警规则激活	Prometheus AlertManager	8 条核心告警全部激活
9	灰度验证	`curl -H "higress: v1"`	按预期路由到灰度版本
10	内存水位安全	`envoy_server_memory_allocated < 60% limit`	安全水位线以下

十、关键注意事项

request 必须等于 limit。 Envoy 对内存敏感，Burstable QoS 在节点资源紧张时会被压缩 CPU 导致延迟飙升。
不要默认不限制超时。 Higress 默认超时为 0（无限），后端不返回时网关永远等。每条路由必须显式设置 higress.io/timeout。
单机限流不等于全局限流。 HPA 伸缩会改变副本数，全局限流阈值随之漂移。需要精确限流用商业版。
高流量场景降低重试次数。 proxy-next-upstream-tries 设为 3 在 10K QPS 时放大为 30K QPS 打向后端，容易雪崩。
traceSampling 要随流量反比。 100% 采样在 1K QPS 没问题，在 20K QPS 会产生 20K samples/s 的追踪数据，存储成本巨大。
滚动更新必须设 rollingMaxUnavailable: "0"。 否则 K8s 会先杀旧 Pod 再建新 Pod，期间无可用实例。
Anti-Affinity 必须配置。 所有 Gateway 副本落在同一台宿主机上，机器挂了等于全部不可用。
onlyPushRouteCluster: true** 保持默认开启。** 大型集群中关闭此项会将全部 Service 推送给 Envoy，内存和推送延迟都会暴增。
灰度优先级：Header > Cookie > 权重。 同一路由同时配了多种灰度方式，只有最高优先级的生效，其余被忽略。
流量镜像的 Host 会自动加 -shadow 后缀。 镜像目标服务需要识别这个后缀以避免执行写入副作用。