微服务网关白名单配置了仍然 401:Nginx 前缀导致的排查与修复
RuoYi-Cloud-Plus 网关白名单已配置但生产环境仍返回 401,根因是 Nginx proxy_pass 没有以 / 结尾,/prod-api 前缀被原样转发。附排查步骤、配置对比与验证清单。
先说结论
白名单配置本身没问题,问题出在 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 | 白名单匹配,放行 |
排查步骤
- 在网关加一行日志,打印
request.getRequestURI(),确认到达网关的真实路径。 - 对比白名单配置和真实路径,重点看前缀、大小写、末尾斜杠。
- 检查
location和proxy_pass是否都以/结尾。 - 如果前面还有一层 SLB、Ingress 或 CDN,逐层确认是否改写了路径。
- 最后再看 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 再比对。
