Higress 是基于 Istio 和 Envoy 开发的云原生网关，支持流量管理、安全防护、可观测性等功能，适用于 Kubernetes 环境或单机快速部署场景。
本文将结合实践步骤，详细讲解在 Ubuntu 24.04 系统中通过 Docker 部署 Higress 的完整流程，并解析其核心原理。
一、环境准备
系统要求
- 操作系统：Ubuntu 24.04（需支持 Docker 和 Docker Compose）
- 硬件资源：建议 2 核 CPU、4GB 内存以上
- 网络：确保可访问 Docker Hub 或阿里云镜像仓库
安装 Docker
sudoaptupdatesudoaptinstalldocker.iosudosystemctlenabledockersudosystemctl startdocker验证安装：
docker--version# 输出示例：Docker version 20.10.24, build 2973d36安装 Docker Compose
sudoaptinstalldocker-compose-plugindockercompose version
二、部署 Higress（单机版）
Higress 提供了all-in-one镜像，包含网关、控制台、Prometheus、Grafana 等组件，适合快速体验。
创建工作目录
mkdirhigress&&cdhigress拉取并运行 Higress 容器
执行以下命令启动 Higress：
dockerrun-d--rm--namehigress-ai\-v${PWD}/data:/data\-p8001:8001-p8080:8080-p8443:8443\higress-registry.cn-hangzhou.cr.aliyuncs.com/higress/all-in-one:latest参数说明：
-v ${PWD}/data:/data：挂载本地data目录用于持久化配置和日志。-p 8001:8001：Higress 控制台端口（默认 8001）。-p 8080:8080：HTTP 网关端口（用于转发业务流量）。-p 8443:8443：HTTPS 网关端口（支持 TLS 加密）。
如下图所示：
验证部署状态
dockerps|grephigress-ai# 确认容器状态为 "Up"，且端口映射正常报错及解决
- 4.1 找不到命令 “docker”
在运行命令时，系统提示找不到 Docker 命令，说明 Docker 尚未安装。
系统提示了三种安装方式，任选其中一种即可：
sudosnapinstalldockersudoaptinstalldocker.iosudoaptinstallpodman-docker。如下图所示：
推荐选择
- 新手或追求简单：推荐 snap install docker，安装便捷，自动更新。
- 追求稳定与系统集成：推荐 apt install docker.io，适合生产环境。
- 追求性能与安全性：推荐 apt install podman-docker，适合现代容器化应用。
如下图所示：
| 特性 | snap install docker | apt install docker.io | apt install podman-docker |
|---|---|---|---|
| 安装方式 | Snap 包管理器 | APT 包管理器 | APT 包管理器 |
| 来源 | Canonical 官方 | Debian/Ubuntu 社区 | Red Hat 主导 |
| 版本更新 | 自动更新 | 手动更新，版本滞后 | 手动更新，版本较新 |
| 兼容性 | 完全兼容 Docker | 完全兼容 Docker | 兼容 Docker CLI |
| 安全性 | 沙盒隔离 | 传统守护进程 | 无守护进程，支持 rootless |
| 资源占用 | 较高 | 中等 | 较低 |
| 配置路径 | /var/snap/docker/current/config/ | /etc/docker/ | /etc/containers/ |
- 4.2 当前登录的用户没有足够的权限来访问 Docker 守护进程，报错详情如下：
docker: permission deniedwhiletrying to connect to the Docker daemon socket at unix:///var/run/docker.sock: Head"http://%2Fvar%2Frun%2Fdocker.sock/_ping":dial unix /var/run/docker.sock: connect: permission denied Run'docker run --help'formoreinformation解决方法：将当前用户添加到 docker 用户组（推荐）
这是官方推荐的持久化解决方案，可以让你在不使用 sudo 的情况下运行 Docker 命令，同时保证了基本的安全性。
- 将你的用户添加到 docker 组
在终端执行以下命令：
sudousermod-aGdocker$USER- 如果系统提示 docker 组不存在，可以先创建它：
sudogroupadddockersudousermod-aGdocker$USER- 激活用户组变更
为了让更改立即生效，可以执行以下命令：
newgrpdocker或者，你也可以直接注销并重新登录你的用户账户。
- 验证，现在，尝试再次运行 Docker 命令，无需 sudo：
dockerps如下图所示：
三、初始化 Higress 控制台
访问初始化页面
打开浏览器，访问
http://localhost:8001/init，进入初始化向导。如下图所示：设置管理员账号
输入用户名（如
admin）和密码，提交后完成初始化。登录控制台
访问
http://localhost:8001，使用初始化时设置的账号密码登录。
四、核心功能配置与原理
（一）路由配置
Higress 通过路由规则将外部请求转发到后端服务，支持基于路径、域名、Header 等条件的匹配。
创建路由
进入控制台 →路由配置→ 点击「创建路由」。
配置示例：
- 路由名称：
test-route - 域名：
example.com（或留空表示通配） - 路径：
/api - 目标服务：选择已注册的服务（如
higress-console）。
- 路由名称：
原理说明
Higress 基于 Istio 的
VirtualService和DestinationRule实现流量路由。控制台配置会转换为 Istio 资源，由 Envoy 代理执行流量转发。如下图所示：
（二）AI 服务集成（可选）
Higress 支持对接大模型服务（如 OpenAI、千问），需配置 AI 服务提供者。
添加 AI 服务
控制台 →AI 服务提供者管理→ 点击「创建 AI 服务提供者」。
配置示例：
- 类型：
OpenAI - 服务地址：
https://api.openai.com/v1 - 凭证：填写 OpenAI API Key。
如下图所示：
- 类型：
关联路由
在路由配置中，选择「AI 路由」并绑定已创建的 AI 服务，即可实现 AI 请求的代理与限流。
（三）监控与可观测性
Higress 内置 Prometheus 和 Grafana，需手动配置监控面板。
配置 Prometheus
编辑
prometheus.yml（位于data/prometheus/目录），添加 Higress 指标抓取任务：scrape_configs:-job_name:'higress'static_configs:-targets:['localhost:15020']# Higress 指标端口
导入 Grafana 面板
- 登录 Grafana（默认地址：
http://localhost:3000，账号密码admin/admin）。 - 导入 Higress 官方提供的 JSON 面板（可在控制台「监控面板」页面下载）。
如下图所示：
- 登录 Grafana（默认地址：
五、常见问题与解决
容器启动失败
- 检查 Docker 版本是否兼容（建议 20.10+）。
- 查看日志：
docker logs higress-ai，定位错误原因。
控制台无法访问
- 确认端口
8001未被占用：sudo lsof -i:8001。 - 检查防火墙：
sudo ufw allow 8001。
- 确认端口
路由转发异常
- 检查目标服务是否健康：
docker ps确认服务容器运行中。 - 验证路由规则：控制台 →服务列表，确认服务已注册。
- 检查目标服务是否健康：
六、总结
通过 Docker 部署 Higress 是快速体验云原生网关功能的最佳方式。本文从环境准备、部署、配置到原理分析，覆盖了 Higress 的核心使用场景。后续可结合 Kubernetes 集群，探索 Higress 在生产环境中的高级功能（如灰度发布、熔断限流）。
参考资料：
- Higress 官方文档：https://higress.cn
- Istio 流量管理：https://istio.io/latest/docs/concepts/traffic-management/
- Docker 官方指南：https://docs.docker.com
