企业官网建设流程全解析

你如果在国内搞AI应用，尤其是大模型网关、Agent编排、多模型接入这类活儿，最近肯定绕不开一个名字：higress。这个云原生网关，我最早接触它的时候它还只是个普通的K8s Ingress控制器，功能中规中矩，该有的路由、限流、熔断都有，但说实话没觉得有什么特别惊艳的地方。直到大模型爆发，AI应用开始铺天盖地地涌出来，我再回头看higress，发现它已经悄悄长成了一个非常对味的AI网关。你在AI时代要接OpenAI、接通义、接各种国产模型，要在网关层做Key管理、Token计量、消费者认证、内容安全审核，甚至要兼容OpenAI的协议格式，这东西几乎是开箱即用。这篇文章我就用实际踩坑的经历，把higress在AI场景下的部署、配置、排错，从头到尾讲一遍，给正在做AI应用网关选型或者被API网关折磨的朋友一个参考。

先说清楚这篇东西是给谁看的。如果你正在做AI应用后端，接手了网关相关的活儿，或者准备把多个大模型API统一接入公司网关，再或者你只是被“AI Agent需要网关做什么”这个问题搞懵了——这篇文章都适合你。我不讲那种教科书级别的定义，直接从实操出发，带你看看higress是怎么从一群网关里杀出来，变成一个真正为AI而生的流量入口。

1. 为什么AI应用需要一套专门的网关

1.1 传统API网关在AI场景下的窘境

在AI应用爆发之前，公司里最常见的网关是Spring Cloud Gateway、Kong、Nginx那一套。它们处理常规的HTTP服务、微服务路由、限流熔断，说实话已经很成熟了，稳定性和性能都有保障。但AI应用来了之后，很多东西变了。

最典型的变化出现在调用协议和流量模型上。原来你写一个后端接口，一个请求进去，数据库查一查，返回一个JSON，几百毫秒结束。但大模型接口不一样，一个对话请求可能要持续几十秒，而且是流式返回，Token是一块一块往外蹦的。传统网关在处理这类长连接和流式响应时，经常会有超时控制不灵活、缓冲区不够用、错误处理逻辑不匹配的问题。更麻烦的是，大模型调用是有Token概念的，你每天消耗多少Token，每个业务方用了多少，这些都要统计。传统网关只认QPS和带宽，对Token计量这个维度是完全空白的。

我举个例子你就明白了。我们团队之前用Nginx做网关，接入一个开源模型的流式接口，结果发现Nginx默认的proxy_buffering会把流式响应全部缓冲到内存里，等到整个响应结束才一次性转给客户端。一个对话响应几十秒，用户那边看到的反应就是长时间无响应，体验极差。后来查了半天，改了一堆配置，才把缓冲关掉勉强能用。但Token计量、消费者级限流、协议转换这些需求，Nginx压根做不了，只能在上层业务代码里自己写。

1.2 AI网关的核心诉求拆解

AI应用接入大模型，通常会有这么几个核心诉求，这些诉求决定了你需要的不是一个普通网关，而是一个专为AI场景设计的网关。

第一是协议适配。现在大模型API的协议可以说是百花齐放，OpenAI的协议、Anthropic的协议、各家国产模型的私有协议，虽然格式大同小异，但细节差异很多。你的业务如果要做多模型切换或者模型灰度，网关如果能统一转换成标准的OpenAI协议格式，上层业务就不用为每个模型写一套适配逻辑。这一点在工程实践里特别值钱。

第二是API Key管理。大模型后端服务的Key属于敏感信息，你不能直接把Key暴露给终端用户。正确的姿势是把Key放在网关层，业务方调用时用网关自己的身份认证体系，网关根据消费者身份不同，把对应的后端Key塞进转发请求里。这样既安全，又方便做配额管理。

第三是Token级别的计量和限流。传统限流只看请求数或每秒请求数(QPS)，但AI场景下单次请求消耗的Token差异巨大，一次长对话可能消耗几百个Token，一次文档分析可能消耗上万Token。如果不做Token级别的限制，用户完全可以用一个大请求把你的配额打满。网关只有能解析流式响应中的Token增量，才能实现精准计量。

第四是内容安全。大模型的输入输出内容在合规层面需要审核，但这块通常由模型服务商自己去处理，如果自己部署模型，就需要网关在转发层做内容检查，比如对接内容安全服务，或者在网关层做简单的敏感词过滤。higress在这块有专门的插件生态，比从零写要省事得多。

其实你可以这么理解：传统API网关管的是“调用次数”，AI网关要管的是“Token消耗”。这个维度的变化，是整个网关能力模型的一次升级。谁能跟上这个变化，谁就能在AI落地项目里抢到先机。

2. higress的整体设计与选型思考

2.1 从Istio生态里长出来的网关

我第一次接触higress时，印象最深刻的不是它的功能列表，而是它的顶层设计——它构建在Istio和Envoy之上。懂云原生的朋友听到这两个名字应该就放心了，Envoy是高性能的代理内核，Istio是服务网格的事实标准，higress相当于是把它们的能力向下沉淀，做成了专注于南北向流量治理的网关。

这带来的好处非常直接：一是性能和稳定性有保证，Envoy在抗并发、连接管理、流式传输上都经过大规模验证；二是生态兼容性好，因为底层就是Istio体系，你原来在Istio里用的VirtualService、DestinationRule这些CRD都可以直接沿用。这句话翻译一下就是——如果你已经有K8s和Istio的基础，上手higress几乎零成本；如果你没有也没关系，higress本身可以独立部署，不依赖Istio控制面，自己就是一套完整的网关方案。

higress早期版本的功能，我认为是照着“好好干活”的路子走的：支持HTTP/HTTPS路由、域名管理、TLS证书、金丝雀发布、限流熔断、JWT认证、自定义插件。这些功能单看都很常规，但组合起来已经可以覆盖90%的企业级流量接入需求。

2.2 面向AI增加的关键能力

真正让我觉得higress“开窍”的，是它在AI方向的几个关键能力迭代。这些能力不是简单的功能堆叠，而是对整个AI应用的接入方式做了重新思考。

第一个是OpenAI协议兼容与转换。higress的AI代理插件(AI Proxy)可以配置多个模型提供方，包括OpenAI、Azure OpenAI、通义千问、文心一言、ChatGLM等。配置之后，网关对外暴露一个OpenAI协议风格的标准接口，后端实际调用的是哪个模型，业务方完全不感知。这在做模型灰度、灾备切换时价值巨大——你只需改网关配置，不用动任何业务代码。

第二个是API Key的集中托管和消费者管理。higress的AI Proxy插件支持把模型提供方的API Key配置在网关侧，同时支持定义多个消费者(Consumer)，每个消费者分配不同的模型配额。终端请求带着自己的身份凭证进来，网关做完认证后，按消费者对应的策略转发，并且在转发时把真正的后端Key注入到上游请求头里。这样用户的Key永远不会泄露到终端，同时每个消费者消耗了多少Token一目了然。

第三个是流式响应的Token计量。这一点是很多网关想做但没做到的。higress的AI统计插件可以解析流式响应中的Token增量数据，实时累加，然后把使用量数据上报给Prometheus等监控系统。你可以在Grafana上直接看到每个消费者的Token消耗曲线，按天、按模型维度统计。这种细粒度的可观测性，对AI应用的资源成本核算至关重要。

第四是AI内容安全检查。higress提供了AI内容安全插件，可以对接阿里云的内容安全服务，对输入和输出内容进行审核。比如用户输入的内容里包含违规词，网关直接在入口处拦截，不用把请求转发到大模型；模型返回的内容有敏感信息，网关也在出口处拦住，不发给用户。对于做C端AI产品的团队来说，这项能力直接决定了你能不能上线。

还有一点值得说，higress的插件机制本身支持Wasm和Go两种扩展方式，如果你有特殊需求，比如自定义一个模型协议转换，或者接入一个冷门的AI服务商，完全可以自己写插件挂上去。这个扩展性我之前在其他网关上很少见到。

2.3 为什么选higress而不是从头自研

曾经有朋友问我，你们团队为什么不用开源的APISIX或者Kong，或者干脆自己写一个网关模块？我的回答是：AI网关这个领域，坑比想象中多，自研的成本远高于收益。

先说自己写。你感觉在业务代码里写一个转发模块，调用大模型API，把结果返回前端，好像并不复杂。但你仔细想一想，这里面涉及流式响应的正确转发、连接池管理、超时重试、并发控制、Token计数、多模型动态切换、API Key的安全存储……每个点单独拿出来都是可以写几周的活，而且线上出了问题，排查链路是散的，压测过不了，更别提高可用。

再说Kong和APISIX。它们都是优秀的网关，但在AI这个赛道上起步比higress晚。截至我写这篇文章的时候，higress已经有完整的AI Proxy、AI Statistics、AI Content Security等一整套AI插件，而其他网关虽然也在迭代，但生态成熟度、文档完整性、社区案例，包括对国内模型服务商的适配程度，暂时都还有差距。国内公有云环境里大模型API的接入需求，higress的支持是最贴合的。

表格对比一下会更直观：

这个表基本代表了我的选型结论：AI时代选网关，不是选一个能转发请求的盒子，而是选一个具备AI上下文感知能力的流量治理系统。higress在这方面，目前是走在最前面的一批。

3. 实操落地：把higress部署成AI网关

3.1 部署环境与安装准备

我这边实际用的环境是Kubernetes 1.26以上的版本，集群规模不大，三个节点，8核16G的云主机。higress的安装方式有两种，一种是通过Helm Chart安装到K8s集群，另一种是Docker Compose单机部署用于测试。生产环境建议用Helm方式。

安装之前需要确保集群里已经准备好了Ingress控制器需要的命名空间，并且有权限创建ClusterRole和ClusterRoleBinding。执行安装命令：

helm repo add higress.io https://higress.io/helm-charts helm repo update helm install higress -n higress-system --create-namespace higress.io/higress

装完之后，正常情况下会看到几个核心Pod在higress-system命名空间里运行：

kubectl get pod -n higress-system

如果你看到类似higress-controller-xxx和higress-gateway-xxx的状态是Running，那安装就算成功了。higress的架构里，controller负责监听配置变更并下发到数据面，gateway就是真正处理流量的Envoy实例。

3.2 配置AI Proxy：统一接入多个大模型

部署完成后，第一步就是配置AI Proxy插件。我们以接入OpenAI和通义千问两个模型提供方为例来演示。

先创建一个全局插件配置，定义好各个模型提供方的base_url和api_key。api_key建议放在K8s Secret里，不要在配置明文出现：

apiVersion: v1 kind: Secret metadata: name: ai-provider-secrets namespace: higress-system type: Opaque stringData: openai-api-key: "sk-xxxx你的OpenAI密钥" dashscope-api-key: "sk-yyyy你的通义密钥"

然后创建AiProxy Plugin：

apiVersion: extensions.higress.io/v1alpha1 kind: WasmPlugin metadata: name: ai-proxy namespace: higress-system spec: defaultConfig: provider: "openai" apiKeys: - name: "openai" value: "$OPENAI_API_KEY" - name: "dashscope" value: "$DASHSCOPE_API_KEY" providers: - name: "openai" type: "openai" baseUrl: "https://api.openai.com/v1" apiKey: "$OPENAI_API_KEY" - name: "dashscope" type: "dashscope" baseUrl: "https://dashscope.aliyuncs.com/api/v1" apiKey: "$DASHSCOPE_API_KEY" defaultTarget: provider: "openai"

这里需要说明一下，defaultConfig里的apiKeys字段用于定义网关在转发时可以使用哪些后端Key，providers字段则声明了可选的模型提供方列表。你也可以在路由级别配置不同的provider，实现“同一个网关入口，不同业务路由到不同模型”的效果。

比如你要为A业务路由到通义千问，为B业务路由到OpenAI，可以创建两个HttpRoute，分别指定不同的provider。

apiVersion: networking.k8s.io/v1 kind: Ingress metadata: name: ai-route-a annotations: higress.io/plugin-config-ai-proxy: | provider: "dashscope" spec: ingressClassName: higress rules: - host: "a.example.com" http: paths: - path: /v1/chat/completions pathType: Prefix backend: service: name: mock-service port: number: 80

这里有个小技巧：后端service可以随便指定一个mock服务，因为AI Proxy插件在匹配到路由后，会在网关内直接把请求转发给配置好的模型提供方，业务后端服务并不实际参与调用。网关在这里等于充当了一个协议转换器，外部看起来是OpenAI格式的接口，内部实际在调用别的模型服务。

3.3 配置消费者与配额管理

模型接入通了之后，下一步就是配置消费者和管理配额。higress的AI Proxy插件提供了consumer字段的概念，你可以在插件配置里定义多个消费者，为不同的消费者设置不同的配额上限。

这里我实际配置了三个消费者，分别对应公司的三个不同业务线：

apiVersion: extensions.higress.io/v1alpha1 kind: WasmPlugin metadata: name: ai-proxy namespace: higress-system spec: defaultConfig: ... consumers: - name: "business-a" credential: "Bearer sk-a-credential" quota: - provider: "openai" maxTokens: 1000000 interval: "1d" - name: "business-b" credential: "Bearer sk-b-credential" quota: - provider: "dashscope" maxTokens: 500000 interval: "1d"

credential就是每个消费者在调用网关时需要携带的认证凭证，网关会根据这个凭证识别身份，再应用对应的配额策略。举个例子，用户调用接口时请求头带Authorization: Bearer sk-a-credential，网关就知道这是business-a的请求，然后按business-a的配额去限制。

这个设计我非常喜欢，因为它把AI应用的“用户”概念落地成了可配置的资源。以前你要做多租户的Token配额管理，得自己写中间件，现在直接在网关里配好，业务代码里不用关心任何配额逻辑。而且配额单位是Token，不是请求次数，这对于AI应用成本控制特别关键。

3.4 开启流式响应与Token统计

在higress的路由配置里，关于流式响应有一个需要特别注意的点：网关默认的响应缓冲策略可能会影响SSE(Server-Sent Events)流式输出的实时性。如果你接入的是模型推理服务，需要确认Proxy配置里允许流式响应直接透传。higress的AI Proxy插件本身支持流式透传，但如果你使用的是普通的HTTP路由(非AI Proxy插件直接兜底)，建议在路由级别加上相关注解：

metadata: annotations: higress.io/proxy-send-timeout: "3600" higress.io/proxy-read-timeout: "3600" higress.io/proxy-buffering: "false"

这几个注解的作用很容易理解：send-timeout和read-timeout控制超时时间，因为大模型流式响应可能会持续很久，默认的超时时间肯定不够；proxy-buffering设为false是关掉缓冲区，让数据边生成边转发，避免用户端长时间等待无响应。

如果你使用AI Proxy插件来转发，higress官方文档里说明它已经内置了对流式响应和Token计数的处理，不需要额外配置这个注解。但如果你做的是自定义插件转发，或者用普通Ingress场景接入模型服务，这些注解就是必须的。

Token统计方面，安装higress的时候默认会部署一套Prometheus监控，你可以在配置里开启AI统计指标。指标会以Counter类型暴露：

higress_ai_token_total{consumer="business-a", provider="openai"} 1024 higress_ai_token_total{consumer="business-b", provider="dashscope"} 512

我在Grafana里建了一个面板，按消费者分组，展示每个消费者当天的Token消耗总量和趋势。这套数据在月底对账、成本分摊的时候非常有用，再也不用靠猜。

3.5 内容安全插件接入

做AI网关，内容安全这块几乎不能省。尤其如果你对外提供的是面向C端用户的AI聊天产品，输入输出的合规审核做不好，分分钟给你惹出麻烦。higress的AI内容安全插件可以对接阿里云的内容安全服务，或者你也可以在插件里配置自己的内容审核HTTP接口。

我这边用的对接方式是这样配置的：

apiVersion: extensions.higress.io/v1alpha1 kind: WasmPlugin metadata: name: ai-content-security namespace: higress-system spec: defaultConfig: serviceName: "aliyun-content-security" servicePort: 443 serviceHost: "green.cn-beijing.aliyuncs.com" action: "block" deniedCode: 403 deniedMessage: "Content is not allowed" defaultTarget: provider: "openai"

配置完成后实测了一下，用户输入“帮我写一段违规内容”的时候，网关直接返回403，请求根本不会发到大模型那边。模型返回的内容如果被审核系统标记为违规，网关同样会把响应拦截下来，替换成自定义的错误信息。这样等于在AI业务的进出口都加了一道闸门。

当然，如果你没有对接云服务的内容安全，你也可以基于higress的Wasm插件机制自己写一个简单的关键字过滤器。higress的插件编写文档里有现成的示例，用Go语言写一个过滤逻辑，编译成Wasm包挂载上去就可以。不过自己写的过滤器显然没有云端服务的语义识别能力，只能做基础的关键词拦截，适合预算有限或者内网环境。

4. 常见问题与排错经验

4.1 AI Proxy插件不生效

这是我在刚开始用higress时踩过的第一个坑。配置好了AiProxy插件，也创建了Ingress，但请求打过去之后报502，后端显示connection refused。

排查过程是这样的：先用kubectl get wasmplugin看插件有没有成功创建，再查看higress-controller的日志，发现插件虽然创建了，但没有被正确匹配到路由上。原因是wasmplugin里的defaultTarget配置和Ingress的绑定关系，需要Ingress上有明确的注解指向插件，或者命名空间和匹配规则设置正确。

解决办法是在Ingress的annotations里显式声明使用哪个插件：

metadata: annotations: higress.io/plugin-config-ai-proxy: "{}"

这个注解的作用是把插件挂载到这条路由上。有了它，higress-controller才会把插件配置下发给对应的Envoy路由。如果没有这个注解，插件即使创建了也不会对该路由生效。这个问题在官方文档里有提到，但表述比较隐晦，我也是翻了好几个issue才确认的。

4.2 流式响应一度不生效

拿到AI Proxy插件后，我很快测了一下流式响应，结果发现模型返回的内容还是被网关缓冲了，前端收到的不是实时的SSE流，而是一整段JSON一次性返回。

排查后确认是higress-gateway的Envoy配置里，全局的gzip压缩和缓冲策略对SSE响应做了额外的处理。解决办法是在Ingress注解里显式关闭缓冲：

higress.io/proxy-buffering: "false" higress.io/proxy-request-buffering: "false"

这里需要注意的是，proxy-buffering控制的是响应缓冲，proxy-request-buffering控制的是请求缓冲。如果你的业务还需要上传大文件给模型做分析，请求缓冲也可以考虑关闭。这个配置改动之后需要等几秒钟让higress-controller把配置下发到数据面，然后重启一下测试请求，才能确认效果。

4.3 Token统计数据偏差

Token计量是AI网关的重头戏，但实际跑了一段时间后，我发现监控面板上的Token消耗数据和模型服务商账单上的数据对不上，差距在5%-10%左右。

原因分析了一下：higress的AI统计插件统计的是网关转发的Token增量，也就是流式响应里每个chunk携带的usage字段或delta内容。但有些模型服务商在非流式模式下返回的Token统计，是在最终响应里一次性给出的，两个统计口径不完全一样。另外，如果某些请求被插件拦截或网关层面报错，Token统计可能不会记录。

要解决这个问题，建议在网关层做双保险：一方面保留higress的Token统计指标，另一方面在业务层把大模型返回的最终usage数据上报到自己的数据系统，月底两边对账。对于成本敏感的场景，还可以考虑在网关配置里开启“精确Token计算”模式，虽然会带来一点性能损耗，但数据一致性会好很多。

4.4 超时和重试导致重复请求

大模型调用时，有时因为上游推理时间过长，网关触发了超时重试，结果导致模型服务商那边生成了两遍，费用翻倍。这是AI网关场景里的一个经典坑。

我这边第一次遇到时还以为是自己代码的bug，后来抓包发现是higress的默认重试策略在作怪。Envoy默认会对某些错误码做重试，包括503和gateway error，而这在AI推理场景下非常危险。解决办法是关闭重试，或在路由上配置更严格的重试条件：

metadata: annotations: higress.io/retry-on: "off"

如果非要启用重试应对临时故障，建议把重试条件限制在明确的连接类错误上，并且设置重试次数为1或者更小。AI推理不是普通HTTP调用，幂等性无法保证，乱重试是会出大事的。这一点我想特别提醒刚开始做AI网关的朋友，不要想当然地沿用之前普通API网关的重试逻辑。

4.5 常见问题速查表

5. 实际使用中的几点体会与扩展方向

5.1 从网关视角看AI应用架构

在把higress用起来之后，我对AI应用的整体架构有了新的理解。以前总觉得网关是基础组件，只要能转发请求就够了；现在看AI应用，网关几乎变成了整个系统的调度中心和策略执行点。谁来调用模型、用什么模型、消耗多少Token、内容合不合规，所有横切关注点都可以在网关层解决，业务后端只需专注于业务逻辑本身。这种架构在团队协作上也有好处：业务同学不用关心后端的模型配置细节，模型团队调整模型版本时，只需要在网关层改配置，前端无感知。

我现在的团队里，网关配置的变更频率已经超过了业务代码的发布频率。一个模型版本的升级，一个不同模型间的切换，一个消费者配额的调整，全部通过higress完成。这在以前是不可想象的，等于基础设施成了AI应用的变更入口。

5.2 可以继续扩展的方向

higress能做的事远不止本文写的这些。我梳理了几个值得继续深入的方向，供你参考。

一是结合higress的Wasm插件机制，做公司内部的ModelOps平台。比如编写自定义插件，对接公司自己的模型注册中心，在网关层实现模型的动态路由、按请求特征自动选择最优模型、以及模型版本的A/B测试。这套能力一旦落地，模型上线就不再是“业务代码改一行、重新发版”的旧节奏。

二是结合higress的限流能力做更细粒度的流控。比如按用户ID做Token级别的阶梯限流，不同会员等级享受不同的模型调用配额，付费用户有更高的Token上限和更快的推理通道。这些策略都可以作为插件配置下发，不用改造业务代码。

三是探索higress在非HTTP协议场景的扩展。大模型应用里还有gRPC、WebSocket等协议，如果未来需要支持多模态模型、实时语音对话，网关的协议适配能力也需要同步演进。虽然目前higress对gRPC的支持还在完善中，但它基于Envoy的底子，扩展空间是有的。

5.3 最后分享一个小技巧

如果你在部署higress后遇到了怎么都排查不清楚的问题，建议先看higress-controller的日志，它会把配置下发的过程全部打印出来。很多问题其实不是转发错误，而是配置没有被正确同步到gateway。另外，higress的官方文档里埋了一个“AI网关最佳实践”的页面，里面有各种主流模型的接入示例，大部分情况下复制改改就能用。

有一点我要承认，higress的文档质量虽然在国内开源项目里算好的，但AI相关的插件文档更新很快，偶尔会出现文档版本和release版本不一致的情况。这个时候不要慌，去GitHub的Release页面看最新的配置文件示例，通常比文档更准确。我踩过几次版本对不上的坑之后，已经养成了先看Release再翻文档的习惯。