← 返回博客列表
微服务网关NginxSa-Token

微服务网关白名单配置了仍然 401:Nginx 前缀导致的排查与修复

RuoYi-Cloud-Plus 网关白名单已配置但生产环境仍返回 401,根因是 Nginx proxy_pass 没有以 / 结尾,/prod-api 前缀被原样转发。附排查步骤、配置对比与验证清单。

鲸码研发团队7 分钟阅读

先说结论

白名单配置本身没问题,问题出在 Nginx 转发时没有去掉 /prod-api 前缀。

location /prod-api/ 配了,但 proxy_pass http://server; 没有以 / 结尾,Nginx 会把 /prod-api/auth4a/logout 原样转给网关;网关的白名单是 /auth4a/logout/**,自然匹配不上,于是继续走 Sa-Token 校验,返回 401。

修复只需要一处:

location /prod-api/ {
    proxy_pass http://server/;  # 末尾这个 / 不能少
}

问题现象

  • 开发环境正常,生产环境返回 401
  • 网关日志显示白名单里确实有 /auth4a/logout
  • 接口返回:
{
  "code": 401,
  "msg": "未能读取到有效 token",
  "data": null
}

这类“配置看起来都对,但只有生产环境错”的问题,优先怀疑请求到达网关时路径已经变了。

请求链路

客户端
  → Nginx /prod-api/
  → 网关 AuthFilter(Sa-Token)
  → 后端服务

关键就在 Nginx 到网关这一段。proxy_pass 末尾有没有 /,决定了 location 匹配到的前缀是保留还是替换。

配置客户端请求到达网关的路径结果
proxy_pass http://server;/prod-api/auth4a/logout/prod-api/auth4a/logout白名单不匹配,401
proxy_pass http://server/;/prod-api/auth4a/logout/auth4a/logout白名单匹配,放行

排查步骤

  1. 在网关加一行日志,打印 request.getRequestURI(),确认到达网关的真实路径。
  2. 对比白名单配置和真实路径,重点看前缀、大小写、末尾斜杠。
  3. 检查 location 和 proxy_pass 是否都以 / 结尾。
  4. 如果前面还有一层 SLB、Ingress 或 CDN,逐层确认是否改写了路径。
  5. 最后再看 Sa-Token 的 SaRouter.match 和 notMatch 顺序,避免把白名单写在拦截之后。

网关侧通常是这样:

SaRouter.match("/**")
    .notMatch(ignoreWhite.getWhites())
    .check(r -> StpUtil.checkLogin());

只要 ignoreWhite 里的路径和真实 URI 对不上,就一定会被拦。

修复配置

location /prod-api/ {
    proxy_set_header Host $http_host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;

    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";

    proxy_pass http://server/;
}

同时确认网关白名单覆盖查询参数和子路径:

security:
  ignore:
    whites:
      - /auth4a/logout/**
      - /auth4a/login/**

/auth4a/logout/** 比精确写 /auth4a/logout 更稳,可以覆盖带参数和子路径的情况。

验证清单

  • curl -i https://域名/prod-api/auth4a/logout 不再返回 401
  • 网关日志里的 URI 是 /auth4a/logout,不带 /prod-api
  • 需要登录的接口仍然返回 401,白名单没有放大
  • WebSocket 接口升级正常,Upgrade 和 Connection 头没有被吞
  • 刷新页面、带查询参数、带末尾斜杠三种情况都验证过

几个容易忽略的边界

  • location 末尾也要有 /:location /prod-api 和 location /prod-api/ 的匹配范围不同。
  • 多级代理:Nginx 前面还有 Ingress 时,可能已经改过一次路径,别只看最外层。
  • proxy_pass 带变量:一旦使用变量,Nginx 不再做前缀替换,行为会变,需要显式 rewrite。
  • 白名单不是越宽越好:只放行真正不需要登录的接口,避免把鉴权打穿。

FAQ

Q:为什么开发环境正常?
A:开发环境通常直连网关,没有 /prod-api 这层前缀,所以路径天然匹配。

Q:把 /prod-api/auth4a/logout/** 加进白名单行不行?
A:能临时绕过,但等于把带前缀的路径也放进白名单,后续换网关或加代理时容易留下隐患。优先修 Nginx。

Q:网关日志显示白名单已加载,为什么还是不生效?
A:日志只能证明配置加载了,不能证明请求 URI 和配置项完全一致。打印真实 URI 再比对。

相关阅读

有类似的微服务、网关或系统集成问题,可以看看我们的项目案例,或直接联系我们。

关于作者

鲸码研发团队,长期做企业级系统、AI 知识库、数据中台与信创环境交付。文中命令与配置均来自实际项目,版本不同请先在测试环境验证。

有类似的技术需求?聊聊 →

继续阅读