NGINX 变量

说明

NGINX 中的 $http_user_agent 变量用于获取来自入站 HTTP 请求的 User-Agent 字符串。该字符串标识发起请求的客户端软件，通常包括客户端的浏览器类型、版本和操作系统等信息。User-Agent 头通常由网页浏览器、移动应用和各种用户代理设置，用于告知服务器它们的能力和特性。需要注意的是，该变量在服务器接收请求时的请求处理阶段被填充，可用于日志记录、处理或条件配置。 当 NGINX 服务器处理入站请求时，它会解析各种 HTTP 头，其中就包括 User-Agent。如果请求中存在 User-Agent 头，则其值会存储在 $http_user_agent 变量中，从而允许服务器管理员根据发起请求的客户端类型制定规则。例如，管理员可能会根据 User-Agent 字符串向不同的浏览器或设备提供不同的内容。该变量的典型值可能包括像 "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.124 Safari/537.36" 这样的字符串（适用于 Google Chrome），或像 "Mozilla/5.0 (iPhone; CPU iPhone OS 14_0 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/14.0 Mobile/15E148 Safari/604.1" 这样的字符串（适用于 iOS 上的 Safari）。

配置示例

server {
    listen 80;

    location / {
        access_log /var/log/nginx/access.log;
        if ($http_user_agent ~* "MSIE") {
            return 403;  # Deny access to Internet Explorer users
        }
        # other configuration...
    }
}

说明

$http_referer 变量在 NGINX 中用于访问 'Referer' HTTP 请求头的值，该头指示链接到被请求资源的网页的 URL。此变量可以帮助确定访客来自何处，使服务器管理员能够根据来源页面执行相应逻辑。例如，如果某个网站提供推荐奖励，它可以使用此变量来跟踪用户是否来自联盟站点。 $http_referer 的值由浏览器发送的 HTTP 头决定。如果浏览器不发送 Referer 头（例如由于用户的隐私设置），该变量将为空。该变量的典型值包括网站的 URL，但在安全上下文中或跨协议重定向时（例如从 HTTPS 到 HTTP）也可能不存在。因此，在配置或脚本中处理该变量可能为空的情况以避免意外行为非常重要。 此外，在将此变量用于记录或决策等用途时，必须确保对其进行适当的清理或校验，因为客户端可能会篡改它。该变量通常用于访问控制、日志记录或重定向规则，从而基于请求来源实现更细粒度的控制。

配置示例

location /example {
    if ($http_referer ~* "example.com") {
        return 403;
    }
}

说明

`$http_via` 变量在 NGINX 中用于访问来自 HTTP 请求的 'via' 头的值。该头通常由 web 代理添加，用于指示请求经过的中间服务器，从而提供关于请求路由以及相关缓存机制的洞察。当客户端通过一个或多个代理发送请求时，每个代理都会附加 'via' 头，串联这些信息，使下游服务器能够分析请求路径。\n\n当 NGINX 处理传入请求的头时，会自动设置此变量。如果存在 'via' 头，`$http_via` 将保存其值；如果请求经过多个代理，值可能包含多段信息。该头的常见值可能包括代理服务器的软件及其版本等详细信息。如果请求没有 'via' 头，则该变量为空，这允许在服务器配置中根据该头的存在与否进行条件逻辑。

配置示例

server {
    listen 80;
    location / {
        if ($http_via) {
            add_header X-Proxy-Server $http_via;
        }
        proxy_pass http://backend;
    }
}

说明

$http_x_forwarded_for 变量在 NGINX 中用于提取 X-Forwarded-For HTTP 头的值，该头通常由请求链中的代理添加以指示客户端的源 IP 地址。当请求经过一个或多个代理时，原始客户端的 IP 地址会被包含在此头中，从而使下游服务器能够获取该信息。它可以包含单个 IP 地址，或以逗号分隔的 IP 列表，表示客户端地址以及处理请求的后续代理。 通常，X-Forwarded-For 头的值会看起来像这样："203.0.113.195"（示例为直接 IP），如果存在代理则可能是 "203.0.113.195, 198.51.100.0"。在配置 NGINX 时，可以在访问日志、条件配置或安全检查中使用此变量，以根据客户端的原始地址允许或拒绝访问。重要的是确保任何配置正确处理收到的头值，尤其是在请求链中存在多个代理时，以避免错误地识别客户端的 IP。 NGINX 仅在客户端发送了 X-Forwarded-For 头时才会设置此变量。在有多个后端服务器需要确定真实客户端 IP 的负载均衡环境中，这个变量尤其有用。用户应注意，如果没有采取适当的安全措施，该头很容易被伪造，因此在安全相关的场景中需要对其进行验证。

配置示例

http {
    log_format custom '$remote_addr - $remote_user [$time_local] "$request" $status $body_bytes_sent "http://$http_x_forwarded_for"';
    access_log /var/log/nginx/access.log custom;

    server {
        listen 80;
        server_name example.com;

        location / {
            # Use $http_x_forwarded_for for access control
            if ($http_x_forwarded_for ~* '203.0.113.195') {
                return 403;
            }
            proxy_pass http://backend_servers;
        }
    }
}

说明

在 NGINX 中，$http_cookie 变量用于访问客户端在 HTTP 请求中发送的 Cookie 头的值。该变量在 NGINX 处理请求并遇到客户端提供的 Cookie 头时被设置。通常，$http_cookie 将包含每个 cookie 的名值对字符串，名值对以分号分隔。例如，如果请求包含 'Cookie: user_id=12345; session_token=abcde;'，那么 $http_cookie 会返回 'user_id=12345; session_token=abcde'。 该变量对依赖 cookie 进行会话管理、跟踪用户状态或根据用户偏好个性化内容的 Web 应用特别有用。可以在诸如 server、location 或 if 指令等不同上下文中访问它。使用此变量时，应注意其输出可能取决于客户端浏览器中设置的 cookie，以及这些 cookie 是否被 NGINX 配置中的相关指令允许或修改。 鉴于 cookie 可能包含敏感信息，建议谨慎处理此变量，以避免在日志或错误消息中无意暴露数据，并在应用逻辑中确保尊重 secure 和 HTTP-only cookie 标志。

配置示例

location / {
    if ($http_cookie ~* "session_id") {
        # Logic that depends on the session_id cookie
    }
}

说明

NGINX 中的 $content_length 变量提供包含在 'Content-Length' HTTP 头中的请求体长度。只有在该头存在的请求（通常为 POST 和 PUT 方法）中才会设置该变量。如果客户端未发送 'Content-Length' 头，该变量将为空。该变量主要用于处理已知内容大小的请求，允许基于传入数据大小执行条件逻辑。 在处理请求时，NGINX 在解析入站请求头后设置 $content_length。如果指定了 'Content-Length' 头，它将保存该数值；但是如果该头缺失或格式不正确，$content_length 将不会反映有效的大小。实际上，该变量的有效值严格为非负整数，表示请求体的字节数。开发者通常使用该变量来施加大小限制、记录请求大小，或更高效地有条件地处理大载荷。

配置示例

http {
    server {
        listen 80;

        location /upload {
            if ($content_length > 10000) {
                return 413;  # Request entity too large
            }
        }
    }
}

说明

$content_type 变量在 NGINX 中在处理响应时会被自动设置，用来表示该响应的 Content-Type 头。通常，它用于指示返回资源的媒体类型，遵循 RFC 6838 定义的格式。常见值包括用于 HTML 文档的 'text/html'、用于 JSON 响应的 'application/json' 以及用于 PNG 图像的 'image/png'。 此变量在请求处理阶段被设置，可以被影响响应的各种指令所修改，例如 'add_header'、'default_type' 和 'types'。当 NGINX 提供静态文件时，Content-Type 根据文件扩展名和在 'http' 区块或特定 'server' 或 'location' 上定义的配置设置来确定。例如，如果请求的是扩展名为 '.html' 的文件，$content_type 通常会被设置为 'text/html'。 在未显式设置类型的情况下，如果存在 'default_type' 指令，NGINX 会默认使用该指令提供的值，否则该变量可能保持未设置。

配置示例

location /images/ {
    types {
        image/png png;
        image/jpeg jpg;
        image/gif gif;
    }
    default_type application/octet-stream;
    add_header Content-Type $content_type;
}

说明

当处理传入请求时，$host 变量非常关键，因为它直接从 Host 请求头或 NGINX 配置中相应配置的服务器名称中提取主机名。当有请求到来时，NGINX 会检查 Host 头；如果存在，则使用该头的值来设置 $host 变量。如果该头不存在，NGINX 则回退到使用处理该请求的 server block 中配置的服务器名称。此行为允许 NGINX 对指向同一服务器实例的不同域名或子域名的请求做出适当响应。 该变量通常被赋值为与客户端访问的域名或 IP 地址相对应的值。例如，如果用户请求 "http://example.com/path"，那么 $host 变量将包含 "example.com"。如果请求未指定主机名且 server block 已定义默认服务器，则 $host 将保存该服务器的名称。需要注意，如果 NGINX 针对不同主机名配置了多个 server block，则 $host 的值对于基于传入 URL 将请求路由到正确的块非常关键。 $host 变量在 server_name 指令存在与否时也可能表现不同。如果配置在某个 server block 中的服务器名称包含通配符或正则，则 $host 的实际值可能会受处理请求时找到的具体匹配结果影响。这确保了请求能够基于特定主机名被正确服务，从而在单个 NGINX 服务器实例上实现多租户配置。

配置示例

server {
    listen 80;
    server_name example.com;

    location / {
        return 200 "Host is: $host";
    }
}

说明

NGINX 中的 $binary_remote_addr 变量用于获取与请求关联的客户端 IP 地址的二进制格式。该变量在访问控制和过滤配置中尤其有用。当接收到请求时，NGINX 会检索客户端的 IP 地址，并将其转换为 32-bit 或 128-bit 的二进制格式，具体取决于客户端使用的是 IPv4 还是 IPv6。通过使用该变量，系统管理员可以在各种访问控制设置（例如 'allow' 和 'deny'）中高效地比较和匹配 IP 地址。\n\n通常，该变量在请求的初始处理期间设置，从包含客户端地址信息的 'sockaddr' 结构中填充。二进制表示使 NGINX 能够直接对允许或拒绝的 IP 列表进行快速比较和检查，而无需在格式之间来回转换。由于它是二进制形式，该变量在处理访问控制指令时对 NGINX 来说效率要高得多，尤其是在高吞吐量场景中。

配置示例

http {
    server {
        location / {
            deny 192.168.1.1;
            allow all;
        }
    }
}

说明

当客户端向服务器发出请求时，NGINX 会填充变量 $remote_addr。它直接从请求的 socket 信息获取客户端的 IP 地址，具体来自与连接关联的 `struct sockaddr`。该变量在访问控制和日志记录场景中至关重要，在这些场景中，了解请求的源 IP 可以决定响应行为或记录来源以便审计。 如果 NGINX 服务器位于反向代理或负载均衡器之后，可能需要结合其他变量（例如 $http_x_forwarded_for）来补充 $remote_addr，以准确反映客户端的原始 IP 地址。在标准配置中，该值通常是 IPv4 或 IPv6 地址，分别用点分十进制或冒号分隔的格式表示。 在将此变量用于访问控制设置时（例如使用 allow/deny 指令），服务器可以基于客户端 IP 做出实时决策，通过允许或阻止特定 IP 的访问来增强安全性。该变量的多功能性使其成为 NGINX 中安全性和分析配置的基础元素。

配置示例

location / {
    deny 192.168.1.0/24;
    allow all;
    access_log /var/log/nginx/access.log combined;
}

说明

$remote_port 变量是一个内置的 NGINX 变量，用于捕获客户端与服务器建立连接时所使用的 TCP 端口号。它主要用于日志记录和基于请求源端口的访问控制。该变量在请求处理过程中被设置，具体是在 NGINX 处理传入连接并初始化请求结构（用于存储各种与客户端相关的详细信息）时。 当客户端连接到服务器时，远端端口由操作系统确定并提供给 NGINX。在典型场景中，该端口号可以在 1024 到 65535 之间，因为 1-1023 范围内的端口被保留给众所周知的服务。它也可能经常变化，因为客户端可能来自不同的应用或环境，从而分配到不同的端口号。NGINX 在指令（例如通过 'log_format' 进行日志记录）中使用此变量，并在访问控制规则中根据源端口范围允许或拒绝请求。

配置示例

server {
    listen 80;
    location / {
        access_log /var/log/nginx/access.log 'Client IP: $remote_addr, Port: $remote_port';
    }
}

说明

变量 $proxy_protocol_addr 是 NGINX 对 PROXY protocol 支持的一部分，该协议允许通过代理服务器传递原始客户端 IP 地址。当客户端连接到启用了 PROXY protocol 支持的 NGINX 服务器时，NGINX 可以解析代理发送的 PROXY protocol 头并提取原始客户端地址。这使 NGINX 能够正确记录请求时使用客户端的实际 IP 地址，而不是本来会被记录的代理的 IP 地址。 该变量通常用于 NGINX 部署在实现了 PROXY protocol 的负载均衡器或反向代理后面的场景。只有当传入连接包含相应的 PROXY protocol 头时，该变量才会被填充；在其他情况下，通常返回空值。直接连接到 NGINX 的客户端无法从该变量中受益，并且它会显示最后一个代理的 IP。根据客户端的连接类型，该变量通常包含 IPv4 或 IPv6 地址之一。

配置示例

server {
    listen 80 proxy_protocol;
    location / {
        proxy_pass http://backend;
        add_header X-Real-IP $proxy_protocol_addr;
    }
}

说明

$proxy_protocol_port 变量在 NGINX 中用于检索 PROXY protocol 报头中指定的端口号，该端口号对应已被代理的连接。它主要在 NGINX 作为反向代理或 负载均衡器 的配置中相关，允许服务器准确识别客户端连接的原始端口。此信息对于日志记录、安全措施或后端服务器的决策可能至关重要。 该变量仅在 upstream server block 中启用 PROXY protocol 时被设置。如果未使用 PROXY protocol，则该变量不会包含有效值，实际解析为 0。该变量的典型值为原始端口号，例如用于 HTTP 和 HTTPS 流量的 80 或 443。使用 $proxy_protocol_port 可以提供关于传入请求的更多上下文，这在多层架构中尤为有价值，因为后端处理可能依赖于原始客户端端口。

配置示例

server {
    listen 80 proxy_protocol;
    location / {
        add_header X-Proxy-Port $proxy_protocol_port;
    }
}

说明

$proxy_protocol_server_addr 变量主要用于涉及 proxy protocol 的配置。proxy protocol 是一项功能，允许 NGINX 在通过另一层（例如 AWS ELB 或其他 reverse proxies）代理请求时接收原始客户端的 IP 地址和端口。该变量在使用 'proxy_protocol' 指令在 server 或 location 块上启用 proxy protocol 时被填充。其值反映了从 proxy protocol 报头解析出的客户端 IP 地址，因此对于基于真实客户端地址而非直接代理地址进行准确的日志记录或访问控制至关重要。 当该变量被设置时，可以显著提高指标和日志的准确性，因为可以跟踪实际客户端地址而不是 reverse proxy 的 IP。如果未使用 proxy protocol 或未正确配置，$proxy_protocol_server_addr 的值将为空字符串。因此，通常会将此变量与其他代理变量结合使用，以确保正确捕获原始客户端的信息。

配置示例

server {
    listen 80 proxy_protocol;
    location / {
        access_log /var/log/nginx/access.log '$proxy_protocol_server_addr';
    }
}

说明

在 NGINX 配置中，变量 $proxy_protocol_server_port 用于检索服务器从 PROXY protocol 头部接收到的端口号。该变量在启用 PROXY protocol 时尤其重要，允许 NGINX 在位于转发客户端连接信息的代理之后时识别原始端口。处理请求时，如果在 server 块中通过 'proxy_protocol on' 指令启用了 PROXY protocol，服务器端口号将根据代理传递的传入连接信息动态设置。例如，如果请求通过端口 80 到达，那么引用 $proxy_protocol_server_port 将得到该值。该变量对于配置 SSL 终止或根据连接最初使用的端口在任何转换之前正确重定向流量非常有用。根据配置和代理服务器的转发行为，它的典型值可能为 '80'（HTTP）或 '443'（HTTPS）。

配置示例

server {
    listen 80 proxy_protocol;
    location / {
        return 200 "Server port: $proxy_protocol_server_port";
    }
}

说明

$proxy_protocol_tlv_ 变量是 NGINX 中带前缀的变量，用于在使用 Proxy Protocol 时检索特定的 Type-Length-Value (TLV) 数据。该协议常用于负载均衡场景，以结构化格式将连接信息（例如客户端 IP 地址）从代理服务器传输到后端服务器。每个 TLV 数据项可以通过一个后缀来访问，该后缀标识所请求的具体信息。 当 NGINX 被配置为从直接客户端连接接收 Proxy Protocol 时，通常会设置这些变量，例如在接收来自也实现该协议的负载均衡器或代理服务器的流量时。常见的 TLV 类型可能包括诸如客户端地址、端口号和其他头部数据等信息。这种附加功能使后端服务器能够基于通常由于 NAT 或其他网络设置而掩盖真实客户端 IP 的客户端数据做出更有依据的决策。 例如，如果某个 TLV 项目使用与客户端地址信息相对应的后缀指定，则该变量将返回由代理发送的相关信息。如果上游代理服务器未提供对应的 TLV 数据，该变量将为空或未设置。在需要基于来源客户端详细信息进行精确流量记录或定制的场景中，这种行为尤其有用，从而提升整体应用性能和用户体验。

配置示例

server {
    listen 80 proxy_protocol;

    location / {
        default_type text/plain;
        return 200 "Client IP: $proxy_protocol_tlv_client_ip\n";
    }
}

说明

`$server_addr` 变量是 NGINX Core 模块的一部分，提供响应请求的服务器的实际 IP 地址。该变量在处理请求期间设置，特别是在 TCP/IP 通信的上下文中，使其能够反映客户端所连接的地址。如果服务器有多个 IP 地址或位于负载均衡器后面，`$server_addr` 将表示 NGINX 用于响应传入客户端请求的主地址。 该变量在日志记录或构建响应头时尤其有用。值得注意的是，`$server_addr` 反映请求被处理时的地址，并且在请求被传递给任何 `location` 块或处理器之前就已确定。在 NGINX 运行而没有特定绑定服务器 IP 的场景（例如在 IP 可能会改变的容器化环境中），可能需要对该变量进行适当配置，以确保它始终返回有效地址。通常，它将返回 IPv4 或 IPv6 地址，具体取决于服务器的配置和客户端请求的性质。

配置示例

server {
    listen 80;
    server_name example.com;
    location / {
        add_header X-Server-IP $server_addr;
        # other configurations
    }
}

说明

$server_port 变量在 NGINX 中会在请求处理过程中动态设置，用于表示服务器监听传入连接的端口。它在配置可能根据端口号而变化的响应时特别有用，例如启用特定的响应头或应用防火墙规则。该变量同时考虑配置中指定的端口和客户端用来发起请求的端口，在多端口设置中提供了清晰的指示。 通常当在 NGINX 配置文件中定义 server block 时会设置该变量。例如，如果某个 server block 配置为监听端口 80，则任何到达该端口的请求都会将 $server_port 变量设为 80。相反，如果 server block 监听的是诸如 443（通常用于 HTTPS）这样的备用端口，变量将反映该值。正因为如此，$server_port 在构建需要区分例如 HTTP 和 HTTPS 流量的配置时是不可或缺的，同时在管理能够运行在非标准端口的应用时也很有用。 $server_port 的典型取值包括 HTTP 的 80、HTTPS 的 443，或任何其他用户定义的端口。该变量不包含协议（HTTP/HTTPS），只关注端口号本身，从而为各种服务器配置提供了灵活性和精确性。

配置示例

server {
    listen 80;
    server_name example.com;

    location / {
        add_header X-Server-Port "$server_port";
    }
}

说明

$server_protocol 变量在 NGINX 中会在处理请求时动态设置，并返回客户端用于连接到服务器的协议版本。该变量在日志记录、条件配置和响应处理等方面特别有用，因为它允许你区分不同的协议版本，例如 HTTP/1.0、HTTP/1.1 或 HTTP/2.0。 通常，该变量在服务器的请求阶段设置，可在多个上下文中使用，包括 http、server 和 location 块。当请求到达 NGINX 服务器时，模块会评估传入请求的详细信息并相应地填充 $server_protocol 变量。其典型值是类似 "HTTP/1.1"、"HTTP/2" 等字符串，但它反映了与客户端在连接建立阶段协商的确切协议。 对于开发人员和系统管理员来说，理解 $server_protocol 变量很重要，因为它可以作为安全策略或功能开关的依据。例如，你可能希望根据连接是否通过 HTTPS 或 HTTP 建立来允许或拒绝访问。记录协议还可以为性能和安全分析提供有价值的洞见。

配置示例

server {
    listen 80;
    server_name example.com;

    location / {
        add_header X-Protocol $server_protocol;
    }
}

说明

$scheme 变量在确定客户端用来向服务器发起请求的协议时至关重要。它会检查与 NGINX 服务器的连接是否使用了 HTTPS 或 HTTP。当请求通过 HTTPS 发起时，$scheme 变量将返回 'https'；而对于 HTTP 请求，则返回 'http'。该变量通常在 NGINX 核心处理请求时设置，其值由服务器上是否存在有效的 SSL 证书决定。因此，如果配置了 SSL 且请求是安全的，变量会被设置为 'https'，否则默认值为 'http'。 还应注意，脚本、重定向或其他配置选项常常使用该变量来在响应输出或 HTTP headers 中生成正确的 URL。例如，在重定向用户或动态构建链接时，使用 $scheme 变量可确保链接根据用户访问服务器的方式引用相应的协议。因此，在同时存在安全和非安全访问的环境中，它起着关键作用。

配置示例

server {
    listen 80;
    server_name example.com;

    location / {
        return 301 $scheme://www.example.com$request_uri;
    }
}

说明

$https 变量是 NGINX 的一个内置变量，用于判断当前请求是否通过 HTTPS 处理。当请求通过安全连接处理时，$https 被设置为 'on'。如果请求不安全（即通过 HTTP 提供），该变量返回 'off'。该变量在将 HTTP 流量重定向到 HTTPS 或根据连接的安全性配置条件响应时特别有用。 $https 变量的值通常在 NGINX 配置了正确的 SSL 证书并监听 HTTPS 端口时被设置。例如，如果某个 NGINX server 块指定了 SSL 证书并监听端口 443，则该块的传入请求中 $https 将被设置为 'on'。相反，如果没有 SSL 配置且服务器监听端口 80，则该变量将为 'off'。需要注意的是，该变量只有 'on' 或 'off' 两种取值。

配置示例

server {
    listen 443 ssl;
    server_name example.com;
    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    location / {
        if ($https = off) {
            return 301 https://$host$request_uri;
        }
        # Handle the secure request
    }
}

说明

在 NGINX 中，$request_port 变量表示接收自客户端的请求所使用的端口。该变量在处理请求时被设置，其值来源于请求头中指定的客户端连接信息。当客户端发出 HTTP 或 HTTPS 请求时，请求会根据匹配条件被路由到指定的 server block，其中匹配条件包括端口号。对于标准的 HTTP 请求，通常为端口 80；对于 HTTPS 请求，通常为端口 443。 如果请求使用了非标准端口，$request_port 将反映该具体端口号。例如，如果客户端连接到端口 8080，则 $request_port 的值将是 "8080"。需要注意的是，在使用像 HTTP/2 这样的协议时，端口可能会被动态协商，但 NGINX 仍会在 $request_port 变量中捕获并反映用于该连接的端口号。了解该值有助于日志记录、条件配置，或在基于接收端口重写 URL 时使用。

配置示例

server {
    listen 80;
    location / {
        return 200 "Request received on port: $request_port";
    }
}

说明

`$is_request_port` 变量用于确定传入的 HTTP 请求是否是在非标准端口上发起的，从而允许服务器区分在标准端口（HTTP 的 80 端口和 HTTPS 的 443 端口）上发起的请求与在其它端口上发起的请求。该变量在请求处理阶段进行求值，具体是在请求被解析时且到达任何处理器之前。 当该变量被设置时，如果请求是在一个备用端口上发起的，则其值为 '1'；如果请求是在标准的 HTTP 或 HTTPS 端口上发起的，则其值为 '0'。这在需要根据请求来源端口应用特定配置、日志记录或访问规则的场景中尤其有用。该变量由 NGINX 根据传入请求的套接字信息自动初始化，无需手动配置。 开发者通常将此变量与访问控制指令或条件块结合使用，以根据请求是发往标准端口还是非标准端口来提供定制响应或日志记录，从而加强针对客户端请求的服务器行为控制。

配置示例

server {
    listen 8080;
    location / {
        if ($is_request_port) {
            return 403;  # Deny access from non-standard ports
        }
        # Other configurations...
    }
}

说明

$request_uri 变量是 NGINX 的一个核心变量，用于捕获客户端请求的完整 URI。它包括路径和查询字符串（如果有）。它在请求处理期间被设置，具体是在 NGINX 从客户端读取请求行时，这使得可以基于该 URI 创建响应。该变量对于请求路由、生成日志以及根据需要创建重定向或重写非常重要。 $request_uri 的典型值可以是类似 "/products/item?id=123" 或 "/api/v1/users" 的路径，前者包含查询字符串而后者不包含。这使得 $request_uri 成为从用户角度引用精确请求的全面方式。它通常与其他变量结合使用，用于记录请求、控制访问，并根据请求的类型或参数优化响应行为。

配置示例

location /api {
    if ($request_uri ~* "/products") {
        # Handle product requests
        proxy_pass http://backend;
    }
}

location / {
    log_format main '$remote_addr - $remote_user [$time_local] "$request $request_uri" $status $body_bytes_sent';
    access_log /var/log/nginx/access.log main;
}

说明

该 $uri 变量在 NGINX 处理 HTTP 请求期间被设置，主要填充为未转义的请求 URI，即 URL 中域名和协议之后的部分。该变量可以包含所请求资源的路径和查询字符串，但不会包含任何额外 server 或 location 指令的修改。$uri 的值在请求处理的早期确定，通常是在 NGINX 解析客户端请求时。这意味着它反映的是客户端最初发送的值，在任何内部重写或重定向之前。 在 server 配置中使用时，$uri 变量允许你基于实际请求的资源做出决定。它在 location 块中尤其有用，可用于访问控制、日志记录或重定向流量。该值通常是表示文件路径或路由的字符串，格式示例为 '/images/photo.jpg' 或 '/api/v1/users'。需要注意的是，如果请求在不同的 location 块中被处理并且该块重写了 URI，则 $uri 将反映该更改。

配置示例

location /images {
    alias /var/www/images;
    error_page 404 = /404.html;
}

location /api/v1 {
    proxy_pass http://backend;
    access_log /var/log/nginx/api_access.log;
    if ($uri ~* /user/(\d+)) {
        # Do something specific for user URIs
    }
}

说明

$document_uri 变量在 NGINX 处理请求时被设置，表示用于识别被请求资源的 URI 部分。与包含查询字符串的 $request_uri 变量不同，$document_uri 严格只包含 URI 路径，因此适用于不需要查询字符串的场景。该变量在记录或日志中尤其有用，能够在服务器上跟踪被访问的 URI，从而记录意图资源请求而不受任何 URL 查询参数的干扰。 $document_uri 的值是在请求经过 NGINX 路由系统处理之后确定的，具体是在 location 上下文中。这意味着它可以反映 NGINX 关于 URI 重写或使用特定 location 块所做的决定。$document_uri 的典型值可以从像 "/index.html" 这样的简单路径到像 "/products/item123" 这样的结构化 URI 不等。URI 中的任何百分号编码字符都会被解码，以便在使用该变量时产生更简洁、对人类更友好的输出。 在访问日志、重写或条件语句中使用此变量可以简化配置，特别是在需要基于被访问资源执行特定操作时。例如，日志格式可以包含 $document_uri 以追踪哪些文档被频繁请求。

配置示例

log_format mylog '$remote_addr - $remote_user [$time_local] "$request" $status $body_bytes_sent "$http_referer" "$http_user_agent" "$document_uri"';

access_log /var/log/nginx/access.log mylog;

说明

`$request` 变量在 NGINX 中于处理 HTTP 请求的过程中被设置，捕获完整的请求行，其中包括 HTTP 方法（GET、POST 等）、请求的 URI 以及 HTTP 协议版本（HTTP/1.1、HTTP/2 等）。该变量在 NGINX 开始处理请求时被填充，并在各种上下文中使用，以提供关于正在处理请求的详细信息。因此，其值通常类似于 'GET /index.html HTTP/1.1' 或 'POST /api/v1/resource HTTP/2'。 `$request` 变量在日志记录或基于特定 HTTP 方法或请求 URI 定制响应时特别有用。例如，通过检查 `$request` 变量的内容，可以设计服务器规则以有条件地重写 URL、记录访问模式，甚至根据请求方法应用安全策略。值得注意的是，一旦请求被处理并生成响应，`$request` 变量保存的是最初接收到时的请求状态，不会被后续处理步骤或内部操作修改。

配置示例

http {
    log_format custom_format '$remote_addr - $remote_user [$time_local] "$request" $status $body_bytes_sent';
    access_log /var/log/nginx/access.log custom_format;
}

说明

NGINX 中的 $document_root 变量提供了用于该请求的文件被提供的根目录的文件系统路径。这个目录通常在 server 或 location block 中通过 `root` 指令设置。它的值由对当前请求最具体的 `root` 指令决定。如果在 server block 和 location block 中都存在 `root` 指令，则更具体的 location block 中的值将优先。 该变量在构建文件路径时很有用，尤其是与 `$uri` 或 `$request_filename` 等其他变量结合使用时。当 NGINX 处理传入请求时，会解析配置并根据匹配的 location 指令分配适当的根目录。如果没有设置 `root`，该变量将返回空字符串，在需要有效路径的配置中错误使用可能导致错误。 需要注意的一点是，如果 server block 定义了 `root`，且没有在特定的 location block 中定义 `root` 指令，那么匹配该 server 的所有请求都将使用 server block 的根目录。该变量经常在各种 NGINX 指令中使用，包括 `try_files`、`rewrite` 和 `alias`，以根据定义的文件结构改变请求的处理方式。

配置示例

server {
    listen 80;
    server_name example.com;
    root /var/www/example.com;

    location / {
        try_files $uri $uri/ =404;
    }
}

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

# Example usage in a log: 
access_log /var/log/nginx/access.log "[$document_root]";

说明

$realpath_root 变量在 NGINX 中提供针对某个请求的当前 location 块根目录的绝对文件路径，会解析所有符号链接。当处理请求时，NGINX 会根据配置的文档根（document root）解析请求的 URI，该文档根由 root 或 alias 指令定义。如果指定的根目录是符号链接，NGINX 会将其解析为文件系统上的实际物理位置，确保路径准确并且不会指向有问题的符号链接引用。 此变量在使用符号链接目录来提供文件的配置中尤其有用，因为它保证在安全检查或与文件相关的操作中使用正确的路径。该变量在请求处理阶段设置，当 NGINX 检查处理该请求的配置块时会设定。$realpath_root 的典型值包括像 '/var/www/html' 或 '/usr/share/nginx/html' 这样的路径，具体取决于相应 `server` 或 `location` 上用户定义的配置。

配置示例

location /images/ {
    alias /var/www/data/images/;
    try_files $uri $uri/ =404;
}

location = /images/logo.png {
    internal;
    root /var/www;
    error_page 404 = @fallback;
}

# Use of $realpath_root
add_header X-Realpath-Root $realpath_root;

说明

NGINX 中的 `$query_string` 变量捕获客户端请求 URI 中的查询字符串。查询字符串是 URL 中跟在 '?' 字符之后的部分，通常包含参数及其值。例如，在 URL `http://example.com/index.html?name=John&age=30` 中，查询字符串是 `name=John&age=30`。当收到请求时，NGINX 会自动填充该变量，可在多种上下文中使用，尤其是在用于条件逻辑的 location 块中。 该变量对于根据查询字符串中传递的特定参数实现逻辑很有用。例如，可以在重写、访问控制或日志配置中使用 `$query_string`，以根据参数引导请求。需要注意的是，该变量只是查询字符串的简单字符串表示，并不解析其内容；如果需要对参数进行更细粒度的控制，管理员需自行处理解析。

配置示例

location /search {
    if ($query_string ~* "keyword=(.*)") {
        set $search_keyword $1;
        add_header Search-Keyword "$search_keyword";
    }
}

说明

在 NGINX 中，$args 变量用于从传入请求的 URL 中检索查询字符串。它包含在 '?' 字符之后作为 URL 一部分传递的任何参数。例如，在类似 'http://example.com/page?name=John&age=30' 的 URL 中，$args 变量会返回 'name=John&age=30'。 当 NGINX 处理 HTTP 请求时，$args 变量会被自动填充，使其在多种上下文中可用，包括在 server 或 location 块内，以及接受变量的指令中。需要注意的是，如果查询字符串中没有参数，$args 的值将是空字符串。此外，应谨慎使用此变量，以避免意外公开可能包含在查询字符串中的敏感信息。

配置示例

location /search {
    if ($args) {
        set $search_query $args;
        # Log or handle the search query
        access_log /var/log/nginx/search.log;
    }
}

说明

NGINX 中的 $is_args 变量返回一个字符串，该字符串要么为空，要么只包含一个问号（'?'）。它专门表示当前请求的 URI 中是否存在查询字符串参数。当请求包含查询参数时（例如 '/path?arg=value'），$is_args 变量将被求值为 '?'，这在构造保留目标 URI 查询字符串的重定向或重写时很有用。 该变量在 NGINX 请求处理生命周期中的请求处理过程中被设置。如果请求 URI 不包含任何查询参数，$is_args 将是空字符串。相反，如果请求带有查询参数，例如 'arg1=value1&arg2=value2'，NGINX 会将 $is_args 设置为仅为 '?'，而不考虑存在的参数。因此，它的值并不反映查询字符串的内容本身，而只是表示其存在。

配置示例

location /example {
    if ($is_args) {
        rewrite ^ /another_example$is_args last;
    }
}

说明

$request_filename 变量在处理请求时由 NGINX 设置，提供对所请求资源的完整文件系统路径。它是基于请求 URI 以及配置中指定的 root 或 alias 指令构建的。当发起请求时，NGINX 会将相关上下文中定义的 root 路径与 URI 组合，得到服务器上可找到所请求文件或目录的绝对路径。例如，如果对 '/images/logo.png' 发出请求，且 server block 的 root 设置为 '/var/www/html'，那么 $request_filename 将是 '/var/www/html/images/logo.png'。\n\n该变量对需要访问文件的模块特别有用，例如处理静态文件、启用自定义日志格式或使用 `try_files` 指令实现条件逻辑。$request_filename 会针对每个请求上下文重新计算，确保其准确反映当前请求的目标。常见用途包括记录所请求的文件路径，或在使用 `try_files` 或其他配置指令进行进一步处理之前检查该文件是否存在。

配置示例

location /images/ {
    root /var/www/html;
    if (!-f $request_filename) {
        return 404;
    }
}

说明

NGINX 中的 $server_name 变量会自动填充为配置中 server block 定义的名称。它可以匹配传入请求的 Host header，或者在 server block 中显式设置。$server_name 的值取决于 server block 的定义；它可以采用多种形式，包括单个名称、wildcard 或 regular expression。如果请求未匹配配置中定义的任何 server blocks，则 $server_name 将未被设置。 该变量通常用于日志记录、错误页面和 rewrite directives，使服务器能够根据请求的主机动态定制响应。当在单个 server block 中为多个 server names 配置时，NGINX 会执行简单的匹配过程，优先选择精确匹配，而不是 wildcards 或 regular expressions。 要有效使用 $server_name 变量，必须正确配置 server block，并确保其与传入请求相匹配。该变量也可以在日志中访问，以提供关于正在处理的请求的上下文，从而有助于调试和分析。

配置示例

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

    location / {
        root /var/www/example;
        index index.html;
    }

    error_page 404 /404.html;
    access_log /var/log/nginx/example.access.log;
    error_log /var/log/nginx/example.error.log;
}

说明

$request_method 变量是 NGINX 核心变量的一部分，用于捕获正在处理的 HTTP 请求的方法。该变量将包含方法动词，例如 GET、POST、PUT、DELETE 或 HEAD，表明客户端打算对给定资源执行的操作。在需要对不同请求类型进行特定处理的场景中，这一点非常重要，例如区分 GET 和 POST 以便不同地处理数据。 当 NGINX 解析传入的 HTTP 请求头时，该变量会在请求处理阶段被设置。它经常用于条件判断或日志配置中，以捕获有关请求的详细信息，便于更好的诊断或根据请求类型应用不同的规则。例如，某些服务器配置可能仅允许对某些端点使用 POST 请求，使用 $request_method 变量可以帮助强制执行这一点： ``` if ($request_method !~ ^(GET|POST)$) { return 405; } ``` 该示例将访问限制为仅允许 GET 和 POST 方法，对所有其他方法返回 405（方法不被允许）状态。

配置示例

location /example {
    if ($request_method = POST) {
        # Handle POST requests
    }
    if ($request_method = GET) {
        # Handle GET requests
    }
}

说明

在 NGINX 中，当服务器配置为使用 HTTP 基本认证时，$remote_user 变量会被设置。这会在配置块中使用 `auth_basic` 指令时发生，提示客户端输入用户名和密码。客户端输入的用户名随后可供服务器使用，并可通过 $remote_user 变量访问。如果客户端未能成功认证，或请求不需要认证，则 $remote_user 将为空。 通常，$remote_user 变量用于日志记录或服务器配置中的授权目的。它可以包含在自定义日志格式中，使管理员能够追踪谁在访问某些资源。此外，该变量可以与条件性配置指令结合，影响访问控制决策，基于已认证用户的身份允许或拒绝访问。 该变量在安全至关重要的场景中最为有用，例如在公开需要用户识别以进行访问控制的敏感数据或服务时。然而，应注意这些信息可能具有敏感性，在日志中使用时应考虑隐私和安全实践，确保访问日志不会暴露可识别个人身份的信息。

配置示例

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

        location / {
            auth_basic "Restricted Area";
            auth_basic_user_file /etc/nginx/.htpasswd;
            access_log /var/log/nginx/access.log combined;
            
            # Include the remote_user in the log
            log_format combined '$remote_addr - $remote_user [$time_local] "$request" $status $body_bytes_sent "$http_referer" "$http_user_agent"';
        }
    }
}

说明

$bytes_sent 变量在 NGINX 中跟踪在响应过程中传输给客户端的总字节数。该变量在请求处理阶段计算，并在所有发生日志记录的上下文中可用。它不仅反映原始响应主体，还包括任何额外发送的字节，例如 HTTP headers。该变量的值在 NGINX 开始向客户端传递响应时确定，并在整个传输过程中持续累积，直到响应完全发送完成。 通常，$bytes_sent 会根据所传输内容的类型而有很大差异；例如，静态文件将以字节为单位报告确切的文件大小，而由脚本生成的动态内容则不那么可预测。此外， 和 可能会由于 content length、headers 和 compression 等差异而影响所报告的大小。总体而言，开发人员和系统管理员主要将此变量用于分析带宽使用情况、计算传输统计，以及调整服务器性能以更高效地响应客户端请求。

配置示例

log_format main '$remote_addr - $remote_user [$time_local] "$request" $status $bytes_sent';
access_log /var/log/nginx/access.log main;

说明

$body_bytes_sent 变量是用于 NGINX 日志记录和性能监控的一个重要指标。它捕获发送给客户端的总数据量，具体来说是响应体中传输的字节数。该变量在每个请求处理过程中设置，一旦响应体生成并发送完毕。需要注意的是，该变量不计算发送给客户端的头部，仅计入主体内容。 在涉及性能评估和带宽计算的场景中，该变量尤其有用。随着 HTTP 请求的处理进展，NGINX 会为已传输的字节维护一个累加器，最终得到 $body_bytes_sent 的值。典型值可能从 0（例如请求导致错误或未发送主体内容的情况）到基于响应性质的任意大小——对于简单的 HTML 页面较小，对于文件下载或媒体流则可能较大。 在实际应用中，$body_bytes_sent 的值可以帮助管理员识别流量模式、用户对内容的参与度以及应用潜在的优化点。通过记录该变量，可以分析带宽使用情况并诊断与响应缓慢相关的问题，方法是将传输的字节与其他变量（例如响应时间和请求速率）进行关联。

配置示例

log_format custom_format '$remote_addr - $remote_user [$time_local] "$request" $status $body_bytes_sent';

access_log /var/log/nginx/access.log custom_format;

说明

$pipe 变量用于 NGINX 服务器中，用来判断请求是否通过 HTTP pipelining 处理。Pipelining 是一种技术，允许在单个连接上发送多个请求，使客户端可以在收到先前响应之前发送额外的请求。在特定场景下，这可以提高性能，尤其是当 Web 浏览器为同时加载资源而发送多个请求时。 该变量可以在 NGINX 配置文件中引用，例如在需要根据请求是否为 pipelined 来有条件地处理某些请求的指令中。当接收到请求时，NGINX 会相应地设置 $pipe 变量的值：如果请求为 pipelined，则将其设置为 "pipelined"，否则该变量未设置（或返回空字符串）。 $pipe 变量的典型用法包括基于请求是否为 pipelined 来进行日志记录以及控制访问或响应处理。例如，你可以为 pipelined 和非 pipelined 请求记录不同的消息，或者根据该变量的值应用不同的缓存机制。

配置示例

http {
    log_format custom_format '[$pipe] $remote_addr - $remote_user [$time_local] "$request" $status $body_bytes_sent "$http_referer" "$http_user_agent"';

    access_log /var/log/nginx/access.log custom_format;
}

说明

$request_completion 变量在 NGINX 中用于反映请求处理的状态。这个变量主要由 NGINX 核心在请求生命周期中设置，它可以取三个值之一：'ok'、'timeout' 或 'failed'。它在日志记录和 NGINX 配置中的条件逻辑中特别有用，使管理员能够根据请求是否成功完成、超时或因其他原因失败采取不同的处理方式。 该变量通常在请求处理过程中在生成响应之后或遇到请求错误时进行评估。如果服务器成功完成对请求的处理，变量值被设置为 'ok'。当请求超过超时设置时，它返回 'timeout'；如果因其他原因失败，则返回 'failed'。这种状态报告的细粒度有助于 NGINX 服务器的诊断和性能监控。

配置示例

log_format custom_format '$remote_addr - $remote_user [$time_local] "$request" $status $body_bytes_sent "$http_referer" "$http_user_agent" $request_completion';

access_log /var/log/nginx/access.log custom_format;

说明

$request_body 变量在 NGINX 中捕获经过服务器处理后的客户端请求主体。它主要在请求方法通常包含主体（例如 POST 或 PUT）时被填充。只有在服务器配置中启用了 'set' 或 'get' 请求主体处理时该变量才可用，通常通过 proxy_pass 指令，或当客户端直接向服务器发送数据时可用。一旦设置，它就保存客户端发送的所有数据，因此在处理表单、文件上传或请求中发送的任何有效载荷时非常有用。 在使用 $request_body 变量时，必须注意请求主体是被缓冲的。默认情况下，其大小可能受 client_max_body_size 指令的限制，该指令限制了被处理并最终存储到此变量中的主体大小。如果主体超过该限制，请求可能会被拒绝，而该变量也不会包含任何数据。$request_body 的典型值可以包括 JSON 有效载荷、multipart form data 或简单文本，具体取决于内容类型和客户端意图。

配置示例

server {
    listen 80;
    server_name example.com;

    location /submit {
        # Capture the request body
        proxy_pass http://backend;
        proxy_set_header X-Request-Body $request_body;
    }
}

说明

$request_body_file 变量用于在 HTTP 请求体超过 NGINX 缓冲区大小限制的场景中。当收到请求时，NGINX 会读取请求体；如果请求体大于预定义的大小，它会将请求体保存到服务器文件系统上的临时文件中。该变量随后保存该临时文件的文件路径，便于对请求体进行后续处理。 该变量主要在请求处理阶段设置，具体是在任何核心处理程序（例如 proxy 或 fastcgi 模块）决定不在内存中完整处理请求体时。该变量的典型值会包含文件系统上的文件路径，例如 `/tmp/nginx_request_body_XXXXXX`。该临时文件通常在请求完成或处理后被删除，从而有效管理服务器磁盘空间。 在经常处理大负载（如文件上传）的配置中，适当配置请求体处理，包括缓冲区大小，对于确保最佳性能并避免服务器过载至关重要。

配置示例

server {
    client_max_body_size 10M;
    location /upload {
        proxy_pass http://backend;
        proxy_request_buffering on;
        # Accessing the request body file:
        if ($request_body_file) {
            log_format custom '$remote_addr $request_body_file';
            access_log /var/log/nginx/custom.log custom;
        }
    }
}

说明

$request_length 变量在 NGINX 中保存客户端请求主体的字节数，该字节数包含头部以及客户端作为请求一部分发送的任何数据（通常出现在 POST 请求中）。这个变量对于监控传入请求的大小以及基于请求大小应用速率限制特别有用。 NGINX 在解析传入请求时设置 $request_length 的值。通常在处理请求的 server 和 location 上下文中填充。记录的大小是请求的总长度，以字节为单位计数。该变量的典型值会根据应用的性质大相径庭；常见的大小可能从 0 字节（对于没有主体的简单 GET 请求）到包含表单或文件上传的复杂 POST 请求的几千字节不等。 当您希望实施安全措施以拒绝过大的请求主体或跟踪客户端请求所消耗的带宽时，此变量很有帮助。因此管理员可以基于此变量设置限制以优化服务器性能并有效管理资源。

配置示例

http {
    server {
        listen 80;
        location /upload {
            client_max_body_size 1M;
            if ($request_length > 1048576) {
                return 413;
            }
        }
    }
}

说明

$request_time 变量提供了在 NGINX 中处理客户端请求所用时间的精确测量。该变量在请求完成时计算，记录从接收请求到将响应返回给客户端的持续时间。具体来说，$request_time 以秒及其小数部分记录该时间，便于评估性能并排查应用中的延迟问题。 $request_time 的值在请求的处理阶段设置，即在 NGINX 发送响应之前。需要注意的是，记录的时间会受到多种因素的影响，包括网络延迟、服务器处理时间以及客户端行为（例如连接速度）。因此，$request_time 的典型值会因应用和服务器负载而大相径庭；它们可能从几毫秒到几秒不等，尤其在高流量或资源密集型操作中。

配置示例

log_format custom '$remote_addr - $remote_user [$time_local] "$request" $status $body_bytes_sent "$http_referer" "$http_user_agent" request_time: $request_time';

access_log /var/log/nginx/access.log custom;

说明

$request_id 变量为到达 NGINX 服务器的每个入站请求提供唯一标识。该标识对于请求跟踪和日志记录非常有用，尤其在分布式系统或微服务架构中，通过在多个服务间关联日志可以帮助调试和监控。默认情况下，如果请求未包含显式的 `X-Request-ID` 头，NGINX 会生成并分配一个 UUID（通用唯一标识符）作为请求 ID。这意味着无论客户端是否指定该头，NGINX 处理的每个请求都可以被跟踪。 当请求到达 NGINX 服务器时，可能会经历若干处理步骤（例如身份验证、访问规则等），而 $request_id 在这些过程中保持一致。重要的是通过使用 `request_id` 模块来启用此变量，该模块在精简的 NGINX 构建中可能不存在。在涉及外部系统或服务（例如 API 网关或负载均衡器）的情况下，通过请求头传递请求 ID 能确保在整个请求生命周期中实现一致的跟踪。 $request_id 的典型值采用 UUID 字符串格式，以确保全局唯一性。例如，示例输出可能类似 `3e4e989c-45c6-4de4-b7d6-2b4ebc4fc417`。这对于在不同系统组件或层之间识别并关联属于同一请求的日志条目非常有帮助。

配置示例

http {
    log_format main '$remote_addr - $remote_user [$time_local] "$request" $status $body_bytes_sent "$_http_referer" "$_http_user_agent" "$request_id"';

daily_log { 
    access_log /var/log/nginx/access.log main;
    
    proxy_set_header X-Request-ID $request_id;
} 
}

说明

在 NGINX 中，$status 变量表示服务器为当前请求生成的响应的状态码。它在 NGINX 处理请求的过程中由 NGINX 自动设置，反映了请求处理的结果。常见的 HTTP 状态码包括 200（成功响应）、404（未找到）和 500（服务器错误）等。 一旦 NGINX 处理请求并生成相应的响应，该变量即可被访问。您可以将此变量用于多种用途，例如记录请求状态或根据请求结果执行条件操作。例如，如果某个请求返回 404 状态码，您可能希望触发特定的错误处理行为或记录日志以跟踪用户遇到页面未找到错误的频率。

配置示例

log_format custom '$remote_addr - $remote_user [$time_local] "${request}" $status ${body_bytes_sent} "$http_referer" "$http_user_agent"';

access_log /var/log/nginx/access.log custom;

说明

$sent_http_content_type 变量是一个内置的 NGINX 变量，用于捕获服务器响应中发送的 Content-Type HTTP 头的值。这个变量通常在响应生成之后使用，允许你访问在服务器配置或请求处理期间确定或设置的 Content-Type。 当请求被处理时，NGINX 会根据各种因素确定适当的 Content-Type，例如所请求资源的文件扩展名、内容协商，或配置文件中的显式设置。响应创建完成并在发送给客户端之前，$sent_http_content_type 变量可用于评估或记录即将发送的 Content-Type。该变量在响应头生成之前未定义，因此如果响应无效或未设置，则可能并非对每个请求都可用。 该变量的典型值可能包括标准 MIME 类型，例如 "text/html", "application/json", "image/png" 等，具体取决于 NGINX 所服务的内容。如果未发送响应，或未指定 Content-Type，则该变量将为空。因此，建议在将其用于日志记录或决策之前先检查它是否已设置。

配置示例

location / {
    add_header Custom-Header "$sent_http_content_type";
    proxy_pass http://backend;
}

说明

当 NGINX 处理请求时，它会收集将要返回给客户端的各类响应头。变量 $sent_http_content_length 专门捕获指示响应体大小（以字节为单位）的 Content-Length 头。该变量在请求处理阶段设置，通常包含表示由服务器生成的响应长度的数值；如果无法确定响应长度，或使用了 chunked transfer encoding 而不是具体的 Content-Length，变量可能为空。 Content-Length 头对于 HTTP/1.1 通信很重要，因为它允许客户端确切知道响应体需要接收多少字节。在生成动态内容的场景中，NGINX 可能要到响应体完全处理完毕才确定内容长度。因此，在需要根据内容大小进行特定处理（例如条件性日志记录或基于内容大小的响应修改）的场景中，使用该变量会很有帮助。

配置示例

server {
    listen 80;
    location / {
        add_header X-Content-Length $sent_http_content_length;
        proxy_pass http://backend;
    }
}

说明

$sent_http_location 变量在 NGINX 的内部重定向期间被赋值，尤其是在模块处理导致 3xx HTTP 响应的请求时。该变量被赋予由指令（例如 `rewrite`、`error_page` 或 `proxy_redirect`）设置的 'Location' 首部的值。它保存了客户端将被重定向到的 URL，这在基于用户输入或请求路径应用访问控制或逻辑时特别有用。 只有在发生指向不同 URI 的内部重定向时该变量才会被设置，并且它可以在多种场景中使用，包括记录请求最终被重定向到的 URL，或与其他 NGINX 变量结合用于更高级的响应逻辑。典型值包括绝对 URL（例如 "http://example.com/target"）或相对 URI（例如 "/target"），具体取决于 NGINX 服务器中重定向的配置。

配置示例

server {
    listen 80;
    location /example {
        return 302 /new-location;
    }
    location /new-location {
        add_header Location $sent_http_location;
        return 200 'Redirected to new location';
    }
}

说明

$sent_http_last_modified 变量在处理涉及获取资源的请求时由 NGINX 自动设置。当 NGINX 响应请求并在 HTTP 响应中包含 Last-Modified 头时，该变量会捕获该头的值。Last-Modified 头用于指示资源最后修改的日期和时间，允许客户端根据资源的新鲜度决定是否缓存或重新获取资源。 该变量在需要精细调整缓存行为或在客户端实现使用 If-Modified-Since 头的条件 GET 请求时非常有用。通过检查 $sent_http_last_modified 的值，可以在服务器端实现逻辑，基于所提供资源的新鲜度修改响应的头或内容。该变量的典型值符合常见的 HTTP 日期格式，例如 'Wed, 21 Oct 2015 07:28:00 GMT'。注意，如果未发送 Last-Modified 头，变量将为空。

配置示例

location /example {
    add_header Last-Modified $sent_http_last_modified;
}

说明

$sent_http_connection 是 NGINX 中的一个变量，用于获取发送给客户端的 'Connection' 响应头的值。该头用于指示客户端在当前请求处理完成后是否应保持与服务器的连接。该变量的典型值可能包括 'keep-alive' 或 'close'，这取决于服务器的配置以及客户端请求的连接性质。 该变量在服务器需要根据客户端请求或使用模式动态调整连接行为的场景中最为有用。例如，如果某些客户端请求持久连接，服务器可以据此做出响应。$sent_http_connection 的值在请求处理期间设置，具体是在构建响应头时。此变量的值由相关上下文中的服务器配置指令决定。 需要注意的重要一点是，如果配置中未指定 'Connection' 头或在处理过程中未显式设置该头，则此变量不会包含任何值，因此在条件表达式或日志记录中使用时应谨慎，以避免意外显示为空的头。

配置示例

server {
    listen 80;
    location / {
        add_header Connection $sent_http_connection;
    }
}

说明

NGINX 核心在为客户端准备响应时设置 $sent_http_keep_alive 变量。它反映了 HTTP 响应中发送的 'Keep-Alive' 头，该头告知客户端服务器是希望在多次 HTTP 请求之间保持连接打开，还是在当前事务后关闭连接。该变量可以取像 'timeout=5' 这样的值，表示在超时之前连接应保持的时间，或 'timeout=0' 表示在响应发送后立即关闭连接。 在配置了 keep-alive 设置时，NGINX 能够高效地管理持久连接，并使用此变量将服务器的偏好传达给客户端。如果禁用了 keep-alive 或者不适用，则该变量可能为空。$sent_http_keep_alive 的状态也可以被诸如 'keepalive_timeout' 等指令影响，后者决定服务器在关闭连接之前允许连接保持空闲的时间，这使得该变量在高流量环境中对性能至关重要，因为保持打开的连接可以减少同一客户端后续请求的延迟。

配置示例

http {
    keepalive_timeout 65;
    server {
        listen 80;
        location / {
            add_header Keep-Alive "$sent_http_keep_alive";
        }
    }
}

说明

NGINX 中的 $sent_http_transfer_encoding 变量保存作为发送给客户端的 HTTP 响应中的 'Transfer-Encoding' 头的值。该变量在使用分块传输编码的 HTTP 响应中特别有用。要使该变量成功赋值，NGINX 配置必须指定传输编码方法，这通常发生在使用动态内容生成机制（例如 PHP 或上游服务器）时。当 NGINX 自行生成响应时，除非明确设置，否则该变量的值可能默认为空字符串。 该变量可以取多种值，最常见的是 `chunked`，表示响应将以一系列分块发送，而不是作为单个完整消息发送。这在可以分块流式传输的大型响应或事先未知响应总大小的情况下尤其有用。如果服务器未设置任何传输编码，则该变量不会包含任何值，反映未使用传输编码。

配置示例

location /api {
    proxy_pass http://backend;
    proxy_set_header Accept-Encoding '';  
}


location /stream {
    proxy_pass http://stream_backend;
    add_header Transfer-Encoding chunked;
}

说明

$sent_http_cache_control 变量检索 NGINX 发送给客户端的 'Cache-Control' HTTP 响应头的值。它在 NGINX 处理响应时被设置，并且可以被多种配置影响，例如 `expires`、`add_header` 或 `proxy_cache`。该变量在调试或自定义服务器返回的响应头时特别有用，允许你捕获并记录实际发送出的缓存指令。 通常，该变量的值可能包含诸如 'no-cache'、'private'、'max-age=3600'、'public' 之类的指令，或者如果未设置该头则可能为空。它可以与其他变量结合使用，根据各种服务器条件或配置动态调整响应头，从而增强对客户端和 HTTP 链中中间代理如何缓存响应的控制。 该变量仅在响应头发送之后进行评估，这意味着它反映的是实际包含在响应中的最终值。如果对 Cache-Control 头有多次设置或修改，该变量将保存响应完成前最后一次设置的值。

配置示例

location /example {
    proxy_pass http://backend;
    add_header Cache-Control "private, max-age=3600";
    log_format custom '$remote_addr - $remote_user [$time_local] "$request" $status $sent_http_cache_control';
    access_log /var/log/nginx/access.log custom;
}

说明

当响应中设置了 Link 头时，NGINX 会使用 `$sent_http_link` 变量。该变量在 API 和 Web 服务中尤其有用，因为提供有关相关资源的信息可以增强客户端的处理和导航。该变量根据响应上下文中定义的 `Link` 头填充，通常由多个可能与当前资源相关的 URIs 构成。\n\n当生成 HTTP 响应时，如果通过配置或在 Lua 中的动态设置设定了 `Link` 头，`$sent_http_link` 将包含该值以供后续处理。它随后可用于重写、日志记录或进一步的响应处理。该变量的典型值是表示一个或多个 URIs 的字符串，通常带有指定的关系（例如 `rel=\"next\"` 或 `rel=\"prev\"`）。\n\n在 API 中实现分页时，该变量特别有用，允许客户端轻松推断下一页或上一页。通过适当设置 Link 头，NGINX 可以通过响应传递相关信息，而无需大量应用逻辑来处理这些引用。

配置示例

http {
    server {
        location /api {
            add_header Link "; rel='next'";
        }
    }
}

说明

NGINX 中的 `$limit_rate` 变量用于限制发送到客户端的响应传输速率。通过调整此变量，管理员可以确保来自特定连接的最大带宽消耗，这在管理服务器资源变得至关重要的场景（例如高流量期间）尤其有用。该变量可以设置为具体的字节值，或从其他变量派生其值，从而根据应用需求实现灵活配置。 该变量可以根据配置中的各种条件动态设置，例如 IP 地址或特定请求特征。默认情况下 `$limit_rate` 的值为 0，意味着传输速率不受限制。如果设置的值大于 0，NGINX 将对每个请求应用限制并相应调整速率；如果速率设置得过低，可能会严重影响用户体验。通常，值以字节/秒为单位给出；例如，将其设置为 `1048576` 将把速率限制为 `1MB/s`。

配置示例

http {
    server {
        location / {
            # Limit transfer rate
            limit_rate 500k;
        }
    }
}

说明

$connection 变量是 NGINX 的内置变量，为服务器处理的每个请求提供唯一的连接标识符。它对调试和日志记录尤其有用，允许管理员在多个请求之间跟踪连接详情。该值基于 socket descriptor，并且是一个整数，会随着每次连接实例而变化。每当处理新的请求时，该变量都会被设置以标识所使用的连接，因此它有助于识别来自同一客户端的并发请求，或在日志中区分不同的用户。 在请求处理期间，当客户端连接到 NGINX 服务器时，会创建一个连接对象，其中包含各种与连接相关的信息，例如客户端地址、连接状态等。$connection 变量与该连接对象直接相关。由于每个客户端可能在单个连接上发出多个请求，因此在实现基于连接的逻辑（例如速率限制、访问控制和定制化日志记录）时，该变量非常有价值。 该变量的典型值是与系统当前连接相关的整数，也可以与通过 HTTP/2 多路复用流的请求关联，在那种情况下同一连接可以同时服务多个请求。请注意，由于 NGINX 使用异步事件驱动模型，同一 $connection 会在请求之间共享，直到连接关闭，此时将为新的连接分配新的标识符。

配置示例

server {
    listen 80;
    location / {
        access_log /var/log/nginx/access.log;
        log_format main '$remote_addr - $remote_user [$time_local] "$request" $status $body_bytes_sent "$http_referer" "$http_user_agent" "$connection"';
    }
}

说明

在 NGINX 中，$connection_requests 变量用于跟踪在单个连接生命周期内已处理的请求数量。每当该连接上发起新请求时，该变量就会递增；当连接首次建立时从零开始。每个请求——无论是初始请求还是由 keep-alive 触发的后续请求——都会增加该计数。该变量对于监控和理解请求模式、优化连接重用以及调试与连接处理相关的性能问题特别有用。 在 NGINX 中，$connection_requests 变量的生命周期始于新连接建立时。对于该连接上的每个传入请求，服务器都会递增该变量，直到连接关闭或请求处理完成。该变量的典型值对于单次请求连接可能从 1 开始，并随着客户端在同一连接中发出的多次请求而相应增加。在保持连接的场景中，该变量允许网站管理员分析 keep-alive 连接在处理多个请求方面相较于为每个请求打开新连接的效率。 鉴于该变量反映的是请求数量，它可用于旨在性能调优或详细请求记录的配置中；从监控该变量获得的洞见可能带来资源分配和响应时间方面的改进。记录该变量可以提供关于客户端行为及其请求模式的有价值信息，从而更容易识别潜在瓶颈或提高效率。

配置示例

log_format custom_format '$remote_addr - $remote_user [$time_local] "$request" $status $body_bytes_sent "$http_referer" "$http_user_agent" "$connection_requests"';

access_log /var/log/nginx/access.log custom_format;

说明

$connection_time 变量在 NGINX 中记录从 NGINX 收到请求到与客户端建立连接所用的持续时间，单位为秒。该值在连接建立时确定，允许从 NGINX 服务器的角度测量延迟。该变量会在连接处理流程中更新，主要适用于与连接时间相关的日志记录或指标收集。在最佳情况下，常见值可能为不到一秒的若干分之一；在高延迟或连接问题的场景下，则可能为数秒或更长时间。 $connection_time 被设置的时机始于 NGINX 工作进程接受到来自客户端的新连接时，这对应于请求开始被处理的时刻。开发人员和管理员可以使用此变量来洞察性能特性，尤其是在监控 Web 服务器在各种网络条件或负载下的行为时。分析这些值有助于推断服务器的健康状况并识别与客户端连接相关的潜在性能瓶颈。

配置示例

log_format main '$remote_addr - $remote_user [$time_local] "$request" ' \
                    '$status $body_bytes_sent "$http_referer" ' \
                    '"$http_user_agent" "$http_x_forwarded_for" ' \
                    'Connection time: $connection_time';

access_log /var/log/nginx/access.log main;

说明

变量 $nginx_version 在 NGINX 启动时由 NGINX 设置，反映当前正在运行的 NGINX 服务器的版本。该变量直接来源于在编译期间 NGINX 源代码中找到的版本信息，这使用户能够检查所使用服务器的确切版本。通常以诸如 '1.21.0' 或 '1.19.10' 之类的格式表示。 该变量可在 NGINX 配置文件的各种上下文中访问，例如日志格式或响应头。这使其对调试和维护特别有用，管理员可以快速确定 NGINX 的版本，而无需在服务器上执行命令。此外，了解版本对于确保与某些模块或配置的兼容性非常重要，尤其是在可能存在多个版本不同的 NGINX 实例的环境中。 总体而言，变量 $nginx_version 主要作为管理员和开发人员的信息工具，提供快速访问的版本详细信息，这对于维护和升级 NGINX 配置至关重要。

配置示例

http {
    log_format my_log '$remote_addr - $remote_user [$time_local] "$request" $status $body_bytes_sent "$http_referer" "$http_user_agent" NGINX/$nginx_version';
    access_log /var/log/nginx/access.log my_log;
}

说明

$hostname 变量在处理请求期间被设置，反映了 NGINX 配置中定义的服务器主机名。如果指定了 'server_name' 指令，它会从中获取该值；否则默认使用服务器操作系统的主机名。该变量对需要知道提供请求的主机名称的应用程序特别有用，便于依赖服务器身份的配置。 NGINX 在请求阶段评估 $hostname 变量，这意味着它可以在多种场景中使用，例如日志记录、重定向或基于条件的服务器路由。它根据处理请求的 server block 生成值——如果定义了多个具有不同名称的 server blocks，则允许实现动态配置。如果未指定 'server_name'，NGINX 将退回使用系统的主机名，该主机名可通过命令行使用 'hostname' 命令在 Linux 系统上确认。 要有效设置此变量，最好在你的 server blocks 中定义 'server_name' 指令，以确保一致的行为，尤其是在具有多个主机名或虚拟主机的环境中。这种做法可以减少歧义，并确保应用使用与收到的请求关联的正确域名。

配置示例

server {
    listen 80;
    server_name example.com;

    location / {
        add_header X-Host $hostname;
    }
}

说明

$pid 变量在 NGINX 中返回当前正在处理客户端请求的工作进程的进程标识符 (PID)。该变量对于调试和日志记录特别有用，使管理员能够识别哪个工作进程正在处理特定请求。PID 在 NGINX 工作进程启动时初始化，并在该工作进程的生命周期内保持不变。$pid 的值是数值，反映了相应工作进程的系统分配 PID，在需要记录有关进程处理的详细信息的场景中非常有用。 由于 NGINX 可以生成多个工作进程，每个进程可能会并发地处理不同的请求。$pid 变量有助于将日志与特定 PID 关联，从而便于更好地诊断和监控。通常，$pid 值从一个定义的数字开始，并且对于操作系统生成的每个新进程递增。用户可以在自定义日志格式中使用该变量，以便了解哪些进程正在处理流量，或在诊断性能瓶颈或单个工作进程问题时提供帮助。

配置示例

log_format custom_log '$remote_addr - $remote_user [$time_local] "$request" '
'"$status $body_bytes_sent "$http_referer" "-" "$http_user_agent" 'Ver: $nginx_version Pid: $pid';

access_log /var/log/nginx/access.log custom_log;

说明

$msec 变量是 NGINX 的内置变量，提供高精度的时间信息。它返回自 Unix 纪元（1970 年 1 月 1 日）以来的当前系统时间（以毫秒为单位）。该值在处理请求时被设置，通常用于日志记录、调试和性能测量。 当收到请求时，NGINX 会获取当前时间并将其转换为毫秒，你可以在各种场景中使用该值，例如访问日志、自定义头或基于时间的条件处理。该变量的高精度在需要测量响应时间或计算请求处理不同阶段之间延迟时尤其有用。由 $msec 输出的值是一个小数，表示自纪元以来经过的总毫秒数。 该变量常与其他与时间相关的变量（例如 $time_iso8601）一起使用，用于生成既包含格式化日期又包含毫秒精度的详细日志。需要注意的是，$msec 变量的准确性取决于底层操作系统和硬件时钟的分辨率。

配置示例

log_format custom_format '$remote_addr - [$time_local] "${request}" $status $body_bytes_sent "$http_referer" "$http_user_agent" $msec';
access_log /var/log/nginx/access.log custom_format;

说明

变量 $time_iso8601 以符合 ISO 8601 标准的格式输出日期和时间。该时间戳通常格式为 'YYYY-MM-DDTHH:MM:SS+ZONE'，例如对应 '2023-10-04T12:34:56+00:00'。该变量由 NGINX 在处理请求时填充，并在配置文件的各种上下文中可用。它利用服务器的本地时区设置，以确保显示的时间与服务器的当前时间设置一致。 它在日志记录目的或在 HTTP headers 的上下文中特别有用，因为无歧义的日期和时间表示可以帮助客户端解析、调试和进行数据分析。通常 NGINX 在每次处理请求时设置该变量，确保在请求生命周期内访问时是最新的。作为时间戳输出的一部分，它包含时区信息，因此适用于需要考虑时区差异的场景。 由于其标准格式，$time_iso8601 在需要精确时间戳的 RESTful API 响应和 web services 中很受青睐，因为它使客户端能够跨不同时区准确地解释接收到的数据。该变量可以按照 NGINX 中传统 date 命令格式的相同方式进行格式化，从而在各种安装环境中保持可用性。

配置示例

http {
    log_format combined '$remote_addr - $remote_user [$time_iso8601] "$request" '
                  '$status $body_bytes_sent "$http_referer" "$http_user_agent"';
    access_log /var/log/nginx/access.log combined;
}

说明

$time_local 变量在 NGINX 中提供在接收到请求时的本地服务器时间。它的格式为 'day/month/year:hour:minute:second zone'，遵循 Common Log Format，该格式在日志条目中被广泛识别。此变量对于日志记录尤为有用，允许管理员根据服务器的时区设置跟踪请求发生的时间。 $time_local 的值在请求处理阶段设置，具体是在应用接收到请求时。因此，它确保时间戳准确对应请求被处理的时刻。默认情况下，该变量按服务器的本地时区格式化，可通过 NGINX 配置中的指令指定。 该变量的典型值可能类似 '12/Apr/2023:18:30:12 +0300'，指示精确的日期和时间以及时区偏移。鉴于其在日志记录中的重要性，通常在自定义日志格式中使用它以精确捕捉请求时间戳，从而便于排查和监控服务器活动。

配置示例

log_format my_log_format '$remote_addr - $remote_user [$time_local] "$request"';

access_log /var/log/nginx/access.log my_log_format;

说明

$tcpinfo_rtt 变量是 NGINX 的 TCP 连接模块的一部分，用于提供 TCP 连接性能的度量。它返回 TCP 连接的往返时间 (RTT) 测量值，反映数据包从发送方到接收方再返回所需的时间。该变量对诊断网络延迟和评估服务器对传入请求的响应能力特别有用。 $tcpinfo_rtt 的值仅在连接建立后可用，对于传入连接可能不会立即设置。通常它返回一个整数值，表示时间，单位为微秒。对于新连接，如果 RTT 信息尚不可用，可能会返回 0，直到能从 TCP 协议栈收集到信息为止。实际上，典型值会根据网络情况有很大差异，开发者可以使用该指标来微调其应用以更好地处理与延迟相关的调整。 该变量可以在日志指令中使用，服务器管理员可以通过记录该指标来跟踪连接性能随时间的变化。将此指标包含在访问日志中，管理员可以分析趋势并识别服务交付中的潜在瓶颈。

配置示例

log_format custom_log '$remote_addr - $remote_user [$time_local] "$request" $status $tcpinfo_rtt';
access_log /var/log/nginx/access.log custom_log;

说明

$tcpinfo_rttvar 变量在 NGINX 中用于提供与 TCP 连接延迟稳定性相关的诊断信息，通过指示往返时延（RTT）的方差来体现。该度量来源于 TCP 协议栈的信息，具体是测量通过 TCP 连接发送的数据包所观察到的 RTT 的方差。当客户端发送请求时，NGINX 会捕获该会话的 TCP 信息，其中包括底层操作系统的 TCP 协议栈报告的 RTT 值。 通常，$tcpinfo_rttvar 只有在完成 TCP 握手之后才可用，在性能调优和监控场景中尤其有用。典型数值会根据网络状况和流量特性有显著差异；较低的值表示网络延迟更稳定且一致，而较高的值反映出不稳定性。因此，监控此变量有助于诊断影响应用性能和用户体验的网络相关问题。 当 NGINX 在适用 TCP 指标的场景下通过 TCP 连接处理请求时，通常会设置此变量。你可以在多种上下文中利用其值，例如日志记录或条件配置，根据请求期间观察到的 RTT 方差来实施定制优化。

配置示例

log_format my_logging_format '$remote_addr - $remote_user [$time_local] "$request" $status $body_bytes_sent "$http_referer" "$http_user_agent" $tcpinfo_rttvar';

access_log /var/log/nginx/access.log my_logging_format;

说明

$tcpinfo_snd_cwnd 变量在 NGINX 中提供连接的当前 TCP 发送拥塞窗口大小，这对于理解网络上数据传输的流量与响应性至关重要。该变量在 NGINX 用作反向代理或负载均衡器的场景中很有用，因为它允许对 TCP 指标进行实时监控，这对性能调优和优化可能至关重要。拥塞窗口大小表示在等待接收方确认之前可以发送的数据量，从而影响整体网络吞吐量。 $tcpinfo_snd_cwnd 的值在活动的 TCP 连接期间设置（即当 TCP 为传输层时），并在数据传输期间反映拥塞窗口大小的变化。典型值会根据网络状况、负载和配置而有很大差异；它们可能非常小，相当于几个 TCP 数据包；如果网络路径可靠且带宽充足，则可能相当大。监控此变量可以帮助管理员识别潜在的性能瓶颈并相应调整服务器配置。

配置示例

location /status {
    default_type text/plain;
    add_header Content-Length 0;
    return 200 "Current congestion window size: $tcpinfo_snd_cwnd bytes\n";
}

说明

NGINX 中的 $tcpinfo_rcv_space 变量提供有关 TCP 接收缓冲区大小的信息，这对管理通过 TCP 的入站连接至关重要。该变量反映了 TCP 协议栈为处理入站数据包而分配的接收空间的当前值。它在 TCP 层建立连接时设置，并根据系统和应用级参数进行配置，例如可能限制最大接收缓冲区大小的 TCP_MAX_RCV_SPACE 值。 当建立连接时，TCP 内核会为入站数据包分配一部分内存，该内存会被填满直到达到指定限制。随着数据被接收，可用的接收空间会减少，从而影响入站连接的数据流。该变量在识别网络性能问题或在高负载下监控应用行为时尤其有用，因为它可以指示应用是否适当地利用了可用资源。 对于 $tcpinfo_rcv_space 的典型值，取决于底层系统配置和网络条件，可能差异很大，但通常会反映标准的 TCP 缓冲区大小，范围可能从几 KB 到几 MB，具体取决于系统设置和负载。对这些值进行合理调优可以优化性能并降低数据传输延迟。

配置示例

server {
    listen 80;

    location /status {
        add_header X-TCP-Receive-Space "$tcpinfo_rcv_space";
        # Additional status logic...
    }
}

说明

在 NGINX 中，变量 "$http_" 是用于访问客户端发送的 HTTP 请求头的动态前缀。该变量的语法是 "$http_"，其中 `` 会转换为小写，且任何连字符会被替换为下划线。例如，如果客户端发送了头 `X-Forwarded-For`，你可以使用 `$http_x_forwarded_for` 来访问其值。此功能使 NGINX 能够方便地处理各种头部，通过统一的命名模式轻松访问任意 HTTP 头。 当客户端向服务器发起请求时，所有 HTTP 头都可在请求上下文中获得，NGINX 会在处理请求期间相应地填充 `$http_` 变量。这些变量可以在配置文件的不同上下文中使用，例如 `server`、`location` 和 `if` 块。通过该变量常见地访问的头包括授权头、自定义应用头，以及像 `User-Agent` 或 `Accept-Encoding` 这样的标准头，从而允许基于某些头的存在或其值进行灵活的请求处理或条件处理。

配置示例

server {
    listen 80;
    location /example {
        if ($http_user_agent ~* "Googlebot") {
            return 403;
        }
        add_header X-Your-Header "$http_x_your_header";
    }
}

说明

在 NGINX 中，当在 server 或 location 块中设置了某些响应头时，$sent_http_ 前缀的变量会被自动生成。对于发送给客户端的每个 HTTP 响应头，都有一个对应的以 $sent_http_ 为前缀的变量。例如，如果你在 server 配置中发送了 HTTP 头 'X-My-Header'，对应的变量将是 $sent_http_x_my_header。通过这些变量，你可以在 NGINX 配置或日志格式中直接访问响应中已发送的 HTTP 头的值。 该变量在需要进行条件日志记录或基于特定头的值自定义输出的场景中特别有用。只有在响应中实际设置了相应头时，$sent_http_ 变量才会被填充；如果某个头未被设置，对应的变量将为空。该机制有助于跟踪和管理各种头信息，这在调试或验证服务器行为（尤其是在测试期间）等场景中至关重要。

配置示例

location /example {
    add_header X-My-Header "MyValue";
    add_header X-Another-Header "AnotherValue";

    # Log sent headers
    access_log /var/log/nginx/example.log custom_format;
}

log_format custom_format 'Sent HTTP Headers: $sent_http_x_my_header, $sent_http_x_another_header';

说明

变量 $sent_trailer_ 与包含尾部字段的 HTTP/1.1 响应一同使用，尾部字段是消息正文之后发送的附加字段。该变量允许 NGINX 访问响应中可能设置的特定尾部字段。它可以作为尾部字段名称的前缀，例如 `$sent_trailer_myfield`，如果 HTTP 响应中指定了 `myfield`，则该变量会返回其值。 通常，该变量在 HTTP 响应阶段被设置，此时尾部字段已确定并准备发送。尾部字段本身在响应头字段中定义，因此与 $sent_trailer_ 变量关联的值将取决于应用程序或后端服务在 NGINX 发送最终响应之前如何填充这些尾部字段。如果指定的尾部字段存在，变量将返回其值；否则返回空字符串。 在前端服务器响应中，尾部字段的使用并不普遍，其支持在很大程度上依赖于客户端和服务器的实现。尾部字段的一些用例包括在流式场景中提供校验和数据或其他应在负载之后出现的元数据，这使得尾部字段成为某些特定应用的有用功能。

配置示例

location /example {
    add_header My-Trailer myvalue;
    # The value of the trailer can be accessed
    echo "$sent_trailer_My-Trailer";
}

说明

在 NGINX 中，以 $cookie_ 为前缀的变量可以方便地访问客户端在 HTTP 请求中设置的 cookie 值。当客户端向 NGINX 服务器发送请求时，可能会包含各种 cookie，这些 cookie 用于存储用户特定信息、会话详情或偏好设置。通过引用 $cookie_（其中 是 cookie 的具体名称），NGINX 会从请求的 cookie 中提取相应的值。 该机制使得可以基于存储在 cookie 中的用户特定数据生成动态内容。例如，如果客户端发送了名为 'user_id' 的 cookie，则可以在配置中通过 $cookie_user_id 来访问它。当该 cookie 存在时，变量返回其值；如果不存在，则返回空字符串。此功能在 Web 应用中被广泛使用，用于根据客户端之前的交互或偏好定制响应。 此外，cookie 变量可以在不同的上下文中使用，例如在 location 或 server 块中，从而根据用户状态进行条件配置和定制化的错误处理。不当处理 cookie 值（例如不验证用户输入）可能导致安全漏洞，因此在使用时必须谨慎管理。

配置示例

server {
    listen 80;
    server_name example.com;

    location / {
        if ($cookie_user_id) {
            add_header X-User-ID $cookie_user_id;
        }
    }
}

说明

在 NGINX 中，以 $arg_ 为前缀的变量用于从请求 URI 中提取查询参数。当客户端发起 HTTP 请求时，URL 可能附带由键值对组成的查询字符串。例如，在请求 URL `http://example.com/path?arg1=value1&arg2=value2` 中，NGINX 允许通过类似 `$arg_arg1` 和 `$arg_arg2` 的相应变量访问这些参数。特定 `$arg_` 变量返回的值对应于关联查询参数的值；如果该参数不存在，则变量返回空字符串。 在需要根据客户端参数影响请求处理的场景（例如重定向、访问控制或条件响应）中，这些变量尤其有用。它们在每次处理请求时都会被求值，因此适合基于客户端输入生成动态内容。需要注意的是，由于这些变量具有上下文敏感性，正确使用它们需要理解 NGINX 配置，尤其是与依赖这些变量的指令放置相关的部分。

配置示例

location /example {
    if ($arg_user_id) {
        return 200 "User ID: $arg_user_id";
    }
    return 400 "No User ID provided";
}

说明

在 NGINX 中，变量 $proxy_host 在将客户端请求转发到后端服务器的反向代理配置中起着关键作用。当请求被代理时，该变量被设置为 proxy_pass 指令中指定 URL 的主机部分。它反映了配置文件中代理设置决定的 upstream 服务器的主机名。 在请求处理过程中可以使用 $proxy_host 变量，特别是在请求被代理的上下文中，例如在使用 proxy_pass 指令的 location 块内。如果 upstream 服务器是用主机名或 IP 地址定义的，$proxy_host 会返回该值，从而可以根据目标服务器的标识动态处理请求。常见的 $proxy_host 值可能是像 "api.example.com" 这样的实际主机名，或者如果在 upstream 定义中直接指定了 IP，则为该 IP 地址。 在使用多个 upstream 服务器时，该变量对于日志记录和调试非常重要。它有助于跟踪请求被发送到哪个服务器，尤其是在处理负载均衡配置时。它也可用于构造自定义请求头或根据解析得到的 upstream 主机名修改请求。

配置示例

location /api {
    proxy_pass http://backend;
    proxy_set_header Host $proxy_host;
}

说明

NGINX 中的 $proxy_port 变量用于指定在 `proxy_pass` 指令中为被代理服务器指定的端口号。该变量在需要根据目标服务器的端口记录日志或有条件地处理请求时特别有用。它会在使用 `proxy_pass` 指令代理请求时被设置。如果在 `proxy_pass` 中给出了主机名，NGINX 会将其解析为地址和端口，而 $proxy_port 变量会检索该端口。通常，该端口在 HTTP 请求中为 80，在 HTTPS 中为 443，但也可能根据您的上游服务器的配置而有所不同。 在请求未被代理，或在 `proxy_pass` 配置中未显式定义端口的情况下，$proxy_port 可能返回空字符串。为有效使用此变量，务必确保您的 `proxy_pass` 配置正确指定了协议和端口。您也可以将其与其他变量（例如 $proxy_host）结合使用，以在配置中创建动态行为。

配置示例

location /example {
    proxy_pass http://backend_server:8080;
    access_log /var/log/nginx/proxy_access.log "Proxy to port: $proxy_port";
}

说明

$proxy_add_x_forwarded_for 变量在 NGINX 中用于构建 X-Forwarded-For 头，这在代理设置中对于保留原始客户端的 IP 地址至关重要。它会将客户端的 IP 地址与 X-Forwarded-For 头中已有的任何已定义 IP 地址有效地合并，确保持多重代理参与时代理地址链得以保留。该变量在请求处理期间设置，当 NGINX 服务器处于代理模式时，通常在使用 proxy_pass 指令的 location block 的配置中。\n\n当 NGINX 处理请求时，如果存在 X-Forwarded-For 头，该变量将取其现有值并追加客户端的 IP 地址。如果该头不存在，则只包含客户端的 IP 地址。例如，如果客户端的 IP 为 192.168.1.5，且前一个代理已将 X-Forwarded-For 头设置为 10.1.1.1，则 $proxy_add_x_forwarded_for 的结果将是 "10.1.1.1, 192.168.1.5"。这是托管在多层代理之后的应用程序用来准确记录和追踪原始客户端 IP 的关键机制。它尤其用于负载均衡场景以保持请求追踪完整。

配置示例

location /api {
    proxy_pass http://backend;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
}

说明

当 HTTP 请求被 NGINX 转发到另一个服务器时，变量 $proxy_add_via 由 NGINX 动态生成。它构建一个 'Via' 头，用于标识所使用的代理方式。该变量通常在请求被代理时设置为格式 '1.1 NGINX'，表示所使用的协议版本及服务器名称。这在调试和管理缓存系统时尤其有用，因为它允许客户端应用和中间代理追踪请求通过 NGINX 代理的路径。\n\n通常在配置中使用 `proxy_pass` 指令时会设置此变量。例如，如果为上游服务器正确配置了 `proxy_pass` 指令，NGINX 将为转发到该服务器的所有请求自动填充 $proxy_add_via 为相应的值。如果多个代理串联，'Via' 头将反映请求所经过的完整路径，从而在共享缓存和路由机制中实现更好的控制与可见性。典型值可能包括 '1.1 NGINX'，或在与 NGINX 一起使用其他代理服务时指示这些服务。

配置示例

location /api {
    proxy_pass http://backend_service;
    proxy_set_header Host $host;
    add_header Via $proxy_add_via;
}

说明

$proxy_internal_host 变量在 NGINX 中主要用于将请求代理到内部位置的配置中。它的作用是保存并返回通常由服务器内部网络设置确定的内部（或后端）主机名。该变量在涉及负载均衡或反向代理的场景中特别有用，因为多个上游服务器可能处理传入请求。根据上下文，该变量将被设置为代理配置中指定的内部主机名；如果未明确定义，则默认为服务器的主机名。 $proxy_internal_host 在处理被 proxy 相关指令（例如 proxy_pass）修改的请求时进行求值。如果定义了 proxy_name，则该名称将用作该变量的值。如果未定义内部主机名，则可能回退到 NGINX 配置规定的默认行为。这可确保请求根据明确的配置或内部默认值正确路由。 这允许基于 $proxy_internal_host 变量做出决策的高级配置，从而启用和管理基于内部主机名的内部路由策略或安全检查。它还可以增强日志记录和调试过程，方便管理员更直观地检查内部代理设置。

配置示例

location /api {
    proxy_pass http://backend_server;
    proxy_set_header Host $proxy_internal_host;
}

说明

$proxy_internal_connection 变量在 NGINX 处理被代理请求并将请求转发到另一个上游服务器的上下文中被设置。它专门用于检查出站连接是否使用内部网络，这由该连接的套接字是否属于您在 NGINX 配置中设置的内部路由规则来决定。默认情况下，如果出站连接是内部连接，该变量的值为 '1'（真）；如果是外部连接，则为 '0'（假）。 该变量在涉及多层代理或基于连接是内部还是外部而强制执行安全约束的配置场景中特别有用。例如，如果您定义了基于连接类型来限制访问或修改头的规则，该变量可以帮助微调这些行为。用户可以在其 NGINX 配置中设置特定配置，以便根据该变量的值做出不同响应，从而增强对被代理请求中连接处理的控制。 典型的使用场景可能包括增加日志记录、仅对内部连接修改请求头而不对外部连接修改，或应用特殊的安全措施以防止在面向公开的连接上暴露某些功能。日志随后可以根据该变量的状态指示不同的路由路径，从而便于故障排查和性能监控。

配置示例

location /proxy {
    proxy_pass http://backend;
    # Log whether the connection is internal or not
    access_log /var/log/nginx/internal_access.log;
    if ($proxy_internal_connection) {
        # Internal requests can have specific handling 
        set $internal 'true';
    }
}

说明

`$proxy_internal_body_length` 变量在 NGINX 中用于服务器之间的代理场景，特别是在 NGINX 作为反向代理时。该变量用于跟踪从上游服务器接收到的请求体的大小。该变量的值在 NGINX 处理来自上游服务器的请求后被设置，通常是在请求被转发或接收到响应时。 在需要监控或处理主体内容大小的配置中，此变量尤其有用。例如，如果你在基于主体大小实现内容过滤、记录或条件处理，`$proxy_internal_body_length` 提供了一种即时且准确的方法来获取传入主体数据的长度。该变量的典型值会根据请求和响应场景而变化，但通常反映请求体中存在的字节数。 在这种代理场景中，当 NGINX 处理请求时，它会计算从被代理内容得出的主体长度，并在执行可能与大小相关的后续操作或指令之前将其设置到该变量中。

配置示例

location /proxy {
    proxy_pass http://backend;
    access_log /var/log/nginx/proxy.log "$proxy_internal_body_length";
}

说明

变量 $proxy_internal_chunked 控制由 NGINX 的 proxy 模块转发的内部响应所使用的传输编码方式。当设置为 "on" 时，表示对于未指定 Content-Length 的响应，应使用 chunked transfer encoding 进行传输，使数据可以在生成时流式发送到客户端。这在响应长度事先未知的动态内容场景下尤为有用。 该变量通常在 location blocks 或 server contexts 中设置，主要用于 proxying 场景，即客户端请求由后端服务器处理时。NGINX 的默认行为是：如果 upstream server 未指定 Content-Length 头部，则使用 chunked encoding，这允许客户端在不必等待整个响应体发送完毕的情况下立即开始处理响应。开发者可以根据具体用例和所连接的 upstream 服务的行为，有选择地启用或禁用此功能，从而在数据如何被提供方面获得更大的灵活性。 在实际使用中，当处理大型或流式响应时，proxy_internal_chunked 可能带来性能上的好处，但对于无法正确处理 chunked responses 的客户端会增加复杂性。因此在配置 NGINX 使用此变量时，应仔细考虑客户端兼容性和性能方面的影响。

配置示例

location /api {
    proxy_pass http://backend;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_buffering off;
    # Enable chunked transfer for internal responses
    set $proxy_internal_chunked on;
}

说明

$fastcgi_script_name 变量在 NGINX 配置中用于检索传递给 FastCGI 服务器的脚本名称。该变量主要在使用 `fastcgi_pass` 指令（将请求转发到 FastCGI 服务器）时被设置。当处理传入请求时，NGINX 会从请求中提取 URI 的脚本部分，并相应地设置该变量的值。它确保 FastCGI 应用接收到用于处理的正确脚本路径，这对依赖特定路由机制的应用至关重要，例如运行在 FastCGI 下的 PHP 或 Python 应用。 在典型用法中，$fastcgi_script_name 会返回诸如 `/index.php` 或 `/app/script.php` 这样的值，反映应执行的脚本。如果没有找到脚本或请求未针对脚本，变量可能为空。因此，该变量不仅对路由到正确脚本很重要，而且在通过 URL 结构严格控制文件访问的应用中也起着关键作用。

配置示例

location / {
    include fastcgi_params;
    fastcgi_pass 127.0.0.1:9000;
    fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
}

说明

在与 FastCGI 应用交互时，NGINX 会使用 $fastcgi_path_info 变量。它提供了可能出现在脚本名之后的额外路径信息（即 URL 中的附加部分）。当处理需要将 URL 的某些元素传递给后端应用以进行处理的 RESTful API 或 Web 应用时，这个值尤其重要。例如，如果对 /api/users/123 发出请求，其中的 '123' 会被视为 path info，并作为 $fastcgi_path_info 变量的值返回。 该变量主要在 NGINX 的 FastCGI 配置中设置，特别是在处理脚本请求时的 server block 中。它使 NGINX 能够将传入请求正确映射到相应的 FastCGI 应用，从而实现更灵活的路由并与可能依赖解析该 path info 的各类 web frameworks 集成。需要注意的是，如果 URL 在脚本名之后没有任何额外的路径段，则 $fastcgi_path_info 将为空。 在典型场景下，当在 NGINX 中定义 FastCGI location block 时，你会设置指向 FastCGI 脚本的路径，同时允许 NGINX 通过该变量管理额外的路径信息，该信息可以被相应的 Web 应用利用。

配置示例

location ~ \.php$ {
    include fastcgi_params;
    fastcgi_pass 127.0.0.1:9000;
    fastcgi_index index.php;
    fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
    fastcgi_param PATH_INFO $fastcgi_path_info;
}

说明

$grpc_internal_trailers 变量在 gRPC 协议上下文中用于访问 gRPC 响应的 trailer 字段。gRPC 中的 trailer 是可以在响应末尾发送的键值对，类似于 HTTP headers，允许在响应体之外传递额外的元数据。只有当服务器处理 gRPC 请求并且能够处理 trailer 字段时，该变量才会被填充。 在处理 gRPC 响应时，如果相关的 trailer 信息被设置为包含，则可以通过 $grpc_internal_trailers 访问。因此，该变量通常包含以类似于 HTTP headers 的格式表示的 trailer 字段的字符串表示，字段之间由逗号或换行符分隔。如果请求没有返回任何 trailers，则该变量将保持为空。使用 trailers 可以提高通信效率，使服务器能够在不增加响应体开销的情况下随响应发送重要信息。

配置示例

location /example {
    grpc_pass grpc://backend;
    add_header Trailer 'grpc-status';
    set $status $grpc_internal_trailers;
}

说明

NGINX 中的 $ssl_protocol 变量会暴露在客户端和服务器之间为安全连接协商的特定 SSL/TLS 协议版本。仅当配置中启用了 SSL 时，此变量才会被设置，并且它反映了运行时当前请求所使用的最新协议版本。它可以返回例如 'TLSv1.2'、'TLSv1.3' 或 'SSLv3' 等值，具体取决于服务器的 SSL 配置中启用的协议。 在使用时，$ssl_protocol 对于在 NGINX 配置中进行记录和条件处理特别有用。例如，管理员可能希望根据所使用协议的安全等级来调整设置。该变量通常在 TLS handshake 过程中被填充，并且像其他 connection-level variables 一样，可在 location 或 server blocks 等不同上下文中访问。这使得基于正在使用的协议版本应用条件逻辑或增强安全措施变得简单。 用户应当理解，不同协议值的可用性在很大程度上取决于 server block 中配置的 cipher suites 和协议。如果某个特定协议版本（例如 TLSv1.3）未启用，$ssl_protocol 的值可能会反映服务器和客户端可以协商的下一个可用版本。

配置示例

server {
    listen 443 ssl;
    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    # Log the SSL protocol used
    access_log /var/log/nginx/ssl_protocol.log 'SSL Protocol: $ssl_protocol';
}

说明

NGINX 中的 $ssl_cipher 变量提供当前用于 SSL/TLS 连接的加密套件名称。该变量对日志记录和调试非常有用，因为它允许管理员确定为安全连接协商的加密算法。$ssl_cipher 的值在 SSL 握手过程中设置，当客户端通过 HTTPS 发起连接时会发生该过程。根据所选的加密套件，$ssl_cipher 变量可能包含诸如 'ECDHE-RSA-AES256-GCM-SHA384' 或 'ECDHE-ECDSA-CHACHA20-POLY1305' 等值。 在为 NGINX 配置 SSL/TLS 时，了解服务器端和客户端的 SSL 实现所支持的加密套件非常重要。支持的加密套件可以在 NGINX 配置文件中使用 ssl_ciphers 指令指定。$ssl_cipher 的实际值将反映在该 ssl_ciphers 指令中设置的配置，并且可能还取决于用于构建 NGINX 的 OpenSSL 版本。如果客户端尝试使用服务器不支持的加密套件进行连接，则连接将失败，且 $ssl_cipher 变量不会被设置。 除了在处理 SSL 连接时存在外，还可以将 $ssl_cipher 与日志记录指令结合使用以捕获与安全相关的数据，从而有助于分析和监控安全会话。这种可见性有助于理解客户端连接、实施安全合规性并优化加密套件配置。

配置示例

server {
    listen 443 ssl;
    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;
    ssl_ciphers 'HIGH:!aNULL:!MD5';
    access_log /var/log/nginx/access.log combined;
    location / {
        add_header X-SSL-Cipher $ssl_cipher;
    }
}

说明

`$ssl_ciphers` 变量在 NGINX 中会在处理 HTTPS 请求时自动设置。该变量保存客户端和服务器在 SSL/TLS 握手过程中协商的密码套件的字符串表示。它对日志记录和调试特别有用，因为它可以让服务器管理员了解用于安全连接的密码套件。 只有在 NGINX 中启用了 SSL 模块时该变量才会被填充，并且仅适用于处理 SSL 连接的 server 块。`$ssl_ciphers` 的典型值可能看起来像 'ECDHE-RSA-AES128-GCM-SHA256:ECDHE-RSA-AES256-GCM-SHA384'，表示一个以逗号分隔的密码套件名称列表。出现在该变量中的具体密码取决于在 NGINX server 上下文中定义的 `ssl_ciphers` 配置指令，以及客户端在握手期间的能力和偏好。 在实践中，`$ssl_ciphers` 还可以通过允许管理员根据所使用密码的强度有条件地调整配置，来促进诸如 HSTS（HTTP 严格传输安全）等安全措施的实施。这种遵循安全通信协议的做法增强了 Web 应用的整体安全性。

配置示例

server {
    listen 443 ssl;
    ssl_certificate     /path/to/certificate.crt;
    ssl_certificate_key /path/to/private.key;
    ssl_ciphers 'ECDHE-RSA-AES128-GCM-SHA256:ECDHE-RSA-AES256-GCM-SHA384';
    access_log /var/log/nginx/ssl_ciphers.log combined;
}

location / {
    add_header X-Cipher-Used "$ssl_ciphers";
}

说明

$ssl_curve 变量在 NGINX 中用于暴露用于建立 SSL/TLS 连接的椭圆曲线。该变量特定于使用 SSL 协议的连接，并在 SSL 握手成功完成后设置。该变量的值可能会根据在握手过程中客户端与服务器协商的椭圆曲线而有所不同。常见值包括 'P-256'、'P-384'、'P-521' 等，具体由服务器的 SSL/TLS 配置决定。 $ssl_curve 的值在 NGINX 配置中的日志记录或条件访问控制场景中特别有用。它可以帮助管理员了解正在使用的曲线，这可能关系到性能考虑或安全合规性需求。需要注意的是，该变量仅在 SSL 激活的上下文中有效，不应在 SSL-enabled server block 或处理安全流量的 location 之外使用。 在配置中使用 $ssl_curve 变量时，应基于对 SSL/TLS 协议以及所选椭圆曲线在密码学操作中重要性的理解来谨慎对待，尤其是在不断变化的安全环境中。

配置示例

server {
    listen 443 ssl;
    server_name example.com;
    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    location / {
        add_header X-Ssl-Curve $ssl_curve;
        # Other location directives
    }
}

说明

$ssl_curves 是 NGINX 中的一个变量，包含已为 SSL/TLS 会话协商用于使用的椭圆曲线名称。使用现代加密标准以确保通信安全时，该变量尤其相关。该变量的值在建立 SSL 连接时设置，如果协商的会话支持多个曲线，它可以反映多个曲线。该变量的典型值可能包括诸如 "P-256"、"P-384" 或 "P-521" 等名称，具体取决于服务器和客户端两端支持的曲线。 该变量在监控和故障排查 SSL/TLS 连接时尤其有用，因为它允许实时查看在安全通信中被接受和使用的加密方法。管理员可以利用此信息确保其配置设置为使用最佳曲线，从而在 Web 应用部署中促进更好的安全实践。值得注意的是，可用的具体椭圆曲线取决于 OpenSSL 库的版本及其配置。 总之，如果您希望控制或优化 SSL 连接的曲线设置，利用 $ssl_curves 变量可以提供有价值的洞见，帮助评估您的配置与当前安全最佳实践的符合程度。

配置示例

server {
    listen 443 ssl;
    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    location /status {
        # Show the negotiated SSL curves for monitoring
        add_header Content-Type text/plain;
        return 200 "$ssl_curves";
    }
}

说明

$ssl_sigalg 变量在 SSL 握手过程中设置，具体是在客户端与 NGINX 服务器建立安全连接时。该变量捕获并提供了在交换中所使用的签名算法的信息，这对审计、日志记录或基于连接期间建立的安全参数进行条件配置非常重要。 $ssl_sigalg 的典型值可以包括用于 SSL/TLS 通信的各种密码算法，例如 `SHA256 with RSA Encryption`、`SHA1`，甚至 `ECDSA` 签名等，这取决于服务器的 SSL 配置和客户端支持的协议。随着 SSL/TLS 协议的发展，可用算法及其表示形式也可能发生变化，从而反映在该变量返回的值中。通常在需要基于签名算法强度进行特定处理的场景中使用该变量，允许服务器管理员强制实施安全策略。 $ssl_sigalg 变量主要在启用 SSL 的虚拟服务器环境中使用，可以与像 `if` 这样的指令中的条件表达式一起使用，或简单地输出到日志格式以便监控。它为希望确保客户端连接使用的签名算法符合安全实践的用户提供了可配置性和洞察。

配置示例

log_format custom_format '$remote_addr - $remote_user [$time_local] "$request" $status $body_bytes_sent "$http_referer" "$http_user_agent" "$ssl_sigalg"';

access_log /var/log/nginx/access.log custom_format;

说明

在 NGINX 中，$ssl_session_id 变量表示与当前活动的 SSL 会话关联的会话 ID。该变量在 SSL 连接建立后可用，通常与 SSL 会话缓存配置结合使用，以优化 SSL/TLS 握手。每个已建立的 SSL 会话都可以通过其会话 ID 引用，该 ID 用于在无需重新协商握手的情况下恢复会话。该变量对于安全地监控、记录或管理用户会话特别有用。 $ssl_session_id 通常是唯一标识 SSL 会话的十六进制字符串。它在握手过程中创建，并在客户端尝试恢复 SSL 会话时使用。如果会话恢复不受支持或被禁用，则该变量可能返回空字符串。因此，必须确保服务器启用了 SSL 会话缓存，才能有效利用该变量的优势。常见的值可能类似 '00:11:22:33:44:55:66:77:88:99:AA:BB'，表示会话 ID 的十六进制表示。 该变量适用于各种场景，例如在日志配置中捕获 SSL 会话信息，或在基于 SSL 会话属性启用特定访问控制时使用。此外，将相关变量（例如 $ssl_protocol 和 $ssl_cipher）与 $ssl_session_id 结合使用可以提供更深入的洞察。

配置示例

http {
    server {
        listen 443 ssl;
        ssl_certificate /etc/ssl/certs/my_cert.pem;
        ssl_certificate_key /etc/ssl/private/my_cert.key;

        location / {
            access_log /var/log/nginx/access.log combined;
            add_header X-SSL-Session-ID $ssl_session_id;
        }
    }
}

说明

$ssl_session_reused 变量在 SSL 握手过程中如果成功重用 SSL 会话则被设置为 'on'，如果创建了新会话则为 'off'。当客户端使用相同的 SSL 会话参数重新连接到服务器时，通常会发生这种重用，从而通过避免完全重新协商来加快握手过程。 NGINX 使用会话 ID 或会话票证来实现会话重用。如果客户端提供服务器识别的有效会话 ID 或票证，服务器将使用现有会话，从而降低延迟并提高性能。监控该变量有助于诊断 NGINX 设置中 SSL 会话管理的效果，对于具有频繁 SSL 连接的高性能应用尤其有用。 $ssl_session_reused 的可能值为 'on' 或 'off'，其中 'on' 表示会话被重用，'off' 表示未重用的新 SSL 连接。该变量通常可以在响应头或日志格式中找到，以帮助故障排查和性能分析。

配置示例

log_format main '$remote_addr - $remote_user [$time_local] "$request" $status $body_bytes_sent "$http_referer" "$http_user_agent" "$ssl_session_reused"';

access_log /var/log/nginx/access.log main;

说明

在 NGINX 中，当服务器配置为支持 TLS 1.3 时会使用 $ssl_early_data 变量，TLS 1.3 支持一种称为 "0-RTT"（或早期数据）的特性。该特性允许客户端在 TLS 握手完全完成之前发送数据，从而实现更快的通信，但同时存在一些安全方面的考量。当收到早期数据时，$ssl_early_data 的值被设置为 "1"；否则设置为 "0"。 该变量在确定如何处理可能使用早期数据发送的请求时特别有用。例如，依赖早期数据可能会引入如重放攻击等风险，因此用户必须实现必要的逻辑来防范此类漏洞。NGINX 可以在条件配置中利用该变量的值，根据请求是否使用了早期数据来应用不同的限制或响应。

配置示例

server {
    listen 443 ssl;
    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    location / {
        # Check if early data was received
        if ($ssl_early_data) {
            return 400;  # Reject early data requests if needed
        }
        # Normal processing for regular requests
        proxy_pass http://backend;
    }
}

说明

变量 $ssl_server_name 在启用 SSL 的 NGINX server 块上下文中设置，主要用于在 SSL 握手阶段根据服务器名称识别哪个虚拟服务器正在处理请求。当客户端向 NGINX 服务器发起 SSL 连接时，服务器会将请求的主机名与每个 server 块中配置的 'server_name' 指令进行比较。使用第一个匹配的服务器，并将该服务器对应的名称存储在 $ssl_server_name 变量中。\n\n如果没有找到匹配的服务器名，$ssl_server_name 将为空，并且可能会改用默认服务器的名称（如果已配置）。该变量的行为类似于 $server_name；然而，它是在 SSL 握手过程中专门填充的，从而可用于日志记录、访问控制以及根据请求的主机名生成响应等各种用途。$ssl_server_name 的典型值为在 server 块中配置的 DNS 名称，例如 'example.com' 或 'www.example.com'。

配置示例

server {
    listen 443 ssl;
    server_name example.com www.example.com;
    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;
    location / {
        add_header X-SSL-Server-Name "$ssl_server_name";
    }
}

说明

$ssl_alpn_protocol 变量特定于在 TLS 握手期间使用 ALPN 的配置，例如 HTTP/2 或其他协议。当通过 HTTPS 建立连接时会设置该变量，从而允许服务器确定客户端选择了哪个应用层协议。它主要对那些在服务中实现协议可变性的服务器有用，例如根据客户端能力同时提供基于 HTTP/1.1 和 HTTP/2 的内容。该变量的值可以是协议名称，例如表示协商协议的 'h2'（用于 HTTP/2）或 'http/1.1'。 该变量对于性能优化尤为重要，因为它允许服务器根据 ALPN 列表使用客户端支持的最合适协议来响应请求。当客户端发起 TLS 握手时，它可以提出多个协议，服务器为该会话决定最合适的协议。如果客户端不支持服务器提供的任何协议，该变量将不会被设置，并且通常会回退到默认协议，通常是 HTTP/1.1。该协商机制可增强不同客户端实现之间的兼容性和性能。

配置示例

server {
    listen 443 ssl;
    ssl_certificate /path/to/certificate.crt;
    ssl_certificate_key /path/to/private.key;
    # Using the variable in a log format to capture the negotiated protocol
    access_log /var/log/nginx/access.log custom_format;

    location / {
        if ($ssl_alpn_protocol = 'h2') {
            # Perform actions specific to HTTP/2
        }
        # Other processing...
    }
}

log_format custom_format '$remote_addr - $remote_user [$time_local] "$request" $status $body_bytes_sent "$http_referer" "$http_user_agent" Protocol: $ssl_alpn_protocol';

说明

$ssl_ech_status 变量在支持 Encrypted ClientHello (ECH) 的 SSL 连接上下文中设置。它在 SSL 握手过程中传达客户端的 ECH 状态（由握手阶段确定）。该变量可以返回各种值，表明是否使用了 ECH 或在握手期间与其使用相关的任何错误。常见值包括 'on'（表示 ECH 成功协商）、'off'（表示客户端不支持）以及表示其他特定问题的错误代码。 当 NGINX 服务器配置了 SSL 和 ECH 支持时，会处理该变量。当客户端连接并尝试发起 ECH 握手时，服务器会评估该请求并相应地设置 $ssl_ech_status。这样，网站管理员可以根据 ECH 的状态实施细粒度访问控制或自定义响应，从而增强对支持 ECH 客户端提供的隐私功能。 在实践中，该变量可用于日志记录或在配置文件中编写条件，以根据客户端对加密的支持情况定制响应。这可能包括自定义应用服务器的行为，甚至根据客户端的安全能力重定向客户端。

配置示例

server {
    listen 443 ssl;
    ssl_certificate /etc/ssl/cert.pem;
    ssl_certificate_key /etc/ssl/key.pem;
    
    location / {
        if ($ssl_ech_status = 'on') {
            add_header X-ECH-Status 'Enabled';
        }
        if ($ssl_ech_status = 'off') {
            return 403;
        }
    }
}

说明

`$ssl_ech_outer_server_name` 变量是 NGINX 的 SSL 模块中的一个独特功能，当客户端在 TLS 握手期间使用 Encrypted ClientHello (ECH) 扩展时，该变量会捕获客户端提供的外层服务器名称。这样可以让客户端在一定程度上对其实际连接的服务器保持隐私，同时仍然使服务器能够根据意图的目标服务器名称来决定如何处理请求。 当客户端协商 ECH 扩展时，该变量会在 SSL 握手期间被设置。如果客户端在其 Encrypted ClientHello 中包含了外层服务器名称，则该变量将包含该名称。该变量的典型值为域名或主机头，例如 'www.example.com' 或 'api.example.com'，取决于客户端一侧的 ECH 实现。如果未提供外层服务器名称或 ECH 协商失败，该变量将为空。 使用该变量对于希望根据客户端原始意图的目标做出不同响应的应用程序尤为有用，同时还能在通信中保留一定程度的隐私。然而，该功能需要客户端具备兼容的设置以使用 ECH，这意味着并非所有请求都会在握手期间基于客户端的配置包含此变量。

配置示例

server {
    listen 443 ssl;
    server_name example.com;
    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/cert.key;
    location / {
        if ($ssl_ech_outer_server_name) {
            add_header X-Outer-Server-Name $ssl_ech_outer_server_name;
        }
    }
}

说明

在 NGINX 中，当发生 SSL 客户端证书验证时会使用 $ssl_client_cert 变量。该变量存储在 SSL 握手过程中提供的客户端证书，格式为 PEM 编码的字符串。当 'ssl_verify_client' 指令被配置为 'on' 且证书验证成功时，该变量被设置为客户端证书的值。 在需要进行客户端身份验证的安全通信场景（例如 API 服务或用户认证系统）中，这个变量特别有用。如果未提供客户端证书或验证失败，该变量将为空。该变量的内容可以记录到日志、在条件语句中进行评估，或在必要时传递给后端应用程序。 典型用途包括基于客户端证书属性（例如通用名 (CN) 或主题备用名 (SAN)）使用该变量来授权访问，从而在应用层增强安全性。在必须以安全方式确保每个客户端身份的服务中，这种方法至关重要，它利用了 SSL/TLS 协议。

配置示例

server {
    listen 443 ssl;
    server_name example.com;

    ssl_certificate /path/to/server.crt;
    ssl_certificate_key /path/to/server.key;

    ssl_client_certificate /path/to/ca.pem;
    ssl_verify_client on;

    location / {
        if ($ssl_client_cert) {
            add_header X-Client-Cert $ssl_client_cert;
        }
    }
}

说明

当 NGINX 配置为处理 SSL/TLS 连接且客户端出示证书用于认证时，会为变量 $ssl_client_raw_cert 赋值。该变量在处理通过 SSL 连接的请求的上下文中可用，当 'ssl_verify_client' 指令设置为 'on' 或 'optional' 时即可使用。原始客户端证书作为单个 base64-encoded 字符串输出，可用于记录、访问控制或任何需要了解客户端证书的应用特定处理。 该变量在实施双向 TLS (mTLS) 的安全环境中特别有用，因为它允许服务器管理员和应用开发者根据客户端证书施加规则，例如为了审计记录敏感信息，或根据证书的有效性或属性动态更改请求处理。此变量的典型值将以 base64-encoded 形式表示客户端在 SSL 握手期间传输的 X.509 证书，因此在需要跨受信任实体进行身份验证的场景中至关重要。 要在实践中使用此变量，NGINX 可以直接记录证书内容或根据证书属性（例如 subject 或 issuer）有条件地路由请求。诸如 'ssl_verify_client' 的设置需要谨慎配置，因为它们会直接影响应用安全性。

配置示例

server {
    listen 443 ssl;
    ssl_certificate /path/to/server.crt;
    ssl_certificate_key /path/to/server.key;
    ssl_verify_client on;

    location / {
        add_header X-Client-Cert $ssl_client_raw_cert;
        # Additional processing...
    }
}

说明

$ssl_client_escaped_cert 变量专门用于 HTTP 服务器上下文，当 HTTPS 连接使用客户端证书认证时使用。当客户端建立安全连接并提供证书时，该变量以既 URL-encoded 又经过安全转义的格式捕获该证书的全部详细信息，以便传输。这在记录日志或作为查询参数传递时特别有用，能够避免在 URL 中引入语法错误。 该变量仅在启用客户端证书验证并在 SSL 握手期间提供有效客户端证书时设置。它保存客户端证书的编码内容，允许服务器端应用利用客户端的身份进行授权或访问控制。该变量的典型值包括实际的 PEM-encoded 证书数据，该数据由 Base64-encoded 的证书组件组成，并被特定的 PEM 头部和尾部行包裹。如果未提供客户端证书，则该变量为空。 与其他 SSL 相关变量（例如 $ssl_client_cert 和 $ssl_client_verify）结合使用时，$ssl_client_escaped_cert 提供了在安全环境中管理客户端验证的完整机制，适用于不仅需要身份验证还需要安全传输证书数据以便进一步处理的场景。

配置示例

server {
    listen 443 ssl;
    server_name example.com;
    ssl_certificate /path/to/server.crt;
    ssl_certificate_key /path/to/server.key;
    ssl_client_certificate /path/to/client_ca.crt;
    ssl_verify_client on;

    location /secure-data {
        add_header X-Client-Cert "$ssl_client_escaped_cert";
    }
}

说明

$ssl_client_s_dn 变量会在客户端在 SSL 握手过程中出示有效的 SSL/TLS 证书时被填充，它包含该证书中指定的客户端的可分辨名称 (DN)。该变量源自客户端证书，并通过展示可分辨名称的属性来识别证书持有者，通常包括诸如通用名称、组织、国家等信息以及其他相关字段。该变量的存在与内容取决于 `ssl_verify_client` 指令被设置为 "on" 或 "optional"，从而确保 NGINX 要求或请求客户端证书。仅当有效的客户端证书被成功验证后，该变量才会在 NGINX 环境中可用。

配置示例

server {
    listen 443 ssl;
    ssl_certificate /path/to/server.crt;
    ssl_certificate_key /path/to/server.key;
    ssl_verify_client on;

    location / {
        if ($ssl_client_s_dn) {
            add_header X-Client-DN $ssl_client_s_dn;
        }
    }
}

说明

$ssl_client_i_dn 变量在使用客户端证书建立 SSL/TLS 连接时会被填充。具体来说，它包含客户端在 TLS 握手过程中由客户端证书提供的可分辨名称 (DN)。该变量主要在需要 SSL/TLS 客户端认证的上下文中可用，这种认证必须在 NGINX 配置中通过诸如 'ssl' 和 'ssl_verify_client' 之类的指令启用。通常，DN 会包含诸如客户端的通用名 (CN)、组织 (O) 和国家 (C) 等信息，按照 X.500 标准的格式。 当该变量被设置后，可在各种配置中使用，范围从根据客户端身份设置访问控制到根据客户端身份自定义响应。然而，如果在 SSL/TLS 连接中未使用客户端证书，该变量将不会包含任何数据。需要注意的是，该变量依赖于客户端认证是否成功；如果客户端未能提供有效证书或验证失败，$ssl_client_i_dn 将为空。对于需要基于客户端证书进行用户身份验证的应用程序而言，此变量的存在非常重要。

配置示例

server {
    listen 443 ssl;
    ssl_certificate /path/to/server.crt;
    ssl_certificate_key /path/to/server.key;
    ssl_verify_client on;

    location / {
        if ($ssl_client_i_dn) {
            return 200 'Client DN: $ssl_client_i_dn';
        }
        return 403 'Access denied';
    }
}

说明

$ssl_client_s_dn_legacy 变量在 NGINX 服务器建立需要客户端认证的 SSL/TLS 连接时被填充。具体来说，它提取客户端证书的主题可分辨名称（DN），其中包含客户端的身份、组织和国家等信息，按照 X.509 标准格式化。该值通常以字符串形式返回，DN 的各元素以文本格式表示，例如 'C=US, ST=California, L=San Francisco, O=Example Corp, CN=example.com'。 仅当启用指令 `ssl_verify_client` 时，该变量才会被设置，该指令要求客户端出示有效的 SSL 证书。如果客户端未提供证书或证书验证失败，该变量将为空。这对于记录日志、访问控制或依赖客户端身份的应用逻辑很有用。典型值会根据使用的客户端证书而大相径庭，且格式遵循标准的 DN 表示法。 在实际使用中，该变量可在不同配置中用于安全检查、基于客户端身份的条件处理，或仅用于记录连接详情以便更好地审计对 Web 服务的访问。例如，应用程序可能会使用此变量基于客户端所属组织强制实施访问控制，或将客户端详情记录用于分析目的。

配置示例

server {
    listen 443 ssl;
    ssl_certificate /path/to/server.crt;
    ssl_certificate_key /path/to/server.key;
    ssl_client_certificate /path/to/ca.crt;
    ssl_verify_client on;

    location /protected {
        if ($ssl_client_s_dn_legacy) {
            add_header X-Client-DN $ssl_client_s_dn_legacy;
        }
    }
}

说明

变量 $ssl_client_i_dn_legacy 在配置为使用 SSL/TLS 并启用客户端认证的 NGINX 服务器处理客户端请求时设置。当客户端在握手过程中提供 SSL 证书时，服务器会处理该证书以提取各种信息，包括客户端的可分辨名称 (DN)。该 DN 包含诸如通用名称 (CN)、组织 (O) 和国家 (C) 等属性。对于 $ssl_client_i_dn_legacy，该变量专门以与早期 NGINX 版本兼容的格式返回此 DN，主要用于向后兼容。该 DN 字符串的格式可能会根据客户端证书的签发方式和证书数据的具体内容而有所不同。

配置示例

server {
    listen 443 ssl;
    server_name example.com;

    ssl_certificate /path/to/your/cert.pem;
    ssl_certificate_key /path/to/your/key.pem;

    ssl_client_certificate /path/to/your/ca.pem;
    ssl_verify_client on;

    location / {
        add_header X-Client-DN $ssl_client_i_dn_legacy;
    }
}

说明

当 NGINX 配置为处理需要客户端证书进行身份验证的 SSL/TLS 连接时，会设置 $ssl_client_serial 变量。如果启用客户端验证，它会检索客户端 SSL 证书的序列号，这通常发生在配置了 "ssl_verify_client" 指令并将其设置为 "on" 或 "optional" 的 server 配置块中。在 TLS 握手期间当提供了有效的客户端证书时，NGINX 可以访问证书的各种属性，包括序列号，而序列号是证书实例的唯一标识符。 $ssl_client_serial 的值通常格式为十六进制字符串，表示证书的序列号。如果未启用客户端验证，或客户端未提供证书，则不会设置该变量，返回空字符串。该变量对于基于所使用的客户端证书身份来实现访问控制、日志记录或审计机制特别有用。

配置示例

server {
    listen 443 ssl;
    ssl_certificate     /path/to/your/server.crt;
    ssl_certificate_key /path/to/your/server.key;
    ssl_verify_client on;

    location / {
        if ($ssl_client_serial) {
            add_header X-Client-Serial $ssl_client_serial;
        }
    }
}

说明

当启用 SSL 客户端认证时，$ssl_client_fingerprint 变量在 NGINX 中使用。它为客户端的 SSL 证书提供一个唯一的指纹，该指纹基于加密哈希，通常使用 SHA-1 或 SHA-256 哈希算法生成。该指纹源自证书的数据，特别是其 `tbsCertificate` 结构。仅当成功执行 SSL 客户端认证时才会设置该变量，这意味着服务器已配置为要求客户端证书，且客户端在 SSL 握手期间已出示有效证书。该变量的典型值类似表示客户端证书哈希的十六进制字符串格式。这对于日志记录、访问控制以及基于客户端身份应用额外自定义逻辑非常有用。

配置示例

server {
    listen 443 ssl;
    ssl_certificate /path/to/server.crt;
    ssl_certificate_key /path/to/server.key;
    ssl_client_certificate /path/to/ca.crt;
    ssl_verify_client on;

    location / {
        # Use the fingerprint in access logs
        access_log /var/log/nginx/access.log combined; # Redis or any other designated log format
        set $client_fp $ssl_client_fingerprint;
        if ($client_fp) {
            # More logic can be applied here based on the fingerprint
        }
    }
}

说明

当 NGINX 服务器被配置为使用 SSL 客户端验证时，会设置变量 $ssl_client_verify。该变量可取特定值，以表示客户端 SSL 证书验证过程的结果。如果未提供客户端证书，则可设置为 'none'；如果未启用客户端验证，则为 'off'；根据验证结果则为 'success' 或 'failed'。此功能属于 NGINX 核心 SSL 模块，该模块管理安全连接，并确保证书可针对在 NGINX 中配置的受信任 CA 证书进行验证。 当通过诸如 "ssl_verify_client" 这样的指令启用客户端证书验证时，服务器使用该变量来判断在 SSL 握手过程中是否提供了有效的客户端证书。验证可以包括对证书有效期、吊销状态以及证书是否由受信任的 Certificate Authority (CA) 签发的检查。在处理请求时，NGINX 会设置 $ssl_client_verify 的值以反映验证结果，该值可在配置段中用于条件处理或记录日志。

配置示例

server {
    listen 443 ssl;
    ssl_certificate /path/to/server.crt;
    ssl_certificate_key /path/to/server.key;
    ssl_client_certificate /path/to/trusted_ca.crt;
    ssl_verify_client on;

    location /private {
        if ($ssl_client_verify != "success") {
            return 403;
        }
        # handle the request for authenticated clients
    }
}

说明

变量 $ssl_client_v_start 是 NGINX 对 SSL/TLS 的支持的一部分，对于记录和调试非常有用。它捕获 SSL 握手的开始时间，更精确地说是客户端和服务器之间 SSL 连接完全建立的时间。此时间戳以自纪元（1970 年 1 月 1 日）以来的秒数表示。 该变量在请求处理期间一旦建立 SSL 连接就会变得可用。可以在请求的上下文中访问 $ssl_client_v_start 的值，从而允许 NGINX 记录该事件发生的精确时刻。了解 SSL 连接的开始时间可以帮助开发人员和系统管理员进行性能监控，因为它有助于理解 SSL 握手的持续时间并排查任何相关的延迟问题。该变量的典型值将以 UNIX 时间戳的形式出现，例如 '1672531199'。

配置示例

server {
    listen 443 ssl;
    server_name example.com;

    ssl_certificate /etc/ssl/certs/example.com.crt;
    ssl_certificate_key /etc/ssl/private/example.com.key;

    access_log /var/log/nginx/access.log combined;

    location / {
        add_header X-SSL-Client-V-Start "$ssl_client_v_start";
    }
}

说明

$ssl_client_v_end 变量在 NGINX 配置为使用 SSL 时可用，用于访问客户端 SSL 会话的结束时间。该时间戳通常在 SSL 连接完成并且客户端完成 SSL 握手时设置。该值以自 January 1, 1970 (the Unix epoch) 起经过的秒数表示。 当与客户端建立 SSL 连接时，会为各种事件记录多个时间戳，包括会话的开始和结束时间。$ssl_client_v_end 变量专门捕获客户端 SSL 连接正式结束的时刻。对于需要了解 SSL 连接持续时间或时间点的场景（例如日志记录、分析等），这非常有用。该变量的值为 Unix time 形式的时间戳，例如典型值可能是 1682467654，对应 UTC 的特定日期和时间。 在需要管理或监控会话的场景中，该变量有助于跟踪客户端与服务器之间安全通信的生命周期，提供有关连接何时建立和结束的洞察，这在高流量环境中尤其有用，在这些环境中安全性能至关重要。

配置示例

server {
    listen       443 ssl;
    server_name  example.com;

    ssl_certificate      /path/to/cert.pem;
    ssl_certificate_key  /path/to/key.pem;

    location / {
        access_log /var/log/nginx/access.log;
        set $end_time $ssl_client_v_end;
        # additional configuration
    }
}

说明

变量 $ssl_client_v_remain 属于 NGINX 的 SSL 模块，在处理客户端证书时使用。当客户端为认证提交证书时，通常会发送一个证书链。$ssl_client_v_remain 变量表示在处理完当前证书后，该证书链中还剩余多少字节。在涉及多个证书的复杂认证场景（例如 mutual TLS (mTLS) 配置）中，这一点尤其有用。 该变量在 SSL 握手发生时设置，并在成功完成 SSL 握手后对服务器指令可见。它返回一个数值，表示尚未读取的证书数据的剩余字节数。通常，它的返回值可能从 0（当所有证书都已处理）到客户端发送的初始证书链的总长度不等。 例如，如果客户端发送了一个总计 300 字节的三证书链，且第一个证书（大约 100 字节）已处理，则在那之后 $ssl_client_v_remain 会报告 200 字节。该信息使 NGINX 能够根据 SSL 服务器的配置以及基于有效证书的任何指定身份验证要求做出有根据的决策。

配置示例

server {
    listen 443 ssl;
    ssl_certificate     server.crt;
    ssl_certificate_key server.key;

    location / {
        if ($ssl_client_v_remain > 0) {
            add_header X-SSL-Client-Remain $ssl_client_v_remain;
        }
    }
}

说明

当客户端在 TLS 握手期间提供 SSL 证书时，会设置变量 $ssl_client_sigalg。它保存用于签署客户端证书的签名算法。此变量对于验证客户端证书的应用程序非常重要，应用程序可能会根据签名算法的安全级别决定是否允许或拒绝访问。$ssl_client_sigalg 的取值可能不同；常见算法包括 'sha256WithRSAEncryption'、'sha1WithRSAEncryption' 等，具体取决于客户端的配置和安全策略。 NGINX 仅在启用客户端 SSL 证书的上下文中设置此变量，特别是在 'server' 和 'location' 块中且 ssl_verify_client 指令被设置为 'on' 或 'optional' 的情况下。如果未提供客户端证书，该变量将为空。这对日志记录或调试特别有用，因为它允许服务器管理员查看访问其服务的客户端使用了哪些签名算法，并基于这些信息做出明智决策。此外，客户端 SSL 配置的更改可能会改变此处生成的值，应相应地进行监控。

配置示例

server {
    listen 443 ssl;
    ssl_certificate /path/to/server.crt;
    ssl_certificate_key /path/to/server.key;
    ssl_client_certificate /path/to/client_ca.crt;
    ssl_verify_client on;

    location / {
        if ($ssl_client_sigalg = 'sha256WithRSAEncryption') {
            # Log or take action for clients using SHA256
            access_log /var/log/nginx/ssl.log;
        }
    }
}

说明

$realip_remote_addr 变量用于在 NGINX 被配置为在代理或负载均衡器后面运行时检索客户端的真实远程 IP 地址。 当客户端通过中间服务器连接时，通常会出现这种情况，标准连接方法难以确定原始客户端的 IP 地址。NGINX 通过使用 X-Real-IP 或 X-Forwarded-For HTTP headers 来有效处理这种情况，这些是传递源 IP 地址的常用标准。 当 NGINX 收到请求时，会按指定顺序检查这些 headers；如果在某个 header 中找到 IP 地址，就将 $realip_remote_addr 变量设置为该值。如果这些 header 不存在，则该变量默认为 NGINX 可见的直接客户端 IP 地址。正确解释此变量通常需要同时正确配置上游代理设置和用于传递客户端 IP 的 headers。这样可以确保显示和记录的信息正确，从而提高数据准确性和安全措施。 通常，$realip_remote_addr 的值要么反映发起请求的客户端的真实远程 IP 地址，要么在无法解析原始 IP 时回退到已知的最后一个 IP。在涉及多层网络的场景中，这一点尤为重要，因为它通过提供准确的客户端标识来增强日志记录和访问控制能力。

配置示例

http {
    set_real_ip_from 192.0.2.0/24; # Allow this range to set the real IP
    real_ip_header X-Forwarded-For;   # Specify the header to use

    server {
        listen 80;
        location / {
            # Access can be logged with the original client's IP
            access_log /var/log/nginx/access.log main;
        }
    }
}

说明

$realip_remote_port 变量用于反向代理场景，表示客户端连接到服务器时使用的原始端口号。当 NGINX 位于负载均衡器或代理之后，并且需要实际的客户端连接详情用于日志或其他处理时，该变量尤其有用。当使用 real_ip 模块时，此变量会变得可用，real_ip 模块允许 NGINX 在请求由其他服务器（例如 Web 应用防火墙或负载均衡器）转发时正确识别客户端的 IP 和端口。 此变量通常包含表示端口号的数字值，例如 443（HTTPS）或 80（HTTP），具体取决于客户端最初如何连接。如果在 NGINX 配置中正确设置了 `real_ip_header` 指令以捕获传入请求的头（如 X-Forwarded-For），并且配置正确且这些头存在，则 $realip_remote_port 变量将准确反映客户端使用的端口。未正确设置可能导致日志记录不正确和客户端连接识别错误。 总之，$realip_remote_port 变量通过确保应用在经由各种中间服务器处理时仍能引用客户端的实际连接详情，从而增强了安全性和监控能力。

配置示例

http {
    set_real_ip_from 192.168.1.1;  # Example trusted proxy
    real_ip_header X-Forwarded-For;
}

server {
    location / {
        access_log /var/log/nginx/access.log combined;
    }
}

# In the combined log format, you can include the realip remote port
log_format combined '$remote_addr - $remote_user [$time_local] "$request" $status $body_bytes_sent "$http_referer" "$http_user_agent" $realip_remote_port';

说明

在 NGINX 中，$invalid_referer 变量用于指示传入 HTTP 请求的 Referer 头是否根据预定义的访问规则被视为无效。该变量主要与 ngx_http_access_module 关联，该模块允许管理员在配置文件中使用 allow 和 deny 指令设置允许或拒绝的 Referer。每当处理请求时，模块会将 Referer 头与已配置的规则进行比对。如果 Referer 与任何允许的条目都不匹配且符合拒绝条件，则将 $invalid_referer 设置为 1。 该功能在内容安全至关重要的场景中特别有用，例如防止未授权网站滥用资源。该变量在 Referer 无效时通常返回值 1；否则保持未设置，表示 Referer 有效。需要注意的是，Referer 可以被客户端篡改，因此不应仅依赖 Referer 检查来执行安全策略。 通过在 NGINX 配置中基于该变量的值实现条件逻辑，$invalid_referer 可以帮助控制对资源的访问，从而实现细粒度的访问管理和安全机制。

配置示例

location /protected {
    valid_referers none blocked example.com;
    if ($invalid_referer) {
        return 403;
    }
}

说明

$secure_link 变量用于在 NGINX 中管理和验证对资源（例如文件或数据）的安全链接，确保基于令牌将访问限制为授权用户。当生成安全链接时，通常会使用包括 document root、URI 和到期时间戳等参数进行哈希。因此，该变量包含客户端用于验证并获取受保护资源访问的此哈希链接的值。 只有在特定条件下该变量才会被设置，尤其是在启用了 secure_link 模块并且在 http、server 或 location 上下文中配置了指定的 `secure_link` 指令时。它通过将提供的令牌与预期的安全链接进行比较来验证请求，确保链接既是有时效性的（仅在特定时段内有效），又对每个客户端是唯一的。该变量的常见值通常反映基于 secure_link 指令配置生成的哈希。 在实践中，这有助于防止对敏感文件的未授权访问，使其适用于需要内容保护的应用场景，例如私有媒体文件或软件下载。为确保平稳运行，除了令牌的生成外，还需要仔细管理它们的过期和停用策略，以提升访问安全性。

配置示例

location /protected_file {
    secure_link $arg_st,$arg_e;
    secure_link_secret your_secret;

    # Validate secure link
    if ($secure_link = "") {
        return 403; # deny access
    }

    # Allow access if validation passes
    root /path/to/your/files;
    add_header Content-Disposition "attachment; filename=protected_file";
}

说明

`$secure_link_expires` 变量在 NGINX 中保存安全链接的过期时间，特别是在使用 `secure_link` 指令时定义。该变量通常与 `$secure_link` 变量一起设置，后者为安全 URL 访问生成唯一签名。它返回的过期时间以 Unix 时间戳格式表示，指示安全资源何时不再可访问。如果未显式设置，默认值为 0，使链接无限期有效，除非通过配置设置限制。 在使用 `$secure_link` 机制时，通常同时定义链接及其过期时间以提供对资源的临时访问。过期时间可以通过 `secure_link` 指令中的 `expires` 参数设置，该指令在你的 NGINX 配置中指定。通过提供合适的过期值，例如当前时间加上某个有效持续时间（例如一天的秒数），你可以基于时间敏感的参数有效地管理对资源的访问。 该变量在需要对文件（例如媒体内容、下载文件或其他敏感资源）实施时限访问的场景中非常有用。将其与访问控制指令结合使用，可以为经过身份验证的用户创建安全的短期链接，从而增强应用的安全性。

配置示例

location /protected {
    secure_link $arg_md5,$secure_link_expires;
    secure_link_md5 "$uri$time$key";
    if ($secure_link = 0) {
        return 403;
    }
}

说明

$uid_got 变量在 NGINX 中表示与请求关联的用户的唯一标识符。该变量通常由 NGINX 核心在处理请求时设置。在需要基于用户权限的访问控制或通过日志跟踪用户活动的配置中，它尤其有用。当收到请求时，NGINX 会检查关联的用户 ID，该 ID 可从多种来源派生，包括系统用户，用于身份验证和授权检查。 在使用基于用户的访问控制的环境中，例如与需要独立用户权限的应用集成时，$uid_got 变量变得至关重要。该变量在连接建立时被填充，并反映分配给该连接的 UID。鉴于其特性，该值可能会根据请求的处理方式和运行上下文而变化。通常，你会看到的值范围为 0 到 65535，对应于类 UNIX 系统上的常见用户 ID（或保留用户 ID）。 为增强安全性和精确的日志记录，可以在自定义的 NGINX 日志格式中记录 $uid_got 变量，或在条件配置中使用它根据用户标识限制访问，从而帮助建立稳健的访问控制策略。

配置示例

location /protected {
    if ($uid_got = 1001) {
        return 403;  # Deny access to users with UID 1001
    }
    proxy_pass http://backend;
}

说明

该 $uid_set 变量在 NGINX Core 中定义，用于反映为当前请求设置的用户 ID。该变量在基于用户身份处理特定访问控制和安全配置时尤其相关。用户 ID 通常通过认证机制建立，例如用户成功登录或发送包含身份凭证的请求。 在使用 $uid_set 时，各种模块通常会在内部对其进行处理，这些模块可能从请求头或会话令牌中提取用户凭证。如果请求发生重定向或后端应用修改了认证上下文，该变量的值可能会在事务中途发生变化。$uid_set 的典型值可能是用户 ID 的数字表示，或者在未找到已认证用户时为一个空字符串。

配置示例

server {
    listen       80;
    server_name  example.com;

    location / {
        if ($uid_set) {
            return 200 'User ID is set';
        }
        return 403 'Access denied';
    }
}

说明

$uid_reset 变量用于 NGINX 服务器的访问控制场景。它主要用于根据已定义的访问规则管理和控制对入站连接的用户标识符（UID）是否重置。当请求因匹配访问控制条件而被拒绝时，例如由 'allow' 和 'deny' 指令定义的 IP 地址块，该变量被设置为 '1'。如果请求被允许，$uid_reset 保持为 '0'。此行为对那些需要依据用户连接是否被拒绝来执行逻辑的应用程序非常重要，允许基于该状态实现自定义响应或日志记录机制。 该变量的实际设置发生在访问模块（access module）执行期间，尤其是在处理入站请求的上下文中。具体来说，如果某条规则因某种条件明确拒绝访问，NGINX 会更新 $uid_reset 变量以反映该拒绝。因此，在配置中使用此变量的用户可以用它来有条件地执行指令或记录在访问控制逻辑中用户 UID 被重置的特定情况，从而有效加强访问权限的安全性与管理。

配置示例

http {
    server {
        location / {
            allow 192.168.1.0/24;
            deny all;
            if ($uid_reset) {
                return 403;
            }
            proxy_pass http://backend;
        }
    }
}

说明

$gzip_ratio 变量是 NGINX 中的一个动态变量，用于表示在启用 gzip 压缩时，响应的压缩后大小与原始大小的比率。该变量在响应被提供时计算，具体是在使用 'gzip' 模块在将输出发送给客户端之前对其进行压缩时。该值基于未压缩响应的大小与压缩后响应的大小计算，便于评估压缩的有效性。 当在 NGINX 中启用了 gzip 模块并且某个响应正在被压缩时，$gzip_ratio 变量会在压缩完成后设置。典型输出值的范围是 1 到 100，其中 100 表示响应根本未被压缩，而较小的值表示压缩效率更高。开发者可以利用此变量监控性能并相应地调整 gzip 设置，以确保带宽的最佳使用并改善用户的加载时间。 在 gzip 无法有效压缩响应的情况下，该变量可能显示为 100。这使得管理员可以诊断某些类型的内容（例如已经压缩的文件，例如 JPEG 图像）不应由 gzip 处理，因为进一步压缩不会带来好处。

配置示例

gzip on;
gzip_min_length 1024;
set $compression_ratio $gzip_ratio;

说明

变量 $limit_conn_status 在 NGINX 中用于表示对客户端请求施加的连接限制的状态。当通过 'limit_conn' 指令启用连接限制时，该变量会被设置以反映客户端连接相对于定义的限制的状态。该变量的典型值包括 'none'（表示未超出限制）、'exceeded'（当客户端超过允许的连接数）或 'aborted'（当连接处理被中止时）。 在 NGINX 配置中，$limit_conn_status 的值对日志记录或条件处理特别有用。它提供了关于服务器对客户端施加的连接限制的重要反馈。可以利用这些反馈来创建自定义响应或基于客户端连接行为记录特定事件。NGINX 在处理请求时，在评估诸如 'limit_conn_zone' 和 'limit_conn' 之类的指令施加的连接限制后设置该变量。

配置示例

http {
    limit_conn_zone $binary_remote_addr zone=addr:10m;

    server {
        limit_conn addr 1;

        location / {
            if ($limit_conn_status = exceeded) {
                return 503;
            }
            # Other configurations...
        }
    }
}

说明

$limit_req_status 变量在 NGINX 配置中用于指示由 'limit_req' 模块定义的速率限制指令产生的响应状态。当请求超过设定速率时，NGINX 可以返回特定的状态码，例如 503（Service Unavailable），或者返回带有 'limit exceeded' 消息的 503。$limit_req_status 变量会捕获这些状态码，并可用于记录日志或进一步处理。 该变量在创建自定义错误页面或基于状态对特定响应进行差异化处理时特别有用。例如，如果请求因为在短时间内请求过多而被限制，你可以在配置中使用 $limit_req_status 的值来决定如何通知用户已达到限额。通常，它可以返回诸如 200（正常请求）、503（因速率限制而被拒绝的请求）或应用配置的其他状态码。 需要注意的是，$limit_req_status 变量仅在有效请求经过 limit_req 指令并且受到速率限制行为影响时才会被填充。如果速率限制未生效，或请求未命中该指令，则该变量将不会被设置。

配置示例

server {
    location /api {
        limit_req zone=one burst=5;
        if ($limit_req_status = 503) {
            return 429 'Too Many Requests';
        }
    }
}

说明

在 NGINX 的 stream module 中，变量 $bytes_received 会动态设置，以反映在特定连接期间从客户端接收的字节数。它有助于监控服务器通过 TCP 或 UDP 数据流接收的数据量。每次从客户端接收到数据时，该变量都会相应更新，可用于日志或性能指标。因此，$bytes_received 本质上会统计所有字节，包括 headers 和 payloads，使其成为带宽分析的有力工具。 该变量在连接开始时初始化，并可在与活动连接相关的各种上下文中使用。例如，在日志格式、监控模块中，或用于基于接收总字节数实现的限速。$bytes_received 的典型值会因应用而异，但通常可从几字节到数兆字节或在高负载时更多，具体取决于流量类型和 NGINX stream 服务器的配置。

配置示例

stream {
    server {
        listen 12345;
        access_log /var/log/nginx/stream_access.log "$remote_addr - $bytes_received bytes received";
    }
}

说明

$session_time 变量在 NGINX 中用于衡量当前流会话的持续时间，专门用于 Stream 模块。该变量在 NGINX 服务器为流建立连接时被设置，并在连接关闭或完成之前持续更新。它表示会话处于活动状态的总时间（以秒为单位），因此在监控和日志记录方面很有用，同时也可用于根据会话持续时间配置会话限制。 通常，当连接启动时，$session_time 将从零开始，并随时间推移而增加，反映会话的持续时间。该值在需要强制会话超时或分析流式应用中的会话性能和使用模式时尤其有用。 需要注意的是，此变量特定于 Stream 模块，在 HTTP 或其他模块中不可用。因此，它主要用于涉及 TCP/UDP 的流媒体上下文，而不是标准的网页服务场景。

配置示例

stream {
    server {
        listen 12345;
        log_format custom_format '$remote_addr - $session_time';
        access_log /var/log/nginx/stream_access.log custom_format;
    }
}

说明

$protocol 变量在 NGINX Stream 中是自动设置的变量，会在与其他 stream 指令相同的作用域内可用，尤其是在 stream 块执行期间。此变量指示已建立连接的协议，表明是 TCP 还是 UDP。它主要用于便于基于所处理协议类型进行日志记录、访问控制或条件配置。 当与 server 建立连接时，会根据 server 和 upstream 块中指定的协议设置此变量。该变量的典型值包括 'tcp' 和 'udp'，能够清晰区分正在处理的流量类型。这在同一服务器进程同时处理 TCP 和 UDP 协议的环境中尤其有用，可根据协议实现差异化的配置和日志记录行为。

配置示例

stream {
    server {
        listen 12345;
        proxy_pass backend;
        log_format custom_format '$remote_addr - $protocol';
        access_log /var/log/nginx/access.log custom_format;
    }
}

说明

$remote_passwd 变量是 NGINX CoolKit 模块的一部分，在处理 Basic HTTP 身份验证 时起着关键作用。具体来说，当客户端以用户名和密码进行认证时，它会从 HTTP 请求的 'Authorization' 头中提取解码后的密码。当客户端发送认证请求时，用户名和密码通常会进行 base64 编码，并以 'Authorization: Basic base64(username:password)' 的格式发送。NGINX 在 CoolKit 模块的帮助下会解码这些信息，以便后续处理可以使用该密码。 该变量在处理包含 'Authorization' 头的 HTTP 请求时被设置。如果该头不存在，或者不符合 Basic 身份验证 的预期格式，则 $remote_passwd 的值将为空。因此，在授权和身份验证很重要的安全应用中，必须谨慎使用该变量，确保在使用密码参与任何逻辑之前先检查是否存在有效凭据。 在实际应用中，$remote_passwd 在与需要用户名/密码验证的后端数据库或服务进行身份验证时可能是关键数据，模块文档中的示例配置对此有说明。

配置示例

location = /auth {
    internal;
    set_quote_sql_str  $user $remote_user;
    set_quote_sql_str  $pass $remote_passwd;
    postgres_pass      database;
    postgres_query     "SELECT login FROM users WHERE login=$user AND pass=$pass";
    postgres_rewrite   no_rows 403;
    postgres_output    none;
}

说明

$location 变量在 NGINX CoolKit Module 中提供与传入请求匹配的 location 块的名称。它在处理 HTTP 请求时求值，每当 NGINX 在其配置中处理 location 指令时都会使用。随着请求在配置中逐步匹配，NGINX 会检查每个 location 块以找到请求的 URI 的最具体匹配。一旦找到匹配，对应 location 块的名称就会存储在该变量中。 $location 变量的典型值可以是精确路径，例如 '/auth'，或者由正则表达式定义的更复杂模式。此功能对记录日志、条件处理以及基于匹配的 location 定制响应非常有用。$location 变量在需要根据匹配的 URI 改变行为的配置场景中尤其有用，例如 URL 重写或访问控制由匹配的 location 决定的情况。 作为一个不可缓存的变量，$location 反映了请求处理上下文的实时变化。这确保了在 NGINX 根据已定义的 location 上下文处理请求时该变量会被动态更新，因此在行为必须依赖于匹配的 URI 的场景中非常重要。

配置示例

http {
    server {
        location = /auth {
            internal;
        }
        location / {
            add_header X-Matched-Location $location;
            proxy_pass http://backend;
        }
    }
}

说明

$google 变量是 NGINX Module for Google 的一部分，专为简化 Google 镜像站点的部署而设计。这个变量在处理那些在 NGINX 配置中使用 `google` 指令配置的请求时动态设置。处理请求时，变量会被填充相关信息以判断该请求是否以 Google 镜像方式处理，从而使 NGINX 能相应地调整其行为。该值通常为一个字符串，指示 Google 过滤器的状态，且会根据具体配置和正在处理的请求而变化。 在示例所示的 location 块中启用 `google` 指令时，$google 变量可能会根据是否激活诸如 Google Scholar 或语言设置之类的附加配置而发生变化。将其与条件判断结合使用或用于日志记录非常有用，以便调试或验证请求是否按指定正确镜像。典型值包括启用状态或与镜像操作相关的特定标识符，从而确保对 Google 资源的简化处理。

配置示例

location / {
    google on;
    error_log  /var/log/nginx/google_error.log;
    access_log /var/log/nginx/google_access.log google;
}

说明

`$google_host` 变量是 NGINX 的 Google 模块的一部分，专门用于创建 Google 服务的镜像。当启用 Google 镜像功能时，该变量会在请求期间动态设置。本质上，它提取针对 Google 的传入请求 URL 的主机部分，从而允许服务器根据需要操作或记录该主机信息。通常在需要基于 Google 主机进行响应修改或记录的位置使用该变量。 当启用 Google 过滤器时，模块会挂接到请求生命周期，捕获包括主机信息在内的请求详细信息。如果请求针对的是有效的 Google 服务，该变量将反映该服务的主机名（例如 `www.google.com`、`news.google.com` 等）。该变量被标记为可更改，意味着它可以在请求处理期间进行调整或更新，从而允许基于应用逻辑或不同请求上下文中的条件进行实时调整。

配置示例

location / {
    google on;
    add_header X-Google-Host $google_host;
}

说明

变量 $google_schema 用于 NGINX Module for Google Mirror creation 中，能动态提供与当前请求上下文关联的 schema 类型。当通过特定的 `location` 指令启用 google filter 时，此变量会被填充，使其能够反映并利用在该指令中配置的设置来呈现结构化数据，主要用于 Google 的索引和数据抓取系统。 该变量在请求处理期间进行求值并检索 schema 类型。适当的 schema 类型可以在 NGINX 配置中定义，通常与所提供的具体内容相关。此变量的常见值可能包括 'WebSite'、'Article' 或 schema.org 识别的其他相关 schema 类型，这些类型有助于向搜索引擎说明所呈现的数据，从而增强站点的 SEO 和可见性。根据配置，此变量允许根据当前请求环境所需的内容类型灵活地更改 schema 类型。 在定义该变量的使用时，应仔细考虑可能利用这些 schema 类型的 JSON-LD 脚本，确保正确的 schema 与所提供的内容相匹配，以最大化搜索引擎对站点内容的耐心和识别。由于该变量会受其他 NGINX 配置的影响，通常需要协调设置以确保对适当请求返回准确的值。

配置示例

location / {
    google on;
    google_schema "WebSite";
}

说明

The $google_schema_reverse 变量在 NGINX 的 Google 过滤模块中使用，用于在处理请求期间管理 Google schema 实现的方向性。当 NGINX 配置中的特定条件触发该变量的行为时（例如当根据模块逻辑预定义的模式匹配到某些请求 URI 或参数时），该变量会被设置。如果启用，该变量会影响 schema 信息在 HTTP 响应中的表示方式，特别是决定它是否应反映默认 Google schema 的 'reverse' 映射或解释。 通常，$google_schema_reverse 的取值可以是 'true' 或 'false'，从而允许在配置文件中进行直接的条件检查。这使得能够更精细地控制 NGINX 如何与针对 Google 服务的请求交互，尤其是在需要根据应用需求以不同方式呈现或处理 schema 数据时，例如为兼容性或搜索引擎的反向索引需求。此功能确保终端用户可以以所需的 schema 表示方式浏览镜像的 Google 体验，以满足其特定用例。

配置示例

location / {  
    google on;  
    if ($google_schema_reverse) {  
        # Additional configuration for reverse schema processing  
        add_header X-Google-Schema 'Reversed';  
    }  
}

说明

`$ssl_session_reused` 变量是 NGINX 用于评估 SSL 连接功能的一部分。具体来说，它用于判断在处理传入请求时是否重用了 SSL 会话。 这种优化通过避免建立新会话的开销来提升性能，从而使 HTTPS 连接的响应时间更快。该变量的值在请求处理阶段被设置为 '1' 或 '0'：'1' 表示会话已成功从之前的连接重用，'0' 表示创建了新的 SSL 会话。 仅当 NGINX 服务器配置中启用 SSL/TLS 时，该变量才适用。SSL 会话的管理通常通过诸如 `ssl_session_cache` 和 `ssl_session_timeout` 之类的指令进行配置。重用会话时，握手过程会被简化，从而显著降低延迟和计算负载。因此，在处理大量安全流量的服务器上，此功能尤其有价值，因为成功的会话重用可以改善吞吐量和用户体验。 要使用此变量，请确保你的 NGINX 服务器已编译并启用了 SSL 支持。同时，检查相关的 SSL 会话缓存设置已正确配置，以便有效优化会话重用。监控 `$ssl_session_reused` 可以洞察 SSL 配置的效率，这对于在安全环境中保持性能至关重要。

配置示例

http {
    ssl_session_cache shared:SSL:10m;
    ssl_session_timeout 10m;
    server {
        listen 443 ssl;
        
        location / {
            add_header X-SSL-Session-Reused $ssl_session_reused;
        }
    }
}