谷雨开源 SaaS 平台（G2rain）

# g2rain-gateway-webflux（WebFlux 网关）

g2rain-gateway-webflux 是基于 Spring Cloud Gateway Server WebFlux 的统一南北向入口：从 g2rain-infra 拉取路由定义并驻留内存，经 Nacos 与 WebClient 转发下游；集成 JWT / DPoP、静态 API Key、签名校验、主体透传、链路日志与统一异常处理；经 Redis Stream（g2rain-syncer） 增量刷新路由与缓存。

源码仓库：github.com/g2rain/g2rain-gateway-webflux (opens new window)

# 与周边服务

客户端 → g2rain-gateway（本服务，Nacos 名 g2rain-gateway）→ lb://下游微服务
              ↓ WebClient
         g2rain-infra（路由定义、国际化错误文案等）
         g2rain-basis（组织/应用侧车、API Key 解析、审计入库等）

路由元数据以 infra 为权威来源；网关不内置本地 route_definition 表。

# 核心能力

能力 说明
动态路由 MemoryRouteLoader 启动时从 infra 加载 RouteDefinitionVo，写入 MemoryRouteRepository 并发布刷新事件
路由增量同步 RouteSync 消费 g2rain-syncer（ROUTE_DEFINE）对单条路由增删改
认证 GatewayTokenAuthFilter（JWT）、GatewayDPoPAuthFilter（DPoP）
静态 API Key ApiKeyFilter 识别 Authorization: Bearer sk-...，经 basis 解析后跳过 JWT/DPoP/签名链
签名校验 SignVerificationFilter
主体与响应 PrincipalForwardFilter、ResponseAdjustFilter
链路日志 TraceLoggingFilter 结构化日志 + Micrometer Baggage/MDC
Kafka 审计日志 启用 Kafka 时，将 GatewayEvent 发往 topic gateway.exchange.event，由 basis 消费入库
国际化错误文案 ErrorMessageStorage 从 infra /i18n_message 拉取并按 Accept-Language 解析
OpenAPI OpenApiController 聚合多服务 Swagger UI（/swagger-ui-config）

# 全局过滤器顺序（偏移越小越靠前）

偏移 过滤器 职责
+100 CachedBodyFilter 缓存请求体
+200 TraceLoggingFilter 追踪日志（响应侧可发 Kafka）
+290 ApiKeyFilter OpenAI 兼容式 sk- API Key 鉴权
+300 GatewayTokenAuthFilter JWT
+400 GatewayDPoPAuthFilter DPoP
+500 ApiPermissionFilter 权限骨架（当前多为透传扩展点）
+600 SignVerificationFilter 签名
+700 PrincipalForwardFilter 身份头转发
+800 ResponseAdjustFilter 响应整形

# Kafka 网关审计（可选）

TraceLoggingFilter 在请求完成后通过 KafkaLogSender 发送 GatewayEvent JSON 到 gateway.exchange.event。

  • 默认 spring.kafka.enabled: false，未配置集群时不发送、不影响启动。
  • 启用示例：SPRING_KAFKA_ENABLED=true、SPRING_KAFKA_BOOTSTRAP_SERVERS=127.0.0.1:9092（与 g2rain-deploy Compose 中 Kafka 对齐）。
  • 消费与持久化见 g2rain-basis 的 AuditEventListener → audit_event 表。

# 静态 API Key（OpenAI 兼容模式）

  • 客户端：Authorization: Bearer sk-...（格式见网关 AuthScheme）。
  • 网关 ApiKeyCache 调用 basis LoginTokenApi 解析哈希后的令牌，映射为 EdgePrincipalContext 并置 staticTokenAuthenticated=true，后续 JWT/DPoP/签名校验跳过。
  • 令牌签发与管理在 basis personal_static_access_token，需应用开启 apiKeySupported。

# 环境要求

  • JDK 25+、Maven 3.9+
  • Nacos、Redis（Stream / 缓存同步）
  • 可发现的 g2rain-infra、g2rain-basis 实例

# 快速开始

git clone https://github.com/g2rain/g2rain-gateway-webflux.git
cd g2rain-gateway-webflux
mvn clean package -DskipTests
java -jar target/g2rain-gateway-webflux-*.jar
  • 默认 HTTP 端口：8083（SERVER_PORT）
  • Nacos 注册名：g2rain-gateway（与 artifact 名 g2rain-gateway-webflux 不同，排查时注意）

# 配置要点

项 说明
spring.kafka.enabled 默认 false；审计日志发往 Kafka 时需开启
spring.cloud.stream Redis Binder，input → g2rain-syncer
gateway-white-list 全局与各 Filter 白名单（key 为 Filter 简单类名）
spring.config.import 可选 Nacos：g2rain-gateway.yml、g2rain-token-keypair.yml

# 相关文档

← g2rain-deploy（Docker Compose 部署） →