网关服务
服务简码
HGWY
默认端口
8080
组件编码
hzero-gateway
简介
1. 概述
基于Spring Cloud Gateway的微服务网关服务
2. 组件坐标
<dependency>
<groupId>org.hzero</groupId>
<artifactId>hzero-gateway</artifactId>
<version>${hzero.service.version}</version>
</dependency>
3. 主要功能
- 用户鉴权
- 限流
- 整体运维
- 动态路由
服务配置
1. 服务配置
这里简单介绍Spring Cloud Gateway的路由配置,详细使用方式移步Spring Cloud Gateway官网2.0.2.RELEASE版本。
# 路由名,需要唯一
spring.cloud.gateway.routes[0].id=hiam
# lb://前缀表示使用ribbon负载均衡机制,路由到服务名为hzero-iam到服务上
spring.cloud.gateway.routes[0].uri=lb://hzero-iam
# 表示路由匹配路径为/iam/**
spring.cloud.gateway.routes[0].predicates[0]=Path=/iam/**
# 表示请求在路由时会去掉path前缀
spring.cloud.gateway.routes[0].filters[0]=StripPrefix=1
# 开启后,gateway会自动将服务发现列表转化为路由(如hzero-iam服务将会自动为其生成/hzero-iam/**匹配路径的路由)
spring.cloud.gateway.discovery.locator.enable=true
spring:
# 文件上传大小限制
http:
multipart:
max-file-size: 30MB
max-request-size: 30MB
cloud:
config:
# 如果设置为 true,当从配置中心获取配置势必,则服务报错无法启动,一般设置为 false 即可
fail-fast: false
# 启用配置中心
enabled: true
# 配置中心地址
uri: http://dev.hzero.org:8010
gateway:
discovery:
locator:
enabled: true
routes:
# This route rule used to forward request to activity server
- id: hiam
uri: lb://hzero-iam
predicates:
- Path=/iam/**
filters:
- StripPrefix=1
# 限流配置,使用方式查阅Spring cloud Gateway官网
# - name: RequestRateLimiter
# args:
# redis-rate-limiter.replenishRate: 1
# redis-rate-limiter.burstCapacity: 1
# rate-limiter: "#{@redisRateLimiter}"
# key-resolver: "#{@userKeyResolver}"
# key-resolver: "#{
# new org.hzero.gateway.ratelimit.CombinedKeyResolver(
# new org.hzero.gateway.ratelimit.UserKeyResolver('white-list','1,2'),
# new org.hzero.gateway.ratelimit.RoleKeyResolver('white-list','1')
# )}"
- id: hoth
uri: lb://hzero-oauth
predicates:
- Path=/oauth/**
filters:
- StripPrefix=0
- PreserveHostHeader
hzero:
gateway:
## gateway-helper 配置
filter:
collect-span:
# 是否统计API访问情况
# 开启此配置会统计每个API的调用次数,数据存储在 Redis 缓存中
enabled: false
common-request:
# 组织级API是否必须检查组织参数
# 设置为 false 则不强制检查租户级API的 organiztionId 参数
check-organization: true
# 项目级API是否必须检查项目参数
# 设置为 false 则不强制检查项目级API的 projectId 参数
check-project: true
helper:
# 是否打印 JWT
enabled-jwt-log: false
# 跳过权限校验的路由
# 对于需要跳过 gateway-helper 权限校验的路径可加到这个参数列表中
permission:
skip-paths:
- /oauth/**
- /swagger/swagger-ui.html
- /swagger/swagger-resources/**
- /swagger/webjars/**
- /swagger/docs/**
- /hwfe/**
- /hwfp/editor-app/**
- /hwfp/lib/**
- /hwfp/activiti-editor
- /*/sock-js/**
- /*/websocket/**
- /maintain
- /actuator/**
- /hexl/lib/**
## 服务整体运维配置
maintain:
# 全局运维信息
global-info:
state: NORMAL
# 服务运维信息
service-maintain-info:
oauth:
state: NORMAL
# 运维接口密钥,不配置则在程序启动时生成随机key
secret-key: hzero
2. 启动类配置
@EnableHZeroConfig是必须加上的注解,用于驱动网关服务的自动配置类,从而启用网关服务功能。
@EnableDiscoveryClient使服务作为服务发现客户端注册到注册中心,推荐使用@EnableDiscoveryClient而不是@EnableEurekaClient,@EnableDiscoveryClient更加灵活。
需要注意的是,在编写引导类时需要指定web环境为REACTIVE类型,由于Spring Cloud Gateway基于webflux包开发,其web容器是REACTIVE类型,而hzero-starter-core包中依赖了web包,如果不指定web容器将会默认走webmvc而冲突。
@EnableHZeroGateway
@EnableDiscoveryClient
public class GatewayApplication {
public static void main(String[] args) {
new SpringApplicationBuilder(GatewayApplication.class)
.web(WebApplicationType.REACTIVE)
.run(args);
}
}
GatewayHelper 鉴权
1. 鉴权过滤器
GatewayHelper 组件提供了一组过滤器来对API鉴权,具体可参考 基础服务调用链路
2. 自定义鉴权
hzero 提供了 hzero-gateway-helper-api
鉴权接口包 和 hzero-gateway-helper-default
默认实现。
如果需要对鉴权逻辑进行整体改造,可以通过实现 org.hzero.gateway.helper.api.AuthenticationHelper 接口来完全定制化鉴权的部分。
如果仅需要对现有鉴权逻辑新增逻辑,可以通过实现 org.hzero.gateway.helper.api.HelperFilter 接口来新增鉴权逻辑。
3. 权限
IAM 刷新权限,并缓存到网关所在的 Redis database 下,网关默认 redis.database=4,如果要修改此配置,确保在IAM服务中加入 hzero.service.gateway.redis-db=xx
。
整体运维
1. 功能说明
整体运维功能用于在服务运维期间提示用户某些服务不可用或全局服务运维,但前提必须保证网关服务可用。运维人员可通过调用网关的运维接口,通过传参设置运维模式和运维信息,或者关闭运维。
2. 配置样例
hzero:
maintain:
global-info:
state: NORMAL
service-maintain-info:
oauth:
state: NORMAL
secret-key: hzero
配置项介绍:
#枚举类型: NORMAL、PAUSED、STOPPED
#分别代表的含义为: 正常运行、暂停服务、停止服务(通常用于将要被废弃的服务)
hzero.maintain.global-info.state=NORMAL
#枚举类型如上
#*表示服务路由前缀,如hzero-oauth服务的路由前缀为/oauth
hzero.maintain.service-maintain-info.*.state=NORAML
# 运维接口密钥,不配置则在程序启动时生成随机key
hzero.maintain.secret-key=key
3. 运维方式
-
open api 方式
请求路径:/maintain?secretKey=&openAll=&openList=&closeList
请求样例: http://localhost:8080/maintain?secretKey=a2fe79b5-bc8c-4d0b-bb95-a9aeada2a47a&openAll=true
响应样例: 200 [空]
请求参数:
参数名 参数含义 是否必输 参数样例 secretKey 密钥 是 4cdc481f-1582-4e7b-817c-f1ecfa8e10e8 openAll 全局状态 是 true or false openList 开启NORMAL状态的路径列表 否 oauth,hpfm,hfle closeList 开启PAUSED状态的路径列表 否 oauth,hpfm,hfle -
配置文件配置
如果没有接入配置中心,直接在应用中配置并重启。
如果接入配置中心,通过配置中心配置即可,利用配置中心的机制刷新配置。
-
注意事项
- 如果没有找到 hzero.maintain.global-info.state 的配置,默认为NORMAL状态
- 如果配置了系统中不存在的路由前缀,且系统中没有使用到该路径资源,则不会对系统造成任何影响
- 如果同时配置了全局状态和特定服务的状态,此时全局状态为NORMAL,则以特定服务的状态为准;此时全局状态不为NORMAL,则以全局状态为准。
- 如果开启了全局状态PAUSED的情况,并且想要不手动修改配置文件并重启的方式来重新开放全局状态NORMAL,则可以使用open api的方式,open api所需密钥可在服务启动前配置在配置文件中,也可以使用默认随机的字符串,随机生成的密钥会在服务启动时打印到日志中(搜索secretKey)。
动态路由
由于网关从Zuul替换为Spring Cloud Gateway,动态路由组件暂无法使用,将会尽快重新支持动态路由功能。