higress-group / higress-console

higress console

Gateway Console for Higress

Higress Console 用于管理 Higress 的配置规则及其他开箱即用的能力集成，首个可用版本考虑基于 kubernetes 部署环境，预期包含服务管理、路由管理、域名管理等基础能力。 后续规划逐步迭代可观测能力、插件能力、登录管理能力，感兴趣的小伙伴一起 Hi~ gress~

前置介绍

此项目包含前端（NodeJS）、后端（Java）两个部分，前端（frontend）部分在构建完成后会随着后端代码（SpringBoot）一起部署。

配合 Higress 安装

在 Higress 安装完之后执行以下安装命令：

kubectl apply -f deploy/install.yaml

本地启动

前端项目

第一步、配置 Node 环境

注：建议Node版本选择长期稳定支持版本 16.18.1及以上

第二步、安装依赖

cd frontend && npm install

第三步、本地启动

npm start

第四步、打包

npm run build
#打包生成文件 frontend/build

后端项目

第一步、配置 Java & Maven 环境

注：建议 JDK 版本选择 17 及以上，Maven 版本选择 3.8.6 及以上（可直接使用项目内自带的 Maven Wrapper，即 mvnw）。

第二步、编译 & 镜像

cd backend && sh bulid.sh
# 脚本中涉及docker命令，本地调试可注释

第三步、部署 & 启动

sh start.sh --local

第四步、访问

主页，默认 8080 端口

http://localhost:8080

swagger，访问 swagger 页面了解 API 情况。

http://localhost:8080/swagger-ui/index.html

higress-console's Issues

路由`基础策略`配置的前端绘制

入口：

预期效果：

卡片方式呈现

表单参考（具体字段会有出入，待#58 明确）：

重写：

Header设置：

跨域：

重试：

Wasm 插件配置前端页面设计与实现

Why do you need it?

参见 #101。

How could it be?

实现效果可参见 #57 中的卡片样式。每个插件为一个卡片。内部配置界面基于后端 API 读取到的插件信息进行绘制。

提升 KubernetesModelConverter 的单测覆盖率

KubernetesModelConverter 是负责将数据在业务模型与 K8s CRD 之间进行转换的核心模块。单元测试需要尽可能的覆盖其各个功能分支。

实现域名管理到configmap/secret的模型映射，以及增删改查 API

统一在 higress-system 命名空间下

apiVersion: v1
kind: ConfigMap
metadata:
  name: domain-wildcard.abc.com
  namespace: default
data:
  domain: "*.abc.com"
  cert: my-secret
  enableHttps: force

名称为domain-开头，后面跟域名，如果出现 * 字符，替换为 wildcard

域名管理功能支持 TLS 配置

How could it be?

• 支持选择 Sercet 关联至 Ingress
• 支持配置强制 HTTPS：使用 Annotation higress.io/ssl-redirect: "true"

证书管理增强

Why do you need it?

目标是降低用户在管理 HTTPS 证书方面的工作量和复杂度。

How could it be?

对接 cert-manager，实现证书自动签发、自动续期等功能。域名管理中可以选择使用自助管理的证书，还是关联 cert-manager 由系统自动维护相关证书。

Other related information

子任务列表：

• #109
• #110
• #111
• #112

实现服务来源API配置到McpBridge模型转换，实现增删改查API

实现Nacos、Zookeeper等服务来源获取服务列表

路由`基础策略`中的Header设置策略实现

根据 #58 定义的API实现到 Ingress annotation 的对应转换

引擎侧相关issue：alibaba/higress#165

请求Header控制

注解	说明
higress.io/request-header-control-add	请求在转发给后端服务时，添加指定Header。若该Header存在，则其值拼接在原有值后面。语法如下：单个Header：Key Value。多个Header：使用YAML特殊符号|，每对Key Value单独处于一行。
higress.io/request-header-control-update	请求在转发给后端服务时，修改指定Header。若该Header存在，则其值覆盖原有值。语法如下：单个Header：Key Value。多个Header：使用YMAL特殊符号|，每对Key Value单独处于一行。
higress.io/request-header-control-remove	请求在转发给后端服务时，删除指定Header。语法如下：单个Header：Key。多个Header：使用英文逗号分隔。

响应Header控制

注解	说明
higress.io/response-header-control-add	请求在收到后端服务响应之后并且转发响应给客户端之前，添加指定Header。若该Header存在，则其值拼接在原有值后面。语法如下：单个Header：Key Value。多个Header：使用YAML特殊符号|，每对Key Value单独处于一行。
higress.io/response-header-control-update	请求在收到后端服务响应之后并且转发响应给客户端之前，修改指定Header。若该Header存在，则其值覆盖原有值。语法如下：单个Header：Key Value。多个Header：使用YMAL特殊符号|，每对Key Value单独处于一行。
higress.io/response-header-control-remove	请求在收到后端服务响应之后并且转发响应给客户端之前，删除指定Header。语法如下：单个Header：Key。多个Header：使用英文逗号分隔。

登录页面增加语言选择功能

由于登录页面与内部页面没有共用同一个模版，用户首次打开控制台时，页面会直接跳到登录页面。用户无法选择语言。

完善后端项目代码格式检查

可以参考 seata 的配置
seata config: https://github.com/seata/seata/blob/0112719ad0e8c4225a9f59a8598f83cda296a760/pom.xml#L268
seata checkstyle.xml: https://github.com/seata/seata/blob/2.x/style/seata_checkstyle.xml
seata suppressions.xml: https://github.com/seata/seata/blob/2.x/style/seata_suppressions.xml

完成域名管理页面绘制

API：https://higress.yuque.com/qnr8w5/wlbt7k/igwto2#SPKqK

实现路由API配置到Ingress简单模型的转换配置，实现增删改查API

ingress 简单模型对应的api字段：

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: tls-example-ingress
spec:
  tls:
  - hosts:
      - https-example.foo.com
    secretName: testsecret-tls
  rules:
  - host: https-example.foo.com
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: service1
            port:
              number: 80

namespace 默认限定 higress-system

• 路由名称->ingress name
• 域名-> tls 中的 hosts 字段以及 rules 中的host 字段
• 路径-> path 和 pathType，注意正则需要搭配 annotation
• 目标服务->backend，注意nacos来源需要搭配annotation

路由管理模块前后端实现对齐 Higress Admin API 设计文档

https://higress.yuque.com/qnr8w5/wlbt7k/igwto2

路由`基础策略`中的重写策略实现

根据 #58 定义的API实现到 Ingress annotation 的对应转换

注解	说明
higress.io/rewrite-target	重写Path，支持捕获组（Capture Group)。
higress.io/upstream-vhost	重写Host。

控制台顶部菜单和Higress官网一致

支持从控制台跳转到官网首页、文档、Github项目地址等链接

路由管理功能支持Method、 Header、Query 等路由条件，实现路径匹配不区分大小写

相关引擎侧 issue：

• alibaba/higress#161
• alibaba/higress#163

前端和后端工程合并，支持一体化打包运行

• 将前端build产物放进后端resource目录
• 调整后端路由和api路径配置

实现Helm制品自动发布

Why do you need it?

免去人工操作，版本发布后可以自动发布Helm制品

How could it be?

当前Helm包放在 OSS 上管理，可以通过github action 上传到OSS。

路由`基础策略`配置的API完善

需求概要

Admin API：https://higress.yuque.com/qnr8w5/wlbt7k/igwto2#IBobg
目前已有四个基础策略对应的路由配置字段：

需要根据对应的 ingress annotation 能力进一步细化 api 字段，提供给这个前端issue用于设计表单格式：#57

实现 Patch API 的机制

annotation 参考

重写

注解	说明
higress.io/rewrite-target	重写Path，支持捕获组（Capture Group)。
higress.io/upstream-vhost	重写Host。

Header 设置

引擎侧相关issue：alibaba/higress#165

请求Header控制

注解	说明
higress.io/request-header-control-add	请求在转发给后端服务时，添加指定Header。若该Header存在，则其值拼接在原有值后面。语法如下：单个Header：Key Value。多个Header：使用YAML特殊符号|，每对Key Value单独处于一行。
higress.io/request-header-control-update	请求在转发给后端服务时，修改指定Header。若该Header存在，则其值覆盖原有值。语法如下：单个Header：Key Value。多个Header：使用YMAL特殊符号|，每对Key Value单独处于一行。
higress.io/request-header-control-remove	请求在转发给后端服务时，删除指定Header。语法如下：单个Header：Key。多个Header：使用英文逗号分隔。

响应Header控制

注解	说明
higress.io/response-header-control-add	请求在收到后端服务响应之后并且转发响应给客户端之前，添加指定Header。若该Header存在，则其值拼接在原有值后面。语法如下：单个Header：Key Value。多个Header：使用YAML特殊符号|，每对Key Value单独处于一行。
higress.io/response-header-control-update	请求在收到后端服务响应之后并且转发响应给客户端之前，修改指定Header。若该Header存在，则其值覆盖原有值。语法如下：单个Header：Key Value。多个Header：使用YMAL特殊符号|，每对Key Value单独处于一行。
higress.io/response-header-control-remove	请求在收到后端服务响应之后并且转发响应给客户端之前，删除指定Header。语法如下：单个Header：Key。多个Header：使用英文逗号分隔。

跨域

注解	说明
higress.io/enable-cors	开启或关闭跨域。
higress.io/cors-allow-origin	允许的第三方站点，第三方站点之间使用英文逗号分隔，支持通配符*。默认值为*，即允许所有第三方站点。
higress.io/cors-allow-methods	允许的请求方法，如GET、POST、PUT等，请求方法之间使用英文逗号分隔，支持通配符*。默认值为GET、PUT、POST、DELETE、PATCH、OPTIONS。
higress.io/cors-allow-headers	允许的请求Header，Header之间使用英文逗号分隔，支持通配符*。默认值为DNT、X-CustomHeader、Keep-Alive、User-Agent、X-Requested-With、If-Modified-Since、Cache-Control、Content-Type、Authorization。
higress.io/cors-expose-headers	允许暴露给浏览器的响应Header，响应Header之间使用英文逗号分隔。
higress.io/cors-allow-credentials	是否允许携带凭证信息。默认允许。
higress.io/cors-max-age	预检结果的最大缓存时间，单位为秒。默认值为1728000秒。

重试

注解	说明
higress.io/proxy-next-upstream-tries	请求的最大重试次数。默认为3次。
higress.io/proxy-next-upstream-timeout	请求重试的超时时间，单位秒。默认未配置超时时间。
higress.io/proxy-next-upstream	请求重试条件，使用英文逗号作为分隔。默认值为error,timeout，合法值如下：error：建立连接失败。timeout：建立连接超时。http_xxx：针对具体响应状态码的情况进行重试。例如：http_502、http_403。non_idempotent：对于非幂等请求出错时进行重试。默认情况下，MSE Ingress针对非幂等POST、PATCH请求出错时不会进行重试；如果配置non_idempotent，可以开启重试。off：关闭重试。

页面集成 prometheus grafana 大盘

增加后端单测框架

Why do you need it?

可以由测试用例驱动开发，免去本地安装higress，降低前后端联调成本

How could it be?

mock apiserver 接口的返回，配置 expect 的资源结构，和生成的资源做比对

Other related information

请求协议转换支持：HTTP → Dubbo

Why do you need it?

Higress 已经支持将 HTTP 请求转换为 Dubbo 请求转发给后端的 Dubbo 服务。故 Higress Console 需要支持配置此类路由。

How could it be?

Higress 中的 Dubbo 协议转换功能参见文档：https://higress.io/zh-cn/docs/user/dubbo.html

这里需要支持用户配置路由目标和转换规则。

Other related information

子任务列表：

• #106
• #107

完善前端项目的样式检查

在根目录帮忙放一个LICENSE文件吧。

控制台前端首页自动重定向到路由配置页面

支持对接 Wasm 插件配置

Why do you need it?

目前 Higress 通过官方仓库已经对外提供了多个内置插件（插件列表），所以 Higress Console 需要支持为路由关联这些 Wasm 插件并配置相关参数。

How could it be?

用户可以在三个层次上配置 Wasm 插件：全局、域名和路由。同时考虑到未来会增加更多插件，也支持对接用户自己开发的插件，所以插件也需要单独的管理模块。插件使用 OCI 镜像的方式进行交付。所有元数据信息均保存在镜像当中。前端界面也需要拉取当前的支持的插件列表并动态生成相关的配置界面。

Other related information

子任务列表：

• #102
• #103
• #104

后端 API 完善请求数据校验机制完善

根据API 设计文档和各个字段的数据格式，完善后端 API 中的请求数据校验机制，在数据格式不合法时抛出 ValidationException。

基本校验

• 空值校验（null 值、空字符串、空列表等）
• 可选值校验
• 数值范围校验

ServiceSource 模型校验

• domain 格式
• zkServicesPath 元素格式

TlsCertificate 模型校验

• cert 格式
• key 格式
• cert 与 key 匹配性

Domain 模型校验

• tlsCertificate 取值有效性

Route 模型校验

• 路径前缀匹配时的 path 格式

支持上传TLS cert和key，自动生成Secret

在 #53 基础上更进一步，支持用户在界面直接上传cert和key

API：https://higress.yuque.com/qnr8w5/wlbt7k/igwto2#dJVG9

支持强制重置部署环境内的Grafana看板配置

当安装包内的Grafana看板有更新，或者实际运行环境中的看板出现错乱时，需要支持强制重置看板配置的功能。

HTTP → Dubbo 前端页面设计与实现

详情参见 #105

证书管理支持查看 cert-manager 生成的证书信息

Why do you need it?

参见 #108

How could it be?

证书管理页面需要支持查看 cert-manager 生成的证书信息，但禁止用户进行编辑和删除操作。

模型更新使用版本号作为乐观锁

为了避免并发更新导致的变更相互覆盖，后端 API 在返回数据给前端是需要同时提供版本号信息（即 ResourceVersion）。前端在提交更新请求时也需要附带版本号信息（创建请求不需要）。如果后端检测到存储中的资源版本号与前端提交的版本号不符，应返回 409 Conflict。前端页面应提示用户刷新页面重新编辑。

增加 CONTRIBUTING.md

介绍前后端工程目录，和开发指引，可以针对配置路由生效的场景举个例子

优化前端构建流程，解决静态资源缓存问题

目前每次重新发布后，都会出现由于静态资源被缓存而导致的界面功能异常问题。被缓存的资源有两部分：

1. 构建生成的静态资源
2. 国际化资源、图片等原始静态资源

故希望能够通过优化前端构建流程的方法，解决静态资源缓存问题。

HTTP → Dubbo 后端路由配置数据结构、API 设计与实现

详情参见 #105

【UI】前端问题总结

1. copyRight 参考higress官网 https://higress.io/zh-cn/
   

2. 登录相关的ICE的可以干掉
   

3. 服务列表中，多个服务地址，以逗号进行分隔
   

4. 服务列表，增加刷选框（前端刷选）

• 按照命名空间刷选（下拉）
• 按照服务名刷选（关键字搜索）
  

服务来源管理页面对接后端 API 并完成联调

服务来源 API 已经实现完成。但由于请求响应模型均有一定调整，前端页面需要重新进行对接并完成联调。

实现基于helm chart部署，并支持在安装higress时根据参数配置自动安装

API 返回服务列表时过滤 K8s 内部命名空间

Why do you need it?

通过 Ingress 把K8s 内部命名空间（如：kube-system）内的服务暴露出去会有安全风险，所以应该对这部分数据进行过滤。

How could it be?

在返回数据时进行过滤。

Other related information

N/A

配置github workflow，提交PR自动构建

Helm Chart 支持部署 cert-manager

Why do you need it?

参见 #108

How could it be?

支持随 Higress Console 一同部署 cert-manager。

路由`基础策略`中的跨域策略实现

根据 #58 定义的API实现到 Ingress annotation 的对应转换

注解	说明
higress.io/enable-cors	开启或关闭跨域。
higress.io/cors-allow-origin	允许的第三方站点，第三方站点之间使用英文逗号分隔，支持通配符*。默认值为*，即允许所有第三方站点。
higress.io/cors-allow-methods	允许的请求方法，如GET、POST、PUT等，请求方法之间使用英文逗号分隔，支持通配符*。默认值为GET、PUT、POST、DELETE、PATCH、OPTIONS。
higress.io/cors-allow-headers	允许的请求Header，Header之间使用英文逗号分隔，支持通配符*。默认值为DNT、X-CustomHeader、Keep-Alive、User-Agent、X-Requested-With、If-Modified-Since、Cache-Control、Content-Type、Authorization。
higress.io/cors-expose-headers	允许暴露给浏览器的响应Header，响应Header之间使用英文逗号分隔。
higress.io/cors-allow-credentials	是否允许携带凭证信息。默认允许。
higress.io/cors-max-age	预检结果的最大缓存时间，单位为秒。默认值为1728000秒。

前端i18n配置

域名管理支持启用证书系统自维护的功能

参见 #108

路由管理功能兼容 networking.k8s.io/v1beta1

1. 通过 K8s API 判断目标集群所支持的 Ingress resource 版本
2. v1beta1 下只支持为 K8s Service 配置路由，不支持其他服务来源
3. v1beta1 下前端界面不允许创建服务来源，需提示用户当前 K8s 版本不支持

Wasm 插件配置后端 API 设计与实现

Why do you need it?

参见 #101。

How could it be?

支持全局、域名和路由三个层次的插件配置。用户可以在这三个层次上启用某个插件并配置其参数，也可以选则禁用某个插件。

后端 API 对接 cert-manager 支持证书自动签发、自动续期功能

参见 #108

此外，证书管理相关接口也需要能够返回由 cert-manager 维护的证书数据，并在数据模型中区分出哪些是用户管理的，哪些是系统内部维护的。

路由`基础策略`中的重试策略实现

根据 #58 定义的API实现到 Ingress annotation 的对应转换

注解	说明
higress.io/proxy-next-upstream-tries	请求的最大重试次数。默认为3次。
higress.io/proxy-next-upstream-timeout	请求重试的超时时间，单位秒。默认未配置超时时间。
higress.io/proxy-next-upstream	请求重试条件，使用英文逗号作为分隔。默认值为error,timeout，合法值如下：error：建立连接失败，请求出错5xx。timeout：建立连接超时，请求出错5xx。invalid_header：请求出错5xx。http_xxx：针对具体响应状态码的情况进行重试。例如：http_502、http_403。non_idempotent：对于非幂等请求出错时进行重试。默认情况下，MSE Ingress针对非幂等POST、PATCH请求出错时不会进行重试；如果配置non_idempotent，可以开启重试。off：关闭重试。

admin登陆认证功能

目前没有登陆认证功能，需要自动生成随机密码，基于secret配置编辑

Wasm 插件数据模型与管理 API 设计与实现

Why do you need it?

参见 #101。

How could it be?

通过 OCI 镜像地址配置一系列系统支持的 Wasm 插件。通过解析镜像内容获取插件元数据信息（如名称、版本号、功能介绍、参数列表等），通过 API 返回给前端界面，以便在前端生成配置界面。

此处需要思考如何管理各个插件的版本号信息。

Other related information

#101 支持对接 Wasm 插件配置

完成服务来源页面绘制