Day 01 / 共 20 天 · 第 1 周 后端架构

项目全景：网关控制台

欢迎来到 Higress Console——higress-group 系列第 4 站。前三站（Envoy/Istio/Higress）都是"引擎"，这一站是"给人用的方向盘"：一个全栈应用，让你在网页上点点点，就能管理 Higress 的路由、服务、插件、AI 供应商。第一天先建立整体印象。

📍 你在整门课的位置（10 天 · 前 5 天后端架构 / 后 5 天 SDK 与存储）
D01 全景→ D02 启动→ D03 分层→ D04 REST→ D05 横切→ D06 SDK→ D07 存储→ D08 客户端→ D09 模型→ D10 流转
💡 先立一套贯穿全课的类比（后面每天都会用到） Higress 是网关"引擎"，Console 是给人用的驾驶舱/遥控器。整套系统可以这样对号入座：前端 React = 仪表盘面板（你点点点的地方）、后端 Controller = 前台接待（收单、验票）、SDK 转换器 = 翻译官（把你在界面填的"人话"译成 K8s 听得懂的 YAML）、K8s API Server = 档案室/仓库（所有配置都以"档案"形式存在这里，没有 MySQL）、鉴权 = 门禁。记住这套角色，后面 10 天讲的每个类都能挂到某个角色上。
L01

Console 是什么

Higress Console 是 Higress（云原生 AI 网关）的 Web 管理控制台（README.md:1-7）——用来管理配置规则（服务/路由/域名）、可观测、插件、AI Provider、登录等能力，首个可用版本基于 Kubernetes 部署。

"网关的操作台" 上一站 Higress 是网关本体，它读 K8s 里的 Ingress + 注解 + CRD 就能工作——但让运维手写这些 YAML 太痛苦。Console 就是那个"帮你把界面点击翻译成 YAML"的管理后台。你在网页上填一个"路由名 + 域名 + 后端服务"，点保存，Console 就替你生成一个带 higress.io/* 注解的 Ingress 写进 K8s，Higress 控制器随即读到并生效。好比路由器的 Web 管理页——你不用记命令行，点几下就配好了。

👶 小白：那流量是不是就从 Console 走进来、再由它转发出去的？

👨‍🏫 老师：不是！这是最常见的误会。Console 一滴流量都不碰——它只是"填表→写档案"的管理后台。真正接住用户流量、按规则转发的是网关数据面（Envoy）。Console 关掉了，已生效的路由照样跑，只是你暂时没法改配置而已。

⚠️ 常见误解：以为 Console = 网关本体。其实 Console 只"生产配置"，网关"消费配置执行流量"，两者通过 K8s 档案室解耦——这条界线是整门课的地基。
L02

三大部分

README.md:11-13 说明本仓库由三部分组成，前端构建后会随后端一起部署：

  • frontend/：React 前端，基于阿里 ice.js（frontend/ice.config.mts、frontend/package.json），产物在 frontend/build。
  • backend/：Java Spring Boot，最终把前端产物一起打进一个 jar。
  • helm/：K8s 部署编排（helm/Chart.yaml、helm/values.yaml、helm/templates/）。
读法：关键结论——前后端最终是单一 jar、单一进程部署。这在企业级 Java 项目里很常见：Maven 构建时先编译前端，再把静态文件塞进后端 classpath，用户只需跑一个 jar。
L03

前端怎么被打进后端 jar

这是本项目最有意思的工程点。backend/console/pom.xml 用 frontend-maven-plugin 在 Maven 构建阶段直接编译前端：


  com.github.eirslett
  frontend-maven-plugin
  ../../frontend/
  • pom.xml:107-139：依次执行 install-node-and-npm → npm install → npx → npm run build。
  • pom.xml:149-158（copy-resources-static）：把 ../../frontend/build 拷进 src/main/resources/static。
  • pom.xml:190：git-commit-id 插件注入版本信息。
为什么要这样折腾？ 前端产物（HTML/JS/CSS）本质是一堆静态文件。Spring Boot 会自动把 classpath:/static/ 里的东西当静态资源对外提供。于是把前端 build 结果拷进这个目录，后端 jar 一跑，访问根路径就是前端页面，访问 /v1/* 就是后端 API——同一个端口、同一个进程，部署超简单。
L04

Maven 多模块

后端是 Maven 多模块项目。父 POM backend/pom.xml：

  • pom.xml:7-11：继承 spring-boot-starter-parent:2.7.18。
  • pom.xml:22-25：两个子模块 sdk 和 console。
  • pom.xml:54-75：关键依赖 retrofit 2.9.0、guava 31.1、fastjson 1.2.83、io.kubernetes:client-java 17.0.0、springdoc 1.8.0（Swagger）。
两个模块的分工：
backend/console（higress-console）= Spring Boot 主应用：REST 控制器 + 控制台自身业务（登录/仪表盘/系统配置）+ Web 静态资源。
backend/sdk（higress-admin-sdk）= 核心 SDK：K8s 客户端、模型转换、各资源 Service（Route/Service/Domain/WasmPlugin/AI…）。
读法：console/pom.xml:24-28 显示 console 依赖 sdk。sdk 刻意不依赖 Spring，可作为独立库使用——这是很讲究的分层设计，我们第 2 周会专门拆 sdk。
L05

和 Higress 的关系（承上）

Console ≠ Higress 本体 千万别混淆：上一站的 Higress 控制器/数据面是"配置引擎 + 流量执行者"；Console 只是"给人用的管理界面"——它生成那些 Higress 要读的配置。你在 Console 建一条路由，Console 把它写成 higress.io/* 注解的 K8s Ingress；然后上一站学的 Higress 控制器 watch 到这个 Ingress，翻译成 Istio 配置喂给 istiod，最终生成 xDS 给 Envoy。Console 和 Higress 通过"K8s 资源"解耦——Console 只管写 K8s，从不直接碰 Envoy。
建议先学完 Higress（上一站）再学本课——你会更清楚 Console 生成的那些 Ingress/注解/CRD 到底被谁、怎么消费。
L06

一句话数据流

浏览器界面点击（建路由/配插件/加 AI provider）
  → React 前端调后端 REST（/v1/routes …）
    → Controller 校验 → Service 处理 → SDK 转换
      → K8s 客户端写 Ingress + 注解 / CRD / ConfigMap / Secret
        → （上一站）Higress 控制器 watch 到 → 转 Istio 配置 → xDS → Envoy 生效
📝 举个例子：一次界面点击变成什么 你在网页上填 name=demo、domain=example.com、后端 service=httpbin:8080，点保存 →
前端发 POST /v1/routes（body 是这三个字段）→ Controller 校验 → SDK "翻译官"把它译成一个 Ingress：
metadata.labels: higress.io/domain_example.com=true、higress.io/resource-definer=higress；annotations: higress.io/destination: httpbin.default.svc.cluster.local:8080 → 写进 K8s 档案室。你的三个字段，就这样落成了一份 K8s 档案。
一句话数据流：界面点击 → K8s 档案（Console 只负责到"写档案"为止） 仪表盘 React 点击 前台接待 Controller 校验 翻译官 SDK 转换 档案室 K8s 写 Ingress 上一站 Higress watch→xDS→Envoy ↑ Console 的活到此结束
图注：前四段（仪表盘→翻译官→档案室）是本课范围；虚线右侧是上一站 Higress 的活。
读法：这条链把第 4 站和前三站接起来了。本课聚焦前四段（浏览器→K8s），第五段是上一站的内容。记住一个总纲：Console 的全部工作，本质是"把界面操作翻译成 K8s 原生对象"。
L07

构建与启动脚本

  • backend/build.sh：./mvnw clean package -Dmaven.test.skip=true（会触发前端构建）→ docker build -t higress-console:0.0.1 -f Dockerfile .。
  • backend/start.sh：带 --local 跑 ./console/target/higress-console.jar，否则跑 /app/higress-console.jar；start.sh:5-7 为 arm64 macOS 加了 JVM 兼容参数。
读法：先记住"一条命令 mvn package 就能同时编好前后端并打成一个 jar"。第 4 周（Day 19）会详细拆 Dockerfile 和 Helm。
L08

今日小结 + 动手

🧠 今天你应该能回答

  • Higress Console 是什么？和 Higress 本体什么关系？
  • 本仓库三大部分？前端怎么被打进后端 jar？
  • 后端两个 Maven 模块（console/sdk）各自负责什么？
  • "界面点击 → K8s 资源"这条数据流的每一段？

✋ 动手

cd /Users/bitmart/work/codes/github/higress-group/higress-console
head -20 README.md
ls backend/ frontend/ helm/
sed -n '22,25p' backend/pom.xml          # 两个子模块
sed -n '101,158p' backend/console/pom.xml # 前端一体化打包
明天预告 · Day 02：后端启动流程——从 HigressConsoleApplication 主类看 Spring Boot 怎么 boot，组件扫描怎么覆盖两个模块，以及最关键的 SdkConfig 怎么在 @PostConstruct 里真正连上 K8s。
← 总目录 Day 02 · 后端启动 →