网关安全

大约 7 分钟约 2226 字

功能描述

blade-gateway-spring-boot-starter 是基于 SpringBoot 的网关启动器，提供了对认证、安全、监控、流量等通用接口控制支持。

GAV 坐标

maven

<dependency>
  <groupId>team.aikero.blade</groupId>
  <artifactId>blade-gateway-spring-boot-starter</artifactId>
</dependency>

gradle

implementation(commonLibs.blade.gateway.spring.boot.starter)

详细说明

安全功能

提供对接口的安全控制能力

展开详情

blade:
  gateway:
    security:
      # 跨域安全
      cors:
        # 路径模式，Ant 风格
        pattern:
          - /gateway/**
        # 允许跨域访问的 Origin，格式为 scheme://host:port，示例如 https://somedomain.com:8081。如果你有多个 Origin，请使用 , 分隔。当 allow_credential 为 false 时，可以使用 * 来表示允许所有 Origin 通过。
        allowedOrigin: "*"
        # 允许跨域访问时请求方携带哪些非 CORS 规范 以外的 Header。如果你有多个 Header，请使用 , 分割。当 allow_credential 为 false 时，可以使用 * 来表示允许所有 Header 通过。
        allowedHeaders: "*"
        # 允许跨域访问的 Method，比如：GET，POST 等。如果你有多个 Method，请使用 , 分割。当 allow_credential 为 false 时，可以使用 * 来表示允许所有 Method 通过。
        allowedMethod: "*"
        # 允许跨域访问时响应方携带哪些非 CORS 规范 以外的 Header。如果你有多个 Header，请使用 , 分割。当 allow_credential 为 false 时，可以使用 * 来表示允许任意 Header。如果不设置，插件不会修改 Access-Control-Expose-Headers 头，详情请参考 Access-Control-Expose-Headers - MDN。
        exposedHeaders: "*"
        # 是否允许跨域访问的请求方携带凭据（如 Cookie 等）
        allowCredentials: true
      # 路径安全控制
      uri:
        # 黑名单，Ant 风格
        blacklist:
          - /block/api
      # IP 安全控制
      ip:
          # 路径匹配模式，Ant 风格
        - pattern:
            - /basic/**
            - /jwt/**
            - /key/**
          # 白名单，模糊匹配
          whitelist:
            - 192.168.*.*
            - 127.0.0.1
          # 黑名单，模糊匹配
          blacklist:
            - 172.*.*.*
      # User-Agent 安全控制
      ua:
        # 路径匹配模式，Ant 风格
        - pattern:
            - /basic/**
            - /jwt/**
            - /key/**
          # 白名单，正则匹配
          whitelist:
            - .*
          # 黑名单，正则匹配
          blacklist:
            - .*examples.com
      # 来源安全控制
      referer:
          # 路径匹配模式，Ant 风格
        - pattern:
            - /basic/**
            - /jwt/**
            - /key/**
          # 白名单，正则匹配
          whitelist:
            - .*
          # 黑名单，正则匹配
          blacklist:
            - "https://examples.com"
      # 请求头安全控制
      header:
          # 路径匹配模式，Ant 风格
        - name: "X-Any-Header"
          pattern:
            - /basic/**
            - /jwt/**
            - /key/**
          # 白名单，正则匹配
          whitelist:
            - .*
          # 黑名单，正则匹配
          blacklist:
            - "AnyValue"

示例

安全拦截示例

{"successful":false,"code":403,"message":"Not allowed","data":null}

认证功能

提供 HTTP Basic、JWT、密钥等接口认证功能

展开详情

blade:
  gateway:
    # 认证管理
    authentication:
      # HTTP 基础认证
      basic:
          # 路径模式，Ant 风格
        - pattern:
            - /basic/**
          # 排除路径
          exclude:
            - /basic/api
          # 用户名
          username: examples
          # 密码
          password: examples
      # JWT 认证    
      jwt:
          # 路径模式，Ant 风格
        - pattern:
            - /jwt/**
          # 排除路径
          exclude:
            - /jwt/api
          # jwt 请求头
          header: X-Authorization
          # jwt 前缀
          prefix: ""
          # jwt 密钥
          secretKey: examples
          # jwt 密钥算法
          algorithm: HS256
          # jwt 是否进行验签
          verify: true
          # jwt 请求头缺失时，是否匹配
          match-on-missing: false
      # 密钥认证
      secret-key:
          # 路径模式，Ant 风格
        - pattern:
            - /key/**
          exclude:
            - /key/api
          # 密钥请求头（支持从 query param 读取）
          header: sk
          # 密钥
          key: examples

拦截示例

基础认证拦截示例

jwt 认证拦截示例

{"successful":false,"code":401,"message":"Invalid token.","data":null}

密钥认证拦截示例

{"successful":false,"code":401,"message":"Invalid secret.","data":null}

代码扩展示例

jwt 认证模式下，支持根据 jwt.name 属性匹配处理器，解析 jwt 信息进行请求加工处理，默认支持 ciam、uacs 两种 token 解析默认处理。实现接口后可通过 Bean 注入，框架自动拾取。

ciam: 解析 ssoToken 提取用户信息，修改请求头并向下游传递
uacs: 解析 uacs token 提取用户信息，修改请求头并向下游传递

interface JwtAuthenticationFilter.JwtAuthPostProcessor {

        /**
         * 是否支持某 JWT 配置，以进行后置处理
         */
        fun support(jwt: GatewayProperties.Authentication.Jwt): Boolean
        
        /**
         * Token 解析处理
         */
        fun apply(exchange: ServerWebExchange, token: String): ServerWebExchange {
        
        }
}

日志功能

提供详细的 API 访问日志，包括请求头、响应头、请求体、响应体等信息。异常请求自动打印请求明细。

blade:
  gateway:
    # 日志功能
    logger:
      access:
        # 路径模式，Ant 风格
        - pattern:
            - /**
          # 日志等级 BASIC：显示基本信息 HEADER：显示详细请求头 BODY：显示请求体
          level: basic
      # 日志汇总记录
      reporter:
        # 是否开启汇总记录
        enabled: true
        host: ${domain.nest-api}
        uri: 
        # 上报批次
        batchSize: 100
    # 通用配置
    config:
      # 路径归一化规则
      normalize-rule:
          # Id
        - pattern: "/\\d{2,}"
          replacement: "/{id}"
          # 中段数值
        - pattern: "/\\d+/"
          replacement: "/{num}/"
          # 流水号
        - pattern: "/\\w+\\d{2,}"
          replacement: "/{serialNum}"
          # 中文
        - pattern: "/[\u4e00-\u9fa5]+"
          replacement: "/{word}"
          # 域名配置
        - pattern: "/domain/conf/([a-z-]+)"
          replacement: "/domain/conf/{env}"

日志示例

basic

> GET /gateway/basic/api
> :remote-address: 127.0.0.1
< 32ms 200 OK

header

> POST /gateway/basic/api
> :remote-address: 10.100.0.200
> Host: dev-ola-api.tiangong.tech
> X-Request-ID: fc2e42c381f19db4f64ac9dd65987a69
> X-Real-IP: 10.100.0.200
> X-Forwarded-For: 10.100.0.200
> X-Forwarded-Host: dev-ola-api.tiangong.tech
> X-Forwarded-Port: 443
> X-Forwarded-Proto: https
> X-Forwarded-Scheme: https
> X-Scheme: https
> content-type: application/json;charset:utf-8
> accept-encoding: gzip
> user-agent: okhttp/4.9.3
> Content-Length: 0
> Transfer-Encoding: chunked
< 14ms 200 OK
< Vary: Origin
< Content-Type: application/json
< Date: Tue, 31 Dec 2024 11:30:00 GMT
< Content-Length: 67
< Access-Control-Expose-Headers: transfer-encoding, Vary, Content-Type, Date, Content-Length
< TraceId: 00baf1afc34f9c8855ce4ecf5e33f9fa
< SpanId: 4bd3f0c11406f35e

body

> POST /gateway/basic/api
> :remote-address: 10.100.0.200
> Host: dev-ola-api.tiangong.tech
> X-Request-ID: fc2e42c381f19db4f64ac9dd65987a69
> X-Real-IP: 10.100.0.200
> X-Forwarded-For: 10.100.0.200
> X-Forwarded-Host: dev-ola-api.tiangong.tech
> X-Forwarded-Port: 443
> X-Forwarded-Proto: https
> X-Forwarded-Scheme: https
> X-Scheme: https
> content-type: application/json;charset:utf-8
> accept-encoding: gzip
> user-agent: okhttp/4.9.3
> Content-Length: 0
> Transfer-Encoding: chunked

No Content

< 14ms 200 OK
< Vary: Origin
< Content-Type: application/json
< Date: Tue, 31 Dec 2024 11:30:00 GMT
< Content-Length: 67
< Access-Control-Expose-Headers: transfer-encoding, Vary, Content-Type, Date, Content-Length
< TraceId: 00baf1afc34f9c8855ce4ecf5e33f9fa
< SpanId: 4bd3f0c11406f35e

No Content

Openapi 功能

开放网关支持，允许加载外部动态路由、自定义支持方法、自定义验证逻辑、自定义请求修改能力。

blade:
  gateway:
    # 开放网关
    openapi:
      # 是否启用
      enabled: true

openapi 代码扩展示例

openapi 功能可通过 OpenapiCustomizer 接口扩展开放网关能力。实现接口后可通过 Bean 注入，框架自动拾取。

/**
 * Openapi 自定义器
 *
 * @author sivan
 */
fun interface OpenapiCustomizer {
    /**
     * 路由列表
     */
    suspend fun routers(): List<Router>

    /**
     * 是否支持给定路由
     */
    suspend fun support(exchange: ServerWebExchange): Boolean {
        val match = UriUtil.match(
            uri = exchange.request.uri.rawPath,
            patterns = routers().filter { it.enabled }.map { it.pattern }.toTypedArray()
        )
        return match
    }

    /**
     * 执行签名解析
     *
     * @return 解析成功返回 exchange
     * @throws SignatureException 解析错误抛出异常
     */
    @Throws(SignatureException::class)
    suspend fun verify(exchange: ServerWebExchange): Boolean {
        return true
    }

    /**
     * 交换机处理器
     *
     * 用于 openapi 请求自定义处理, 修改请求头等
     *
     * @return 修改后的 exchange
     */
    suspend fun exchangeProcessor(exchange: ServerWebExchange): ServerWebExchange {
        return exchange
    }
}

流量功能

提供接口流量监控、限流、控制能力

版本路由
支持四种策略：无版本服务匹配、精确匹配、语义化版本 - 范围匹配、服务回滚
[-] 接口限流
[-] 流量监控

blade:
  gateway:
    # 流量
    traffic:
      # 版本路由
      version:
        # 版本请求头（支持从 query param 读取）
        header: version
        # 服务版本缺失时，是否匹配
        matchOnMiss: false
        # 匹配失败时，是否回滚
        fallback: true

流量示例

版本路由
当服务端指定 metadata.version: 1.0.0 时，客户端在请求时传递 version: 1.0.0，网关将通过版本号进行服务过滤。

服务端：

spring:
  application:
    name: blade-examples
  cloud:
    nacos:
      discovery:
        metadata:
          version: 1.0.0

客户端：

> GET /gateway/basic/api
> version: 1.0.0

动态路由

提供动态加载和刷新路由的能力。

blade:
  gateway:
    # 路由配置
    router:
      # 是否启用动态路由
      enabled: true
      # http 路由配置
      http:
        host: http://localhost
        uri: /router/list
        expire: 30
        auto-refresh: false

当前仅支持 HTTP 协议，加载路由配置。

json 格式路由与 yaml 基本相同，差异化重点在于 predicates 和 filters 的配置。

yaml 对于 = 左右两侧的数据在构造存在特殊处理，序列化后的结果与 json 一致；
json 直接查看时，会发现存在部分 _genkey_ 占位符，属于 Spring Cloud 默认的处理，无任何实际用途。

以 predicates 为例，filters 同理:

yaml

spring:
  cloud:
    gateway:
      routes:
      - id: header_route
        uri: https://example.org
        predicates:
        - Header=X-Request-Id, \d+
        - Path=/example/**

json

{
    "id": "header_route",
    "uri": "https://example.org",
    "predicates": [
        {
            "name": "Header",
            "args": {
                "_genkey_0": "X-Request-Id"
                "_genkey_1": "\d+"
            }
        },
        {
            "name": "Path",
            "args": {
                "_genkey_0": "/example/**"
            }
        }
    ]
}

完整 HTTP 报文如下：

展开详情

{
    "successful": true,
    "code": 200,
    "message": "操作成功",
    "data": [
        {
            "id": "uuid-1",
            "uri": "lb://example-service",
            "order": "0",
            "predicates": [
                {
                    "name": "Path",
                    "args": {
                        "_genkey_0": "/bin"
                    }
                }
            ],
            "filters": [
                {
                    "name": "AddRequestHeader",
                    "args": {
                        "_genkey_0": "Cookie",
                        "_genkey_1": "tasty"
                    }
                }
            ],
            "metadata": {
                "weight": "10"
            }
        },
        {
            "id": "uuid-2",
            "uri": "http://example.com",
            "order": "1",
            "predicates": [
                {
                    "name": "Path",
                    "args": {
                        "_genkey_0": "/example/**"
                    }
                }
            ],
            "filters": [
                {
                    "name": "AddRequestHeader",
                    "args": {
                        "_genkey_0": "Cookie",
                        "_genkey_1": "tasty"
                    }
                }
            ],
            "metadata": {
                "weight": "10"
            }
        }
    ]
}

缓存功能

提供全局的缓存能力，支持缓存接口响应。

blade:
  gateway:
    cache:
      enabled: true
      api:
        pattern:
          # 域名配置接口缓存
          - /sys-admin/domain/conf/{env:([a-z-]+)}

主要功能如下：

实时根据接口的成功调用结果，更新最新缓存（redis 长期缓存，保证多节点缓存一致性）
缓存条件 GET 请求、Status：200、Content-Type：application/json、text/*
异常时，输出缓存结果，上报钉钉消息，通知路由所在的项目负责人，回显错误原因及响应值