Nginx 静态资源鉴权

付费资料、内部附件、会员视频这类静态文件,不适合直接公开。如果让后端把文件读出来再转发给客户端,吞吐和内存都会被大文件拖垮。auth_request 是目前最省事的方案:Nginx 先同步请求一次鉴权接口,通过就直接从磁盘返回文件,不过就返回 401/403——文件数据全程不经过后端。

1
2
3
4
客户端 ──> Nginx ──┬── 子请求 /auth ──> 鉴权服务(校验 Token / Cookie)
│ │
│ 2xx ▼ 放行:Nginx 直接读本地文件返回(零拷贝)
│ 401/403 ▼ 拦截:原样返回 401/403

一、auth_request 的工作语义

auth_request /auth; 会在交给内容处理器之前,先发起一个到 /auth 的内部子请求:

子请求返回对原始请求的影响
2xx放行,走当前 location 的静态文件处理
401拒绝,客户端收到 401 Unauthorized
403拒绝,客户端收到 403 Forbidden
其他状态码按错误处理(通常表现为拒绝),不要指望鉴权接口的自定义状态码能透传给客户端

几个关键细节:

  • 子请求是同步的,鉴权耗时直接加到每个受保护请求的首字节延迟上,所以鉴权逻辑要快(能本地验 JWT 就不要走数据库);
  • 子请求不共享请求体,Content-Length 之类的头按 Nginx 默认行为处理,通常需要手动清理;
  • 子请求只看状态码,响应体直接丢弃,后端不要为了传信息返回大 body;
  • 想给后端传值,用 auth_request_set 把子请求响应头读成变量,再注入原始请求。

二、生产级配置示例

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
server {
listen 18001;
server_name localhost;

# 业务主入口
location / {
proxy_pass http://127.0.0.1:18000;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
}

# 受保护的静态资源
location /upload/ {
auth_request /auth;

# 把鉴权服务返回的身份信息读出来(可选)
auth_request_set $auth_user $upstream_http_x_auth_user;

alias /var/www/uploads/;

# expires 已同时输出 Expires 与 Cache-Control: max-age,
# 不要再 add_header Cache-Control,否则会出现重复响应头
expires 1d;
access_log /var/log/nginx/upload-access.log combined;
}

# 内部鉴权子请求
location = /auth {
internal; # 外部直接访问 /auth 会 404,防止被伪造或踩点

proxy_pass http://127.0.0.1:18000/api/auth/check;

# 鉴权不需要请求体,关掉以省带宽/内存
proxy_pass_request_body off;
proxy_set_header Content-Length "";

# 把原始请求的关键信息传给鉴权服务
proxy_set_header Host $host;
proxy_set_header X-Original-URI $request_uri;
proxy_set_header X-Original-Method $request_method;
proxy_set_header X-Original-Client-IP $remote_addr;
proxy_set_header Cookie $http_cookie;
proxy_set_header Authorization $http_authorization;
proxy_set_header Referer $http_referer;
proxy_set_header User-Agent $http_user_agent;

# 鉴权要快,避免长超时堆积连接
proxy_connect_timeout 3s;
proxy_read_timeout 5s;
}
}

要点:

  • 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
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
app.get('/api/auth/check', async (req, res) => {
try {
const token =
req.headers.authorization?.replace(/^Bearer\s+/i, '') ||
req.cookies?.session_id;

const user = await verifyUser(token);
if (!user) return res.sendStatus(401); // 未登录
if (!canAccess(user, req.headers['x-original-uri'])) {
return res.sendStatus(403); // 已登录但无权限
}

// 通过:2xx 即可;X-Auth-User 供 Nginx 的 auth_request_set 读取
res.set('X-Auth-User', String(user.id));
return res.sendStatus(200);
} catch (err) {
console.error('auth check failed:', err);
return res.sendStatus(503); // 后端异常 → 拒绝,不放行
}
});

约定:

  • 200 放行、401 未登录、403 无权限、5xx 视为拒绝;
  • try/catch 必须兜底,鉴权服务故障时默认拒绝,不能因为异常而放行;
  • 不要在响应体里返回文件内容或大对象,body 会被 Nginx 丢弃;
  • Token 校验尽量在内存/本地完成(JWT 验签、Redis 单次 Get),一次 HTTP 鉴权子请求不值得再打一次远程链路。

四、验证与排错

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
# 1. 无凭证 → 期待 401/403(由鉴权服务决定)
curl -i http://localhost:18001/upload/secret.pdf

# 2. 正确 Token → 200,并拿到文件(检查 Content-Length / Content-Type)
curl -i -H "Authorization: Bearer valid_token_123" \
http://localhost:18001/upload/secret.pdf

# 3. 断点续传 Range 请求也要鉴权
curl -i -H "Range: bytes=0-99" \
-H "Authorization: Bearer valid_token_123" \
http://localhost:18001/upload/secret.pdf

# 4. 外部直接访问 /auth → 404(internal 生效)
curl -i http://localhost:18001/auth

# 5. 查看 Nginx 配置(合并所有 include 后的最终结果)
nginx -T

排错顺序建议:

  1. nginx -t 先过语法;
  2. 后端单独 curl 鉴权接口,确认状态码与返回头;
  3. 打开 Nginx error.log(子请求失败、upstream 拒绝都会在这里);
  4. 用 $auth_user 或 $upstream_http_x_auth_user 记日志,确认 auth_request_set 是否真的读到;
  5. 用浏览器重复抓取同一资源,确认 401/403 不会被中间缓存。

五、关键避坑清单

  1. internal; 必须保留:否则任何人访问 /auth 都能触发一次鉴权,甚至被当作探测接口;
  2. 记得关请求体转发(proxy_pass_request_body off; + Content-Length ""):否则 POST 上传/大表单会把 body 无谓地转发给鉴权服务;
  3. alias / root 斜杠:location /upload/ ↔ alias /var/www/uploads/ 必须同斜杠策略;不确定就用绝对路径 root + 完整路径校验;
  4. 重复响应头:expires 与 add_header Cache-Control 会各写一份,前面已说明;
  5. 401/403 的语义:401 表示"没登录",403 表示"登录了但看不了";对下载类接口不要做 302 登录跳转,直接把状态码交给前端处理;
  6. 不要缓存鉴权结果到未经隔离的共享缓存:受保护资源若经过 CDN,需确认 Cache-Control: private 或在 CDN 侧绕过缓存;浏览器私有缓存也建议留 max-age 不要无限期;
  7. 鉴权失败必须默认拒绝:后端 5xx 时 Nginx 同样不会放行,但要在代码里显式 return 4xx/5xx,不要吞异常;
  8. 性能预算:auth_request 是同步的,鉴权接口 P95 应尽量控制在几十毫秒;大流量站点可在 Nginx 层做短时缓存(注意按用户隔离)或改用 JWT 本地验签。

六、另一种思路:X-Accel-Redirect

如果只想保护一部分路由(而不是整个目录),可以让后端全程接管请求,鉴权通过后再把文件"让"给 Nginx:

1
2
3
4
location /internal/ {
internal;
alias /var/www/uploads/;
}
1
2
3
4
// 后端:先校验,再返回内部位置头,文件内容仍由 Nginx 传输
res.set('X-Accel-Redirect', '/internal/secret.pdf');
res.set('Content-Type', 'application/pdf');
res.sendStatus(200);

两种方案的文件数据都不过后端;区别是:auth_request 由 Nginx 触发、配置集中,更适合"整个目录统一鉴权";X-Accel-Redirect 需要业务代码参与,适合"鉴权逻辑和文件元数据强相关"的场景。

七、参考资料

  1. Nginx 官方文档:ngx_http_auth_request_module
  2. Nginx 官方文档:internal 指令
  3. Nginx 官方文档:auth_request_set
  4. 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 + 日志)。