ngx_http_referer_module 模块概述

一、使用场景

• 防盗链
  仅允许本站或特定域名的页面直接引用图片、视频等资源，拒绝第三方网站直接嵌入。
• 流量控制
  阻止来自社交媒体、搜索引擎或未知来源的大量自动化抓取。
• 安全审计
  简易记录并过滤可疑 Referer，以减少非法请求。

注意

• Referer 头可被伪造或在部分隐私/安全插件中被屏蔽（置空或删除）。
• 浏览器也可能因隐私设置或 HTTPS→HTTP 跨协议请求而不发送 Referer。

二、示例配置

http {server {listen 80;server_name www.example.com example.com;# 定义合法 Referer 列表：#  none           —— 允许无 Referer#  blocked        —— 允许被防火墙/代理剥离的 Referer#  server_names   —— 允许包含本 server_name 的 Referer#  *.example.com  —— 允许子域名#  example.*      —— 允许任意 top‐level 后缀#  /images/       —— 可加 URI 路径前缀#  ~\.google\.    —— 正则匹配 “google.” 字样valid_referers none blocked server_names*.example.com example.* www.example.com/images/~*\.google\.;# 若 Referer 不在上述列表，则标记为 invalidif ($invalid_referer) {# 防盗链示例：返回 403，或重定向到站内图片return 403;# 或# rewrite ^/images/(.*)$ /images/nohotlink.png last;}location /images/ {root /var/www/html;}}
}

三、指令详解

1. referer_hash_bucket_size

Syntax:   referer_hash_bucket_size size;
Default:  64;
Context:  server, location

• 设置存储 Referer 哈希表的桶大小（以字节为单位），应与 CPU 缓存行大小对齐以提升查找效率。
• 一般无需调整，除非出现哈希冲突警告。

2. referer_hash_max_size

Syntax:   referer_hash_max_size size;
Default:  2048;
Context:  server, location

• 设置哈希表中可能存储的最大条目数。
• 若合法 Referer 条目非常多（数百以上），可适当增大。

3. valid_referers

Syntax:   valid_referers none | blocked | server_names | string ...;
Default:  —;
Context:  server, location

• none：允许请求头中没有 Referer 字段。

• blocked：允许头部中存在但被防火墙或代理剥离（即不以 http:///https:// 开头）的情况。

• server_names：允许 Referer 中包含当前 server_name 列表的任一名称。

• 字符串或通配：

  • 精确匹配域名或带路径前缀（如 www.example.com/images/）。
  • 通配符 * 仅可用于前缀或后缀（如 *.example.com、example.*）。

• 正则表达式：以 ~（区分大小写）或 ~*（不区分大小写）开头，匹配 http:///https:// 之后的 URI 部分。

匹配顺序：

1. 精确字符串
2. 最长前缀通配
3. 最长后缀通配
4. 正则表达式（配置文件中出现的顺序）
5. default（若未指定 default，则视为不匹配）

四、内置变量

变量	含义
$invalid_referer	匹配合法 Referer 时为空字符串；否则为 "1"（真值）

可结合 if ($invalid_referer) 或 map、geo 等指令做更复杂的访问控制。

五、常见示例

1. 防盗链：只允许本站域名加载图片

valid_referers none blocked server_names *.example.com;location ~* \.(gif|jpg|jpeg|png)$ {if ($invalid_referer) {return 403;}expires 30d;
}

2. 允许搜索引擎过来抓取

valid_referers none blocked server_names~*google\.  ~*bing\.  ~*yahoo\.;

通过 ngx_http_referer_module，可以在 Nginx 层面实现简易的来源过滤与防盗链，为静态资源及页面访问增加一层来源验证。