网关服务配置

**本文引用的文件** - [bootstrap.yml](file://lemes-cloud/lemes-gateway/src/main/resources/bootstrap.yml) - [LemesGatewayConfiguration.java](file://lemes-cloud/lemes-gateway/src/main/java/com/lenovo/lemes/gateway/config/LemesGatewayConfiguration.java) - [LemesGlobalFilter.java](file://lemes-cloud/lemes-gateway/src/main/java/com/lenovo/lemes/gateway/filter/LemesGlobalFilter.java) - [LemesRequestLimitFilter.java](file://lemes-cloud/lemes-gateway/src/main/java/com/lenovo/lemes/gateway/filter/requestLimit/LemesRequestLimitFilter.java) - [LemesGatewayProperties.java](file://lemes-cloud/lemes-gateway/src/main/java/com/lenovo/lemes/gateway/config/LemesGatewayProperties.java) - [requestLimit.lua](file://lemes-cloud/lemes-gateway/src/main/resources/lua/requestLimit.lua) - [gateway.yaml](file://lemes-cloud/src/devops/k8s/service/base/gateway.yaml) - [gateway-dcc-npi-https.yaml](file://lemes-cloud/src/devops/k8s/service/base/gateway-dcc-npi-https.yaml) - [gateway-igreen-https.yaml](file://lemes-cloud/src/devops/k8s/service/base/gateway-igreen-https.yaml)

目录

1. 简介
2. 项目结构
3. 核心组件
4. 架构总览
5. 详细组件分析
6. 依赖关系分析
7. 性能考虑
8. 故障排查指南
9. 结论
10. 附录

简介

本文件面向开发与运维团队，提供DeviceMate项目的Spring Cloud Gateway网关部署与配置指导。内容涵盖路由规则、负载均衡、熔断降级、请求限流（滑动窗口）、安全配置（JWT校验、CORS、HTTPS、访问控制）、监控与日志、以及路由转发（服务发现、动态路由、请求头处理、响应转换）等主题，并结合Kubernetes部署清单说明实际运行环境。

项目结构

• 网关工程位于 lemes-cloud/lemes-gateway，核心配置集中在 resources/bootstrap.yml，运行时通过Nacos进行配置中心与服务注册发现。
• Java侧通过自定义全局过滤器实现统一鉴权、限流、请求头透传与日志统计。
• Kubernetes部署清单位于 lemes-cloud/src/devops/k8s/service/base，包含Deployment、Service与Ingress（HTTPS/TLS）配置。

图表来源

• bootstrap.yml:1-101
• LemesGatewayConfiguration.java:1-34
• LemesGlobalFilter.java:1-288
• LemesRequestLimitFilter.java:1-91
• LemesGatewayProperties.java:1-20
• requestLimit.lua:1-29
• gateway.yaml:1-166
• gateway-dcc-npi-https.yaml:1-64
• gateway-igreen-https.yaml:1-46

章节来源

• bootstrap.yml:1-101
• gateway.yaml:1-166

核心组件

• 应用与服务发现
  • 通过Nacos进行服务注册与配置拉取，应用名为网关自身，支持按命名空间、组别隔离。
  • 网关端口与优雅停机配置在bootstrap.yml中定义。
• 全局过滤器
  • 统一鉴权（支持Header与Query中的Bearer Token或API Token），忽略URL白名单匹配，透传traceId、终端标识、XFF等头部。
  • 集成限流过滤器，基于Redis Lua脚本实现滑动窗口限流。
  • 统一日志输出，包含响应状态、耗时、用户ID、来源IP等。
• 负载均衡与WebClient
  • 通过注解启用负载均衡，使用WebClient发起下游服务请求，便于后续扩展熔断与重试。
• 限流机制
  • 支持全局、按用户、按IP三种维度的滑动窗口限流；规则可热更新。
• Kubernetes部署
  • Deployment副本数、亲和性、探针、环境变量、Sidecar与持久化日志目录。
  • Ingress配置TLS与路径转发，支持多域名与路径前缀。

章节来源

• bootstrap.yml:13-101
• LemesGatewayConfiguration.java:9-34
• LemesGlobalFilter.java:42-194
• LemesRequestLimitFilter.java:18-91
• LemesGatewayProperties.java:10-20
• gateway.yaml:1-166

架构总览

下图展示请求在网关侧的关键流转：鉴权与限流前置过滤、忽略URL放行、下游服务调用、响应回写与日志统计。

图表来源

• LemesGlobalFilter.java:61-194
• LemesRequestLimitFilter.java:27-89

详细组件分析

路由规则与动态路由

• 动态路由与规则定义
  • 网关未在仓库中显式声明Spring Cloud Gateway路由配置文件，但通过全局过滤器实现统一鉴权与限流，路由转发逻辑依赖服务名与负载均衡。
  • 若需新增路由规则，请在网关配置中心或本地配置文件中补充Route定义（例如application.yml），并确保服务名与Nacos注册一致。
• 忽略URL白名单
  • 白名单用于跳过鉴权与限流，覆盖登录、公钥获取、OAuth、静态资源等路径。
• 服务发现与负载均衡
  • 通过Nacos注册中心自动发现下游服务实例，WebClient默认具备轮询LB能力。

章节来源

• bootstrap.yml:37-56
• LemesGatewayConfiguration.java:11-15

负载均衡策略

• WebClient启用负载均衡，使用服务名调用下游服务，避免硬编码IP。
• Netty解码器最大初始行长度已调整以适配大请求场景。

章节来源

• LemesGatewayConfiguration.java:11-32

熔断降级机制

• 当前未引入Spring Cloud Circuit Breaker或Resilience4j相关配置。
• 建议在下游服务调用处增加熔断与降级策略，结合WebClient与容错库实现。

（本节为通用建议，不直接分析具体文件）

请求限流配置

• 限流类型与规则
  • 支持全局、按用户、按IP三种维度；规则可热更新。
  • 规则包含时间窗口、最大请求数、目标URL（可选）。
• 实现原理
  • 基于Redis Sorted Set实现滑动窗口计数，Lua脚本原子性执行。
  • 每条规则生成唯一Key，包含前缀、类型、URL与标识。
• 配置入口
  • 在bootstrap.yml中启用并配置规则（当前示例为注释状态，可按需启用）。

图表来源

• LemesRequestLimitFilter.java:27-89
• requestLimit.lua:1-29

章节来源

• bootstrap.yml:57-80
• LemesRequestLimitFilter.java:18-91
• requestLimit.lua:1-29

安全配置

• JWT验证
  • 支持从Header或Query中获取Bearer Token，未携带或格式不正确时返回未授权。
• API Token与权限校验
  • 支持API Token，通过Redis缓存的权限表进行路径级校验。
• 忽略URL白名单
  • 白名单内路径跳过鉴权与限流。
• CORS与HTTPS
  • CORS未在网关Java层显式配置，建议在上游Ingress中设置相关响应头或在业务服务侧配置。
  • Ingress已配置TLS与多域名，满足HTTPS要求。
• 访问控制
  • 结合白名单与API Token权限表，实现基础访问控制。

章节来源

• LemesGlobalFilter.java:64-194
• gateway-dcc-npi-https.yaml:24-42
• gateway-igreen-https.yaml:24-34

监控与日志

• Actuator端点
  • 暴露shutdown端点，支持优雅停机。
• 健康检查与探针
  • 配置liveness/readiness/startup探针，结合preStop钩子实现平滑下线。
• 日志
  • Log4j2配置，输出到应用日志目录；全局过滤器记录请求路径、用户ID、来源IP、耗时等。
• 运维指标
  • 建议接入Prometheus/Grafana或APM工具采集请求量、错误率、延迟等指标。

章节来源

• bootstrap.yml:82-101
• gateway.yaml:73-112

路由转发与请求头处理

• 请求头透传
  • 网关会透传traceId、XFF、终端标识、开发者标记等头部至下游服务。
• 响应转换
  • 网关层不进行响应体转换，保持透明转发。
• 服务发现
  • 通过服务名调用下游，结合Nacos实现服务发现与实例变更感知。

章节来源

• LemesGlobalFilter.java:145-151

依赖关系分析

• 组件耦合
  • 全局过滤器依赖属性配置、限流过滤器、WebClient与Redis工具。
  • 限流过滤器依赖Lua脚本与Redis模板。
• 外部依赖
  • Nacos用于配置与注册发现；Redis用于限流计数；下游服务通过WebClient调用。

图表来源

• LemesGatewayConfiguration.java:9-34
• LemesGatewayProperties.java:10-20
• LemesGlobalFilter.java:42-288
• LemesRequestLimitFilter.java:18-91

性能考虑

• Netty解码器最大初始行长度已调整，适合大请求场景。
• 限流采用Redis原子计数，Lua脚本减少往返开销。
• 建议对热点接口增加缓存与异步处理，避免阻塞传播。
• Ingress层面设置合理的超时与Body大小限制，防止慢请求拖垮网关。

章节来源

• LemesGatewayConfiguration.java:25-32
• gateway-dcc-npi-https.yaml:26-29

故障排查指南

• 未授权访问
  • 检查请求是否携带Bearer Token或API Token；确认白名单是否误匹配。
• 限流频繁
  • 检查限流规则配置与Redis Key前缀；核对用户ID/IP识别是否正确。
• 健康检查失败
  • 查看探针配置与日志；确认preStop钩子是否成功触发优雅停机。
• HTTPS/TLS问题
  • 核对Ingress TLS Secret与域名映射；确认证书有效与路径前缀匹配。

章节来源

• LemesGlobalFilter.java:174-193
• LemesRequestLimitFilter.java:77-81
• gateway.yaml:73-112
• gateway-dcc-npi-https.yaml:36-42

结论

本配置文档梳理了DeviceMate网关在服务发现、负载均衡、安全鉴权、限流、监控与Kubernetes部署方面的要点。建议在现有基础上完善路由规则、熔断降级与CORS配置，并持续优化限流策略与探针参数，以提升稳定性与可观测性。

附录

• 部署清单说明
  • Deployment：副本数、亲和性、探针、环境变量、Sidecar与日志挂载。
  • Service/Ingress：ClusterIP暴露、Nginx Ingress注解、TLS与多域名路径转发。
• 配置中心与命名空间
  • Nacos地址、命名空间、组别、共享配置等在bootstrap.yml中集中管理。

章节来源

• gateway.yaml:1-166
• gateway-dcc-npi-https.yaml:1-64
• gateway-igreen-https.yaml:1-46
• bootstrap.yml:19-33