Nginx 静态资源鉴权
付费资料、内部附件、会员视频这类静态文件,不适合直接公开。如果让后端把文件读出来再转发给客户端,吞吐和内存都会被大文件拖垮。auth_request 是目前最省事的方案:Nginx 先同步请求一次鉴权接口,通过就直接从磁盘返回文件,不过就返回 401/403——文件数据全程不经过后端。
1 | |
一、auth_request 的工作语义
auth_request /auth; 会在交给内容处理器之前,先发起一个到 /auth 的内部子请求:
| 子请求返回 | 对原始请求的影响 |
|---|---|
| 2xx | 放行,走当前 location 的静态文件处理 |
| 401 | 拒绝,客户端收到 401 Unauthorized |
| 403 | 拒绝,客户端收到 403 Forbidden |
| 其他状态码 | 按错误处理(通常表现为拒绝),不要指望鉴权接口的自定义状态码能透传给客户端 |
几个关键细节:
- 子请求是同步的,鉴权耗时直接加到每个受保护请求的首字节延迟上,所以鉴权逻辑要快(能本地验 JWT 就不要走数据库);
- 子请求不共享请求体,
Content-Length之类的头按 Nginx 默认行为处理,通常需要手动清理; - 子请求只看状态码,响应体直接丢弃,后端不要为了传信息返回大 body;
- 想给后端传值,用
auth_request_set把子请求响应头读成变量,再注入原始请求。
二、生产级配置示例
1 | |
要点:
auth_request_set示例把鉴权接口返回的X-Auth-User存进$auth_user,后续若需要(例如代理到后端、记日志)可以直接引用;- 想额外输出
private而不是public缓存语义,最简单的做法是去掉expires,改用add_header Cache-Control "private, max-age=86400";;标准和第三方模块headers-more也可以在保留expires的同时改写Cache-Control; alias的结尾斜杠:location /upload/时,alias /var/www/uploads/;两边都要带斜杠,否则拼接出错误路径导致 404;$request_uri包含 query string,鉴权服务可以基于"文件 + 参数"做细粒度判断。
三、后端鉴权接口(Express 示例)
1 | |
约定:
- 200 放行、401 未登录、403 无权限、5xx 视为拒绝;
try/catch必须兜底,鉴权服务故障时默认拒绝,不能因为异常而放行;- 不要在响应体里返回文件内容或大对象,body 会被 Nginx 丢弃;
- Token 校验尽量在内存/本地完成(JWT 验签、Redis 单次 Get),一次 HTTP 鉴权子请求不值得再打一次远程链路。
四、验证与排错
1 | |
排错顺序建议:
nginx -t先过语法;- 后端单独
curl鉴权接口,确认状态码与返回头; - 打开 Nginx
error.log(子请求失败、upstream 拒绝都会在这里); - 用
$auth_user或$upstream_http_x_auth_user记日志,确认auth_request_set是否真的读到; - 用浏览器重复抓取同一资源,确认 401/403 不会被中间缓存。
五、关键避坑清单
internal;必须保留:否则任何人访问/auth都能触发一次鉴权,甚至被当作探测接口;- 记得关请求体转发(
proxy_pass_request_body off;+Content-Length ""):否则 POST 上传/大表单会把 body 无谓地转发给鉴权服务; alias/root斜杠:location /upload/↔alias /var/www/uploads/必须同斜杠策略;不确定就用绝对路径root+ 完整路径校验;- 重复响应头:
expires与add_header Cache-Control会各写一份,前面已说明; - 401/403 的语义:401 表示"没登录",403 表示"登录了但看不了";对下载类接口不要做 302 登录跳转,直接把状态码交给前端处理;
- 不要缓存鉴权结果到未经隔离的共享缓存:受保护资源若经过 CDN,需确认
Cache-Control: private或在 CDN 侧绕过缓存;浏览器私有缓存也建议留max-age不要无限期; - 鉴权失败必须默认拒绝:后端 5xx 时 Nginx 同样不会放行,但要在代码里显式
return 4xx/5xx,不要吞异常; - 性能预算:
auth_request是同步的,鉴权接口 P95 应尽量控制在几十毫秒;大流量站点可在 Nginx 层做短时缓存(注意按用户隔离)或改用 JWT 本地验签。
六、另一种思路:X-Accel-Redirect
如果只想保护一部分路由(而不是整个目录),可以让后端全程接管请求,鉴权通过后再把文件"让"给 Nginx:
1 | |
1 | |
两种方案的文件数据都不过后端;区别是:auth_request 由 Nginx 触发、配置集中,更适合"整个目录统一鉴权";X-Accel-Redirect 需要业务代码参与,适合"鉴权逻辑和文件元数据强相关"的场景。
七、参考资料
- Nginx 官方文档:ngx_http_auth_request_module
- Nginx 官方文档:internal 指令
- Nginx 官方文档:auth_request_set
- RFC 7235: HTTP/1.1 Authentication —— 401/403 的规范语义
八、小结
auth_request /auth;+ 内部location = /auth是标准做法;- 鉴权接口只回状态码(200 放行 / 401 未登录 / 403 无权限),body 会被丢弃;
- 一定加
internal;、关请求体转发、避开expires与add_header Cache-Control的重复头; - 鉴权要快、要能兜底拒绝,并保留可观测性(
auth_request_set+ 日志)。
Nginx 静态资源鉴权
https://bubao.github.io/posts/15f703f2.html
