Linux下Nginx防CSRF配置指南

本文深入剖析了Nginx中`valid_referer`指令在防范CSRF攻击时的真实能力与严重局限：它并非专为CSRF设计，而仅是一种脆弱的Referer白名单校验机制，仅对传统同源Web页面表单提交等少数可控场景有效；在API接口、小程序、SPA路由及跨协议请求等现代主流场景下极易失效甚至误拦，还存在if语句逻辑陷阱、配置覆盖风险和白名单静态固化等运维隐患；文章不仅指出哪些路径绝对禁用该配置，更给出了更可靠、分层组合的防御方案——包括Origin双校验、CSRF Token透传、X-Frame-Options与CSP强化等实用策略，并提醒动态白名单需借助OpenResty或WAF实现，帮助开发者避开常见误区，构建真正健壮的安全防线。

valid_referer 不能单独防 CSRF，它只在特定场景下有效，且极易因 Referer 被浏览器清空或客户端不发而误拦正常请求。

valid_referer 的真实作用范围

这个模块本质是 Referer 白名单校验，不是 CSRF 专用防护。它只对「带 Referer 头、且该头未被浏览器策略抹除」的 Web 页面请求起效。比如用户从 https://admin.example.com 点击一个表单提交到 /api/transfer，Referer 是完整的，valid_referers 才能匹配；但如果是 Axios 发起的跨域 API 调用（默认不带 Referer）、小程序发起的请求（根本无 Referer）、或 HTTPS 页面加载 HTTP 图片（浏览器清空 Referer），$invalid_referer 就恒为 "1"，直接 403。

• none：允许 Referer 完全缺失（如地址栏直输、书签访问）
• blocked：允许 Referer 存在但协议/域名被代理或防火墙截断（如值为 example.com 而非 https://example.com）
• server_names：匹配当前 Nginx server_name 列表中的任意主机名（注意：不支持通配符匹配子域名，除非显式列出 *.example.com）
• 字符串或正则：如 example.com、~* \.example\.com$，但正则性能略低，生产环境慎用

location 中 if($invalid_referer) 的坑

Nginx 的 if 在 location 块中属于“伪条件”，它不支持嵌套逻辑，且与 proxy_pass 共存时容易触发变量捕获异常。更关键的是：if 内部的 return 或 rewrite 会中断请求流程，但不会阻止后续配置块执行 —— 如果你同时在外部 location 里写了 proxy_pass，非法 Referer 请求仍可能透传到后端。

• 必须把 if ($invalid_referer) 放在 proxy_pass 之前，且确保没有其他 location 或 rewrite 规则覆盖它
• 不要在 if 里写 break，break 对 return 无效；要用 return 403 确保立即终止
• 调试时加日志：log_format referer_log '$http_referer $invalid_referer'; access_log /var/log/nginx/referer.log referer_log;，否则你看不到真实 Referer 值和匹配结果

哪些接口绝对不该用 valid_referer 校验

对以下三类路径启用 valid_referer 几乎必然导致功能故障：

• /api/ 或 /v1/ 开头的通用接口：移动端 App、Electron 桌面应用、微信小程序均不发送 Referer
• 单页应用（SPA）的前端路由跳转：React/Vue Router 的 history.push 不刷新页面，Referer 保持不变，首次加载后所有 API 请求 Referer 都是初始入口页，极易误判
• HTTPS 页面内嵌 HTTP 资源：现代浏览器（Chrome/Firefox）默认执行 Referrer Policy: strict-origin-when-cross-origin，跨协议时直接清空 Referer 头

真正适合的场景只有：静态资源防盗链（图片/CSS/JS）、后台管理页内部表单提交（且确认所有入口都来自同域页面）、或内网系统中可控的 Web 端调用。

比 valid_referer 更靠谱的 Nginx 层 CSRF 防御组合

单靠 Referer 校验太脆弱。实际生产中建议组合使用：

• 对 /admin/ 类路径，用 valid_referers + $http_origin 双校验（Origin 更难伪造，但需注意旧版 IE 不支持）
• 要求前端在每个敏感请求头里带 X-Csrf-Token，Nginx 用 map 指令提取并透传给后端，由应用层做 token 验证（Nginx 不生成也不校验 token，只做透传）
• 配合 add_header X-Frame-Options "DENY" 和 add_header Content-Security-Policy "frame-ancestors 'none'" 阻止页面被嵌入 iframe，切断部分 CSRF 传播路径

最常被忽略的一点：valid_referer 规则一旦写死，就无法动态更新白名单。如果业务要接入新合作方域名，必须 reload Nginx 进程，这在高可用场景下有风险。真要动态控制，得换用 OpenResty + Lua 或上 WAF。

本篇关于《Linux下Nginx防CSRF配置指南》的介绍就到此结束啦，但是学无止境，想要了解学习更多关于文章的相关知识，请关注golang学习网公众号！