Docker 部署 Higress：体验 API 网关、控制台与 AI 网关

本文在单台主机上部署 Higress v2.2.4 All-in-One 版本。一个容器同时运行控制面、Envoy 网关、Higress Console 和内置插件服务，配置持久化到宿主机目录，适合本地评估、开发测试和 PoC。

Higress 官方明确说明 All-in-One 模式没有经过大规模生产使用。本文的 Compose 配置解决可重复启动、数据持久化和版本固定问题，但不把它描述为高可用生产方案；正式生产环境应进一步评估官方 Kubernetes/Helm 部署。

部署结论

项目	本文采用的值
GitHub 地址	higress-group/higress
独立运行仓库	higress-group/higress-standalone
官方镜像	`higress-registry.cn-hangzhou.cr.aliyuncs.com/higress/all-in-one:2.2.4`；镜像仓库没有公开匿名目录页，链接指向官方镜像使用文档
项目版本	`v2.2.4`，发布于 2026-08-13
镜像摘要	`sha256:930b314be06e4b435617a39ac8dc8f17c9d60a4faf2c96aa7aafe9e85381ad9b`
正式部署	Docker Compose，All-in-One 单容器
快速体验	支持 `docker run`；容器停止后删除，挂载到 `data/` 的配置仍保留
适用范围	本地体验、开发测试、单机 PoC
主机架构	Linux `amd64`、`arm64`，已通过镜像清单核对
最低资源	官方未给出 CPU、内存和磁盘下限；启动前应确认宿主机有足够可用资源
对外端口	`8001` Console、`8080` HTTP Gateway、`8443` HTTPS Gateway
持久化位置	`./data` -> `/data`
外部依赖	无数据库、缓存或 Kubernetes；测试上游使用 `httpbin.org`
验证范围	官方资料核对、镜像标签/摘要/架构检查、Compose 静态校验；未拉取镜像或启动容器
资料核对日期	2026-08-27

All-in-One 是最快看到控制台和路由效果的方式。Compose 是本文的正式路径，因为它能固定镜像摘要、声明重启策略并保留统一的运行配置。

运行结构

浏览器通过 8001 访问 Console；业务请求通过 8080 或 8443 进入 Envoy 网关。Console 写入的域名、服务来源、路由和插件配置保存在 /data，重建容器后仍可加载。

text

管理员浏览器 ---> 127.0.0.1:8001 ---> Higress Console
客户端请求  ---> 主机:8080/8443 ---> Envoy Gateway ---> 后端 API / LLM
                                            |
                                      ./data 持久化配置

准备条件

已安装 Docker Engine 或 Docker Desktop，并且 docker compose 可用。
8001、8080、8443 没有被其他程序占用。
主机可以访问 Higress 阿里云镜像仓库；第一次启动需要下载体积较大的 All-in-One 镜像。
使用 httpbin.org 验证路由时，Higress 容器需要能够访问互联网和解析 DNS。

bash

docker --version
docker compose version
docker info --format '{{.Architecture}}'

检查端口占用：

bash

lsof -nP -iTCP:8001 -sTCP:LISTEN
lsof -nP -iTCP:8080 -sTCP:LISTEN
lsof -nP -iTCP:8443 -sTCP:LISTEN

Linux 没有 lsof 时可以使用 ss -lntp。如果端口已有监听者，先确认进程归属，再修改 Compose 左侧的宿主机端口；不要直接终止不明进程。

Docker 快速体验

这一段用于临时体验。容器使用 --rm，停止后会自动删除；data/ 是宿主机绑定目录，里面的配置不会随容器一起删除。

bash

mkdir -p "$HOME/apps/higress-trial/data"
cd "$HOME/apps/higress-trial"

docker run -d --rm --name higress-trial \
  -e MODE=full \
  -e O11Y=off \
  -e USE_PLUGIN_SERVER=on \
  -v "$PWD/data:/data" \
  -p 127.0.0.1:8001:8001 \
  -p 127.0.0.1:8080:8080 \
  -p 127.0.0.1:8443:8443 \
  higress-registry.cn-hangzhou.cr.aliyuncs.com/higress/all-in-one:2.2.4@sha256:930b314be06e4b435617a39ac8dc8f17c9d60a4faf2c96aa7aafe9e85381ad9b

镜像下载和内部组件启动需要时间。查看最近日志，并等待 Console 返回 HTTP 响应：

bash

docker logs --tail=200 higress-trial
curl -I http://127.0.0.1:8001/

浏览器打开 http://127.0.0.1:8001/。首次访问会要求初始化管理员账号，不存在需要沿用的默认密码。

结束快速体验：

bash

docker stop higress-trial

准备长期保留本次配置时，继续使用下面的 Compose，并把快速体验目录中的 data/ 复制到正式目录。复制前先停止容器，避免配置正在写入。

Docker Compose 正式部署

创建部署目录

bash

mkdir -p "$HOME/apps/higress/data"
cd "$HOME/apps/higress"

创建 compose.yaml：

yaml

name: higress

services:
  higress:
    image: higress-registry.cn-hangzhou.cr.aliyuncs.com/higress/all-in-one:2.2.4@sha256:930b314be06e4b435617a39ac8dc8f17c9d60a4faf2c96aa7aafe9e85381ad9b
    container_name: higress
    restart: unless-stopped
    environment:
      MODE: full
      O11Y: "off"
      USE_PLUGIN_SERVER: "on"
    ports:
      - "127.0.0.1:8001:8001"
      - "127.0.0.1:8080:8080"
      - "127.0.0.1:8443:8443"
    volumes:
      - ./data:/data
    extra_hosts:
      - "host.docker.internal:host-gateway"
    networks:
      - gateway-net

networks:
  gateway-net:
    name: gateway-net

三个端口默认只绑定 127.0.0.1，避免未完成账号、TLS 和访问控制配置时暴露到局域网或公网。host.docker.internal:host-gateway 让 Linux 上的容器能够访问宿主机服务；Docker Desktop 通常已经内置该域名。

gateway-net 使用固定名称。其他 Docker Compose 应用可以把需要接入网关的服务连接到这个外部网络，Higress 随后可以通过服务名访问它们。

校验并启动

bash

docker compose config
docker compose pull
docker compose up -d
docker compose ps
docker compose logs --tail=200 higress

docker compose ps 应显示 higress 为运行状态。继续检查容器内部的核心进程：

bash

docker exec higress supervisorctl status \
  apiserver controller pilot gateway console plugin-server

这些进程应显示 RUNNING。本文关闭了 O11Y，Prometheus、Loki 和 Grafana 不在本次验收范围内。

初始化控制台

浏览器打开：

text

http://127.0.0.1:8001/

首次访问时创建管理员账号并设置强密码。完成初始化后重新登录，应该能看到服务来源、服务列表、路由配置、域名管理、证书管理和插件市场等入口。

如果 Higress 部署在远程 Linux 主机上，保持 Console 只监听服务器的 127.0.0.1，从本机建立 SSH 隧道：

bash

ssh -L 8001:127.0.0.1:8001 user@example-server

然后仍然访问 http://127.0.0.1:8001/。将 user@example-server 替换为自己的 SSH 登录目标；不要为了省事直接把未加固的管理端口开放到公网。

创建第一条 API 路由

下面沿用官方快速开始中的 httpbin.org 示例，用于验证 Console、配置下发、域名匹配、路由和上游访问整条链路。

创建服务来源

进入“服务来源”，创建一条 DNS 服务来源：

字段	值
类型	`DNS 域名`
名称	`httpbin`
服务端口	`80`
域名列表	`httpbin.org`

保存后，在“服务列表”中确认出现类似 httpbin.dns 的目标服务。

创建域名

进入“域名管理”并创建：

字段	值
域名	`foo.bar.com`
协议	`HTTP`

该域名只用于网关的 Host 匹配，不需要修改 DNS 或本机 hosts，因为稍后的 curl 会直接设置 Host 请求头。

创建路由

进入“路由配置”并创建：

字段	值
路由名称	`httpbin`
域名	`foo.bar.com`
路径匹配	前缀匹配 `/`
方法	留空，匹配所有 HTTP 方法
目标服务	`httpbin.dns`

保存后等待几秒，让控制面把配置下发到 Envoy。

通过网关请求

bash

curl -i http://127.0.0.1:8080/get \
  -H 'Host: foo.bar.com'

成功时应返回 HTTP 200 和 JSON 内容，其中 url 指向 http://foo.bar.com/get 或对应的上游请求信息。返回 404 通常说明域名或路径没有匹配；返回 503 通常说明目标服务解析失败或上游不可达。

接入现有单体应用

应用运行在宿主机

假设 Java 应用监听宿主机 9000，创建 DNS 服务来源时使用：

text

域名：host.docker.internal
端口：9000

不要填写 localhost 或 127.0.0.1，它们在 Higress 容器里指向 Higress 容器自身。先从容器内验证宿主机端口：

bash

docker exec higress curl -I http://host.docker.internal:9000/

应用也运行在 Docker 中

把业务容器加入 gateway-net。在业务项目的 Compose 中声明：

yaml

services:
  orders-api:
    image: your-registry.example/orders-api:1.0.0
    networks:
      - gateway-net

networks:
  gateway-net:
    external: true
    name: gateway-net

这里的镜像地址只是结构示例，不是可直接拉取的公共镜像。实际接入时替换为自己的固定版本镜像，然后在 Higress 的 DNS 服务来源中填写 orders-api 和应用容器实际监听端口。业务容器不必把端口发布到宿主机，只需和 Higress 位于同一个 Docker 网络。

体验 AI 网关

普通 API 路由验证完成后，可以继续在 Console 中配置 AI 能力：

在“大模型提供商”中添加实际使用的模型厂商和凭据。
在“AI 路由”中选择对外路径、模型和目标提供商。
根据需要启用 ai-proxy、AI 负载均衡、Token 限流、统计或内容安全插件。
使用 Console 生成的调用示例，或者把 OpenAI SDK 的 base_url 改成 Higress Gateway 地址后验证。

模型密钥属于敏感信息，只在 Console 的凭据字段中录入，不要写进 Compose、文章命令、Git 仓库或聊天记录。不同模型厂商的协议和模型名会变化，本节不提供虚构的通用密钥或模型 ID。

验证持久化

完成 httpbin 路由后重建容器：

bash

docker compose up -d --force-recreate
docker compose ps
curl -i http://127.0.0.1:8080/get -H 'Host: foo.bar.com'

重新登录 Console 后，域名、服务来源和路由仍应存在，请求也应继续返回 HTTP 200。这证明配置来自宿主机 data/，而不是只存在于旧容器可写层。

日常运维

bash

cd "$HOME/apps/higress"

docker compose ps
docker compose logs --tail=200 higress
docker compose restart higress
docker compose stop
docker compose start

检查磁盘占用：

bash

du -sh data
docker system df

不要把 docker system prune -a 当成日常维护命令，它可能删除同一主机上其他项目仍需要的镜像和缓存。

备份与恢复

All-in-One 的状态集中在 data/。备份时短暂停止容器，避免复制到一半时配置继续变化：

bash

cd "$HOME/apps/higress"
docker compose stop higress

backup_file="$HOME/higress-2.2.4-$(date +%Y%m%d-%H%M%S).tar.gz"
tar -czf "$backup_file" compose.yaml data
tar -tzf "$backup_file" | head -50

docker compose start higress

恢复时先解压到新目录验证，不直接覆盖现有部署：

bash

restore_dir="$HOME/apps/higress-restore"
mkdir -p "$restore_dir"
tar -xzf "$HOME/higress-backup.tar.gz" -C "$restore_dir"
cd "$restore_dir"
docker compose config

把示例归档名替换为实际备份文件。确认文件完整、端口不会与现有实例冲突后，再停止旧实例并启动恢复目录中的 Compose。恢复完成后重新检查登录、路由和网关请求。

升级与回退

升级前读取目标版本 Release 和 Docker 部署文档，确认 All-in-One 镜像已经发布，并记录新镜像的多架构摘要。

bash

cd "$HOME/apps/higress"
docker compose stop higress
tar -czf "$HOME/higress-before-upgrade-$(date +%Y%m%d-%H%M%S).tar.gz" compose.yaml data
docker compose start higress

随后把 compose.yaml 的 image 同时改为目标版本标签和对应摘要，再执行：

bash

docker compose config
docker compose pull
docker compose up -d
docker compose logs --tail=200 higress

验证 Console 登录、核心进程、普通 API 路由和 AI 路由。需要回退时先恢复原镜像标签和摘要；如果新版本已经改变持久化数据格式，仅切换旧镜像可能不安全，应使用升级前备份恢复到独立目录后验证。

对外开放前的边界

Console 8001 继续限制在 127.0.0.1，通过 SSH 隧道、VPN 或受控反向代理访问。
需要向局域网提供 API 时，只把 Gateway 端口改成例如 0.0.0.0:8080:8080，同时配置主机防火墙、鉴权和限流。
公网 HTTPS 应使用受信任证书、明确域名和访问策略，不要依赖体验环境中的默认状态。
固定镜像标签和摘要；升级时主动更新，不使用浮动的 latest。
定期备份 data/，并在另一目录做恢复演练。
All-in-One 不提供多节点高可用。需要生产级弹性、滚动升级和故障隔离时，迁移到官方 Helm/Kubernetes 部署。

常见问题

Console 无法访问

先检查容器和进程：

bash

docker compose ps
docker compose logs --tail=200 higress
docker exec higress supervisorctl status console apiserver controller

如果主机端口被占用，修改 Compose 左侧端口，例如 127.0.0.1:18001:8001，再访问 http://127.0.0.1:18001/。远程主机默认不能从外部直接访问 127.0.0.1:8001，应使用 SSH 隧道。

路由返回 404

404 多数是 Host 或路径不匹配。确认请求包含正确的 Host：

bash

curl -i http://127.0.0.1:8080/get -H 'Host: foo.bar.com'

同时检查域名配置是 foo.bar.com，路由路径为前缀 /，配置保存后等待数秒再请求。

路由返回 503

503 通常表示 Envoy 已匹配路由，但连接不到上游。检查 DNS 和直接访问：

bash

docker exec higress getent hosts httpbin.org
docker exec higress curl -I http://httpbin.org/get

接入宿主机服务时使用 host.docker.internal；接入其他容器时确认双方都在 gateway-net，并使用容器服务名而不是宿主机端口映射地址。

插件启用后没有生效

本文启用了内置 Plugin Server。检查相关进程和日志：

bash

docker exec higress supervisorctl status plugin-server gateway
docker compose logs --tail=300 higress

如果把 USE_PLUGIN_SERVER 改为 off，Higress 会改从公网 OCI 镜像仓库加载 Wasm 插件；受限网络环境可能因此加载失败。

拉取镜像超时

先单独验证镜像仓库：

bash

docker pull higress-registry.cn-hangzhou.cr.aliyuncs.com/higress/all-in-one:2.2.4

官方 README 还列出了北美和东南亚区域仓库，但不同区域的镜像同步状态可能变化。切换区域前先核对目标标签和摘要，或者把已验证镜像同步到自己控制的私有仓库，不要随意使用来源不明的镜像代理。

部署完成后

先保留 httpbin 路由作为基线，再接入一个真实的单体 API，验证路径改写、鉴权、限流和错误处理。随后可以添加一个实际 LLM 提供商，检查普通 API 和 AI API 是否能在同一个 Console 中统一管理。

准备让其他用户访问前，完成 Console 隔离、Gateway 鉴权、HTTPS、日志留存和备份恢复演练。确认 All-in-One 无法满足可用性目标时，再迁移到 Kubernetes/Helm，而不是继续在单容器上堆叠生产职责。

总结

本文固定使用 Higress v2.2.4 All-in-One 多架构镜像，以 Docker Compose 部署 Console、控制面、Envoy Gateway 和插件服务，并通过 httpbin.org 完成首条 API 路由验证。配置保存在宿主机 data/，容器重建后应继续存在。

这套方式适合快速体验和单机 PoC，不是高可用生产架构。最重要的运维约束是保护 8001 管理端口、备份 data/、固定镜像摘要，并在升级后同时验证普通路由和 AI 路由。

参考资料

Higress 官方仓库 - 核对日期：2026-08-27
Higress v2.2.4 Release - 发布时间：2026-08-13
官方 Docker All-in-One 部署文档 - 核对端口、数据卷、运行模式和生产边界
官方快速开始 - 核对首次初始化、DNS 服务来源、域名和路由配置
Higress Standalone 仓库 - 核对 All-in-One 构建、环境变量和独立部署限制
Standalone release-provenance.json - 核对 v2.2.4 组件版本、摘要和 amd64/arm64 平台
Docker 官方 Compose 文档 - 核对 Compose 操作方式

Docker 部署 Higress：体验 API 网关、控制台与 AI 网关 ​

部署结论 ​

运行结构 ​

准备条件 ​

Docker 快速体验 ​

Docker Compose 正式部署 ​

创建部署目录 ​

校验并启动 ​

初始化控制台 ​

创建第一条 API 路由 ​

创建服务来源 ​

创建域名 ​

创建路由 ​

通过网关请求 ​

接入现有单体应用 ​

应用运行在宿主机 ​

应用也运行在 Docker 中 ​

体验 AI 网关 ​

验证持久化 ​

日常运维 ​

备份与恢复 ​

升级与回退 ​

对外开放前的边界 ​

常见问题 ​

Console 无法访问 ​

路由返回 404 ​

路由返回 503 ​

插件启用后没有生效 ​

拉取镜像超时 ​

部署完成后 ​

总结 ​

参考资料 ​

Docker 部署 Higress：体验 API 网关、控制台与 AI 网关

部署结论

运行结构

准备条件

Docker 快速体验

Docker Compose 正式部署

创建部署目录

校验并启动

初始化控制台

创建第一条 API 路由

创建服务来源

创建域名

创建路由

通过网关请求

接入现有单体应用

应用运行在宿主机

应用也运行在 Docker 中

体验 AI 网关

验证持久化

日常运维

备份与恢复

升级与回退

对外开放前的边界

常见问题

Console 无法访问

路由返回 404

路由返回 503

插件启用后没有生效

拉取镜像超时

部署完成后

总结

参考资料