Higress AI 网关实战教程：一行 Docker 命令搭好你的 AI Native API 网关
【免费下载链接】higress🤖 AI Gateway | AI Native API Gateway项目地址: https://gitcode.com/GitHub_Trending/hi/higress
Higress 是一款云原生 API 网关，内核基于 Istio 和 Envoy，主打 AI 网关能力：统一接入各家大模型、托管 MCP Server、给 API 加限流鉴权。它解决的是"模型供应商协议不统一、API 缺少流量与安全管控"这两个问题。项目是 CNCF 沙箱项目，当前版本 v2.2.4（见 VERSION），支持每秒数十万请求级别的生产场景。
5 分钟上手：三种安装方式与第一次验证
安装有三条路，先看你属于哪种人：
| 方式 | 命令/步骤 | 适合谁 |
|---|---|---|
| Docker（最省事） | 一条docker run起 all-in-one 镜像 | 本地学习、演示、小型站点 |
| Helm 部署 K8s | helm install加--set global.hub=镜像源 | 已有集群、要上生产 |
| 源码构建 | 克隆仓库https://gitcode.com/GitHub_Trending/hi/higress，参考 Makefile.core.mk | 改内核、发镜像 |
Docker 方式只需 4 步，全程约 3~5 分钟（主要花在拉镜像上）：
- 建一个工作目录：
mkdir higress && cd higress，容器配置会写到这个目录 - 执行启动命令：
docker run -d --rm --name higress-ai -v ${PWD}:/data \ -p 8001:8001 -p 8080:8080 -p 8443:8443 \ higress-registry.cn-hangzhou.cr.aliyuncs.com/higress/all-in-one:latest- 浏览器打开
http://localhost:8001，进入 UI 控制台 - 验证成功：在控制台"服务来源"里能看到默认入口，再向 8080 端口发一个 HTTP 请求，返回 200 或路由提示信息，说明网关在转发
三个端口记清楚，后面调试全靠它：
- 8001：UI 控制台入口
- 8080：网关 HTTP 入口
- 8443：网关 HTTPS 入口
拉镜像超时的话，把镜像源换成北美higress-registry.us-west-1.cr.aliyuncs.com或东南亚higress-registry.ap-southeast-7.cr.aliyuncs.com，Helm 部署则通过global.hub参数配置。
核心能力拆解：四个模块逐项看
AI 网关：一份 OpenAI 协议打通所有模型
适用场景：你同时用 OpenAI、Claude、通义千问、Moonshot 等好几家模型，不想为每家写一套对接代码。具体操作：部署 AI Proxy 插件（源码在 plugins/wasm-go/extensions/ai-proxy/），在控制台把目标供应商和 API Key 配上，客户端照 OpenAI 格式调/v1/chat/completions即可。得到结果：插件自动检测请求协议（OpenAI 或 Claude 格式）并转成目标供应商协议，模型名可通过modelMapping映射，多个 Key 随机负载、失效自动切换；仓库 provider 目录里能数出 50 来个已适配供应商，还支持 vllm/ollama 这类自建模型。
MCP Server 托管：让 AI Agent 统一调用工具
适用场景：你要把一批工具 API 暴露给 AI Agent（MCP 协议），还要管住谁能调、能调多快。具体操作：通过插件机制在 Higress 上托管 MCP Server，示例配置参考 samples/mcp/。得到结果：工具调用走网关后，统一获得认证鉴权、细粒度限流、完整审计日志和可观测指标；更新 MCP 逻辑时流量无损，长连接不断。
控制台与服务发现：路由、域名、插件一个界面管完
适用场景：需要可视化管路由，后端服务散落在不同注册中心。具体操作：先在"服务来源"里对接 K8s Service、Nacos、ZooKeeper、Consul、Eureka，或直接用静态 IP/DNS；再到路由页选域名、定义匹配规则、绑定目标服务；域名页可管 TLS 证书（支持对接 Let's Encrypt 自动续签）；插件页可给指定域名或指定路由单独挂插件。得到结果：路由变更毫秒级生效，不用重启网关；监控页内置 Prometheus 和 Grafana，开箱即可看指标。
安全与流量治理：限流、认证、WAF 开箱即用
适用场景：对外 API 要做认证和防刷。具体操作：在插件市场选对应插件挂到域名或路由上，认证类支持 key-auth、hmac-auth、jwt-auth、basic-auth、oidc，防护类有 WAF 和 IP/Cookie 限流（plugins/wasm-go/extensions/ 下 50 余个官方插件）。得到结果：不写业务代码就完成鉴权与限流，插件以 Wasm 沙箱运行，独立升级、热更新，不中断流量。
常见误区纠正：先对照这 5 条
| 错误做法 | 正确做法 |
|---|---|
| 拉镜像一直超时就干等 | 换区域镜像源（北美/东南亚），K8s 用global.hub指定 |
| 浏览器开 8080 等控制台 | 控制台在 8001；8080/8443 是给业务流量走的 |
| 配了 AI 插件就直接请求上游模型地址 | 先建路由让请求进入网关，由插件转发到供应商 |
| 觉得改了插件不生效，重启容器 | 先检查插件是否绑定到了对应的域名/路由，变更本身秒级热更新 |
| 拿 all-in-one Docker 镜像直接上生产 | Docker 版适合学习与小型站点，生产用 Helm 部署 K8s |
边界与注意事项：这些事它做不了或需要条件
- Docker 版不是生产形态：all-in-one 镜像面向个人开发，正式环境走 Helm + K8s，镜像源、组件版本都通过 values 管理
- AI 能力依赖上游 Key：插件只做协议转换和治理，模型本身要你自己有账号和额度
- 网关不替你部署后端：服务要先存在于 K8s、Nacos 等它支持的服务来源里，它负责发现和路由
- 插件沙箱有语言边界：官方插件生态以 Go/Wasm 为主（plugins/wasm-go/、plugins/wasm-rust/、plugins/wasm-cpp/），C++ 等语言走独立编译链路
- 合规提醒：网关上的审计日志、认证配置涉及业务数据，生产部署前按 SECURITY.md 流程管理漏洞与凭据；使用各家模型需遵守相应服务商的条款
写在最后
Higress 的价值一句话：一条 Docker 命令，把模型接入、工具托管、流量与安全治理收进一个网关。现在就可以按第一节的 4 步把 all-in-one 跑起来，打开http://localhost:8001完成你的第一次路由配置；想深入看原理，直接读 docs/architecture.md 和 CONTRIBUTING_CN.md 参与贡献。
【免费下载链接】higress🤖 AI Gateway | AI Native API Gateway项目地址: https://gitcode.com/GitHub_Trending/hi/higress
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
