Higress 之一 · 理论与架构

环境：192.168.110.207

系列：之一（理论）→ 之二（安装）→ 之三（路由验收）→ 之四（增强与附录）→ 之五（新增接口场景）→ 之六（企业级能力展示）

HTML：docs/html_cursor/Higress_之一_理论与架构_cursor.html

本文含：理论、架构、本次实装踩坑案例（架构选型）、相关常量附录

0. 内部凭据一览（本系列凡鉴权处均用下表）

内网文档，明文收录；勿外传。换密后请同步改本表、console.env、_config.py 与各脚本默认值。

调用示例（复制即用）：

# Console 登录
curl -sS -c /tmp/hc.ck -X POST http://192.168.110.207:8001/session/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"Higress207admin!"}'

# 经 Higress → LiteLLM
curl -sS http://192.168.110.207:18080/llm/v1/models \
  -H "Authorization: Bearer sk-litellm-bocheng-207"

# 经 Higress → Xinference
curl -sS http://192.168.110.207:18080/xf/v1/models \
  -H "Authorization: Bearer xf-K8H3LiS27H4188XdOyWJj74MWMOlIR9tZbiybDbxbSas7eAI"

落盘备份：patches_cursor/Higress部署/console.env（含上表主要项）。

1. 为什么要 Higress

你们已经有 LiteLLM :4000（模型路由）和 Dify :80（应用编排）。Higress 的定位不是替换它们，而是做 总入口 / 策略层：

一句话：Key 进门看 Higress（一期透传）；模型叫什么名字看 LiteLLM。

2. 架构图（落地后的真实形态）

HTML / Markdown 预览均可看图；图源：docs/md_cursor/assets/higress_arch_*_cursor.svg（HTML 侧同步一份）。

2.1 总览：客户端 → Higress → 三后端 → GPU

flowchart TB
  C[客户端 / SDK / 浏览器]
  subgraph HG["Higress standalone · 192.168.110.207"]
    GW["Gateway :18080 / :18443"]
    CON["Console :8001"]
    NAC["Nacos :8848"]
  end
  LLM["LiteLLM :4000<br/>模型名路由 / LB"]
  DIFY["Dify :80<br/>Agent / 知识库"]
  XF["Xinference :9997<br/>Embedding / Rerank"]
  VLLM["vLLM qwen3.6-27b<br/>116.62.10.183:8000"]

  C --> GW
  GW -->|"/llm/* rewrite"| LLM
  GW -->|"Host: dify.ai.local"| DIFY
  GW -->|"/xf/* rewrite"| XF
  LLM -->|chat| VLLM
  LLM -->|embeddings| XF
  CON -.->|管理| GW
  NAC -.->|配置| GW

原端口直连保留（排障用）：:80 / :4000 / :9997。业务推荐总入口 :18080。

2.2 路由分流：路径前缀 vs Host

flowchart LR
  GW["Higress :18080"]
  GW -->|"前缀 /llm + 去前缀"| LLM["LiteLLM :4000"]
  GW -->|"前缀 /xf + 去前缀"| XF["Xinference :9997"]
  GW -->|"Host dify.ai.local<br/>根路径 / 不 rewrite"| DIFY["Dify :80"]

要点：

2.3 四层职责（防重复配置）

flowchart TB
  L1["L1 Higress：入口 / TLS / 限流 / WAF / 路由"]
  L2["L2 LiteLLM：model 路由 / 多机 LB / 上游 Key"]
  L3a["L3a Dify：Agent / RAG"]
  L3b["L3b Xinference：向量推理"]
  L4["L4 vLLM 183：大模型推理"]
  L1 --> L2 --> L4
  L1 --> L3a
  L1 --> L3b
  L2 --> L3b

一句话对照：Key 进门看 Higress（一期透传）；模型叫什么名字看 LiteLLM。

2.4 文本简图（无图环境备用）

客户端 / SDK / 浏览器
        │
        ▼
┌───────────────────────────────┐
│ Higress Gateway  :18080       │  ← 推荐总入口
│ Console          :8001        │
│ Nacos            :8848        │
└───────────────┬───────────────┘
                │
   ┌────────────┼────────────────────┐
   ▼            ▼                    ▼
/llm/*      Host: dify.ai.local    /xf/*
   │            │                    │
LiteLLM:4000  Dify:80           Xinference:9997
   │
   ├─ chat → vLLM (183)
   └─ embeddings → Xinference

3. 路径与 Host 约定

4. 和 LiteLLM 的分工

5. 端口一览

6. 本次实装案例：架构选型阶段踩过的坑

下列问题出现在 2026-08-26 于 192.168.110.207 首次落地 Higress 过程中，直接影响「总入口怎么画图、路径怎么定」。详细安装/路由操作见之二、之三。

案例 A：Gateway 不能占 :80 —— 与 Dify 冲突

现象 / 背景

• 官方 standalone 默认 --gateway-http-port=80、--console-port=8080。
• 本机探测时 :80 已被 Dify 占用：

ss -lntu | grep -E ':(80|8001|8848|18080)\s'
# 当时可见：0.0.0.0:80 已 LISTEN（Dify）
# 18080 / 8001 / 8848 空闲

若强行用默认 80 会怎样

• get-higress.sh 绑定失败，或把 Dify 挤掉，现网 Agent / 控制台中断。

解决方案（已采用）

1. 设计阶段冻结端口：Gateway 18080、HTTPS 18443、Console 8001、Nacos 8848。
2. 安装命令显式传参（见之二），写入 patches_cursor/Higress部署/install_options.env。
3. 文档与 _config.py 的 HIGRESS_* 常量与上述端口一致。
4. 不迁移 Dify 的 :80；总入口用新端口，降低一次性风险。

验证

curl -sS -o /dev/null -w "%{http_code}\n" http://127.0.0.1:80/      # Dify 仍在
curl -sS -o /dev/null -w "%{http_code}\n" http://127.0.0.1:18080/  # Higress
curl -sS -o /dev/null -w "%{http_code}\n" http://127.0.0.1:8001/   # Console

案例 B：Dify 不能走 /dify 子路径 —— 必须改成 Host 路由

现象（真实复现）

一期曾按「路径总入口」配置：

• 前缀 /dify/ → 后端 dify.static:80，并开启 rewrite 去前缀。

验收时：

curl -sS -o /dev/null -w "%{http_code} redirect=%{redirect_url}\n" \
  http://127.0.0.1:18080/dify/

得到类似：

307 redirect=http://127.0.0.1:18080/auth/refresh?redirect_url=%2F

注意：跳转目标是 /auth/refresh，没有 /dify 前缀。浏览器随后打到 Higress 的「默认路由 / Console landing」，而不是 Dify 登录页。根因是 Dify 前端按「站点根路径」发绝对路径重定向，不感知自己挂在子路径下。

排查步骤

1. 确认 LiteLLM、Xinference 同构的「前缀 + rewrite」是通的（/llm/v1/models、/xf/v1/models 有 JSON）。说明网关与 rewrite 机制本身正常。
2. 单独对 Dify 看 Location / redirect_url，确认丢前缀。
3. 查阅 Dify 是否支持 PUBLIC_URL 子路径部署——本环境未改 Dify 本体，优先改网关侧接入方式。

解决方案（已采用）

1. 删除（或停用）路径路由 dify / dify-root。
2. Console 创建域名 dify.ai.local（enableHttps=off）。
3. 创建路由 dify-host：domains=["dify.ai.local"]，路径前缀 /，关闭 rewrite，后端仍 dify.static:80。
4. 客户端 hosts：

192.168.110.207  dify.ai.local

1. 访问：http://dify.ai.local:18080/（未登录返回 307 到 /auth/refresh 且 Host 仍是 dify.ai.local 即属正常）。

架构结论写入本册的原因

• 「总入口」不等于「所有后端都能安全子路径化」。
• SPA/带绝对跳转的控制台 → 优先 Host 路由；纯 API（LiteLLM/Xinference）→ 路径前缀 + 去前缀 rewrite 更合适。

下一篇：安装 Compose 与 Console → Higress_之二_Compose安装与控制台_cursor.md

附录 A：本册相关完整常量（scripts_cursor/_config.py 中 Higress 段）

以下为仓库内实际片段，换机时与之二/之三端口表一并修改：

# Higress 总入口（207 · Docker Compose standalone）
HIGRESS_GATEWAY_HTTP_PORT = 18080
HIGRESS_GATEWAY_HTTPS_PORT = 18443
HIGRESS_CONSOLE_PORT = 8001
HIGRESS_NACOS_PORT = 8848
HIGRESS_BASE = "http://192.168.110.207:18080"
HIGRESS_CONSOLE = "http://192.168.110.207:8001"
HIGRESS_LLM_BASE = "http://192.168.110.207:18080/llm/v1"
HIGRESS_DIFY_BASE = "http://192.168.110.207:18080/dify"
HIGRESS_XF_BASE = "http://192.168.110.207:18080/xf/v1"
HIGRESS_INSTALL_DIR = "/opt/higress"
HIGRESS_PATCH_DIR = "/opt/workbuddy/patches_cursor/Higress部署"
HIGRESS_ENC_KEY = "bocheng207higressenckey32chars!!"  # 恰好 32 字符
HIGRESS_ADMIN_USER = "admin"
HIGRESS_ADMIN_PASS = "Higress207admin!"
HIGRESS_DIFY_HOST = "dify.ai.local"
HIGRESS_BACKEND_HOST = "192.168.110.207"

注：HIGRESS_DIFY_BASE 仍保留路径形态字符串供对照；实际推荐访问为 http://dify.ai.local:18080/（见案例 B）。