xfy/lolly
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity
lolly/docs/19-nginx-http-modules-detail.md
xfy 80936ae66b feat(server,proxy,ssl,docs): 完成 Phase 7 功能完善 
主要变更：
- WebSocket 代理支持 (internal/proxy/websocket.go)
- OCSP stapling 实现 (internal/ssl/ocsp.go)
- 监控状态端点 (internal/server/status.go)
- 新增 nginx 模块文档 (19-24)
- UDP 代理超时配置支持
- 多模块代码注释完善和功能增强

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-04-03 13:13:12 +08:00

42 KiB
Raw Blame History

NGINX HTTP 功能模块详解

本文档详细介绍 NGINX 常用的 HTTP 功能模块及其配置方法。

1. ngx_http_access_module (访问控制模块)

概述

ngx_http_access_module 模块用于限制对某些客户端地址的访问，提供简单的基于 IP 的访问控制功能。

核心指令

指令 语法 默认值 说明 上下文
allow allow address | CIDR | unix: | all; - 允许指定地址访问 http, server, location, limit_except
deny deny address | CIDR | unix: | all; - 拒绝指定地址访问 http, server, location, limit_except

配置示例

# 拒绝单个 IP
location /admin/ {
    deny  192.168.1.1;
    allow 192.168.1.0/24;
    deny  all;
}

# 只允许内网访问管理后台
server {
    listen 80;
    server_name admin.example.com;

    location / {
        allow 10.0.0.0/8;
        allow 172.16.0.0/12;
        allow 192.168.0.0/16;
        deny  all;

        proxy_pass http://backend;
    }
}

# 拒绝特定网段，允许其他
location /api/ {
    deny  192.168.1.0/24;
    allow all;
}

应用场景

  • 管理后台保护：限制只有内网 IP 可以访问管理后台
  • API 访问控制：限制特定 IP 才能调用敏感 API
  • 防御恶意 IP：封禁已知的攻击源 IP 地址

2. ngx_http_auth_basic_module (基础认证模块)

概述

ngx_http_auth_basic_module 模块允许使用 HTTP 基本认证协议验证用户名和密码，提供简单的用户名/密码访问控制。

核心指令

指令 语法 默认值 说明 上下文
auth_basic auth_basic string | off; off 启用基本认证并设置提示信息 http, server, location, limit_except
auth_basic_user_file auth_basic_user_file file; - 指定密码文件路径 http, server, location, limit_except

配置示例

# 基本认证配置
location /admin/ {
    auth_basic           "Administrator's Area";
    auth_basic_user_file /etc/nginx/.htpasswd;
}

# 生成密码文件
# 使用 htpasswd 工具
# htpasswd -c /etc/nginx/.htpasswd username

# 使用 openssl 生成
# printf "username:$(openssl passwd -crypt password)\n" >> /etc/nginx/.htpasswd

# 多区域不同认证
server {
    listen 80;
    server_name example.com;

    location /admin/ {
        auth_basic           "Admin Area";
        auth_basic_user_file /etc/nginx/admin.htpasswd;
        proxy_pass http://backend;
    }

    location /api/private/ {
        auth_basic           "API Access";
        auth_basic_user_file /etc/nginx/api.htpasswd;
        proxy_pass http://api_backend;
    }
}

密码文件格式

# /etc/nginx/.htpasswd
username1:encrypted_password1
username2:encrypted_password2

应用场景

  • 开发环境保护：为开发环境添加简单密码保护
  • 内部文档访问：限制内部文档仅供授权用户访问
  • 简单后台管理：小型项目的后台管理保护

3. ngx_http_auth_request_module (请求认证模块)

概述

ngx_http_auth_request_module 模块通过子请求实现基于外部服务的认证，允许向认证服务发送请求验证用户身份。

核心指令

指令 语法 默认值 说明 上下文
auth_request auth_request uri | off; off 启用认证请求并指定认证 URI http, server, location
auth_request_set auth_request_set $variable value; - 从认证响应中设置变量 http, server, location

配置示例

# 基础认证代理配置
location /private/ {
    auth_request /auth;
    auth_request_set $auth_status $upstream_status;

    proxy_pass http://backend;
}

# 认证服务 location
location = /auth {
    internal;
    proxy_pass http://auth-server/verify;
    proxy_pass_request_body off;
    proxy_set_header Content-Length "";
    proxy_set_header X-Original-URI $request_uri;
    proxy_set_header X-Original-Method $request_method;
}

# 完整示例：JWT 验证
server {
    listen 80;
    server_name api.example.com;

    location /api/ {
        auth_request /auth_jwt;
        auth_request_set $auth_user $upstream_http_x_user_id;
        auth_request_set $auth_roles $upstream_http_x_roles;

        proxy_set_header X-User-ID $auth_user;
        proxy_set_header X-Roles $auth_roles;
        proxy_pass http://api_backend;
    }

    location = /auth_jwt {
        internal;
        proxy_pass http://auth-service/validate;
        proxy_pass_request_body off;
        proxy_set_header Content-Length "";
        proxy_set_header Authorization $http_authorization;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

# 带缓存的认证
location /protected/ {
    auth_request /auth;
    auth_request_set $auth_cache $upstream_http_x_auth_cache;

    proxy_cache_key "$cookie_session_id$request_method$host$request_uri";
    proxy_pass http://backend;
}

应用场景

  • OAuth/JWT 认证：集成 OAuth2 或 JWT 认证服务
  • 集中式认证：统一认证中心验证用户身份
  • 多系统单点登录：实现跨系统的统一认证
  • 自定义认证逻辑：实现复杂的认证业务逻辑

4. ngx_http_autoindex_module (自动索引模块)

概述

ngx_http_autoindex_module 模块用于自动生成目录列表页面，当请求以 / 结尾时展示目录内容。

核心指令

指令 语法 默认值 说明 上下文
autoindex autoindex on | off; off 启用自动目录列表 http, server, location
autoindex_exact_size autoindex_exact_size on | off; on 显示精确文件大小 http, server, location
autoindex_format autoindex_format html | xml | json | jsonp; html 目录列表格式 http, server, location
autoindex_localtime autoindex_localtime on | off; off 使用本地时间显示 http, server, location

配置示例

# 基本目录浏览
location /files/ {
    root /data/public;
    autoindex on;
}

# 优化显示格式
location /downloads/ {
    root /data/downloads;
    autoindex on;
    autoindex_exact_size off;   # 显示 KB/MB 而非字节
    autoindex_localtime on;      # 本地时间格式
}

# JSON 格式 API
location /api/files/ {
    root /data/public;
    autoindex on;
    autoindex_format json;
}

# 文件服务器配置
server {
    listen 80;
    server_name files.example.com;

    location / {
        root /var/www/files;
        autoindex on;
        autoindex_exact_size off;
        autoindex_localtime on;

        # 美化目录页面（可选）
        add_header X-Robots-Tag "noindex, nofollow";
    }
}

应用场景

  • 文件下载站：提供文件目录浏览和下载功能
  • 文档服务器：文档资源的目录化访问
  • 镜像站点：软件镜像的目录展示
  • 内部资源共享：企业内部文件共享访问

5. ngx_http_browser_module (浏览器检测模块)

概述

ngx_http_browser_module 模块用于根据 User-Agent 请求头创建变量，标识是否为古老或现代浏览器。

核心指令

指令 语法 默认值 说明 上下文
ancient_browser ancient_browser string ...; - 定义古老浏览器标识 http, server, location
ancient_browser_value ancient_browser_value value; 1 古老浏览器变量值 http, server, location
modern_browser modern_browser browser version | unlisted; - 定义现代浏览器 http, server, location
modern_browser_value modern_browser_value value; 0 现代浏览器变量值 http, server, location

配置示例

# 定义古老浏览器
http {
    ancient_browser "MSIE 6.0";
    ancient_browser "MSIE 5.5";
    ancient_browser "MSIE 5.0";
    ancient_browser "MSIE 4.0";

    # 定义现代浏览器
    modern_browser msie 7.0;
    modern_browser opera 9.0;
    modern_browser safari 3.0;
    modern_browser firefox 3.0;
    modern_browser chrome 1.0;

    server {
        listen 80;

        location / {
            # 古老浏览器重定向
            if ($ancient_browser) {
                rewrite ^ /browser-not-supported.html last;
            }

            # 现代浏览器正常访问
            proxy_pass http://backend;
        }
    }
}

# 根据浏览器类型分配不同后端
server {
    listen 80;
    server_name app.example.com;

    location / {
        # 古老浏览器使用兼容版本
        if ($ancient_browser) {
            proxy_pass http://legacy_backend;
            break;
        }

        # 现代浏览器使用标准版本
        proxy_pass http://modern_backend;
    }
}

# 浏览器日志记录
log_format browser '$remote_addr - $remote_user [$time_local] '
                   '"$request" $status $body_bytes_sent '
                   '"$http_user_agent" ancient=$ancient_browser';

access_log /var/log/nginx/browser.log browser;

应用场景

  • 浏览器兼容性提示：检测古老浏览器提示用户升级
  • 差异化服务：为不同浏览器提供不同版本的内容
  • 统计分析：分析用户浏览器分布情况
  • 功能降级：为古老浏览器提供简化功能

6. ngx_http_charset_module (字符集模块)

概述

ngx_http_charset_module 模块用于将指定的字符集添加到 Content-Type 响应头，并可以在不同字符集之间转换响应内容。

核心指令

指令 语法 默认值 说明 上下文
charset charset charset | off; off 设置响应字符集 http, server, location, if in location
charset_map charset_map source_charset destination_charset { ... } - 定义字符集映射 http
override_charset override_charset on | off; off 覆盖源字符集 http, server, location, if in location
source_charset source_charset charset; - 设置源字符集 http, server, location, if in location

配置示例

# 基本字符集设置
server {
    listen 80;
    server_name example.com;

    charset utf-8;
    source_charset utf-8;
}

# 字符集转换
location /legacy/ {
    source_charset gb2312;
    charset utf-8;
}

# 字符集映射定义
http {
    charset_map koi8-r utf-8 {
        # 从 koi8-r 到 utf-8 的字符映射
        80 E28099;   # 单引号
        95 E280A6;   # 省略号
        9A C2A0;     # 不换行空格
    }
}

# 不同路径不同字符集
server {
    listen 80;

    location /cn/ {
        charset gb2312;
        root /var/www/cn;
    }

    location /en/ {
        charset utf-8;
        root /var/www/en;
    }

    location /jp/ {
        charset shift_jis;
        root /var/www/jp;
    }
}

# 根据来源覆盖字符集
location /api/ {
    charset utf-8;
    override_charset on;  # 强制使用 utf-8
    proxy_pass http://backend;
}

应用场景

  • 多语言网站：为不同语言设置合适的字符集
  • 遗留系统兼容：转换旧系统的非 UTF-8 编码
  • API 标准化：统一 API 响应字符集为 UTF-8
  • 字符集规范化：确保所有响应使用正确字符集

7. ngx_http_geo_module (地理位置变量模块)

概述

ngx_http_geo_module 模块用于根据客户端 IP 地址创建变量，实现基于地理位置的访问控制或内容定制。

核心指令

指令 语法 默认值 说明 上下文
geo geo [$address] $variable { ... } - 定义地理位置映射 http

配置示例

# 基本地理位置定义
http {
    geo $geo {
        default        unknown;
        127.0.0.1      local;
        192.168.1.0/24 internal;
        10.0.0.0/8     internal;
        1.2.3.4        china;
        5.6.7.8        usa;
    }

    server {
        listen 80;

        location / {
            add_header X-Geo $geo;
            return 200 "Your location: $geo";
        }
    }
}

# 使用变量作为数据源
geo $arg_ip $geo {
    default        unknown;
    192.168.0.0/16 local;
}

# 复杂地理位置配置
geo $geo_country {
    default        other;
    include        /etc/nginx/geo/countries.conf;  # 包含外部文件

    # 中国 IP 段
    1.0.1.0/24     cn;
    1.0.2.0/23     cn;
    1.0.32.0/19    cn;
    # ... 更多 IP 段

    # 美国 IP 段
    3.0.0.0/8      us;
    4.0.0.0/8      us;
    # ... 更多 IP 段

    delete         127.0.0.0/16;  # 删除特定范围
    proxy          192.168.100.1;  # 递归查询代理
    proxy_recursive on;             # 启用递归代理
}

# 应用示例：区域路由
server {
    listen 80;
    server_name example.com;

    location / {
        if ($geo_country = cn) {
            proxy_pass http://cn_backend;
            break;
        }

        if ($geo_country = us) {
            proxy_pass http://us_backend;
            break;
        }

        proxy_pass http://default_backend;
    }
}

# 访问限制
geo $allowed {
    default        0;
    192.168.0.0/16 1;
    10.0.0.0/8     1;
    172.16.0.0/12  1;
}

server {
    location /admin/ {
        if ($allowed = 0) {
            return 403;
        }
        proxy_pass http://backend;
    }
}

应用场景

  • 区域路由：根据用户地区路由到不同服务器
  • 地理位置限制：限制或允许特定地区访问
  • 内容定制：根据地区显示不同内容
  • 访问统计分析：按地理位置统计访问日志

8. ngx_http_geoip_module (GeoIP 模块)

概述

ngx_http_geoip_module 模块使用 MaxMind GeoIP 数据库创建变量，提供基于 IP 的地理位置信息（国家、城市、坐标等）。

核心指令

指令 语法 默认值 说明 上下文
geoip_country geoip_country file; - 指定国家数据库 http
geoip_city geoip_city file; - 指定城市数据库 http
geoip_org geoip_org file; - 指定组织数据库 http
geoip_proxy geoip_proxy address | CIDR; - 定义代理服务器 http
geoip_proxy_recursive geoip_proxy_recursive on | off; off 递归搜索代理 http

配置示例

# 基本 GeoIP 配置
http {
    geoip_country /usr/share/GeoIP/GeoIP.dat;
    geoip_city    /usr/share/GeoIP/GeoLiteCity.dat;

    server {
        listen 80;

        location /geo {
            add_header X-Country-Code $geoip_country_code;
            add_header X-Country-Name $geoip_country_name;
            add_header X-City $geoip_city;
            add_header X-Region $geoip_region;
            add_header X-Region-Name $geoip_region_name;
            add_header X-Latitude $geoip_latitude;
            add_header X-Longitude $geoip_longitude;

            return 200 "Country: $geoip_country_name, City: $geoip_city";
        }
    }
}

# 代理环境配置
http {
    geoip_country /usr/share/GeoIP/GeoIP.dat;
    geoip_proxy 192.168.1.0/24;
    geoip_proxy_recursive on;

    server {
        location / {
            proxy_set_header X-Country $geoip_country_code;
            proxy_pass http://backend;
        }
    }
}

# 区域限制示例
server {
    listen 80;
    server_name example.com;

    location / {
        # 禁止特定国家访问
        if ($geoip_country_code = "CN") {
            return 403;
        }

        proxy_pass http://backend;
    }
}

# 多数据库配置
http {
    geoip_country /usr/share/GeoIP/GeoIP.dat;
    geoip_city    /usr/share/GeoIP/GeoLiteCity.dat;
    geoip_org     /usr/share/GeoIP/GeoIPASNum.dat;

    server {
        location /api/geo {
            default_type application/json;
            return 200 '{
                "country_code": "$geoip_country_code",
                "country_name": "$geoip_country_name",
                "city": "$geoip_city",
                "region": "$geoip_region",
                "latitude": "$geoip_latitude",
                "longitude": "$geoip_longitude",
                "org": "$geoip_org"
            }';
        }
    }
}

可用变量

变量名 说明
$geoip_country_code 两位国家代码
$geoip_country_code3 三位国家代码
$geoip_country_name 国家名称
$geoip_city 城市名称
$geoip_region 地区代码
$geoip_region_name 地区名称
$geoip_latitude 纬度
$geoip_longitude 经度
$geoip_postal_code 邮政编码
$geoip_org 组织/ISP 名称

应用场景

  • 地理位置服务：为应用提供用户地理位置信息
  • 内容本地化：根据国家展示不同语言/货币的内容
  • 访问控制：基于国家代码限制访问
  • CDN 优化：根据地理位置选择最近的服务器

9. ngx_http_map_module (变量映射模块)

概述

ngx_http_map_module 模块用于创建变量，其值取决于其他变量的值，实现灵活的变量映射和转换。

核心指令

指令 语法 默认值 说明 上下文
map map string $variable { ... } - 定义变量映射 http
map_hash_max_size map_hash_max_size size; 2048 哈希表最大大小 http
map_hash_bucket_size map_hash_bucket_size size; 32|64|128 哈希桶大小 http

配置示例

# 基本变量映射
http {
    map $http_host $backend {
        default       backend_default;
        example.com   backend_example;
        api.example.com backend_api;
        "*.test.com"  backend_test;
    }

    server {
        location / {
            proxy_pass http://$backend;
        }
    }
}

# 主机名到后端映射
map $host $backend_pool {
    default              http://default_backend;
    "~^(?<name>.+)\\.example\\.com$"  http://$name_backend;
    www.example.com      http://www_backend;
    api.example.com      http://api_backend;
}

# User-Agent 映射
map $http_user_agent $is_mobile {
    default       0;
    "~*android"   1;
    "~*iphone"    1;
    "~*ipad"      1;
    "~*mobile"    1;
}

# 应用示例
server {
    location / {
        if ($is_mobile) {
            rewrite ^ /mobile$request_uri last;
        }
        proxy_pass http://desktop_backend;
    }
}

# 复杂映射配置
map $http_upgrade $connection_upgrade {
    default          close;
    websocket        upgrade;
}

# 用于 WebSocket 代理
location /ws/ {
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection $connection_upgrade;
    proxy_pass http://ws_backend;
}

# 状态码映射
map $status $loggable {
    ~^[23]  0;      # 2xx 和 3xx 不记录
    default 1;      # 其他状态码记录
}

access_log /var/log/nginx/access.log combined if=$loggable;

# 复杂正则映射
map $request_uri $cache_key {
    default          $request_uri;
    "~^/api/(?<version>v\\d+)/"  /api/$version/generic;
}

# 多条件映射
map "$scheme:$server_port" $is_https {
    default     0;
    "https:443" 1;
    "https:8443" 1;
}

映射规则

源值格式 说明
string 精确匹配字符串
"~regex" 正则匹配（区分大小写）
"~*regex" 正则匹配（不区分大小写）
"!~regex" 正则不匹配（区分大小写）
"!~*regex" 正则不匹配（不区分大小写）

应用场景

  • 动态后端选择：根据请求信息选择不同后端
  • 设备类型检测：根据 User-Agent 识别设备类型
  • 缓存键定制：创建自定义缓存键
  • 条件日志记录：根据条件决定是否记录日志
  • 变量转换：将一个变量的值转换为另一个值

10. ngx_http_realip_module (真实 IP 模块)

概述

ngx_http_realip_module 模块用于当 NGINX 位于代理或负载均衡器后方时，将客户端的真实 IP 地址替换为请求头中的地址。

核心指令

指令 语法 默认值 说明 上下文
set_real_ip_from set_real_ip_from address | CIDR | unix:; - 定义可信代理地址 http, server, location
real_ip_header real_ip_header field | X-Real-IP | X-Forwarded-For | proxy_protocol; X-Real-IP 指定真实 IP 来源头 http, server, location
real_ip_recursive real_ip_recursive on | off; off 递归解析 http, server, location

配置示例

# 基本真实 IP 配置
http {
    set_real_ip_from 192.168.1.0/24;
    set_real_ip_from 10.0.0.0/8;
    set_real_ip_from 172.16.0.0/12;
    real_ip_header X-Forwarded-For;
    real_ip_recursive on;
}

# CDN/云服务配置
http {
    # Cloudflare
    set_real_ip_from 103.21.244.0/22;
    set_real_ip_from 103.22.200.0/22;
    set_real_ip_from 103.31.4.0/22;
    # ... 更多 Cloudflare IP

    # 阿里云 SLB
    set_real_ip_from 100.64.0.0/10;

    real_ip_header X-Forwarded-For;
    real_ip_recursive on;

    server {
        listen 80;

        location / {
            # 现在 $remote_addr 是真实客户端 IP
            add_header X-Real-Client-IP $remote_addr;
            proxy_pass http://backend;
        }
    }
}

# 多级代理配置
server {
    listen 80;

    set_real_ip_from 192.168.0.0/16;
    set_real_ip_from unix:;      # 允许 Unix socket
    real_ip_header X-Forwarded-For;
    real_ip_recursive on;         # 递归获取最左侧非代理 IP

    location / {
        # X-Forwarded-For: client, proxy1, proxy2
        # recursive on 会选择 client 作为 remote_addr
        proxy_pass http://backend;
    }
}

# 不同 location 不同配置
server {
    location /api/ {
        set_real_ip_from 10.0.0.0/8;
        real_ip_header X-Real-IP;
        proxy_pass http://api_backend;
    }

    location /app/ {
        set_real_ip_from 192.168.1.0/24;
        real_ip_header X-Forwarded-For;
        proxy_pass http://app_backend;
    }
}

应用场景

  • 反向代理环境：获取客户端真实 IP 用于日志和访问控制
  • CDN 部署：从 CDN 请求头中提取源客户端 IP
  • 负载均衡器后方：在负载均衡架构中保持真实 IP 信息
  • 安全防护：基于真实 IP 进行访问限制和防护

11. ngx_http_referer_module (Referer 防盗链模块)

概述

ngx_http_referer_module 模块用于基于 Referer 请求头字段过滤请求，实现简单的防盗链功能。

核心指令

指令 语法 默认值 说明 上下文
valid_referers valid_referers none | blocked | server_names | string ...; - 定义有效的 Referer http, server, location
referer_hash_max_size referer_hash_max_size size; 2048 哈希表最大大小 server, location
referer_hash_bucket_size referer_hash_bucket_size size; 64 哈希桶大小 server, location

配置示例

# 基本防盗链配置
location /images/ {
    valid_referers none blocked server_names
                   *.example.com example.com
                   *.example.cn;

    if ($invalid_referer) {
        return 403;
    }

    root /var/www/images;
}

# 图片防盗链（返回替代图片）
location ~* \\.(gif|jpg|jpeg|png|bmp|swf|flv)$ {
    valid_referers none blocked *.example.com example.com
                   *.google.com *.baidu.com;

    if ($invalid_referer) {
        # 返回防盗链提示图片
        rewrite ^/ /images/forbidden.png break;
    }

    root /var/www/static;
}

# 视频防盗链
location /videos/ {
    valid_referers none blocked server_names
                   *.example.com;

    if ($invalid_referer) {
        return 403 "Forbidden: Hotlinking is not allowed";
    }

    # 限制下载速度
    limit_rate 500k;

    root /var/www/videos;
}

# 复杂防盗链配置
server {
    listen 80;
    server_name file.example.com;

    location /downloads/ {
        valid_referers none blocked;
        valid_referers server_names;
        valid_referers *.example.com;
        valid_referers *.example.cn;
        valid_referers ~\\.example\\.com$;  # 正则匹配

        if ($invalid_referer) {
            # 重定向到登录页
            rewrite ^ http://example.com/login?ref=$request_uri redirect;
        }

        root /var/www/downloads;
    }
}

# 允许空 Referer（直接访问）
location /public/ {
    valid_referers none server_names;  # none 允许直接访问
    root /var/www/public;
}

valid_referers 参数说明

参数 说明
none 允许 Referer 头缺失的请求（直接访问）
blocked 允许 Referer 存在但被防火墙或代理删除的请求
server_names 允许 server_name 中配置的服务器名称
string 具体的 URL 或域名
*.example.com 匹配指定域名的所有子域名
~regex 正则表达式匹配

应用场景

  • 图片防盗链：防止其他网站直接引用图片资源
  • 视频防盗链：保护视频资源不被非法盗链
  • 下载保护：限制资源下载来源
  • 流量控制：防止带宽被外部网站消耗

12. ngx_http_secure_link_module (安全链接模块)

概述

ngx_http_secure_link_module 模块用于检查请求链接的真实性，保护资源不被未授权访问，通过 MD5 哈希和过期时间验证链接有效性。

核心指令

指令 语法 默认值 说明 上下文
secure_link secure_link expression; - 定义安全链接 MD5 值 http, server, location
secure_link_md5 secure_link_md5 expression; - 定义 MD5 计算表达式 http, server, location
secure_link_secret secure_link_secret word; - 定义密钥（简化版） location

配置示例

# 完整版安全链接配置
location /s/ {
    # 从请求参数获取 MD5 和过期时间
    secure_link $arg_md5,$arg_expires;
    secure_link_md5 "$secure_link_expires$uri$remote_addr secret_key";

    # $secure_link 变量值：
    # - 空字符串：链接无效
    # - "0"：链接已过期
    # - "1"：链接有效

    if ($secure_link = "") {
        return 403;
    }

    if ($secure_link = "0") {
        return 410;  # Gone，链接过期
    }

    # 链接有效，提供文件
    root /var/www/secure;
}

# 下载链接生成示例（Python）
# import hashlib
# import time
#
# secret = "secret_key"
# uri = "/s/file.pdf"
# expires = str(int(time.time()) + 3600)  # 1小时后过期
#
# md5_hash = hashlib.md5(f"{expires}{uri}127.0.0.1 {secret}".encode()).hexdigest()
# url = f"http://example.com{uri}?md5={md5_hash}&expires={expires}"

# 简化版安全链接
location /p/ {
    secure_link_secret my_secret_password;

    if ($secure_link = "") {
        return 403;
    }

    root /var/www/protected;
}

# 简化版链接格式：/p/md5_hash/filename
# MD5 生成：echo -n "filename secret" | md5sum

# 带 IP 限制的安全链接
location /download/ {
    secure_link $arg_md5,$arg_expires;
    secure_link_md5 "$secure_link_expires$uri$remote_addr my_secret";

    if ($secure_link = "") {
        return 403 "Invalid link";
    }

    if ($secure_link = "0") {
        return 410 "Link expired";
    }

    # 记录下载日志
    access_log /var/log/nginx/secure_downloads.log;

    # 限速下载
    limit_rate 1m;

    alias /var/www/downloads/;
}

# 不同路径不同密钥
location /premium/ {
    secure_link $arg_key,$arg_time;
    secure_link_md5 "$secure_link_expires$uri$remote_addr premium_secret";

    if ($secure_link != "1") {
        return 403;
    }

    root /var/www/premium;
}

应用场景

  • 临时下载链接：生成限时有效的下载链接
  • 付费内容保护：保护付费资源不被直接访问
  • 会员专享资源：为会员生成专属访问链接
  • 防盗链升级：比 referer 更安全的资源保护方案

13. ngx_http_split_clients_module (A/B 测试模块)

概述

ngx_http_split_clients_module 模块用于基于客户端 IP 地址或变量创建变量，实现 A/B 测试或按比例分流。

核心指令

指令 语法 默认值 说明 上下文
split_clients split_clients string $variable { ... } - 定义分流规则 http

配置示例

# 基本 A/B 测试配置
http {
    # 基于 remote_addr 分流
    split_clients "${remote_addr}AAA" $variant {
        50%               variant_a;
        40%               variant_b;
        *                 variant_c;  # 剩余 10%
    }

    server {
        listen 80;

        location / {
            add_header X-Variant $variant;

            if ($variant = "variant_a") {
                proxy_pass http://backend_a;
                break;
            }

            if ($variant = "variant_b") {
                proxy_pass http://backend_b;
                break;
            }

            proxy_pass http://backend_c;
        }
    }
}

# 灰度发布配置
http {
    split_clients "${http_cookie}AAA" $canary {
        10%               canary;
        *                 stable;
    }

    server {
        location / {
            if ($canary = "canary") {
                proxy_pass http://canary_backend;
                break;
            }

            proxy_pass http://stable_backend;
        }
    }
}

# 多版本测试
http {
    split_clients "${remote_addr}${http_user_agent}AAA" $version {
        33.33%            v1;
        33.33%            v2;
        *                 v3;
    }

    server {
        location / {
            proxy_set_header X-Version $version;
            proxy_pass http://backend_$version;
        }
    }
}

# 与 cookie 结合实现粘性分流
http {
    # 优先检查 cookie，没有则新建
    split_clients "${remote_addr}AAA" $ab_group {
        50%               A;
        *                 B;
    }

    map $cookie_ab_group $sticky_group {
        default  $cookie_ab_group;
        ""       $ab_group;
    }

    server {
        location / {
            add_header Set-Cookie "ab_group=$sticky_group; Path=/; Max-Age=2592000" always;

            if ($sticky_group = "A") {
                proxy_pass http://backend_a;
                break;
            }

            proxy_pass http://backend_b;
        }
    }
}

分流算法说明

参数 说明
string 用于计算哈希的字符串，通常包含 $remote_addr
percentage% 流量百分比（总和不能超过 100%）
* 匹配剩余所有流量

应用场景

  • A/B 测试：将流量分配到不同版本进行效果对比
  • 灰度发布：逐步将流量切换到新版本
  • 蓝绿部署：平滑切换生产环境
  • 流量分担：按比例分散到不同后端

14. ngx_http_ssi_module (SSI 模块)

概述

ngx_http_ssi_module 模块用于处理 SSI（Server Side Includes）命令，在服务器端将多个文件内容合并到响应中。

核心指令

指令 语法 默认值 说明 上下文
ssi ssi on | off; off 启用 SSI 处理 http, server, location, if in location
ssi_last_modified ssi_last_modified on | off; off 保留原始 Last-Modified http, server, location
ssi_min_file_chunk ssi_min_file_chunk size; 1k 最小文件块大小 http, server, location
ssi_silent_errors ssi_silent_errors on | off; off 静默处理错误 http, server, location
ssi_types ssi_types mime-type ...; text/html 处理 MIME 类型 http, server, location
ssi_value_length ssi_value_length length; 256 SSI 命令值最大长度 http, server, location

配置示例

# 基本 SSI 配置
server {
    listen 80;

    location / {
        ssi on;
        root /var/www/html;
    }
}

# 多类型 SSI 处理
server {
    ssi on;
    ssi_types text/html application/xhtml+xml;
    ssi_silent_errors on;

    location / {
        root /var/www/html;
    }
}

# 大型页面优化
server {
    ssi on;
    ssi_min_file_chunk 10k;  # 小于 10k 的文件不单独处理

    location / {
        root /var/www/html;
    }
}

# 局部禁用 SSI
server {
    ssi on;

    location / {
        root /var/www/html;
    }

    location /no-ssi/ {
        ssi off;
        root /var/www/static;
    }
}

SSI 命令示例

<!--# 包含其他文件 -->
<!--#include file="header.html" -->
<!--#include virtual="/header.html" -->

<!--# 包含远程内容 -->
<!--#include virtual="/remote/content" wait="yes" -->

<!--# 设置变量 -->
<!--#set var="name" value="value" -->
<!--#set var="docroot" value="$DOCUMENT_ROOT" -->

<!--# 条件判断 -->
<!--#if expr="$name = /test/" -->
    <p>匹配成功</p>
<!--#elif expr="$name = /other/" -->
    <p>其他匹配</p>
<!--#else -->
    <p>默认内容</p>
<!--#endif -->

<!--# 循环 -->
<!--#config timefmt="%A" -->

<!--# 显示文件信息 -->
<!--#flastmod file="file.html" -->
<!--#fsize file="file.html" -->

<!--# 调用 CGI -->
<!--#exec cmd="date" -->
<!--#exec cgi="/cgi-bin/script.cgi" -->

<!--# 完整示例：页面模板 -->
<!DOCTYPE html>
<html>
<head>
    <!--#set var="title" value="页面标题" -->
    <title><!--#echo var="title" --></title>
    <!--#include virtual="/common/head.html" -->
</head>
<body>
    <!--#include virtual="/common/header.html" -->

    <main>
        <h1><!--#echo var="title" --></h1>
        <p>页面内容</p>
    </main>

    <!--#include virtual="/common/footer.html" -->
</body>
</html>

SSI 变量

变量名 说明
DOCUMENT_NAME 当前文件名
DOCUMENT_URI 当前 URI
QUERY_STRING_UNESCAPED 未转义的查询字符串
DATE_LOCAL 本地时间
DATE_GMT GMT 时间
LAST_MODIFIED 最后修改时间

应用场景

  • 页面模板化：将公共部分（头尾）抽离为单独文件
  • 动态内容嵌入：在静态页面中嵌入动态内容
  • 多语言支持：根据条件加载不同语言内容
  • 内容组合：将多个内容源组合成一个页面

15. ngx_http_sub_module (文本替换模块)

概述

ngx_http_sub_module 模块用于替换响应中的指定字符串，可以在输出时动态修改内容。

核心指令

指令 语法 默认值 说明 上下文
sub_filter sub_filter string replacement; - 定义替换规则 http, server, location
sub_filter_last_modified sub_filter_last_modified on | off; off 保留 Last-Modified http, server, location
sub_filter_once sub_filter_once on | off; on 只替换第一次出现 http, server, location
sub_filter_types sub_filter_types mime-type ...; text/html 处理的 MIME 类型 http, server, location

配置示例

# 基本文本替换
location / {
    sub_filter 'http://old-domain.com' 'https://new-domain.com';
    proxy_pass http://backend;
}

# 多替换规则
location / {
    sub_filter 'Welcome' '欢迎';
    sub_filter 'Login' '登录';
    sub_filter 'Logout' '退出';
    sub_filter_once off;  # 替换所有出现
    proxy_pass http://backend;
}

# 变量替换
location / {
    sub_filter 'SERVER_TIME' $time_iso8601;
    sub_filter 'REMOTE_ADDR' $remote_addr;
    sub_filter_once off;
    proxy_pass http://backend;
}

# HTML 注入
location / {
    sub_filter '</head>' '<script src="/analytics.js"></script></head>';
    sub_filter '</body>' '<footer>Copyright 2024</footer></body>';
    proxy_pass http://backend;
}

# 链接替换为绝对路径
location / {
    sub_filter 'href="/' 'href="https://cdn.example.com/';
    sub_filter 'src="/' 'src="https://cdn.example.com/';
    sub_filter_once off;
    sub_filter_types text/html text/css;
    proxy_pass http://backend;
}

# 开发环境提示
location / {
    sub_filter '<body>' '<body><div style="background:yellow;padding:10px;">开发环境</div>';
    proxy_pass http://backend;
}

# 完整示例：CDN 替换
server {
    listen 80;
    server_name cdn.example.com;

    location / {
        proxy_pass http://origin_backend;

        # 替换资源链接到 CDN
        sub_filter 'href="/static/' 'href="https://cdn.example.com/static/';
        sub_filter 'src="/static/' 'src="https://cdn.example.com/static/';
        sub_filter_once off;
        sub_filter_types text/html application/javascript text/css;

        # 保留缓存头
        sub_filter_last_modified on;
    }
}

配置参数说明

参数 说明
sub_filter_once on 只替换每个响应中的第一个匹配项
sub_filter_once off 替换所有匹配项
sub_filter_last_modified on 保留原始 Last-Modified 头（用于缓存）
sub_filter_types 指定处理的 MIME 类型

应用场景

  • 域名迁移：批量替换旧域名为新域名
  • CDN 集成：将资源链接替换为 CDN 地址
  • 内容本地化：替换页面中的特定文本
  • 环境标识：添加开发/测试环境标识
  • 分析代码注入：动态注入统计代码

16. ngx_http_userid_module (用户 ID 模块)

概述

ngx_http_userid_module 模块用于设置 cookie 以标识客户端，实现用户跟踪和会话管理。

核心指令

指令 语法 默认值 说明 上下文
userid userid on | v1 | log | off; off 启用用户 ID http, server, location
userid_domain userid_domain name | none; none cookie 域 http, server, location
userid_expires userid_expires time | max | off; off cookie 过期时间 http, server, location
userid_flags userid_flags off | flag ...; none cookie 标志 http, server, location
userid_mark userid_mark letter | digit | = | off; off 标记字符 http, server, location
userid_name userid_name name; UID cookie 名称 http, server, location
userid_p3p userid_p3p string | none; none P3P 头 http, server, location
userid_path userid_path path; / cookie 路径 http, server, location
userid_service userid_service number; IP 地址最后一段 服务标识 http, server, location

配置示例

# 基本用户 ID 配置
server {
    listen 80;

    userid on;
    userid_name uid;
    userid_domain example.com;
    userid_path /;
    userid_expires 365d;
}

# 完整用户跟踪配置
server {
    listen 80;
    server_name track.example.com;

    userid on;
    userid_name _uid;
    userid_domain .example.com;   # 跨子域
    userid_path /;
    userid_expires max;            # 浏览器会话
    userid_flags httponly secure;  # 安全标志

    location / {
        proxy_pass http://backend;
        proxy_set_header X-User-ID $uid_got$uid_set;
    }
}

# 仅日志记录模式
server {
    userid log;  # 不设置 cookie，只记录已有 ID

    log_format uid '$remote_addr - $uid_got [$time_local] '
                   '"$request" $status';
    access_log /var/log/nginx/uid.log uid;
}

# 多站点统一 ID
http {
    userid_name _ga;
    userid_domain .example.com;
    userid_path /;
    userid_expires 2y;

    server {
        server_name www.example.com;
        userid on;
    }

    server {
        server_name blog.example.com;
        userid on;
    }

    server {
        server_name shop.example.com;
        userid on;
    }
}

# 与日志结合
server {
    userid on;
    userid_name session_id;

    log_format tracking '$remote_addr $uid_got $request_time '
                        '"$request" $status';

    access_log /var/log/nginx/tracking.log tracking;
}

Cookie 版本

版本 说明
v1 使用 Base64 编码，默认版本
on 同 v1
log 不设置新 cookie，仅记录现有 ID
off 禁用

可用变量

变量名 说明
$uid_got 客户端发送的 cookie 值
$uid_set 设置的 cookie 值
$uid_reset 重置 cookie 的标志

应用场景

  • 用户行为跟踪：追踪用户跨页面访问行为
  • A/B 测试：识别用户所属的测试组
  • 会话管理：配合应用实现会话跟踪
  • 访问统计：分析用户访问模式和频次
  • 广告追踪：记录用户来源和转化

附录：模块编译与加载

静态编译

# 配置时启用模块
./configure \
    --with-http_ssl_module \
    --with-http_realip_module \
    --with-http_geoip_module \
    --with-http_sub_module \
    --with-http_addition_module \
    --with-http_auth_request_module \
    --with-http_secure_link_module \
    --with-http_slice_module \
    --with-http_stub_status_module

make && make install

动态模块加载

# nginx.conf
load_module modules/ngx_http_geoip_module.so;

http {
    # 使用模块
}

检查已编译模块

# 查看编译参数
nginx -V

# 查看已加载模块
nginx -V 2>&1 | tr ' ' '\n' | grep module

模块组合使用示例

# 综合应用示例：安全且可追踪的文件下载

http {
    # 真实 IP 获取
    set_real_ip_from 10.0.0.0/8;
    real_ip_header X-Forwarded-For;

    # 用户 ID 跟踪
    userid on;
    userid_name download_id;
    userid_expires 1d;

    # 地理位置
    geoip_country /usr/share/GeoIP/GeoIP.dat;

    server {
        listen 80;
        server_name download.example.com;

        # 访问控制
        location /premium/ {
            # 基础认证
            auth_basic "Premium Downloads";
            auth_basic_user_file /etc/nginx/premium.htpasswd;

            # 防盗链
            valid_referers none blocked *.example.com;
            if ($invalid_referer) {
                return 403;
            }

            # 安全链接验证
            secure_link $arg_md5,$arg_expires;
            secure_link_md5 "$secure_link_expires$uri$remote_addr secret";

            if ($secure_link = "") {
                return 403;
            }

            if ($secure_link = "0") {
                return 410;
            }

            # 日志记录
            access_log /var/log/nginx/premium_downloads.log;

            alias /var/www/premium/;
        }
    }
}