【实战】Ubuntu 24.04下本地部署开源项目Higress

Higress 是基于 Istio 和 Envoy 开发的云原生网关，支持流量管理、安全防护、可观测性等功能，适用于 Kubernetes 环境或单机快速部署场景。

本文将结合实践步骤，详细讲解在 Ubuntu 24.04 系统中通过 Docker 部署 Higress 的完整流程，并解析其核心原理。

一、环境准备

系统要求
- 操作系统：Ubuntu 24.04（需支持 Docker 和 Docker Compose）
- 硬件资源：建议 2 核 CPU、4GB 内存以上
- 网络：确保可访问 Docker Hub 或阿里云镜像仓库

安装 Docker

bash 复制代码

sudo apt update
sudo apt install docker.io
sudo systemctl enable docker
sudo systemctl start docker

验证安装：

bash 复制代码

docker --version
# 输出示例：Docker version 20.10.24, build 2973d36

安装 Docker Compose

bash 复制代码

sudo apt install docker-compose-plugin
docker compose version

二、部署 Higress（单机版）

Higress 提供了 all-in-one 镜像，包含网关、控制台、Prometheus、Grafana 等组件，适合快速体验。

创建工作目录
bash 复制代码
```
mkdir higress && cd higress
```
拉取并运行 Higress 容器

执行以下命令启动 Higress：
bash 复制代码
```
docker run -d --rm --name higress-ai \
  -v ${PWD}/data:/data \
  -p 8001:8001 -p 8080:8080 -p 8443: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 加密）。
  如下图所示：

验证部署状态

bash 复制代码

docker ps | grep higress-ai
# 确认容器状态为 "Up"，且端口映射正常

报错及解决

4.1 找不到命令 "docker"
在运行命令时，系统提示找不到 Docker 命令，说明 Docker 尚未安装。
系统提示了三种安装方式，任选其中一种即可：

bash 复制代码

sudo snap install docker
sudo apt install docker.io
sudo apt install podman-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 守护进程，报错详情如下：

bash 复制代码

docker: permission denied while trying 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' for more information

解决方法：将当前用户添加到 docker 用户组（推荐）

这是官方推荐的持久化解决方案，可以让你在不使用 sudo 的情况下运行 Docker 命令，同时保证了基本的安全性。

将你的用户添加到 docker 组
在终端执行以下命令：

bash 复制代码

sudo usermod -aG docker $USER

如果系统提示 docker 组不存在，可以先创建它：

bash 复制代码

sudo groupadd docker
sudo usermod -aG docker $USER

激活用户组变更
为了让更改立即生效，可以执行以下命令：

bash 复制代码

newgrp docker

或者，你也可以直接注销并重新登录你的用户账户。

验证，现在，尝试再次运行 Docker 命令，无需 sudo：

bash 复制代码

docker ps

如下图所示：

三、初始化 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 指标抓取任务：
  yaml 复制代码
```
scrape_configs:
  - job_name: 'higress'
    static_configs:
      - targets: ['localhost:15020']  # Higress 指标端口
```
导入 Grafana 面板
- 登录 Grafana（默认地址：http://localhost:3000，账号密码 admin/admin）。
- 导入 Higress 官方提供的 JSON 面板（可在控制台「监控面板」页面下载）。
  如下图所示：

五、常见问题与解决

容器启动失败
- 检查 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