gateway-service.yaml

gateway-service.yaml 用于配置微服务网关，将外部请求转发到对应的业务服务，并控制哪些接口无需登录即可通过网关鉴权。

一、需要修改的配置

在 Nacos 当前网关使用的环境中编辑 gateway-service.yaml，按下面的场景修改。沿用交付配置部署、没有新增接口或调整访问范围时，通常无需修改。

1. 新增或调整路由

新增业务服务，或新增的接口路径尚未被现有路由覆盖时，需要在 spring.cloud.gateway.routes 列表中追加路由。

例如，新服务在 Nacos 中注册为 example-service，需要接收 /buyer/example/** 请求，可以追加下面这一项：

# 追加到现有 spring.cloud.gateway.routes 列表中。
- id: example-service
  uri: lb://example-service
  predicates:
    - Path=/buyer/example/**
  filters:
    - PreserveHostHeader

修改内容	怎么填写
id	使用唯一的路由标识，不能与现有路由重复
uri	lb:// 后填写实际的 Nacos 服务注册名
Path	填写需要转发的请求路径，可用英文逗号分隔多个路径模式

如果只是已有服务新增了接口，先检查现有 Path 是否已覆盖。例如 /buyer/goods/** 已覆盖该前缀下的新增接口，通常无需再加路由；未覆盖时，在对应路由的 Path 中补充新路径即可。

需要改变转发后的路径时，再配置 RewritePath，详见下方“路径重写”。新增规则与现有路径重叠时，应同时检查路由顺序和优先级。

2. 调整无需登录的放行 URL

接口需要在未登录时访问，就修改 ignored.urls。先区分请求方法，再选择对应列表：

场景	修改位置	生效范围
公开查询接口，只允许 GET 请求跳过网关鉴权	ignored.urls.get	仅 GET 请求
登录、注册、第三方回调等公开入口	ignored.urls.all	所有请求方法

例如，公开查询 /buyer/example/summary，并开放回调入口 /buyer/example/callback：

ignored:
  urls:
    get:
      # 保留已有路径，在列表中追加。
      - /buyer/example/summary
    all:
      # 保留已有路径，在列表中追加。
      - /buyer/example/callback

不再需要公开的接口，从对应列表中移除即可。仅需开放查询时，不要将路径加入 all；回调接口跳过网关鉴权后，仍应由业务接口校验签名等信息。

路由和放行配置分别负责“转发到哪里”和“是否需要网关鉴权”。新增路由不会自动放行，新增放行路径也不会自动建立路由。

3. 调整日志位置

需要固定网关日志位置时，修改 logging.file.name，例如：

logging:
  file:
    name: /opt/server/logs/gateway-service.out

将路径替换为实际日志位置，并确保运行用户具有写入权限；不需要调整时保留原配置。

示例范围

下文省略了部分路由和放行 URL。请在交付配置的基础上修改，不要用精简示例覆盖完整配置。

二、路由配置

基本写法

spring:
  cloud:
    gateway:
      routes:
        - id: goods-service
          uri: lb://goods-service
          predicates:
            - Path=/seller/goods/**,/admin/goods/**,/buyer/goods/**,/admin/goodssearch/**,/goods/**
          filters:
            - PreserveHostHeader
        # 其他业务路由沿用交付配置，此处省略。

配置项	说明
routes	网关路由列表，每一项定义一组请求的转发规则
id	路由标识，同一份路由配置中应保持唯一
uri	目标服务地址；lb://goods-service 表示通过服务发现及负载均衡访问 goods-service
predicates	路由匹配条件，示例使用 Path 按请求路径匹配
Path	需要转发的路径模式；同一条 Path 中可用英文逗号分隔多个路径，匹配其中任意一个即可
filters	匹配路由后执行的过滤器，例如保留 Host 请求头或重写路径
PreserveHostHeader	转发时保留原请求的 Host 请求头，不会自动添加或删除路径前缀

例如，请求 /buyer/goods/search 匹配商品服务路由，会转发到注册名为 goods-service 的实例。该路由没有配置路径重写，转发后的路径仍为 /buyer/goods/search。

业务路由说明

下表概括所提供配置的路由用途，路径仅列举部分示例，完整范围以交付配置为准。

路由 ID	目标服务	主要用途及路径示例
goods-service	lb://goods-service	商品相关接口，如 /buyer/goods/**、/seller/goods/**、/admin/goods/**
system-service	lb://system-service	系统设置、页面、地区、验证码、上传等基础接口，如 /base/pages/**、/base/captchas/**、/admin/settings/**
payment-service	lb://payment-service	支付相关接口，如 /payment/**、/buyer/payment/**
trade-pay-service	lb://trade-service	订单支付信息相关接口，如 /buyer/order/pay/order/**、/buyer/order/pay/trade/**
rewritepath-route	lb://payment-service	将 /order/pay/** 改写为 /payment/** 后转发
trade-service	lb://trade-service	交易、订单、售后等接口，如 /buyer/trade/**、/seller/order/**
promotion-service	lb://promotion-service	促销、拼团等接口，如 /buyer/promotions/**、/seller/promotion/**
member-service	lb://member-service	会员、店铺、登录和第三方连接等接口，如 /buyer/members/**、/buyer/passport/**
statistics-service	lb://statistics-service	统计、后台首页和访问记录等接口，如 /seller/statistics/**、/admin/index/**
distribution-service	lb://distribution-service	分销接口，如 /buyer/distribution/**、/seller/distribution/**
live-video-service	lb://live-video-service	直播相关接口，如 /live-video/**、/seller/live-video/**
im-service-ws	lb:ws://im-service	即时通信 WebSocket 连接，匹配 /im/ws
im-service	lb://im-service	即时通信 HTTP 接口，匹配 /im/**

直播、即时通信等服务是否需要部署，以实际产品功能为准。路由 ID 不要求与目标服务名称相同，例如 trade-pay-service 实际转发到的是 trade-service。

三、路径重写

spring:
  cloud:
    gateway:
      routes:
        - id: rewritepath-route
          uri: lb://payment-service
          predicates:
            - Path=/order/pay/**
          filters:
            - RewritePath=/order/pay/(?<segment>.*), /payment/$\{segment}

该路由用于兼容外部请求路径和支付服务实际接口路径：

项目	示例
网关收到的路径	/order/pay/example
segment 捕获内容	example
转发到支付服务的路径	/payment/example

RewritePath 使用正则表达式捕获路径片段，再替换为目标路径。YAML 中沿用 $\{segment} 写法，不要直接改成 Spring 配置占位符形式的 ${segment}。

这条规则应位于更宽泛的 /order/** 路由之前，避免请求先匹配交易路由。新增或调整路由时，也应检查路径重叠与路由优先级。写法说明可参考 Spring Cloud Gateway 路径重写。

四、WebSocket 转发

spring:
  cloud:
    gateway:
      routes:
        - id: im-service-ws
          uri: lb:ws://im-service
          predicates:
            - Path=/im/ws
          filters:
            - PreserveHostHeader
        - id: im-service
          uri: lb://im-service
          predicates:
            - Path=/im/**
          filters:
            - PreserveHostHeader

lb:ws://im-service 表示通过负载均衡建立 WebSocket 转发；lb://im-service 用于普通 HTTP 请求。较具体的 /im/ws 路由应位于宽泛的 /im/** 路由之前。

前端实际使用的连接路径应与路由一致；如果入口前还有反向代理，也需要支持 WebSocket 协议升级。相关机制可参考 Spring Cloud Gateway 官方说明。

五、网关鉴权放行

ignored.urls 是当前项目的网关鉴权配置，用于指定哪些请求跳过网关的 Token 和权限检查。它不是路由表，也不是跨域配置；请求即使被放行，仍需要匹配正确路由才能转发。

精简示例

ignored:
  urls:
    get:
      - /base/site-show
      - /buyer/goods/**
      # 其他仅允许 GET 请求放行的路径沿用交付配置。
    all:
      - /buyer/passport/login
      # 其他需要对所有请求方法放行的路径沿用交付配置。

配置项	生效范围	适用场景
ignored.urls.get	仅匹配 GET 请求	无需登录的公共查询，如站点信息、公开商品信息等
ignored.urls.all	匹配所有 HTTP 请求方法	登录、注册、第三方回调等需要公开入口的接口，按实际业务逐项配置

例如，/buyer/goods/** 放在 get 中，只会放行该模式下的 GET 请求；不会因此自动放行相同路径的 POST、PUT 或 DELETE 请求。如果将该模式放入 all，则会扩大到所有请求方法。

放行路径按项目的 Ant 风格路径匹配器处理，** 可匹配多级路径。修改时应尽量限定到所需接口，不要为了排除登录错误而直接放行整个 /admin/** 或 /seller/**。

长列表如何维护

交付配置中的公共基础接口、买家端接口、登录回调、API 文档和 WebSocket 等放行列表，本页不逐条展开。维护时按以下原则处理：

1. 先确认接口是否确实需要在未登录状态下访问。
2. 只开放查询时优先放入 get；确实需要其他请求方法时，再按实际路径加入 all。
3. 路径应填写网关收到并用于鉴权匹配的请求路径，不要直接使用 RewritePath 改写后的下游路径。
4. 第三方回调和 WebSocket 放行只表示跳过网关鉴权，接口自身仍需按业务要求验证签名、连接身份等信息。
5. API 文档及静态资源是否需要公开，应按实际环境保留或调整，不必将示例中的所有公开路径照搬到每个环境。

六、日志配置

logging:
  file:
    name: logs/gateway-service.out
  pattern:
    console: "%d{yyyy-MM-dd HH:mm:ss} ${LOG_LEVEL_PATTERN:-%5p} %m%n"

配置项	说明
logging.file.name	应用日志文件名。示例为相对路径，实际位置取决于启动进程的工作目录；需要固定位置时可改为实际绝对路径
logging.pattern.console	控制台日志格式，包含时间、日志级别和消息正文
${LOG_LEVEL_PATTERN:-%5p}	日志级别输出格式的占位表达式，未覆盖时使用 %5p

该文件日志与启动脚本通过重定向保存的控制台输出可能是两份日志。排查问题时，应结合实际启动方式确认日志位置和运行用户的目录写入权限。

七、修改后验证

1. 在当前网关使用的 Nacos 环境中修改 gateway-service.yaml，保留未调整的路由和放行列表。
2. 检查目标服务已注册且实例地址可达，uri 中的服务名称与注册名称一致。
3. 逐项验证普通业务路由、支付路径重写和 WebSocket 连接。
4. 验证公开 GET 请求可以访问，同时受保护的写入接口仍要求登录和权限检查。
5. 检查网关日志中的路由匹配、无可用实例、连接失败或鉴权异常。

配置发布后，还需确认当前版本的网关已实际刷新相关路由和鉴权配置；未生效时按部署方式重新加载或重启网关，再验证请求行为。