Higress 环境搭建 - 我的博客

NOTE
本文讲解 Higress 的三种部署方式，从快速体验到生产级部署，覆盖不同场景需求。

部署方式对比#

方式	适用场景	复杂度	生产可用
Docker Compose	本地体验、开发测试	⭐	❌
Kubernetes + Helm	生产环境、云原生	⭐⭐⭐	✅
本地源码编译	插件开发、二次开发	⭐⭐⭐⭐	❌

方式一：Docker Compose（快速体验）#

一键安装脚本#

1
# 官方一键脚本（最简单）
2
curl -fsSL https://higress.io/standalone/get-higress.sh | bash -s -- -a
3

4
# 参数说明：
5
# -a: 自动安装依赖（Docker/Docker Compose）
6
# -c: 指定配置目录（默认 ~/.higress）
7
# -p: 指定端口（默认 8080/8443）

手动 Docker Compose#

1
version: '3.8'
2

3
services:
4
  higress:
5
    image: higress-registry.cn-hangzhou.cr.aliyuncs.com/higress/all-in-one:latest
6
    container_name: higress
7
    ports:
8
      - "8080:8080"     # HTTP 网关端口
9
      - "8443:8443"     # HTTPS 网关端口
10
      - "8001:8001"     # Higress Console 端口
11
    volumes:
12
      - ./data:/data    # 持久化配置
13
    restart: unless-stopped
14
    environment:
15
      - CONFIG_TEMPLATE=standalone

1
# 启动
2
docker compose up -d
3

4
# 查看日志
5
docker compose logs -f higress
6

7
# 访问 Console
8
open http://localhost:8001

验证安装#

1
# 检查容器状态
2
docker ps | grep higress
3

4
# 测试网关（默认返回 404，因为没有配置路由）
5
curl -i http://localhost:8080
6

7
# 查看 Higress 版本
8
docker exec higress higress version

方式二：Kubernetes + Helm（生产推荐）#

前置要求#

Kubernetes 1.28+
Helm 3.8+
kubectl 配置好集群访问

准备 K8s 集群（本地实验）#

1
# 方案 1：kind（推荐，轻量）
2
kind create cluster --name higress
3

4
# 方案 2：minikube
5
minikube start --cpus=4 --memory=8192
6

7
# 方案 3：云厂商 K8s（ACK/TKE/CCE/EKS）
8
# 按厂商文档创建集群

Helm 安装 Higress#

1
# 1. 添加 Helm 仓库
2
helm repo add higress https://higress.io/helm-charts
3
helm repo update
4

5
# 2. 查看可用版本
6
helm search repo higress --versions
7

8
# 3. 安装（生产配置）
9
helm install higress higress/higress \
10
  -n higress-system \
11
  --create-namespace \
12
  --set global.local=false \
13
  --set higress-core.controller.replicas=2 \
14
  --set higress-core.gateway.replicas=2 \
15
  --set higress-console.replicas=1
16

17
# 4. 等待部署完成
18
kubectl wait --for=condition=available deployment/higress-controller \
19
  -n higress-system --timeout=300s

Helm Values 配置详解#

1
# values.yaml（生产推荐配置）
2
global:
3
  local: false                    # 非本地模式
4
  o11y:
5
    enabled: true                 # 启用可观测性
6
    grafana:
7
      enabled: true
8

9
higress-core:
10
  controller:
11
    replicas: 2                   # 控制面副本数（高可用）
12
    resources:
13
      requests:
14
        cpu: 500m
15
        memory: 512Mi
16
      limits:
17
        cpu: 2000m
18
        memory: 2Gi
19

20
  gateway:
21
    replicas: 2                   # 数据面副本数（按流量调整）
22
    resources:
23
      requests:
24
        cpu: 1000m
25
        memory: 1Gi
26
      limits:
27
        cpu: 4000m
28
        memory: 4Gi
29
    service:
30
      type: LoadBalancer          # 生产用 LoadBalancer，测试用 NodePort
31
      annotations:
32
        # 云厂商 SLB 注解（按实际调整）
33
        service.beta.kubernetes.io/alibaba-cloud-loadbalancer-spec: "slb.s2.small"
34

35
higress-console:
36
  replicas: 1
37
  service:
38
    type: ClusterIP               # 通过 Ingress 暴露，不直接 LoadBalancer
39
  admin:
40
    password: "your-strong-password"  # 务必修改默认密码

验证 K8s 部署#

1
# 检查 Pod 状态
2
kubectl get pods -n higress-system
3
# NAME                                    READY   STATUS    RESTARTS   AGE
4
# higress-controller-xxx                  1/1     Running   0          2m
5
# higress-gateway-xxx                     1/1     Running   0          2m
6
# higress-console-xxx                     1/1     Running   0          2m
7

8
# 检查 Service
9
kubectl get svc -n higress-system
10
# NAME                TYPE           CLUSTER-IP      EXTERNAL-IP     PORT(S)
11
# higress-gateway     LoadBalancer   10.96.xxx.xxx   47.xxx.xxx.xxx  80:3xxxx/TCP,443:3xxxx/TCP
12

13
# 访问网关
14
curl -i http://<EXTERNAL-IP>
15

16
# 访问 Console（通过 port-forward）
17
kubectl port-forward svc/higress-console 8001:8001 -n higress-system
18
open http://localhost:8001

方式三：本地开发环境（插件开发）#

安装依赖#

1
# Go 1.24+（Wasm 插件开发必需）
2
# 下载：https://go.dev/dl/
3
go version  # 确认 go1.24.x
4

5
# Docker（构建 Wasm 镜像）
6
docker --version
7

8
# kubectl（K8s 操作）
9
kubectl version --client
10

11
# helm（Higress 部署）
12
helm version
13

14
# oras（OCI 镜像推送）
15
oras version

本地 Higress 开发环境#

1
# 1. 克隆 Higress 源码
2
git clone https://github.com/alibaba/higress.git
3
cd higress
4

5
# 2. 启动本地 K8s（kind）
6
make kind-up
7

8
# 3. 部署 Higress（开发模式）
9
make deploy-dev
10

11
# 4. 验证
12
kubectl get pods -n higress-system

Wasm 插件开发环境#

1
# 1. 克隆 wasm-go SDK
2
git clone https://github.com/higress-group/wasm-go.git
3
cd wasm-go
4

5
# 2. 创建插件项目
6
mkdir my-plugin && cd my-plugin
7
go mod init my-plugin
8

9
# 3. 编写 main.go（见第 09 篇）
10

11
# 4. 编译 Wasm
12
GOOS=wasip1 GOARCH=wasm go build -o plugin.wasm
13

14
# 5. 本地测试（用 Higress 开发环境加载）

Higress Console 使用#

访问 Console#

1
# K8s 部署：port-forward
2
kubectl port-forward svc/higress-console 8001:8001 -n higress-system
3

4
# Docker Compose：直接访问
5
open http://localhost:8001
6

7
# 默认账号密码：admin / admin（首次登录强制修改）

Console 功能概览#

模块	功能
概览	网关状态、QPS、延迟、错误率监控
路由管理	可视化配置域名、路径、Header 路由规则
服务来源	配置服务发现（K8s/Nacos/Consul/DNS/静态）
插件市场	浏览、安装、配置 Wasm 插件
策略配置	限流、熔断、重试、超时、CORS 等
监控告警	Prometheus/Grafana 集成、日志查询
系统设置	用户管理、权限、全局配置

通过 Console 配置第一个路由#

1
1. 登录 Console → 路由管理 → 创建路由
2
2. 填写：
3
   - 路由名称：demo-route
4
   - 域名：demo.example.com
5
   - 路径：/api/*
6
   - 目标服务：httpbin（内置测试服务）
7
3. 保存 → 测试：
8
   curl -H "Host: demo.example.com" http://<gateway-ip>/api/get

常见问题#

Q1: Docker Compose 启动失败，端口被占用#

1
# 查看端口占用
2
lsof -i :8080
3
# 或
4
netstat -tlnp | grep 8080
5

6
# 修改 docker-compose.yml 端口映射
7
ports:
8
  - "18080:8080"   # 改用 18080

Q2: K8s 部署后 Pod 一直 Pending#

1
# 查看 Pod 事件
2
kubectl describe pod <pod-name> -n higress-system
3

4
# 常见原因：
5
# 1. 资源不足 → 调整 replicas 或 resources
6
# 2. 存储类缺失 → 检查 PVC 状态
7
# 3. 镜像拉取失败 → 检查 imagePullSecrets

Q3: Console 无法访问#

1
# 检查 Service
2
kubectl get svc higress-console -n higress-system
3

4
# 检查 Pod 日志
5
kubectl logs -n higress-system deploy/higress-console
6

7
# 确认 port-forward 正常
8
kubectl port-forward svc/higress-console 8001:8001 -n higress-system

Q4: Wasm 插件编译失败#

1
# 确认 Go 版本
2
go version  # 需要 go1.24+
3

4
# 确认环境变量
5
echo $GOOS   # 编译时设为 wasip1
6
echo $GOARCH # 编译时设为 wasm
7

8
# 正确编译命令
9
GOOS=wasip1 GOARCH=wasm go build -o plugin.wasm

复习卡片#

TIP
快速复习清单

三种部署方式：Docker Compose（体验）、K8s+Helm（生产）、源码编译（开发）

Docker Compose：curl -fsSL https://higress.io/standalone/get-higress.sh | bash -s -- -a

K8s Helm：helm install higress higress/higress -n higress-system --create-namespace

核心组件：higress-controller（控制面）、higress-gateway（数据面）、higress-console（Web UI）

Console 访问：port-forward 8001 端口，默认 admin/admin

Wasm 插件编译：Go 1.24+，GOOS=wasip1 GOARCH=wasm go build

生产配置要点：controller/gateway 各 2 副本、LoadBalancer Service、强密码

TIP
下一篇：核心概念将深入讲解 Higress 的架构设计：Envoy/Istio/Wasm 的关系、数据面与控制面、路由/服务/域名/插件模型。
返回 Higress 学习路线总览 | 合集页