Nginx日志过滤敏感信息及log_format自定义变量失效问题

API 探路者

2026-5-20

针对Nginx 1.2.5日志自定义变量与敏感信息过滤的解决方案

核心问题分析

你遇到的问题主要和Nginx 1.2.5的版本特性、变量作用域及配置规范有关：

自定义变量不生效：大概率是log_format定义位置错误（比如放在了server块内），或者set指令的作用域未覆盖到所有请求；
$arg_password被置空：默认情况下Nginx不会自动清空该变量，可能是配置误操作（比如用了unset）、参数未实际传递，或是第三方模块干扰。

正确配置步骤

1. 严格遵循log_format定义规则（必须在http块）

Nginx 1.2.5中log_format只能在http块级别定义，不能放在server或location内，否则格式完全不生效，会导致日志空行或异常。

我们结合map模块（1.2.5已支持）实现敏感参数过滤，同时配置自定义变量：

http {
    # 第一步：用map过滤敏感请求参数
    map $args $filtered_args {
        default $args; # 默认保留所有参数
        # 匹配password参数，替换为***
        ~*password=[^&]+ $masked_password;
        # 可扩展匹配secret/key等其他敏感参数
        ~*secret=[^&]+ $masked_secret;
    }

    # 单独处理password的替换逻辑
    map $args $masked_password {
        ~*(password=)[^&]+ $1***;
    }

    # 单独处理secret的替换逻辑
    map $args $masked_secret {
        ~*(secret=)[^&]+ $1***;
    }

    # 第二步：定义自定义日志格式，引用变量
    log_format custom_request_log '$remote_addr - $remote_user [$time_local] '
                                 '"$request_method $uri $server_protocol" '
                                 '$status $body_bytes_sent '
                                 '"$http_referer" "$http_user_agent" '
                                 'FilteredParams: "$filtered_args" '
                                 'CustomVar: "$yyy"';

    server {
        listen 80;
        server_name your-domain.com;

        # 第三步：设置全局自定义变量（server块内，确保所有请求都能触发）
        set $yyy 'abc';

        location / {
            root /path/to/your/webroot;
            index index.html;
        }

        # 第四步：指定使用自定义日志格式
        access_log /var/log/nginx/custom_access.log custom_request_log;
    }
}

2. 排查自定义变量不生效的常见坑

作用域问题：如果把set $yyy 'abc'放在某个特定location里，只有匹配该location的请求才会有变量值，其他请求的$yyy会是空的。要全局生效就放在server块里；
配置重载：修改配置后必须执行nginx -s reload，老版本偶尔需要重启Nginx才能完全生效；
语法错误：用nginx -t检查配置语法，避免因括号、引号缺失导致配置失效。

3. 解决$arg_password置空问题

先做基础测试确认变量是否能正常获取：

log_format test_log '$arg_password';
access_log /var/log/nginx/test_pass.log test_log;

发起请求http://your-domain.com?password=123456，查看日志是否显示123456：

如果没有，检查请求是否真的传递了参数；
排查配置中是否有unset $arg_password这类指令；
若安装了第三方安全模块，尝试临时禁用后测试是否恢复正常。

验证配置

修改后先检查语法：

nginx -t

确认无误后重载配置：

nginx -s reload

发起测试请求后查看日志，确认：

自定义变量$yyy显示为abc；
敏感参数（如password）被替换为***；
日志无空行，请求信息正常记录。

内容的提问来源于stack exchange，提问作者unional