入口与模型网关：Higress

一句话：网关的价值不是“多一层转发”，而是把认证、配额、模型差异、MCP 接入和访问证据收敛到一个入口；但它只负责准入、转发与记录，任务状态和结果验收永远不在网关。

网关的职责边界见 AI 网关与统一流量治理 与 生产治理与降级；本篇只讲 Higress 这一类开源网关怎么落地。

拼装位置：上游是渠道与业务应用 → 本篇做认证、配额、模型与 MCP 转发 → 下游是 Service Gateway、模型端点与 MCP Server；交界字段 Authorization、consumer、X-AgentScope-Tenant / Namespace。

为什么需要

没有统一入口时，每个 Agent 应用各自接模型：A 团队用厂商 SDK，B 团队用 OpenAI 兼容层，C 团队直连内网推理服务。结果是对外有三套鉴权、四套超时、五种重试；对内不知道谁在花钱、谁在调哪个模型、谁把工具暴露到了公网。更麻烦的是切换模型：每个应用都要改代码、重启、重新测试。

网关要解决的是入口处的共性问题：

• 调用方只认一个地址、一种协议，厂商差异被屏蔽；
• 身份、配额、内容安全在入口统一执行，应用不再各自实现；
• 模型故障时能切换候选，工具调用能统一收敛；
• 每次请求留下可关联的访问记录，供计费和排障。

注意最后一条是“记录”，不是“账本”。网关能告诉你发生了什么，不能告诉你任务是否完成。

核心机制

一、三种网关语义，别混成一个

语义	处理对象	核心问题	Higress 覆盖度
LLM 网关	模型 API	协议转换、配额、路由、缓存	强
MCP 网关	工具与数据	工具发现、协议转换、统一入口	较强，授权需外补
Agent 网关	Agent 身份与任务	任务归属、预算、验收	部分，任务语义需外补

三者可以部署在同一个进程里，但语义不能混：模型请求是无状态的补全，工具调用是有副作用的动作，Agent 调用是有生命周期的任务。把三者都当“HTTP 转发”，就会出现“工具被重试两次”“任务失败但网关显示 200”。

二、一条请求经过什么

图中三道闸的顺序不能换：先认证再配额，否则匿名请求也能消耗配额；先配额再路由，否则超额请求已经打到昂贵模型。日志在最后，但 trace 上下文必须从入口就注入，否则下游的模型调用和工具调用无法串成一条链。

三、认证、消费者与配额

• 认证策略族：Key Auth、HMAC、JWT、Basic、OIDC 开箱可用。企业里通常用 OIDC 接统一身份，机器调用用 Key 或 JWT。
• 消费者（Consumer）：把“谁在用”从 Key 上解耦出来。一个消费者可以有多个 Key，配额挂在消费者上；轮换 Key 不影响配额累计。
• Token 级限流：除了 QPS，还能按输入/输出 Token 消耗做配额，避免“请求数不多但每次塞十万字”的滥用。
• Key 池：上游供应商的多个 Key 轮询，单个 Key 被限流时自动切换；这是可用性手段，不是成本手段。

工程上要把“消费者”与业务租户对齐：消费者名就是租户 ID，Key 只是凭据。否则换 Key 就换了一套账。

四、模型路由：负载、降级与缓存

• 统一协议：对 OpenAI 兼容接口做统一入口，屏蔽不同厂商的鉴权与字段差异；应用只改 base URL 就能切换模型。
• 负载与降级：同一逻辑模型配多个端点，按权重或优先级分流；主端点超时/错误时切候选。降级必须做能力等价校验——文本模型可以互为备份，带工具调用或长上下文的模型不能随便降。
• 语义缓存：相似问题命中缓存，降低重复调用；但缓存键必须带租户、模型版本和提示词版本，否则会把 A 租户的答案给 B 租户。
• 成本感知路由：Higress 提供的是路由与降级能力，不是“按难度自动选模型”的决策器；后者要么放在本地路由（见第 05 篇），要么自建分类服务。

五、MCP 统一入口：收敛，不等于授权

Higress 支持把 HTTP 接口转换成 MCP 协议，也支持代理原生 MCP Server，把分散的工具收敛为一个入口。这解决的是“每个 Agent 各自配置 MCP 地址、各自处理协议差异”的问题。

但三个问题仍在网关之外：

1. 发现不等于授权：工具出现在目录里，不代表当前租户能调用；授权要在消费者、订阅和工具策略三处校验。
2. 工具级 ACL 不够细：网关通常只能按路由或工具名控制，做不到“这个 Agent 只能查订单、不能改订单”；参数级约束要在 MCP Server 或运行时做。
3. SSRF 与出站：MCP Server 可能访问内网；网关要限制出站目标，不能只看入站。

六、流式、热更新与部署形态

• 流式：网关对流式 Body 做真正的透传，Wasm 插件可以处理 SSE 报文；否则首 Token 延迟会被缓冲吃掉。
• 热更新：Wasm 插件独立升级、毫秒级生效，不需要 reload；这对长连接和流式会话很关键。
• 部署：可以跑在 K8s 上，也可以一条 Docker 命令独立启动；对接 Nacos、ZooKeeper、Consul、Eureka 做服务发现，深度集成 Dubbo、Nacos、Sentinel。

最小上手

先用“一个消费者 + 一条模型路由 + 一条 MCP 路由”跑通，不要一上来配全量策略：

# 策略示意，具体 CRD 与字段名以所选版本官方文档为准
consumer:
  name: tenant-a
  auth: oidc
  quota: { qps: 50, tokens_per_minute: 200000 }
route:
  - name: chat
    match: { path: /v1/chat/completions }
    upstream:
      primary: qwen-max
      fallback: [qwen-plus]
    plugins: [ai-token-ratelimit, ai-cache, otel-tracing]
  - name: tools
    match: { path: /mcp/* }
    upstream: mcp-registry
    plugins: [key-auth, otel-tracing]

验收看四件事：无 Token 请求被拒；同一消费者超过 Token 配额返回 429 且带重试提示；主模型不可用时自动切到候选并留下降级标记；一条请求的 trace 能串到下游模型与工具。

生产动作

• 超时分层：连接、首包、流式空闲分别设限，网关超时要小于上游总预算，避免下游还在算、网关已经断开。
• 重试只给幂等请求：模型补全可以有限重试，工具调用必须由业务幂等键决定；网关不替业务做重试决策。
• 429 语义统一：区分“配额耗尽”“上游限流”“并发过高”，返回不同的重试建议，否则客户端只会盲目重试。
• 严格预算按不变量做：可用 = 授权 − 已结算 − 在途预留；检查与预留放在同一原子操作，结束后按实际消耗幂等结算并释放多余预留；重试单独占额；跨层重试共享一个 attempt 预算（网关 3 次 × 应用 3 次不等于 9 次上游调用）。ai-token-ratelimit / ai-quota 只做准入与计量，账本在 Budget Service，不能单独承诺严格上限；字段与 SQL 见 24 §四.4.5。
• Trace 上下文入口注入：注入 traceparent 与租户标签，下游 Service、Dataplane、工具全部继承。
• 日志脱敏：请求体可能含个人信息与密钥，默认不落全文；需要排障时按采样与授权开启。
• 灰度与回滚：模型路由、插件、限流阈值都要能按租户或百分比灰度，回滚不依赖重启。

边界

• 网关不是状态机：它不知道任务执行到哪、是否完成、是否需要人工审批；这些属于运行时的会话事件日志。
• 网关不是预算账本：Token 计数有延迟与重试重复，严格预算需要业务侧做预留与结算，不能只看网关计数。
• 网关不是授权终点：市场订阅、工具策略、数据权限仍在各自系统；网关只做入口处的第一道校验。
• LiteLLM 不是替代品，是另一种取舍：LiteLLM 更轻、模型聚合与虚拟 Key 更顺手，适合团队级或作为库嵌入；但它不以 K8s 网关、Wasm 插件、MCP 统一入口为主战场。选型看你要的是“模型代理”还是“入口治理”。
• 别把所有策略塞进网关：内容安全、工具参数校验、业务规则各有更合适的层；网关插件越多，升级与排障越难。

讲清楚

网关解决的是入口处的共性问题：统一认证、消费者配额、模型协议转换与降级、MCP 工具收敛、访问记录。Higress 基于 Istio 与 Envoy，强在 K8s 原生、Wasm 热更新、流式透传和 100+ 模型接入。

它有三种语义：LLM 网关、MCP 网关、Agent 网关；前两者成熟，第三者只覆盖接入与托管，任务归属、预算和验收仍要平台补。MCP 统一入口解决“收敛”，不解决“授权”；工具级、参数级权限要在运行时与工具侧做。

判断网关是否用对，看三条：超额请求是否在打到模型前被拒；主模型故障是否自动降级且标记；一次请求能否从入口追到模型与工具。三条之外，不要期待网关替你保存任务状态。

适用：Higress 2026 年社区版能力 | 初稿 2026-10