nginxngx_http_module(7)指令详解

nginx ngx_http_module(7) 指令详解

nginx 模块目录

nginx 全指令目录

一、目录 1.1 模块简介

以下是您请求的Nginx HTTP相关模块的简述：

ngx_http_proxy_protocol_vendor_module：这是一个商业订阅模块，允许从云平台的应用特定TLV（Type-Length-Value）字段中获取连接的额外信息。它支持通过PROXY协议头获取更多关于连接的详细信息，适用于AWS、Google Cloud Platform 和 Microsoft Azure 等云平台。

ngx_http_random_index_module：随机索引模块，允许从目录中随机选择一个文件作为索引文件返回给用户。这对于需要展示随机内容（如图片、文章等）的应用非常有用。只需启用该模块并配置 random_index on; 即可实现随机索引功能。

ngx_http_realip_module：真实IP模块，用于恢复客户端的真实IP地址。当Nginx位于反向代理或负载均衡器之后时，客户端的真实IP地址可能会被代理服务器的IP地址覆盖。通过配置 set_real_ip_from 和 real_ip_header 指令，可以将代理服务器传递的真实IP信息提取出来并应用到日志记录和其他逻辑中。

ngx_http_referer_module：来源控制模块，基于HTTP Referer头进行访问控制。可以通过设置允许或拒绝来自特定来源的请求，防止未经授权的网站链接到你的资源。常用的指令包括 valid_referers，用于指定有效的来源域名。

ngx_http_rewrite_module：重写模块，提供强大的URL重写功能。可以基于正则表达式匹配URL，并根据规则进行重定向或内部重写。这对于SEO优化、维护旧链接或简化复杂的URL结构非常有用。常用指令包括 rewrite 和 if。

ngx_http_scgi_module：SCGI支持模块，允许Nginx与SCGI（Simple Common Gateway Interface）应用服务器通信。类似于FastCGI，但更简单，适用于某些特定的应用环境。通过 scgi_pass 指令指定SCGI服务器地址。

ngx_http_secure_link_module：安全链接模块，提供一种方法来保护资源免受未经授权的访问。通过生成带有时间戳和签名的链接，确保只有拥有有效签名的用户才能访问特定资源。这在分发受限资源（如视频、文档等）时非常有用。

ngx_http_session_log_module：会话日志模块，用于记录用户的会话信息。它可以捕获并记录每个会话的详细信息，如开始时间、结束时间、访问路径等。这对于分析用户行为和优化用户体验非常有帮助。需要注意的是，该模块并不是标准Nginx的一部分，可能需要额外安装或编译。

ngx_http_slice_module：切片模块，允许将大文件分割成多个小块进行传输。这对于提高大文件下载的效率和可靠性非常有用，尤其是在网络条件不佳的情况下。通过 slice 指令指定每个切片的大小。

ngx_http_split_clients_module：客户端拆分模块，用于根据一定的规则（如IP地址范围或哈希值）将客户端分配到不同的组别。这在A/B测试或灰度发布中非常有用，可以按比例分配流量到不同的版本或服务。常用的指令是 split_clients，用于定义拆分规则。

1.2 指令目录 1.2.1 ngx_http_proxy_protocol_vendor_module 1.2.2 ngx_http_random_index_module random_index 1.2.3 ngx_http_realip_module set_real_ip_fromreal_ip_headerreal_ip_recursive 1.2.4 ngx_http_referer_module referer_hash_bucket_sizereferer_hash_max_sizevalid_referers 1.2.5 ngx_http_rewrite_module breakifreturnrewriterewrite_logsetuninitialized_variable_warn 1.2.6 ngx_http_scgi_module scgi_bindscgi_buffer_sizescgi_bufferingscgi_buffersscgi_busy_buffers_sizescgi_cachescgi_cache_background_updatescgi_cache_bypassscgi_cache_keyscgi_cache_lockscgi_cache_lock_agescgi_cache_lock_timeoutscgi_cache_max_range_offsetscgi_cache_methodsscgi_cache_min_usesscgi_cache_pathscgi_cache_purgescgi_cache_revalidatescgi_cache_use_stalescgi_cache_validscgi_connect_timeoutscgi_force_rangesscgi_hide_headerscgi_ignore_client_abortscgi_ignore_headersscgi_intercept_errorsscgi_limit_ratescgi_max_temp_file_sizescgi_next_upstreamscgi_next_upstream_timeoutscgi_next_upstream_triesscgi_no_cachescgi_paramscgi_passscgi_pass_headerscgi_pass_request_bodyscgi_pass_request_headersscgi_read_timeoutscgi_request_bufferingscgi_send_timeoutscgi_socket_keepalivescgi_storescgi_store_accessscgi_temp_file_write_sizescgi_temp_path 1.2.7 ngx_http_secure_link_module secure_linksecure_link_md5secure_link_secret 1.2.8 ngx_http_session_log_module session_logsession_log_formatsession_log_zone 1.2.9 ngx_http_slice_module slice 1.2.10 ngx_http_split_clients_module split_clients 二、解释 2.1 ngx_http_proxy_protocol_vendor_module

ngx_http_proxy_protocol_vendor_module 的模块，该模块允许从 PROXY 协议头中获取云平台特定的 TLV（Type-Length-Value）信息。

主要功能

ngx_http_proxy_protocol_vendor_module 模块（版本 1.23.3）允许从应用特定的 PROXY 协议头中获取连接在云平台上的额外信息。支持的云平台包括 Amazon Web Services (AWS)、Google Cloud Platform 和 Microsoft Azure。

配置要求

启用 PROXY 协议：必须在 listen 指令中通过设置 proxy_protocol 参数来启用 PROXY 协议。商业订阅：此模块是 Nginx 商业订阅的一部分，不是开源版本的标准模块。

支持的云平台

Amazon Web Services (AWS)Google Cloud Platform (GCP)Microsoft Azure

嵌入变量

该模块提供了一些嵌入变量，用于提取来自 PROXY 协议头中的特定信息：

$proxy_protocol_tlv_aws_vpce_id：从 PROXY 协议头中表示 AWS VPC 终端节点 ID 的 TLV 值。$proxy_protocol_tlv_azure_pel_id：从 PROXY 协议头中表示 Azure 私有终端链接 ID 的 TLV 值。$proxy_protocol_tlv_gcp_conn_id：从 PROXY 协议头中表示 Google Cloud PSC 连接 ID 的 TLV 值。

使用示例

以下是一些具体的配置示例，展示如何利用 ngx_http_proxy_protocol_vendor_module 来实现其功能。

基本配置

假设你想启用 PROXY 协议并使用该模块提取特定于云平台的信息：

http { upstream backend { server backend1.example :8080; server backend2.example :8080; } server { listen 80 proxy_protocol; # 启用 PROXY 协议 listen 443 ssl proxy_protocol; # 如果需要 HTTPS 支持 ssl_certificate /etc/nginx/ssl/example .crt; ssl_certificate_key /etc/nginx/ssl/example .key; location / { proxy_pass http://backend; # 设置自定义请求头以传递云平台特定信息 proxy_set_header X-Conn-ID $proxy_protocol_tlv_gcp_conn_id; proxy_set_header X-AWS-VPC-Endpoint-ID $proxy_protocol_tlv_aws_vpce_id; proxy_set_header X-Azure-Pel-ID $proxy_protocol_tlv_azure_pel_id; } } }

在这个例子中：

listen 80 proxy_protocol; 和 listen 443 ssl proxy_protocol; 启用了 PROXY 协议。proxy_set_header 指令用于将从 PROXY 协议头中提取的云平台特定信息添加到请求头中，并转发给后端服务器。

处理不同云平台的特定信息

假设你希望根据不同的云平台处理特定信息，可以使用条件判断来实现：

http { upstream backend { server backend1.example :8080; server backend2.example :8080; } server { listen 80 proxy_protocol; listen 443 ssl proxy_protocol; ssl_certificate /etc/nginx/ssl/example .crt; ssl_certificate_key /etc/nginx/ssl/example .key; location / { proxy_pass http://backend; if ($proxy_protocol_tlv_aws_vpce_id) { proxy_set_header X-AWS-VPC-Endpoint-ID $proxy_protocol_tlv_aws_vpce_id; } if ($proxy_protocol_tlv_azure_pel_id) { proxy_set_header X-Azure-Pel-ID $proxy_protocol_tlv_azure_pel_id; } if ($proxy_protocol_tlv_gcp_conn_id) { proxy_set_header X-GCP-Connection-ID $proxy_protocol_tlv_gcp_conn_id; } } } }

在这个例子中：

使用 if 语句检查特定的嵌入变量是否存在，并相应地设置请求头。

注意事项

商业订阅：请注意，ngx_http_proxy_protocol_vendor_module 是 Nginx 商业订阅的一部分，如果你使用的是开源版本的 Nginx，则无法直接使用此模块。

安全性：确保正确配置 SSL/TLS 证书，保护传输中的数据安全。

日志记录：合理配置日志级别和格式，便于监控和故障排查。特别是注意记录与 PROXY 协议相关的错误信息和性能指标。

2.1.1 指令列表 2.2 ngx_http_random_index_module

ngx_http_random_index_module 是 Nginx 的一个模块，用于在目录索引中随机选择并显示一个文件。当启用该模块时，Nginx 不会按照默认顺序（如字母顺序）列出目录中的文件，而是从目录中随机选择一个文件作为索引文件展示给用户。

这个功能特别适用于需要随机展示内容的场景，例如展示随机图片、文档或网页等。

主要功能

随机索引文件：从目录中随机选择一个文件作为索引文件。与 autoindex 结合使用：通常与 autoindex on; 指令结合使用来列出目录内容，但只展示随机选定的一个文件而不是整个目录列表。

使用示例

以下是一些简化的配置示例，展示了如何使用 ngx_http_random_index_module 来实现随机索引文件功能。

基本随机索引配置

假设你希望在一个目录中随机展示一个文件：

server { listen 80; server_name example ; location /images/ { root /var/ /html; autoindex on; random_index on; } }

在这个例子中：

root /var/ /html; 指定了根目录为 /var/ /html。autoindex on; 启用了目录列表显示功能。random_index on; 启用了随机索引文件功能，Nginx 将从 /var/ /html/images/ 目录中随机选择一个文件进行展示。

仅随机索引而不显示目录列表

如果你不希望显示整个目录列表，而只是随机展示一个文件，可以禁用 autoindex：

server { listen 80; server_name example ; location /images/ { root /var/ /html; autoindex off; random_index on; } }

在这个例子中：

autoindex off; 禁用了目录列表显示功能，因此用户只会看到随机选择的一个文件。

指定文件类型

如果你想限制随机索引仅应用于特定类型的文件（例如 .jpg 图片），可以通过 location 匹配规则来实现：

server { listen 80; server_name example ; location ~* ^/images/.*\.(jpg|jpeg)$ { root /var/ /html; autoindex off; random_index on; } }

在这个例子中：

location ~* ^/images/.*\.(jpg|jpeg)$ 使用正则表达式匹配 .jpg 和 .jpeg 文件。autoindex off; 禁用了目录列表显示功能。random_index on; 启用了随机索引文件功能，Nginx 将从 /var/ /html/images/ 目录中随机选择一个 .jpg 或 .jpeg 文件进行展示。

多个目录的随机索引

如果你有多个目录需要启用随机索引，可以在不同的 location 块中分别配置：

server { listen 80; server_name example ; location /images/ { root /var/ /html; autoindex off; random_index on; } location /documents/ { root /var/ /html; autoindex off; random_index on; } }

在这个例子中：

/images/ 和 /documents/ 目录都启用了随机索引功能，但它们是独立配置的。

注意事项

性能影响：虽然随机索引功能对性能的影响较小，但在处理大量文件的目录时，仍然可能会有一定的开销。建议根据实际需求合理使用该功能。

安全性：确保目录中没有包含敏感信息的文件，因为这些文件可能会被随机选中并展示给用户。可以通过适当的权限设置和文件过滤来增强安全性。

缓存问题：如果启用了缓存机制（如代理缓存或浏览器缓存），请确保缓存的内容不会导致用户每次都看到相同的文件。可以通过适当的缓存策略（如禁用缓存或使用版本化 URL）来解决这个问题。

调试与测试：在生产环境中部署前，务必进行充分的测试，确保随机索引功能按预期工作。可以使用工具如 curl 或浏览器开发者工具来检查响应内容。

2.2.1 指令列表 random_index

random_index 指令用于控制是否随机选择并返回目录中的文件。这有助于实现简单的负载均衡或内容随机化。

Syntax: random_index on | off; Default: random_index off; Context: location on：启用随机选择文件功能。off：禁用随机选择文件功能，默认行为。

案例

基本用法

最简单的 random_index 用法是启用或禁用随机选择文件功能：

server { listen 80; server_name example ; location /random_files/ { # 启用随机选择文件功能 random_index on; # 其他配置 root /var/ /html/files; } }

在这个例子中：

当用户访问 /random_files/ 路径时，Nginx 将从 /var/ /html/files 目录中随机选择一个文件返回给客户端。

注意事项

适用场景：适用于需要随机展示文件的场景，如图片轮播、文章推荐等。性能考虑：对于大目录或频繁请求的情况，确保服务器性能能够支持频繁的目录扫描操作。 2.3 ngx_http_realip_module

ngx_http_realip_module 是 Nginx 的一个模块，用于重写客户端的 IP 地址信息。当你的服务器位于反向代理、负载均衡器或其他中间设备之后时，客户端的真实 IP 地址通常会被这些中间设备的 IP 地址所掩盖。ngx_http_realip_module 通过解析来自这些中间设备的特定 HTTP 头（如 X-Real-IP 或 X-Forwarded-For），恢复并记录客户端的真实 IP 地址。

主要功能

恢复客户端真实 IP：从指定的 HTTP 头中提取客户端的真实 IP 地址。设置信任的代理地址：定义哪些代理服务器是可信的，从而避免伪造的 IP 地址被误认为是客户端的真实 IP。日志记录和变量传递：在日志和其他模块中正确使用客户端的真实 IP 地址。

常用指令

以下是 ngx_http_realip_module 中一些常用的指令及其说明：

set_real_ip_from: 定义信任的代理服务器或网络范围。可以是一个单一 IP 地址、CIDR 范围或主机名。

set_real_ip_from 192.168.1.0/24; set_real_ip_from 203.0.113.5;

real_ip_header: 指定从哪个 HTTP 头中提取客户端的真实 IP 地址。常见的头包括 X-Real-IP 和 X-Forwarded-For。

real_ip_header X-Real-IP; # 或者 real_ip_header X-Forwarded-For;

real_ip_recursive: 启用递归查找真实的客户端 IP 地址。如果启用此选项，Nginx 将会遍历 X-Forwarded-For 头中的所有 IP 地址，并跳过信任的代理 IP 地址，直到找到第一个非信任的 IP 地址作为客户端的真实 IP。

real_ip_recursive on;

使用示例

以下是一些具体的配置示例，展示了如何使用 ngx_http_realip_module 来恢复客户端的真实 IP 地址。

基本配置

假设你有一个反向代理服务器，它会在请求中添加 X-Real-IP 头来传递客户端的真实 IP 地址：

http { # 定义信任的代理服务器 set_real_ip_from 192.168.1.1; # 设置从 X-Real-IP 头中提取客户端的真实 IP 地址 real_ip_header X-Real-IP; server { listen 80; server_name example ; location / { root /var/ /html; index index.html index.htm; } } }

在这个例子中：

set_real_ip_from 192.168.1.1; 定义了信任的反向代理服务器 IP 地址。real_ip_header X-Real-IP; 指定了从 X-Real-IP 头中提取客户端的真实 IP 地址。

使用 X-Forwarded-For 头

如果你的反向代理服务器使用 X-Forwarded-For 头来传递客户端的真实 IP 地址，你可以这样配置：

http { # 定义信任的代理服务器 set_real_ip_from 192.168.1.0/24; set_real_ip_from 203.0.113.5; # 设置从 X-Forwarded-For 头中提取客户端的真实 IP 地址 real_ip_header X-Forwarded-For; # 启用递归查找真实的客户端 IP 地址 real_ip_recursive on; server { listen 80; server_name example ; location / { root /var/ /html; index index.html index.htm; } } }

在这个例子中：

set_real_ip_from 192.168.1.0/24; 和 set_real_ip_from 203.0.113.5; 定义了多个信任的反向代理服务器 IP 地址或 CIDR 范围。real_ip_header X-Forwarded-For; 指定了从 X-Forwarded-For 头中提取客户端的真实 IP 地址。real_ip_recursive on; 启用了递归查找真实的客户端 IP 地址。Nginx 将会遍历 X-Forwarded-For 头中的所有 IP 地址，并跳过信任的代理 IP 地址，直到找到第一个非信任的 IP 地址作为客户端的真实 IP。

结合日志记录

为了确保日志文件中记录的是客户端的真实 IP 地址，可以在日志格式中使用 $remote_addr 变量：

http { # 定义信任的代理服务器 set_real_ip_from 192.168.1.1; # 设置从 X-Real-IP 头中提取客户端的真实 IP 地址 real_ip_header X-Real-IP; # 自定义日志格式，确保记录客户端的真实 IP 地址 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; server { listen 80; server_name example ; location / { root /var/ /html; index index.html index.htm; } } }

在这个例子中：

log_format custom ... 定义了一个自定义的日志格式，并使用 $remote_addr 变量来记录客户端的真实 IP 地址。access_log /var/log/nginx/access.log custom; 指定了使用自定义的日志格式记录访问日志。

注意事项

安全性：确保只信任来自已知代理服务器的 IP 地址。错误的信任配置可能会导致伪造的 IP 地址被误认为是客户端的真实 IP。HTTP 头验证：确保代理服务器正确设置了相应的 HTTP 头（如 X-Real-IP 或 X-Forwarded-For），并且这些头没有被恶意篡改。性能影响：解析和处理额外的 HTTP 头对性能的影响很小，但在高并发环境下，请根据实际情况进行优化。测试验证：在部署之前进行全面测试，确保所有配置按预期工作，并检查是否有任何潜在的问题（如 IP 地址不正确、日志记录异常等）。 2.3.1 指令列表 set_real_ip_from

set_real_ip_from 指令用于指定信任的 IP 地址或网络范围，这些地址被视为可信代理。结合 real_ip_header 指令使用，可以将客户端的真实 IP 地址恢复。

Syntax: set_real_ip_from address | CIDR | unix:; Default: — Context: http, server, location address：单个 IP 地址。CIDR：IP 地址块（例如 192.168.1.0/24）。unix:：表示来自 Unix 套接字的连接。

案例

基本用法

最简单的 set_real_ip_from 用法是指定信任的 IP 地址或网络范围：

http { server { listen 80; server_name example ; # 设置信任的 IP 地址 set_real_ip_from 192.168.1.1; set_real_ip_from 192.168.1.0/24; # 其他配置 location / { proxy_pass http://backend_server; real_ip_header X-Forwarded-For; } } }

在这个例子中：

Nginx 将信任来自 192.168.1.1 和 192.168.1.0/24 网络范围内的代理服务器，并从中获取真实的客户端 IP 地址。

注意事项

安全性：确保仅信任可信赖的代理服务器，以避免伪造客户端 IP 地址的风险。配置正确性：确保所有信任的代理服务器都被正确配置，以避免遗漏或错误的信任设置。 real_ip_header

real_ip_header 指令用于指定哪个 HTTP 头字段包含客户端的真实 IP 地址。这通常与 set_real_ip_from 指令一起使用，以恢复通过代理服务器传递的真实客户端 IP 地址。

Syntax: real_ip_header field | X-Real-IP | X-Forwarded-For | proxy_protocol; Default: real_ip_header X-Real-IP; Context: http, server, location field：自定义的头字段名称。X-Real-IP：默认值，表示使用 X-Real-IP 头字段。X-Forwarded-For：使用 X-Forwarded-For 头字段。proxy_protocol：使用 PROXY 协议来传递客户端信息。

案例

使用 X-Real-IP 头字段

最简单的 real_ip_header 用法是指定使用 X-Real-IP 头字段：

http { server { listen 80; server_name example ; # 设置信任的 IP 地址 set_real_ip_from 192.168.1.1; # 使用 X-Real-IP 头字段获取真实客户端 IP 地址 real_ip_header X-Real-IP; location / { proxy_pass http://backend_server; } } }

在这个例子中：

Nginx 将从 X-Real-IP 头字段中获取真实客户端 IP 地址。

使用 X-Forwarded-For 头字段

你可以指定使用 X-Forwarded-For 头字段：

http { server { listen 80; server_name example ; # 设置信任的 IP 地址 set_real_ip_from 192.168.1.1; # 使用 X-Forwarded-For 头字段获取真实客户端 IP 地址 real_ip_header X-Forwarded-For; location / { proxy_pass http://backend_server; } } }

在这个例子中：

Nginx 将从 X-Forwarded-For 头字段中获取真实客户端 IP 地址。

注意事项

兼容性：不同的代理服务器可能使用不同的头字段传递客户端 IP 地址，请根据实际情况选择合适的头字段。安全性：确保信任的代理服务器不会被恶意篡改头字段，以防止伪造客户端 IP 地址。 real_ip_recursive

real_ip_recursive 指令用于控制是否递归地处理 X-Forwarded-For 头字段中的 IP 地址链。这有助于在多层代理的情况下准确获取原始客户端 IP 地址。

Syntax: real_ip_recursive on | off; Default: real_ip_recursive off; Context: http, server, location This directive appeared in versions 1.3.0 and 1.2.1. on：启用递归处理，默认行为。off：禁用递归处理。

案例

基本用法

最简单的 real_ip_recursive 用法是启用或禁用递归处理：

http { server { listen 80; server_name example ; # 设置信任的 IP 地址 set_real_ip_from 192.168.1.1; # 使用 X-Forwarded-For 头字段获取真实客户端 IP 地址 real_ip_header X-Forwarded-For; # 启用递归处理 real_ip_recursive on; location / { proxy_pass http://backend_server; } } }

在这个例子中：

当启用 real_ip_recursive on 时，Nginx 将递归地处理 X-Forwarded-For 头字段中的 IP 地址链，以获取原始客户端 IP 地址。

禁用递归处理

你可以禁用递归处理：

http { server { listen 80; server_name example ; # 设置信任的 IP 地址 set_real_ip_from 192.168.1.1; # 使用 X-Forwarded-For 头字段获取真实客户端 IP 地址 real_ip_header X-Forwarded-For; # 禁用递归处理 real_ip_recursive off; location / { proxy_pass http://backend_server; } } }

在这个例子中：

当禁用 real_ip_recursive off 时，Nginx 只会使用 X-Forwarded-For 头字段中的第一个 IP 地址作为客户端 IP 地址。

注意事项

多层代理：在多层代理环境下，启用递归处理可以更准确地获取原始客户端 IP 地址。安全性：确保信任的代理服务器不会被恶意篡改头字段，以防止伪造客户端 IP 地址。 2.4 ngx_http_referer_module

ngx_http_referer_module 是 Nginx 的一个标准模块，用于控制基于 HTTP Referer 头的访问。Referer 头通常包含用户从哪个页面跳转到当前页面的信息。通过 ngx_http_referer_module，你可以实现防止盗链（hotlinking）等功能，确保资源只能从特定的网站访问。

主要功能

防盗链：阻止其他网站直接链接到你的资源（如图片、视频等），从而减少不必要的带宽消耗。允许列表和拒绝列表：可以设置允许或拒绝访问的 Referer 列表。重定向：当请求不符合规则时，可以将请求重定向到指定的 URL。

常用指令

以下是与 ngx_http_referer_module 模块相关的常用配置指令及其简要说明：

valid_referers：定义合法的 Referer 值。如果请求的 Referer 不在这些值中，Nginx 会将其视为无效。

block_referer：阻止非法 Referer 请求（可选，结合 valid_referers 使用）。

return 或 rewrite：用于处理无效 Referer 请求，可以返回错误代码或重定向到指定页面。

使用示例

以下是一些具体的配置示例，展示如何利用 ngx_http_referer_module 来实现防盗链和其他相关功能。

基本配置 - 防止盗链

假设你想防止其他网站直接链接到你网站上的图片资源：

server { listen 80; server_name example ; location /images/ { # 定义合法的 Referer 值 valid_referers none blocked server_names *.example example.* ~\.google\.; if ($invalid_referer) { return 403; # 如果 Referer 不合法，返回 403 错误 } root /var/ /example /images; } }

在这个例子中：

valid_referers 指令定义了哪些 Referer 是合法的：

none 表示允许没有 Referer 的请求（例如直接输入 URL 访问）。blocked 表示允许被防火墙或其他安全设备屏蔽的 Referer。server_names 表示允许来自当前服务器名称的 Referer。*.example 和 example.* 允许来自所有子域名的 Referer。~\.google\. 是一个正则表达式，匹配任何包含 .google. 的 Referer。

if ($invalid_referer) 检查 $invalid_referer 变量，如果 Referer 不合法，则返回 403 错误。

配置重定向

如果你希望在检测到非法 Referer 时将请求重定向到另一个页面（例如一个提示页面），可以使用 rewrite 指令：

server { listen 80; server_name example ; location /images/ { valid_referers none blocked server_names *.example example.* ~\.google\.; if ($invalid_referer) { rewrite ^/images/(.*)$ http://example /hotlink-warning.html break; } root /var/ /example /images; } }

在这个例子中：

当检测到非法 Referer 时，使用 rewrite 指令将请求重定向到 /hotlink-warning.html 页面。

组合多个条件

你可以组合多个条件来进一步细化防盗链策略。例如，允许某些特定的 Referer 并对其他所有请求进行重定向：

server { listen 80; server_name example ; location /images/ { valid_referers none blocked server_names *.example example.* ~\.google\.; if ($invalid_referer) { # 对非法 Referer 返回 403 错误 return 403; } if ($request_uri ~* \.(jpg|jpeg|png|gif)$) { # 对图片文件应用额外的限制 valid_referers none blocked server_names *.example example.*; if ($invalid_referer) { rewrite ^/images/(.*)$ http://example /hotlink-warning.html break; } } root /var/ /example /images; } }

在这个例子中：

对所有请求检查 Referer 是否合法，并返回 403 错误。对于图片文件（.jpg, .jpeg, .png, .gif），进一步检查 Referer 并重定向到警告页面。

注意事项

性能考虑：

使用 if 指令可能会影响性能，尤其是在高并发场景下。尽量简化条件判断，避免复杂的嵌套逻辑。

安全性：

确保 Referer 列表的准确性，避免误封合法请求。注意 Referer 头可以被伪造，因此不要完全依赖它来进行重要的安全决策。

日志记录：

合理配置日志级别和格式，便于监控和故障排查。特别是注意记录与 Referer 相关的错误信息和访问情况。 2.4.1 指令列表 referer_hash_bucket_size

referer_hash_bucket_size 用于设置哈希表中每个桶的大小，该哈希表用于存储和查找引用头（Referer header）的信息。这有助于优化内存使用和哈希查找性能。

Syntax: referer_hash_bucket_size size; Default: referer_hash_bucket_size 64; Context: server, location This directive appeared in version 1.0.5. size：指定每个桶的大小，默认为 64 字节。

案例

基本用法

最简单的 referer_hash_bucket_size 用法是指定每个桶的大小：

server { listen 80; server_name example ; location / { valid_referers none blocked server_names; referer_hash_bucket_size 128; # 设置每个桶的大小为 128 字节 if ($invalid_referer) { return 403; } } }

在这个例子中，设置了 referer_hash_bucket_size 128，这意味着每个桶的大小为 128 字节。

注意事项

内存使用：较大的桶尺寸可能会增加内存占用，但可以提高哈希查找的效率。性能优化：根据实际需求调整桶尺寸，以平衡内存使用和查找性能。 referer_hash_max_size

referer_hash_max_size 用于设置哈希表的最大尺寸，该哈希表用于存储和查找引用头（Referer header）的信息。这有助于控制哈希表的大小，避免过大的内存消耗。

Syntax: referer_hash_max_size size; Default: referer_hash_max_size 2048; Context: server, location This directive appeared in version 1.0.5. size：指定哈希表的最大尺寸，默认为 2048。

案例

基本用法

最简单的 referer_hash_max_size 用法是指定哈希表的最大尺寸：

server { listen 80; server_name example ; location / { valid_referers none blocked server_names; referer_hash_max_size 4096; # 设置哈希表的最大尺寸为 4096 if ($invalid_referer) { return 403; } } }

在这个例子中，设置了 referer_hash_max_size 4096，这意味着哈希表的最大尺寸为 4096。

注意事项

内存管理：较大的哈希表尺寸可能会增加内存消耗，但可以减少哈希冲突的概率。性能优化：根据实际需求调整哈希表尺寸，以平衡内存使用和性能。 valid_referers

valid_referers 用于定义哪些引用头（Referer header）是有效的。Nginx 使用此指令来验证请求的来源，并可以根据结果执行不同的操作（如返回 403 错误）。

Syntax: valid_referers none | blocked | server_names | string ...; Default: — Context: server, location none：表示没有 Referer 头。blocked：表示 Referer 头被防火墙或其他安全软件阻止。server_names：表示与服务器名称匹配的 Referer 头。string：可以是具体的字符串或正则表达式，用于匹配特定的 Referer 头。

案例

基本用法

最简单的 valid_referers 用法是指定哪些 Referer 是有效的：

server { listen 80; server_name example ; location /protected_content/ { valid_referers none blocked server_names *.example ; if ($invalid_referer) { return 403; # 如果 Referer 无效，返回 403 错误 } } }

在这个例子中，设置了 valid_referers none blocked server_names *.example ，这意味着允许没有 Referer 头、被阻止的 Referer 头、服务器名称以及以 .example 结尾的 Referer 头。

复杂条件

根据实际需求设置更复杂的有效 Referer 条件：

server { listen 80; server_name example ; location /specific_referers/ { valid_referers none blocked server_names *.trusted ~\.anotherdomain\ $; if ($invalid_referer) { return 403; # 如果 Referer 无效，返回 403 错误 } } location /allow_all_referers/ { valid_referers any; # 允许所有 Referer 头 } }

在这个例子中：

对于 /specific_referers/ 路径下的请求，设置了多个有效 Referer 条件，包括没有 Referer 头、被阻止的 Referer 头、服务器名称、以 .trusted 结尾的 Referer 头以及匹配正则表达式的 Referer 头（如 \anotherdomain\ ）。对于 /allow_all_referers/ 路径下的请求，允许所有 Referer 头。

注意事项

安全性：合理配置有效 Referer 条件可以防止未经授权的访问，增强安全性。灵活性：根据实际需求灵活配置有效 Referer 条件，确保合法请求不会被误判。 2.5 ngx_http_rewrite_module

ngx_http_rewrite_module 是 Nginx 的一个核心模块，用于根据指定的规则修改请求的 URI 或者其他请求头信息。该模块允许你在处理请求之前对其进行重写操作，从而实现 URL 重定向、参数修改、条件判断等功能。这对于 SEO 优化、维护旧链接、动态路由等场景非常有用。

主要功能

URL 重写：根据正则表达式匹配并重写请求 URI。重定向：将客户端请求重定向到新的 URL。条件判断：基于变量值进行条件判断，并执行相应的重写或重定向操作。返回状态码：直接返回特定的 HTTP 状态码（如 403、404 等）。

常用指令

rewrite：根据正则表达式匹配并重写请求 URI。

if：根据条件判断执行某些操作。

return：立即终止请求处理并返回指定的状态码和可选的响应体。

set：设置一个新的变量值。

使用示例

以下是一些简化的配置示例，展示了如何使用 ngx_http_rewrite_module 来实现各种重写和重定向操作。

基本 URL 重写

假设你希望将旧的 URL /old-url 重写为新的 URL /new-url：

server { listen 80; server_name example ; location / { # 将 /old-url 重写为 /new-url，并永久重定向 rewrite ^/old-url$ /new-url permanent; } }

在这个例子中：

rewrite ^/old-url$ /new-url permanent; 匹配 /old-url 并将其重写为 /new-url，同时返回 301 状态码告知客户端这是一个永久重定向。

带条件的重写

假设你希望根据用户代理（User-Agent）对特定浏览器进行不同的重写操作：

server { listen 80; server_name example ; location / { if ($http_user_agent ~* "MSIE") { # 如果是 IE 浏览器，重写 URL rewrite ^(.*)$ /ie/$1 break; } if ($http_user_agent ~* "Chrome") { # 如果是 Chrome 浏览器，重写 URL rewrite ^(.*)$ /chrome/$1 break; } } }

在这个例子中：

if ($http_user_agent ~* "MSIE") 判断是否为 IE 浏览器，如果是，则将所有请求重写到 /ie/ 目录下。if ($http_user_agent ~* "Chrome") 判断是否为 Chrome 浏览器，如果是，则将所有请求重写到 /chrome/ 目录下。

重定向到新域名

假设你希望将所有请求重定向到新的域名：

server { listen 80; server_name oldsite ; location / { # 将所有请求重定向到 newsite return 301 http:// .newsite $request_uri; } }

在这个例子中：

return 301 http:// .newsite $request_uri; 将所有请求重定向到新的域名，并保留原始的 URI 路径。

根据文件是否存在进行重写

假设你希望根据某个文件是否存在来决定是否重写 URL：

server { listen 80; server_name example ; location / { if (-f $request_filename/index.html) { # 如果存在 index.html 文件，重写到该文件 rewrite (.*) $1/index.html break; } if (-f $request_filename.html) { # 如果存在 .html 文件，重写到该文件 rewrite (.*) $1.html break; } } }

在这个例子中：

if (-f $request_filename/index.html) 判断是否存在 index.html 文件，如果存在，则重写到该文件。if (-f $request_filename.html) 判断是否存在 .html 文件，如果存在，则重写到该文件。

设置变量并使用

假设你希望在重写过程中设置一个变量，并根据该变量进行进一步的操作：

server { listen 80; server_name example ; location / { set $redirect_url "http:// .newsite "; if ($request_method = POST) { # 如果是 POST 请求，返回 405 方法不允许 return 405; } if ($request_uri ~* "^/old-path/(.*)") { # 设置重定向目标 URL set $redirect_url "http:// .newsite /new-path/$1"; } # 重定向到设置的目标 URL return 301 $redirect_url; } }

在这个例子中：

set $redirect_url "http:// .newsite "; 初始化一个变量 $redirect_url。if ($request_method = POST) 判断是否为 POST 请求，如果是，则返回 405 方法不允许。if ($request_uri ~* "^/old-path/(.*)") 匹配 /old-path/ 开头的 URI，并设置 $redirect_url 为目标 URL。return 301 $redirect_url; 根据 $redirect_url 的值进行重定向。

注意事项

性能影响：虽然 ngx_http_rewrite_module 提供了强大的功能，但在复杂的重写规则下可能会对性能产生一定影响。建议尽量简化重写规则，避免过度嵌套的条件判断。

缓存问题：如果启用了缓存机制（如代理缓存或浏览器缓存），请确保缓存的内容不会导致旧的重写规则生效。可以通过适当的缓存策略（如禁用缓存或使用版本化 URL）来解决这个问题。

调试与测试：在生产环境中部署前，务必进行充分的测试，确保重写规则按预期工作。可以使用工具如 curl 或浏览器开发者工具来检查响应内容。

curl -v http://example /old-url

安全性：确保重写规则不会暴露敏感信息或被恶意利用。例如，避免使用过于宽泛的正则表达式，以免意外地重写不应修改的 URL。

2.5.1 指令列表 break

break 用于在满足某些条件时终止当前的 if 或 rewrite 规则链。这有助于避免不必要的规则处理，提高性能并简化配置。

Syntax: break; Default: — Context: server, location, if

案例

在 if 语句中使用 break

最简单的 break 用法是在 if 语句中终止进一步的规则处理：

server { listen 80; server_name example ; location / { if ($http_user_agent ~* "BadBot") { return 403; # 如果 User-Agent 包含 "BadBot"，返回 403 错误 break; # 终止进一步的规则处理 } if ($request_method = POST) { proxy_pass http://backend_server; # 如果请求方法是 POST，转发到后端服务器 break; # 终止进一步的规则处理 } try_files $uri $uri/ =404; # 尝试文件或目录，否则返回 404 错误 } }

在这个例子中，使用了 break 来终止进一步的规则处理：

如果请求的 User-Agent 包含 “BadBot”，返回 403 错误并终止进一步的规则处理。如果请求方法是 POST，转发到后端服务器并终止进一步的规则处理。

在 rewrite 规则中使用 break

在 rewrite 规则中使用 break 可以避免不必要的重写：

server { listen 80; server_name example ; location /old_path/ { rewrite ^/old_path/(.*)$ /new_path/$1 break; # 重写 URL 并终止进一步的重写 } location /another_path/ { rewrite ^/another_path/(.*)$ /final_path/$1 last; # 重写 URL 并继续处理其他规则 } }

在这个例子中：

对于 /old_path/ 路径下的请求，URL 被重写为 /new_path/ 并终止进一步的重写。对于 /another_path/ 路径下的请求，URL 被重写为 /final_path/ 并继续处理其他规则。

注意事项

规则链控制：合理使用 break 可以避免不必要的规则处理，提高性能。逻辑清晰：确保 break 的使用符合预期逻辑，避免意外行为。 if

if 指令用于根据条件执行特定的配置块。这个指令可以帮助实现基于条件的路由和处理逻辑。

Syntax: if (condition) { ... } Default: — Context: server, location condition：可以是变量（如 $request_method）、比较操作（如 =、!=）或正则表达式匹配等。{ ... }：包含满足条件时要执行的配置指令。

案例

基本用法

最简单的 if 用法是指定一个具体的条件并执行相应的配置：

server { listen 80; server_name example ; location / { # 如果请求方法是 POST，则返回 405 Method Not Allowed if ($request_method = POST) { return 405; } proxy_pass http://backend; } }

在这个例子中：

设置了 if ($request_method = POST)，这意味着如果请求方法是 POST，Nginx 将返回 405 状态码。

动态设置不同配置

你可以根据不同的条件动态设置不同的行为：

server { listen 80; server_name example ; location / { # 如果请求头中包含 "Upgrade" 字段，则代理到 WebSocket 后端 if ($http_upgrade = "websocket") { proxy_pass http://websocket_backend; break; } # 如果请求 URI 包含 "/api/v1"，则代理到 API v1 后端 if ($request_uri ~* ^/api/v1/) { proxy_pass http://api_v1_backend; break; } # 其他请求代理到默认后端 proxy_pass http://default_backend; } }

在这个例子中：

对于包含 "Upgrade": "websocket" 的请求，设置了 proxy_pass http://websocket_backend，适合 WebSocket 请求。对于 /api/v1/ 路径的请求，设置了 proxy_pass http://api_v1_backend，适合 API v1 请求。其他请求代理到默认后端。

注意事项

性能影响：频繁使用 if 指令可能会影响性能，尽量减少不必要的复杂条件判断。适用场景：适用于需要基于条件进行路由和处理的应用场景。例如，在多版本API、WebSocket支持等环境中使用。调试和监控：如果你遇到条件判断问题，可以检查以下几点： 确保条件设置合理，并符合你的需求。查看Nginx的日志文件，确认是否有与此相关的警告或错误信息。使用工具模拟不同负载条件下的请求进行测试，确保在各种情况下都能正常工作。 return

return 指令用于立即返回指定的状态码或重定向到指定的URL。这个指令帮助实现快速响应和重定向。

Syntax: return code [text]; return code URL; return URL; Default: — Context: server, location, if code：HTTP状态码，如 200, 301, 404 等。text：可选参数，返回的内容文本。URL：可选参数，重定向的目标URL。

案例

基本用法

最简单的 return 用法是指定一个具体的返回状态码和内容文本或URL：

server { listen 80; server_name example ; location /maintenance { # 返回 503 Service Unavailable 并显示自定义消息 return 503 "The site is under maintenance. Please try again later."; } location /old-page { # 重定向到新的页面 return 301 example /new-page; } }

在这个例子中：

设置了 return 503 "The site is under maintenance. Please try again later."，这意味着Nginx将返回 503 状态码并显示自定义消息。设置了 return 301 example /new-page，这意味着Nginx将重定向到新的页面。

动态设置不同配置

你可以根据不同的路径或条件动态设置不同的返回状态码和URL：

server { listen 80; server_name example ; location /v1/api/ { # 如果请求的是旧版API，重定向到新版API if ($request_uri ~* ^/v1/api/(.*)) { return 301 /v2/api/$1; } } location /expired-promo { # 如果访问已过期的促销页面，返回 410 Gone return 410; } }

在这个例子中：

对于 /v1/api/ 路径的请求，设置了 return 301 /v2/api/$1，适合旧版API重定向。对于 /expired-promo 路径的请求，设置了 return 410，适合已过期的促销页面。

注意事项

SEO友好性：对于永久重定向（如 301），确保更新所有相关的链接以避免SEO问题。适用场景：适用于需要快速响应和重定向的应用场景。例如，在网站维护、版本升级、错误页面等环境中使用。调试和监控：如果你遇到返回状态码或重定向问题，可以检查以下几点： 确保返回状态码和内容设置合理，并符合你的需求。查看Nginx的日志文件，确认是否有与此相关的警告或错误信息。使用工具模拟不同负载条件下的请求进行测试，确保在各种情况下都能正常工作。 rewrite

rewrite 指令用于根据正则表达式修改请求的URI。这个指令帮助实现URL重写功能。

Syntax: rewrite regex replacement [flag]; Default: — Context: server, location, if regex：正则表达式，用于匹配请求的URI。replacement：替换后的URI。flag：可选参数，控制重写的行为，如 last, break, redirect, permanent 等。

案例

基本用法

最简单的 rewrite 用法是指定一个具体的正则表达式和替换后的URI：

server { listen 80; server_name example ; location / { # 将旧版URL重写为新版URL rewrite ^/old-page/(.*)$ /new-page/$1 permanent; } }

在这个例子中：

设置了 rewrite ^/old-page/(.*)$ /new-page/$1 permanent，这意味着Nginx将把 /old-page/ 开头的请求重写为 /new-page/，并使用 301 永久重定向。

动态设置不同配置

你可以根据不同的路径或条件动态设置不同的重写规则：

server { listen 80; server_name example ; location /api/ { # 将旧版API请求重写为新版API请求 rewrite ^/api/v1/(.*)$ /api/v2/$1 last; } location /legacy/ { # 将旧版静态资源请求重写为新版静态资源请求 rewrite ^/legacy/(css|js)/(.*)$ /static/$1/$2 break; } }

在这个例子中：

对于 /api/v1/ 路径的请求，设置了 rewrite ^/api/v1/(.*)$ /api/v2/$1 last，适合旧版API重写。对于 /legacy/ 路径的请求，设置了 rewrite ^/legacy/(css|js)/(.*)$ /static/$1/$2 break，适合旧版静态资源重写。

注意事项

正则表达式的准确性：确保正则表达式能够准确匹配预期的URI，并且不会误匹配其他请求。适用场景：适用于需要重写URL的应用场景。例如，在网站改版、API版本升级、静态资源迁移等环境中使用。调试和监控：如果你遇到URL重写问题，可以检查以下几点： 确保正则表达式和替换后的URI设置合理，并符合你的需求。查看Nginx的日志文件，确认是否有与此相关的警告或错误信息。使用工具模拟不同负载条件下的请求进行测试，确保在各种情况下都能正常工作。 rewrite_log

rewrite_log 指令用于启用或禁用重写规则的日志记录。这个指令帮助调试和优化重写规则。

Syntax: rewrite_log on | off; Default: rewrite_log off; Context: http, server, location, if on：启用重写规则的日志记录。off：禁用重写规则的日志记录（默认值）。

案例

基本用法

最简单的 rewrite_log 用法是指定是否启用日志记录：

server { listen 80; server_name example ; location / { # 启用重写规则的日志记录 rewrite_log on; # 示例重写规则 rewrite ^/old-page/(.*)$ /new-page/$1 permanent; } }

在这个例子中：

设置了 rewrite_log on，这意味着Nginx将记录所有重写规则的日志信息。

动态设置不同配置

你可以根据不同的路径或条件动态设置是否启用日志记录：

server { listen 80; server_name example ; location /debug/ { # 在调试路径下启用重写规则的日志记录 rewrite_log on; # 示例重写规则 rewrite ^/debug/(.*)$ /internal/$1 break; } location /production/ { # 在生产路径下禁用重写规则的日志记录 rewrite_log off; # 示例重写规则 rewrite ^/production/(.*)$ /external/$1 permanent; } }

在这个例子中：

对于 /debug/ 路径，设置了 rewrite_log on，适合调试环境。对于 /production/ 路径，设置了 rewrite_log off，适合生产环境。

注意事项

日志量管理：启用日志记录可能会增加日志文件的大小，尤其是在高流量环境下。确保定期清理或归档日志文件。适用场景：适用于需要调试和优化重写规则的应用场景。例如，在开发、测试阶段使用。调试和监控：如果你遇到重写规则调试问题，可以检查以下几点： 确保日志记录设置合理，并符合你的需求。查看Nginx的日志文件，确认是否有与此相关的警告或错误信息。使用工具模拟不同负载条件下的请求进行测试，确保在各种情况下都能正常工作。 set

set 指令用于设置或修改 Nginx 配置中的变量值。

Syntax: set $variable value; Default: — Context: server, location, if $variable：指定要设置的变量名称。value：指定变量的新值。

案例

基本用法

最简单的 set 用法是指定一个变量并为其赋值：

server { listen 80; server_name example ; location /dynamic_path { # 设置一个自定义变量 set $custom_var "Hello, World!"; # 使用该变量 add_header X-Custom-Header $custom_var; proxy_pass http://backend.example ; } }

在这个例子中：

$custom_var 被设置为 "Hello, World!" 并通过 add_header 指令添加到响应头中。

动态设置变量值

你可以根据条件动态设置变量值：

server { listen 80; server_name example ; location / { if ($request_method = POST) { # 根据请求方法设置变量 set $custom_var "This is a POST request"; } if ($request_method = GET) { # 根据请求方法设置变量 set $custom_var "This is a GET request"; } # 使用该变量 add_header X-Custom-Header $custom_var; proxy_pass http://backend.example ; } }

在这个例子中：

如果请求方法是 POST，则 $custom_var 被设置为 "This is a POST request"。如果请求方法是 GET，则 $custom_var 被设置为 "This is a GET request"。

注意事项

变量作用域：Nginx 变量的作用域仅限于当前请求处理过程中，不能跨请求共享。适用场景：适用于需要动态生成内容或根据条件进行逻辑判断的应用场景。例如，在 API 网关中，可能需要根据不同的请求方法设置不同的响应头。调试和监控：如果你遇到变量设置问题，可以检查以下几点： 确保变量名正确且没有拼写错误。查看Nginx的日志文件，确认是否有与此相关的警告或错误信息。 uninitialized_variable_warn

uninitialized_variable_warn 指令用于控制是否对未初始化的变量发出警告。

Syntax: uninitialized_variable_warn on | off; Default: uninitialized_variable_warn on; Context: http, server, location, if on：启用未初始化变量的警告，默认值为 on。off：禁用未初始化变量的警告。

案例

基本用法

最简单的 uninitialized_variable_warn 用法是指定是否启用未初始化变量的警告：

http { uninitialized_variable_warn off; server { listen 80; server_name example ; location / { # 使用未初始化的变量 if ($uninitialized_var) { return 403; } proxy_pass http://backend.example ; } } }

在这个例子中：

uninitialized_variable_warn off 禁用了未初始化变量的警告，即使 $uninitialized_var 未被初始化也不会发出警告。

启用警告

你可以启用未初始化变量的警告：

http { uninitialized_variable_warn on; server { listen 80; server_name example ; location / { # 使用未初始化的变量 if ($uninitialized_var) { return 403; } proxy_pass http://backend.example ; } } }

在这个例子中：

uninitialized_variable_warn on 启用了未初始化变量的警告，如果 $uninitialized_var 未被初始化，Nginx 将发出警告。

注意事项

调试帮助：启用未初始化变量的警告可以帮助你在开发和调试阶段发现潜在的问题。性能影响：禁用未初始化变量的警告可能会减少日志输出，但在生产环境中应谨慎使用，以避免隐藏潜在的配置错误。适用场景：适用于需要严格控制配置正确性的应用场景。例如，在生产环境中，建议保持默认设置（启用警告）以确保配置的健壮性。 2.6 ngx_http_scgi_module

ngx_http_scgi_module 是 Nginx 的一个模块，用于支持 SCGI（Simple Common Gateway Interface）协议。SCGI 是一种类似于 CGI（Common Gateway Interface）的协议，但设计上更高效，通常用于将动态内容生成的任务委托给后端应用服务器。

主要功能

反向代理：将请求转发到运行 SCGI 协议的应用服务器。负载均衡：可以与多个后端 SCGI 服务器配合使用，实现负载均衡。参数传递：允许在请求中传递额外的参数给后端服务器。

常用指令

以下是 ngx_http_scgi_module 中一些常用的指令及其说明：

scgi_pass: 指定 SCGI 服务器的地址。可以是 IP 地址和端口，也可以是 Unix 域套接字。

scgi_param: 设置传递给 SCGI 后端的参数。可以设置静态值或从请求中提取变量。

scgi_bind: 绑定本地地址和端口，用于与 SCGI 服务器通信。这在有多个网络接口时特别有用。

scgi_buffer_size: 设置用于读取响应的第一部分缓冲区大小。

scgi_buffers: 设置用于读取响应的缓冲区数量和大小。

scgi_busy_buffers_size: 设置在写入客户端之前可以使用的最大缓冲区大小。

使用示例

以下是一些具体的配置示例，展示了如何使用 ngx_http_scgi_module 来处理 SCGI 请求。

基本配置

假设你有一个运行 SCGI 协议的应用服务器，监听在 127.0.0.1:9000：

server { listen 80; server_name example ; location /scgi-bin/ { # 将请求转发到 SCGI 服务器 scgi_pass 127.0.0.1:9000; # 设置传递给 SCGI 后端的参数 scgi_param SCRIPT_FILENAME /var/ /cgi-bin$fastcgi_script_name; scgi_param QUERY_STRING $query_string; scgi_param REQUEST_METHOD $request_method; scgi_param CONTENT_TYPE $content_type; scgi_param CONTENT_LENGTH $content_length; } }

在这个例子中：

scgi_pass 127.0.0.1:9000; 指定了 SCGI 服务器的地址和端口。scgi_param ... 设置了传递给 SCGI 后端的各种参数，包括脚本文件路径、查询字符串、请求方法等。

结合负载均衡

你可以将请求分发到多个 SCGI 服务器，实现负载均衡：

upstream scgi_backend { server 192.168.1.10:9000 weight=3 max_fails=3 fail_timeout=30s; server 192.168.1.11:9000 weight=1 max_fails=3 fail_timeout=30s; } server { listen 80; server_name example ; location /scgi-bin/ { # 将请求转发到上游 SCGI 服务器组 scgi_pass scgi_backend; # 设置传递给 SCGI 后端的参数 scgi_param SCRIPT_FILENAME /var/ /cgi-bin$fastcgi_script_name; scgi_param QUERY_STRING $query_string; scgi_param REQUEST_METHOD $request_method; scgi_param CONTENT_TYPE $content_type; scgi_param CONTENT_LENGTH $content_length; } }

在这个例子中：

upstream scgi_backend { ... } 定义了一个上游服务器组，包含两个 SCGI 服务器，并设置了权重和其他参数。scgi_pass scgi_backend; 将请求转发到定义的上游服务器组。

处理特定请求

假设你希望处理特定类型的请求并将其转发到 SCGI 服务器：

server { listen 80; server_name example ; location ~ \.pl$ { # 将 .pl 文件请求转发到 SCGI 服务器 scgi_pass 127.0.0.1:9000; # 设置传递给 SCGI 后端的参数 scgi_param SCRIPT_FILENAME /var/ /cgi-bin$fastcgi_script_name; scgi_param QUERY_STRING $query_string; scgi_param REQUEST_METHOD $request_method; scgi_param CONTENT_TYPE $content_type; scgi_param CONTENT_LENGTH $content_length; } location / { root /var/ /html; index index.html index.htm; } }

在这个例子中：

location ~ \.pl$ { ... } 匹配所有以 .pl 结尾的请求，并将这些请求转发到 SCGI 服务器。其他请求将由根目录下的静态文件处理。

注意事项

安全性：确保只信任来自已知 SCGI 服务器的请求，并正确设置防火墙规则和访问控制列表，防止未经授权的访问。性能优化：根据实际需求调整缓冲区大小和其他相关参数，以提高性能。例如，增加 scgi_buffers 和 scgi_busy_buffers_size 可以减少 I/O 操作次数。错误处理：配置适当的错误页面和日志记录，以便在出现问题时能够快速定位和解决。测试验证：在部署之前进行全面测试，确保所有配置按预期工作，并检查是否有任何潜在的问题（如请求未正确转发、参数传递错误等）。 2.6.1 指令列表 scgi_bind

scgi_bind 指令用于绑定 SCGI 请求的本地地址和端口。

Syntax: scgi_bind address [transparent] | off; Default: — Context: http, server, location address：指定要绑定的本地 IP 地址。transparent：可选参数，表示透明代理模式。off：禁用绑定功能。

案例

基本用法

最简单的 scgi_bind 用法是指定一个本地地址：

location /scgi/ { # 绑定 SCGI 请求到本地地址 127.0.0.1 scgi_bind 127.0.0.1; scgi_pass scgi_backend; }

在这个例子中：

SCGI 请求将绑定到本地地址 127.0.0.1。

使用透明代理模式

你可以使用透明代理模式：

location /scgi/ { # 绑定 SCGI 请求到本地地址 127.0.0.1，并启用透明代理模式 scgi_bind 127.0.0.1 transparent; scgi_pass scgi_backend; }

在这个例子中：

SCGI 请求将绑定到本地地址 127.0.0.1，并且启用了透明代理模式。

禁用绑定

你可以禁用绑定功能：

location /scgi/ { # 禁用 SCGI 请求的绑定 scgi_bind off; scgi_pass scgi_backend; }

在这个例子中：

SCGI 请求不会绑定到任何特定的本地地址。

注意事项

网络配置：确保绑定的本地地址在网络配置中是有效的，并且具有相应的权限。透明代理模式：透明代理模式通常需要特殊的操作系统支持和权限设置。适用场景：适用于需要控制 SCGI 请求的源地址的应用场景。例如，在多网卡服务器上，可能需要指定特定的本地地址来发送 SCGI 请求。 scgi_buffer_size

scgi_buffer_size 指令用于设置读取 SCGI 响应的第一个缓冲区大小。

Syntax: scgi_buffer_size size; Default: scgi_buffer_size 4k|8k; Context: http, server, location size：指定第一个缓冲区的大小，默认值为 4k 或 8k，取决于平台。

案例

基本用法

最简单的 scgi_buffer_size 用法是指定一个特定的缓冲区大小：

location /scgi/ { # 设置第一个缓冲区大小为 16KB scgi_buffer_size 16k; scgi_pass scgi_backend; }

在这个例子中：

第一个缓冲区大小被设置为 16KB。

动态设置不同配置

你可以根据不同的路径或条件动态设置不同的缓冲区大小：

location /small_scgi/ { # 设置较小的缓冲区大小，适合小响应 scgi_buffer_size 4k; scgi_pass scgi_backend; } location /large_scgi/ { # 设置较大的缓冲区大小，适合大响应 scgi_buffer_size 32k; scgi_pass scgi_backend; }

在这个例子中：

对于 /small_scgi/ 路径，设置了 scgi_buffer_size 4k，适合小响应。对于 /large_scgi/ 路径，设置了 scgi_buffer_size 32k，适合大响应。

注意事项

性能优化：合理设置缓冲区大小可以显著提高性能，特别是在处理大响应体的情况下。过大的缓冲区可能导致内存占用增加，而过小的缓冲区可能导致频繁的 I/O 操作。适用场景：适用于需要优化 SCGI 响应处理的应用场景。例如，在代理返回大量数据的服务时，可能需要增大缓冲区大小以提高性能。调试和监控：如果你遇到缓冲区大小问题，可以检查以下几点： 确保缓冲区大小设置合理，并符合你的需求。查看Nginx的日志文件，确认是否有与此相关的警告或错误信息。 scgi_buffering

scgi_buffering 指令用于控制是否启用SCGI（Simple Common Gateway Interface）请求的缓冲。这对于优化处理动态内容的性能非常重要。

Syntax: scgi_buffering on | off; Default: scgi_buffering on; Context: http, server, location on（默认）：启用SCGI请求的缓冲，Nginx会在响应到达时将其存储在内存中，并在适当的时候发送给客户端。off：禁用SCGI请求的缓冲，响应将直接从后端服务器传递给客户端，不经过Nginx的内部缓冲机制。

案例

启用缓冲

假设我们希望启用SCGI请求的缓冲：

http { server { listen 80; server_name example ; location /dynamic/ { scgi_pass scgi_backend; scgi_buffering on; # 启用SCGI请求的缓冲 } } }

禁用缓冲

如果我们希望禁用SCGI请求的缓冲：

http { server { listen 80; server_name example ; location /dynamic/ { scgi_pass scgi_backend; scgi_buffering off; # 禁用SCGI请求的缓冲 } } }

注意事项

性能优化：启用缓冲可以提高性能，特别是在处理大响应或高并发请求时。实时性：禁用缓冲可以减少延迟，确保响应能尽快传递给客户端，但可能会增加服务器负载。 scgi_buffers

scgi_buffers 指令用于设置用于SCGI请求的缓冲区数量和大小。这对于管理内存使用和优化响应处理非常重要。

Syntax: scgi_buffers number size; Default: scgi_buffers 8 4k|8k; Context: http, server, location number：指定缓冲区的数量。size：指定每个缓冲区的大小，通常为4KB或8KB。

案例

基本用法

假设我们希望设置8个4KB的缓冲区：

http { server { listen 80; server_name example ; location /dynamic/ { scgi_pass scgi_backend; scgi_buffers 8 4k; # 设置8个4KB的缓冲区 } } }

使用更大缓冲区

如果我们希望使用更大的缓冲区来处理较大的响应：

http { server { listen 80; server_name example ; location /dynamic/ { scgi_pass scgi_backend; scgi_buffers 16 8k; # 设置16个8KB的缓冲区 } } }

注意事项

内存管理：合理设置缓冲区数量和大小，避免占用过多内存。性能优化：根据实际需求调整缓冲区配置，以优化响应处理速度。 scgi_busy_buffers_size

scgi_busy_buffers_size 指令用于设置在响应被发送到客户端时，允许同时处于“忙碌”状态的缓冲区总大小。这对于优化响应传输效率非常重要。

Syntax: scgi_busy_buffers_size size; Default: scgi_busy_buffers_size 8k|16k; Context: http, server, location size：指定允许处于“忙碌”状态的缓冲区总大小，默认值通常是8KB或16KB。

案例

基本用法

假设我们希望设置“忙碌”缓冲区的总大小为16KB：

http { server { listen 80; server_name example ; location /dynamic/ { scgi_pass scgi_backend; scgi_busy_buffers_size 16k; # 设置“忙碌”缓冲区的总大小为16KB } } }

使用默认值

如果我们希望使用默认的“忙碌”缓冲区大小：

http { server { listen 80; server_name example ; location /dynamic/ { scgi_pass scgi_backend; # 默认情况下，scgi_busy_buffers_size 是8KB或16KB } } }

注意事项

传输效率：合理设置“忙碌”缓冲区大小，可以提高响应传输效率，特别是在高并发场景下。资源分配：确保不会因为过大的“忙碌”缓冲区导致系统资源耗尽。 scgi_cache

scgi_cache 指令用于启用或禁用SCGI请求的缓存。这对于加速动态内容的响应时间非常有用。

Syntax: scgi_cache zone | off; Default: scgi_cache off; Context: http, server, location zone：指定用于缓存的共享内存区域名称。off（默认）：禁用SCGI请求的缓存。

案例

启用缓存

假设我们希望启用SCGI请求的缓存，并使用名为 scgi_cache_zone 的共享内存区域：

http { # 定义缓存区域 scgi_cache_path /var/cache/nginx/scgi levels=1:2 keys_zone=scgi_cache_zone:10m max_size=1g inactive=60m; server { listen 80; server_name example ; location /dynamic/ { scgi_pass scgi_backend; scgi_cache scgi_cache_zone; # 启用SCGI请求的缓存 } } }

禁用缓存

如果我们希望禁用SCGI请求的缓存：

http { server { listen 80; server_name example ; location /dynamic/ { scgi_pass scgi_backend; scgi_cache off; # 禁用SCGI请求的缓存 } } }

注意事项

性能优化：启用缓存可以显著提高动态内容的响应速度，特别是在频繁请求相同内容的情况下。内容一致性：确保缓存的内容是最新的，避免因缓存导致的内容不一致问题。 scgi_cache_background_update

scgi_cache_background_update 指令用于控制是否启用后台更新缓存的功能。当启用时，如果缓存过期但仍有请求命中该缓存，Nginx 会在后台异步地更新缓存内容，而不影响当前请求。

Syntax: scgi_cache_background_update on | off; Default: scgi_cache_background_update off; Context: http, server, location This directive appeared in version 1.11.10. on：启用后台更新缓存功能。off：禁用后台更新缓存功能，默认行为。

案例

基本用法

最简单的 scgi_cache_background_update 用法是启用或禁用后台更新缓存功能：

http { server { listen 80; server_name example ; location /cache_example/ { # 启用后台更新缓存功能 scgi_cache_background_update on; # 其他配置 scgi_pass unix:/tmp/fastcgi.socket; scgi_cache my_cache; scgi_cache_valid 200 10m; } } # 定义缓存区域 scgi_cache_path /path/to/cache levels=1:2 keys_zone=my_cache:10m max_size=1g inactive=60m use_temp_path=off; }

在这个例子中：

当用户访问 /cache_example/ 路径时，如果缓存过期但仍有请求命中该缓存，Nginx 将在后台异步地更新缓存内容，而不会阻塞当前请求。

注意事项

性能优化：后台更新缓存可以减少因缓存过期而导致的延迟，提高用户体验。资源管理：确保服务器有足够的资源处理后台更新任务，以避免对其他服务的影响。 scgi_cache_bypass

scgi_cache_bypass 指令用于指定条件，决定哪些请求不使用缓存。这有助于根据特定条件（如请求参数、请求头等）绕过缓存直接从后端获取数据。

Syntax: scgi_cache_bypass string ...; Default: — Context: http, server, location string：一个或多个条件表达式，通常是一个变量名或其组合。如果表达式的值为非零或非空字符串，则请求将不使用缓存。

案例

基本用法

最简单的 scgi_cache_bypass 用法是指定条件绕过缓存：

http { server { listen 80; server_name example ; location /bypass_example/ { # 绕过缓存的条件：如果请求参数中有 "nocache" 参数 set $nocache ""; if ($arg_nocache) { set $nocache 1; } # 设置绕过缓存的条件 scgi_cache_bypass $nocache; # 其他配置 scgi_pass unix:/tmp/fastcgi.socket; scgi_cache my_cache; scgi_cache_valid 200 10m; } } # 定义缓存区域 scgi_cache_path /path/to/cache levels=1:2 keys_zone=my_cache:10m max_size=1g inactive=60m use_temp_path=off; }

在这个例子中：

如果请求 URL 中包含 nocache 参数（例如 /bypass_example/?nocache=1），则 Nginx 将绕过缓存，直接从后端获取数据。

多个条件

你可以设置多个条件来绕过缓存：

http { server { listen 80; server_name example ; location /multi_bypass_example/ { # 绕过缓存的条件：如果有 "nocache" 参数或 "X-No-Cache" 请求头 set $nocache ""; if ($arg_nocache) { set $nocache 1; } if ($http_x_no_cache) { set $nocache 1; } # 设置绕过缓存的条件 scgi_cache_bypass $nocache; # 其他配置 scgi_pass unix:/tmp/fastcgi.socket; scgi_cache my_cache; scgi_cache_valid 200 10m; } } # 定义缓存区域 scgi_cache_path /path/to/cache levels=1:2 keys_zone=my_cache:10m max_size=1g inactive=60m use_temp_path=off; }

在这个例子中：

如果请求 URL 中包含 nocache 参数或请求头中包含 X-No-Cache，则 Nginx 将绕过缓存，直接从后端获取数据。

注意事项

条件设计：确保绕过缓存的条件符合实际需求，避免不必要的缓存绕过导致性能下降。调试和验证：在生产环境中启用前进行充分测试，确保绕过逻辑正确无误。 scgi_cache_key

scgi_cache_key 指令用于定义生成缓存键的规则。缓存键决定了如何标识缓存中的条目，因此直接影响缓存的命中率和一致性。

Syntax: scgi_cache_key string; Default: — Context: http, server, location string：生成缓存键的字符串表达式，通常包括请求的 URI、查询参数、主机名等。

案例

基本用法

最简单的 scgi_cache_key 用法是指定缓存键的生成规则：

http { server { listen 80; server_name example ; location /cache_example/ { # 定义缓存键：基于请求的 URI 和查询参数 scgi_cache_key "$scheme$request_method$host$request_uri"; # 其他配置 scgi_pass unix:/tmp/fastcgi.socket; scgi_cache my_cache; scgi_cache_valid 200 10m; } } # 定义缓存区域 scgi_cache_path /path/to/cache levels=1:2 keys_zone=my_cache:10m max_size=1g inactive=60m use_temp_path=off; }

在这个例子中：

缓存键由协议（$scheme）、请求方法（$request_method）、主机名（$host）和请求 URI（$request_uri）组成，确保不同的请求路径和参数生成唯一的缓存键。

使用自定义变量

你可以使用自定义变量来生成更复杂的缓存键：

http { server { listen 80; server_name example ; location /custom_cache_key/ { # 定义缓存键：基于请求的 URI、查询参数和用户 ID set $cache_key "$scheme$request_method$host$request_uri"; if ($cookie_user_id) { set $cache_key "$cache_key$user_id:$cookie_user_id"; } # 设置缓存键 scgi_cache_key $cache_key; # 其他配置 scgi_pass unix:/tmp/fastcgi.socket; scgi_cache my_cache; scgi_cache_valid 200 10m; } } # 定义缓存区域 scgi_cache_path /path/to/cache levels=1:2 keys_zone=my_cache:10m max_size=1g inactive=60m use_temp_path=off; }

在这个例子中：

如果请求中包含 user_id Cookie，则将其与默认的缓存键拼接在一起，形成更细粒度的缓存键。

注意事项

唯一性：确保生成的缓存键能够唯一标识每个请求，避免缓存冲突和错误。灵活性：根据应用需求灵活调整缓存键的生成规则，以满足不同的缓存策略。 scgi_cache_lock

scgi_cache_lock 指令用于控制是否启用缓存锁机制。当启用时，如果多个请求同时请求同一个未缓存或已过期的资源，Nginx 将只允许一个请求去后端获取数据，其余请求等待缓存更新完成后再返回缓存结果。

Syntax: scgi_cache_lock on | off; Default: scgi_cache_lock off; Context: http, server, location This directive appeared in version 1.1.12. on：启用缓存锁机制。off：禁用缓存锁机制，默认行为。

案例

基本用法

最简单的 scgi_cache_lock 用法是启用或禁用缓存锁机制：

http { server { listen 80; server_name example ; location /lock_example/ { # 启用缓存锁机制 scgi_cache_lock on; # 其他配置 scgi_pass unix:/tmp/fastcgi.socket; scgi_cache my_cache; scgi_cache_valid 200 10m; } } # 定义缓存区域 scgi_cache_path /path/to/cache levels=1:2 keys_zone=my_cache:10m max_size=1g inactive=60m use_temp_path=off; }

在这个例子中：

当用户访问 /lock_example/ 路径时，如果多个请求同时请求同一个未缓存或已过期的资源，Nginx 将只允许一个请求去后端获取数据，其余请求等待缓存更新完成后再返回缓存结果。

配合其他缓存指令

你可以结合其他缓存指令一起使用：

http { server { listen 80; server_name example ; location /combined_example/ { # 启用缓存锁机制 scgi_cache_lock on; # 启用后台更新缓存 scgi_cache_background_update on; # 设置缓存键 scgi_cache_key "$scheme$request_method$host$request_uri"; # 其他配置 scgi_pass unix:/tmp/fastcgi.socket; scgi_cache my_cache; scgi_cache_valid 200 10m; } } # 定义缓存区域 scgi_cache_path /path/to/cache levels=1:2 keys_zone=my_cache:10m max_size=1g inactive=60m use_temp_path=off; }

在这个例子中：

结合了缓存锁机制和后台更新缓存功能，进一步优化了缓存性能和用户体验。

注意事项

高并发场景：在高并发场景下，启用缓存锁机制可以有效减少对后端服务器的压力，避免重复请求。超时设置：确保合理设置 scgi_cache_lock_timeout（默认为 5 秒），以防止长时间等待导致的请求延迟。 scgi_cache_lock_age

scgi_cache_lock_age 用于设置在缓存锁定期间，等待上游服务器响应的最大时间。如果超过这个时间，Nginx 将释放锁并允许其他请求继续处理。

Syntax: scgi_cache_lock_age time; Default: scgi_cache_lock_age 5s; Context: http, server, location This directive appeared in version 1.7.8. time：指定最大等待时间，默认为 5 秒。

案例

基本用法

最简单的 scgi_cache_lock_age 用法是指定最大等待时间：

server { listen 80; server_name example ; location /scgi_backend/ { scgi_pass scgi_backend; scgi_cache my_cache; scgi_cache_lock on; # 启用缓存锁定 scgi_cache_lock_age 10s; # 设置最大等待时间为 10 秒 } }

在这个例子中，设置了 scgi_cache_lock_age 10s，这意味着 Nginx 将等待上游服务器响应最多 10 秒，之后将释放锁。

注意事项

性能优化：合理设置等待时间可以避免长时间阻塞，提高系统响应速度。负载均衡：结合其他负载均衡配置，如 upstream 和 keepalive，以优化整体性能。 scgi_cache_lock_timeout

scgi_cache_lock_timeout 用于设置在启用缓存锁定时，等待上游服务器响应的超时时间。如果超过这个时间，Nginx 将返回一个错误或使用缓存中的数据（如果有的话）。

Syntax: scgi_cache_lock_timeout time; Default: scgi_cache_lock_timeout 5s; Context: http, server, location This directive appeared in version 1.1.12. time：指定超时时间，默认为 5 秒。

案例

基本用法

最简单的 scgi_cache_lock_timeout 用法是指定超时时间：

server { listen 80; server_name example ; location /scgi_backend/ { scgi_pass scgi_backend; scgi_cache my_cache; scgi_cache_lock on; # 启用缓存锁定 scgi_cache_lock_timeout 15s; # 设置超时时间为 15 秒 } }

在这个例子中，设置了 scgi_cache_lock_timeout 15s，这意味着 Nginx 将等待上游服务器响应最多 15 秒，之后将超时并可能返回错误或使用缓存中的数据。

注意事项

用户体验：合理的超时时间可以平衡响应速度和用户体验，过长的超时可能导致用户等待时间过长。系统稳定性：确保上游服务器的健康状态，避免不必要的超时。 scgi_cache_max_range_offset

scgi_cache_max_range_offset 用于设置 SCGI 缓存中支持的最大范围偏移量。这有助于控制缓存中存储的数据块大小，适用于需要部分内容缓存的场景。

Syntax: scgi_cache_max_range_offset number; Default: — Context: http, server, location This directive appeared in version 1.11.6. number：指定最大范围偏移量，默认没有设置。

案例

基本用法

最简单的 scgi_cache_max_range_offset 用法是指定最大范围偏移量：

server { listen 80; server_name example ; location /scgi_backend/ { scgi_pass scgi_backend; scgi_cache my_cache; scgi_cache_max_range_offset 1048576; # 设置最大范围偏移量为 1MB (1048576 字节) } }

在这个例子中，设置了 scgi_cache_max_range_offset 1048576，这意味着缓存中支持的最大范围偏移量为 1MB。

注意事项

内存管理：较大的范围偏移量可能会增加内存消耗，但可以支持更大范围的内容缓存。应用场景：适用于需要部分内容缓存的场景，如视频流或大文件下载。 scgi_cache_methods

scgi_cache_methods 用于定义哪些 HTTP 方法的响应可以被缓存。默认情况下，只有 GET 和 HEAD 请求的响应会被缓存。

Syntax: scgi_cache_methods GET | HEAD | POST ...; Default: scgi_cache_methods GET HEAD; Context: http, server, location GET：允许缓存 GET 请求的响应。HEAD：允许缓存 HEAD 请求的响应。POST：允许缓存 POST 请求的响应（非幂等方法，需谨慎使用）。

案例

基本用法

最简单的 scgi_cache_methods 用法是指定允许缓存的 HTTP 方法：

server { listen 80; server_name example ; location /scgi_backend/ { scgi_pass scgi_backend; scgi_cache my_cache; scgi_cache_methods GET HEAD POST; # 允许缓存 GET、HEAD 和 POST 请求的响应 } }

在这个例子中，设置了 scgi_cache_methods GET HEAD POST，这意味着 Nginx 将缓存 GET、HEAD 和 POST 请求的响应。

复杂条件

根据实际需求设置不同的缓存方法：

server { listen 80; server_name example ; location /cache_get_head/ { scgi_pass scgi_backend; scgi_cache my_cache; scgi_cache_methods GET HEAD; # 仅缓存 GET 和 HEAD 请求的响应 } location /cache_all_methods/ { scgi_pass scgi_backend; scgi_cache my_cache; scgi_cache_methods GET HEAD POST DELETE PUT; # 缓存多种 HTTP 方法的响应 } }

在这个例子中：

对于 /cache_get_head/ 路径下的请求，仅缓存 GET 和 HEAD 请求的响应。对于 /cache_all_methods/ 路径下的请求，缓存 GET、HEAD、POST、DELETE 和 PUT 请求的响应。

注意事项

安全性：谨慎选择允许缓存的 HTTP 方法，特别是对于非幂等方法（如 POST），以避免潜在的安全问题。应用需求：根据实际应用需求合理配置允许缓存的 HTTP 方法，确保缓存的有效性和一致性。 scgi_cache_min_uses

scgi_cache_min_uses 指令用于设置缓存项被使用的最少次数。只有当请求的缓存项达到指定的使用次数时，该缓存项才会被存储到缓存中。

Syntax: scgi_cache_min_uses number; Default: scgi_cache_min_uses 1; Context: http, server, location number：指定缓存项被使用的最少次数，默认值为 1。

案例

基本用法

最简单的 scgi_cache_min_uses 用法是指定一个具体的最小使用次数：

server { listen 80; server_name example ; location / { # 设置缓存项至少需要被请求2次才能被缓存 scgi_cache_min_uses 2; scgi_cache my_cache; proxy_pass http://backend; } }

在这个例子中：

设置了 scgi_cache_min_uses 2，这意味着Nginx将只缓存那些至少被请求了两次的资源。

动态设置不同配置

你可以根据不同的路径或条件动态设置不同的最小使用次数：

server { listen 80; server_name example ; location /frequent/ { # 对频繁访问的内容设置较低的最小使用次数 scgi_cache_min_uses 1; scgi_cache my_cache; proxy_pass http://backend_frequent; } location /rare/ { # 对不常访问的内容设置较高的最小使用次数 scgi_cache_min_uses 5; scgi_cache my_cache; proxy_pass http://backend_rare; } }

在这个例子中：

对于 /frequent/ 路径，设置了 scgi_cache_min_uses 1，适合频繁访问的内容。对于 /rare/ 路径，设置了 scgi_cache_min_uses 5，适合不常访问的内容。

注意事项

缓存命中率：适当调整最小使用次数可以提高缓存命中率，但过高的值可能导致某些内容无法被缓存。适用场景：适用于需要优化缓存策略的应用场景。例如，在高流量网站、API网关等环境中使用。调试和监控：如果你遇到缓存命中问题，可以检查以下几点： 确保最小使用次数设置合理，并符合你的需求。查看Nginx的日志文件，确认是否有与此相关的警告或错误信息。使用工具模拟不同负载条件下的请求进行测试，确保在各种情况下都能正常工作。 scgi_cache_path

scgi_cache_path 指令用于定义SCGI缓存的数据存储路径和其他相关参数。这个指令帮助配置缓存的存储位置和行为。

Syntax: scgi_cache_path path [levels=levels] [use_temp_path=on|off] keys_zone=name:size [inactive=time] [max_size=size] [min_free=size] [manager_files=number] [manager_sleep=time] [manager_threshold=time] [loader_files=number] [loader_sleep=time] [loader_threshold=time] [purger=on|off] [purger_files=number] [purger_sleep=time] [purger_threshold=time]; Default: — Context: http path：指定缓存数据存放的目录。levels：可选参数，指定缓存文件的子目录层次结构，如 1:2 表示一级目录名长度为1，二级目录名长度为2。use_temp_path：可选参数，是否使用临时目录存放缓存文件。keys_zone：必需参数，指定共享内存区域名称和大小。inactive：可选参数，指定缓存项在不活动状态下的最长保留时间。max_size：可选参数，指定缓存的最大尺寸。min_free：可选参数，指定缓存区剩余空间的最小值。manager_files：可选参数，指定每次清理操作处理的文件数。manager_sleep：可选参数，指定每次清理操作之间的间隔时间。manager_threshold：可选参数，指定每次清理操作的最大执行时间。loader_files：可选参数，指定每次加载操作处理的文件数。loader_sleep：可选参数，指定每次加载操作之间的间隔时间。loader_threshold：可选参数，指定每次加载操作的最大执行时间。purger：可选参数，是否启用缓存清除功能。purger_files：可选参数，指定每次清除操作处理的文件数。purger_sleep：可选参数，指定每次清除操作之间的间隔时间。purger_threshold：可选参数，指定每次清除操作的最大执行时间。

案例

基本用法

最简单的 scgi_cache_path 用法是指定一个具体的缓存路径和共享内存区域：

http { scgi_cache_path /data/nginx/cache levels=1:2 keys_zone=my_cache:10m max_size=1g inactive=60m use_temp_path=off; server { listen 80; server_name example ; location / { scgi_cache my_cache; proxy_pass http://backend; } } }

在这个例子中：

设置了 scgi_cache_path /data/nginx/cache levels=1:2 keys_zone=my_cache:10m max_size=1g inactive=60m use_temp_path=off，这意味着Nginx将在 /data/nginx/cache 目录下存储缓存文件，并使用共享内存区域 my_cache，最大缓存大小为1GB，不活动时间为60分钟，不使用临时目录。

动态设置不同配置

你可以根据不同的需求动态设置不同的缓存路径和参数：

http { scgi_cache_path /data/nginx/frequent_cache levels=1:2 keys_zone=frequent_cache:10m max_size=1g inactive=30m use_temp_path=off; scgi_cache_path /data/nginx/rare_cache levels=1:2 keys_zone=rare_cache:10m max_size=500m inactive=120m use_temp_path=off; server { listen 80; server_name example ; location /frequent/ { scgi_cache frequent_cache; proxy_pass http://backend_frequent; } location /rare/ { scgi_cache rare_cache; proxy_pass http://backend_rare; } } }

在这个例子中：

对于 /frequent/ 路径，设置了 scgi_cache frequent_cache，适合频繁访问的内容。对于 /rare/ 路径，设置了 scgi_cache rare_cache，适合不常访问的内容。

注意事项

磁盘空间管理：确保有足够的磁盘空间来存放缓存文件，并定期清理不再需要的文件以避免磁盘满的问题。适用场景：适用于需要缓存SCGI响应内容的应用场景。例如，在高并发应用、API网关等环境中使用。调试和监控：如果你遇到缓存路径或参数设置问题，可以检查以下几点： 确保缓存路径和参数设置合理，并符合你的需求。查看Nginx的日志文件，确认是否有与此相关的警告或错误信息。使用工具模拟不同负载条件下的请求进行测试，确保在各种情况下都能正常工作。 scgi_cache_purge

scgi_cache_purge 指令用于清除特定URI的缓存。这个指令帮助手动或自动地删除不需要的缓存项。

Syntax: scgi_cache_purge string ...; Default: — Context: http, server, location This directive appeared in version 1.5.7. string：指定要清除缓存的URI模式。

案例

基本用法

最简单的 scgi_cache_purge 用法是指定一个具体的URI模式：

server { listen 80; server_name example ; location /purge/ { # 清除匹配 /cache/* 的缓存 scgi_cache_purge my_cache $request_uri; } location / { scgi_cache my_cache; proxy_pass http://backend; } }

在这个例子中：

设置了 scgi_cache_purge my_cache $request_uri，这意味着Nginx将根据 $request_uri 变量清除匹配的缓存项。

动态设置不同配置

你可以根据不同的需求动态设置不同的清除规则：

server { listen 80; server_name example ; location ~ /purge(/.*) { # 根据URL中的路径部分清除缓存 scgi_cache_purge my_cache $1; } location / { scgi_cache my_cache; proxy_pass http://backend; } }

在这个例子中：

设置了 location ~ /purge(/.*)，并使用 scgi_cache_purge my_cache $1 来根据URL中的路径部分清除缓存。

注意事项

缓存一致性：及时清除无效或过期的缓存项可以保持数据的一致性。适用场景：适用于需要手动或自动清除缓存的应用场景。例如，在内容管理系统（CMS）、电商网站等环境中使用。调试和监控：如果你遇到缓存清除问题，可以检查以下几点： 确保清除规则设置合理，并符合你的需求。查看Nginx的日志文件，确认是否有与此相关的警告或错误信息。使用工具模拟不同负载条件下的请求进行测试，确保在各种情况下都能正常工作。 scgi_cache_revalidate

scgi_cache_revalidate 指令用于控制是否在返回缓存内容之前重新验证缓存的有效性。这个指令帮助确保返回的内容是最新的。

Syntax: scgi_cache_revalidate on | off; Default: scgi_cache_revalidate off; Context: http, server, location This directive appeared in version 1.5.7. on：启用重新验证。off：禁用重新验证（默认值）。

案例

基本用法

最简单的 scgi_cache_revalidate 用法是指定是否启用重新验证：

server { listen 80; server_name example ; location / { # 启用重新验证 scgi_cache_revalidate on; scgi_cache my_cache; proxy_pass http://backend; } }

在这个例子中：

设置了 scgi_cache_revalidate on，这意味着Nginx将在返回缓存内容之前重新验证其有效性。

动态设置不同配置

你可以根据不同的路径或条件动态设置是否启用重新验证：

server { listen 80; server_name example ; location /static/ { # 对静态资源禁用重新验证 scgi_cache_revalidate off; scgi_cache my_cache; proxy_pass http://backend_static; } location /dynamic/ { # 对动态内容启用重新验证 scgi_cache_revalidate on; scgi_cache my_cache; proxy_pass http://backend_dynamic; } }

在这个例子中：

对于 /static/ 路径，设置了 scgi_cache_revalidate off，适合静态资源。对于 /dynamic/ 路径，设置了 scgi_cache_revalidate on，适合动态内容。

注意事项

性能与实时性平衡：启用重新验证可以确保返回的内容是最新的，但可能会增加请求的延迟。根据实际需求选择合适的配置。适用场景：适用于需要确保缓存内容最新性的应用场景。例如，在新闻网站、社交平台等环境中使用。调试和监控：如果你遇到重新验证问题，可以检查以下几点： 确保重新验证设置合理，并符合你的需求。查看Nginx的日志文件，确认是否有与此相关的警告或错误信息。使用工具模拟不同负载条件下的请求进行测试，确保在各种情况下都能正常工作。 scgi_cache_use_stale

scgi_cache_use_stale 指令用于指定在某些错误情况下是否可以使用过期的缓存数据。

Syntax: scgi_cache_use_stale error | timeout | invalid_header | updating | http_500 | http_503 | http_403 | http_404 | http_429 | off ...; Default: scgi_cache_use_stale off; Context: http, server, location error：在发生错误时使用过期缓存。timeout：在超时时使用过期缓存。invalid_header：在收到无效响应头时使用过期缓存。updating：在正在更新缓存时使用过期缓存。http_500：在上游服务器返回 500 错误时使用过期缓存。http_503：在上游服务器返回 503 错误时使用过期缓存。http_403：在上游服务器返回 403 错误时使用过期缓存。http_404：在上游服务器返回 404 错误时使用过期缓存。http_429：在上游服务器返回 429 错误时使用过期缓存。off：禁用使用过期缓存，默认值为 off。

案例

基本用法

最简单的 scgi_cache_use_stale 用法是指定在某些错误情况下使用过期缓存：

server { listen 80; server_name example ; location /scgi/ { # 在发生错误或超时时使用过期缓存 scgi_cache_use_stale error timeout; scgi_pass scgi_backend; } }

在这个例子中：

如果上游服务器发生错误或请求超时，Nginx 将使用过期缓存数据。

多种错误情况

你可以根据不同的错误情况动态设置使用过期缓存的条件：

server { listen 80; server_name example ; location /scgi/ { # 在多种错误情况下使用过期缓存 scgi_cache_use_stale error timeout invalid_header http_500 http_503; scgi_pass scgi_backend; } }

在这个例子中：

如果上游服务器发生错误、超时、收到无效响应头或返回 500 或 503 错误，Nginx 将使用过期缓存数据。

注意事项

用户体验：启用此功能可以在上游服务器出现问题时，仍能提供有效的响应内容，提升用户体验。适用场景：适用于需要高可用性和稳定性的应用场景。例如，在代理 API 服务时，可能需要在上游服务器不可用时提供过期但有效的缓存数据。调试和监控：如果你遇到缓存使用问题，可以检查以下几点： 确保缓存配置正确，并且缓存数据有效。查看Nginx的日志文件，确认是否有与此相关的警告或错误信息。 scgi_cache_valid

scgi_cache_valid 指令用于设置不同 HTTP 响应码的缓存时间。

Syntax: scgi_cache_valid [code ...] time; Default: — Context: http, server, location code：指定要设置缓存时间的 HTTP 响应码（如 200、301、404 等）。time：指定缓存时间（如 1m 表示 1 分钟，1h 表示 1 小时）。

案例

基本用法

最简单的 scgi_cache_valid 用法是指定一个特定响应码的缓存时间：

server { listen 80; server_name example ; location /scgi/ { # 设置 HTTP 200 响应的缓存时间为 10 分钟 scgi_cache_valid 200 10m; scgi_pass scgi_backend; } }

在这个例子中：

HTTP 200 响应将被缓存 10 分钟。

多个响应码设置

你可以为多个响应码设置不同的缓存时间：

server { listen 80; server_name example ; location /scgi/ { # 设置多个响应码的缓存时间 scgi_cache_valid 200 10m; scgi_cache_valid 404 1m; scgi_cache_valid any 1h; scgi_pass scgi_backend; } }

在这个例子中：

HTTP 200 响应将被缓存 10 分钟。HTTP 404 响应将被缓存 1 分钟。其他任何响应将被缓存 1 小时。

注意事项

性能优化：合理设置缓存时间可以显著提高性能，特别是在处理频繁请求的内容时。过长的缓存时间可能导致数据不及时更新，而过短的缓存时间可能导致频繁的缓存失效。适用场景：适用于需要优化缓存策略的应用场景。例如，在代理静态资源或 API 服务时，可能需要根据不同的响应码设置不同的缓存时间。调试和监控：如果你遇到缓存时间设置问题，可以检查以下几点： 确保缓存时间设置合理，并符合你的需求。查看Nginx的日志文件，确认是否有与此相关的警告或错误信息。 scgi_connect_timeout

scgi_connect_timeout 指令用于设置与 SCGI 服务器建立连接的超时时间。

Syntax: scgi_connect_timeout time; Default: scgi_connect_timeout 60s; Context: http, server, location time：指定超时时间（如 10s 表示 10 秒）。

案例

基本用法

最简单的 scgi_connect_timeout 用法是指定一个特定的超时时间：

server { listen 80; server_name example ; location /scgi/ { # 设置连接超时时间为 30 秒 scgi_connect_timeout 30s; scgi_pass scgi_backend; } }

在这个例子中：

Nginx 将等待最多 30 秒来与 SCGI 服务器建立连接。

动态设置不同配置

你可以根据不同的路径或条件动态设置不同的连接超时时间：

server { listen 80; server_name example ; location /fast_scgi/ { # 设置较短的连接超时时间，适合快速响应的服务 scgi_connect_timeout 10s; scgi_pass scgi_backend_fast; } location /slow_scgi/ { # 设置较长的连接超时时间，适合慢速响应的服务 scgi_connect_timeout 60s; scgi_pass scgi_backend_slow; } }

在这个例子中：

对于 /fast_scgi/ 路径，设置了 scgi_connect_timeout 10s，适合快速响应的服务。对于 /slow_scgi/ 路径，设置了 scgi_connect_timeout 60s，适合慢速响应的服务。

注意事项

性能影响：合理的超时时间可以帮助避免长时间等待未响应的连接，但在生产环境中应谨慎调整以确保系统的稳定性和响应性。适用场景：适用于需要控制请求响应时间的应用场景。例如，在代理不同响应速度的服务时，可能需要根据服务特性设置不同的连接超时时间。调试和监控：如果你遇到连接超时问题，可以检查以下几点： 确保超时时间设置合理，并符合你的需求。查看Nginx的日志文件，确认是否有与此相关的警告或错误信息。 scgi_force_ranges

scgi_force_ranges 指令用于强制启用范围请求（range requests），即使上游服务器没有明确支持。

Syntax: scgi_force_ranges on | off; Default: scgi_force_ranges off; Context: http, server, location This directive appeared in version 1.7.7. on：强制启用范围请求。off：不强制启用范围请求，默认值为 off。

案例

基本用法

最简单的 scgi_force_ranges 用法是指定是否强制启用范围请求：

server { listen 80; server_name example ; location /large_files/ { # 强制启用范围请求 scgi_force_ranges on; scgi_pass scgi_backend; } }

在这个例子中：

即使上游服务器不支持范围请求，Nginx 也会处理范围请求。

不启用范围请求

你可以选择不启用范围请求：

server { listen 80; server_name example ; location /small_files/ { # 不强制启用范围请求 scgi_force_ranges off; scgi_pass scgi_backend; } }

在这个例子中：

如果上游服务器不支持范围请求，Nginx 将不会处理范围请求。

注意事项

性能优化：强制启用范围请求可以提高大文件传输的效率，尤其是在网络不稳定的情况下。然而，如果上游服务器不支持范围请求，可能会导致不必要的复杂性。适用场景：适用于需要高效传输大文件的应用场景。例如，在代理视频流或大文件下载服务时，可能需要强制启用范围请求以提高传输效率。调试和监控：如果你遇到范围请求问题，可以检查以下几点： 确保上游服务器的配置支持范围请求，或者在必要时启用 scgi_force_ranges。查看Nginx的日志文件，确认是否有与此相关的警告或错误信息。 scgi_hide_header

scgi_hide_header 指令用于指定哪些响应头不应传递给客户端。这对于控制向客户端公开的响应头信息非常有用，特别是当后端服务器返回一些不需要或不安全的响应头时。

Syntax: scgi_hide_header field; Default: — Context: http, server, location field：指定要隐藏的响应头字段名称。

案例

基本用法

假设我们希望隐藏 X-Powered-By 和 Server 响应头：

http { server { listen 80; server_name example ; location /dynamic/ { scgi_pass scgi_backend; scgi_hide_header X-Powered-By; # 隐藏 X-Powered-By 响应头 scgi_hide_header Server; # 隐藏 Server 响应头 } } }

注意事项

安全性：通过隐藏不必要的响应头，可以减少潜在的安全风险。隐私保护：避免暴露服务器的技术细节，增强隐私保护。 scgi_ignore_client_abort

scgi_ignore_client_abort 指令用于控制当客户端中断连接时，Nginx是否继续处理与后端SCGI服务器的请求。这对于提高资源利用率和防止不必要的处理非常重要。

Syntax: scgi_ignore_client_abort on | off; Default: scgi_ignore_client_abort off; Context: http, server, location on：即使客户端中断连接，Nginx也会继续处理与后端SCGI服务器的请求。off（默认）：如果客户端中断连接，Nginx会立即停止处理与后端SCGI服务器的请求。

案例

启用忽略客户端中断

假设我们希望在客户端中断连接时继续处理请求：

http { server { listen 80; server_name example ; location /dynamic/ { scgi_pass scgi_backend; scgi_ignore_client_abort on; # 继续处理请求，即使客户端中断连接 } } }

禁用忽略客户端中断

如果我们希望在客户端中断连接时立即停止处理请求：

http { server { listen 80; server_name example ; location /dynamic/ { scgi_pass scgi_backend; scgi_ignore_client_abort off; # 默认行为，客户端中断时立即停止处理请求 } } }

注意事项

资源管理：启用此选项可以防止资源浪费，但在某些情况下可能会导致不必要的处理。性能优化：根据实际需求选择合适的配置，以平衡资源利用和性能。 scgi_ignore_headers

scgi_ignore_headers 指令用于指定哪些响应头不应被Nginx处理。这对于过滤掉不必要的响应头，确保只有有效的响应头传递给客户端非常重要。

Syntax: scgi_ignore_headers field ...; Default: — Context: http, server, location field：指定要忽略的响应头字段名称，多个字段之间用空格分隔。

案例

基本用法

假设我们希望忽略 Set-Cookie 和 Expires 响应头：

http { server { listen 80; server_name example ; location /dynamic/ { scgi_pass scgi_backend; scgi_ignore_headers Set-Cookie Expires; # 忽略 Set-Cookie 和 Expires 响应头 } } }

注意事项

一致性：确保忽略的响应头不会影响应用程序的功能和用户体验。安全性：通过忽略不必要的响应头，可以减少潜在的安全问题。 scgi_intercept_errors

scgi_intercept_errors 指令用于控制是否拦截后端SCGI服务器返回的错误响应，并允许Nginx根据这些错误响应进行处理（如自定义错误页面）。这对于提供更好的用户体验和更灵活的错误处理非常重要。

Syntax: scgi_intercept_errors on | off; Default: scgi_intercept_errors off; Context: http, server, location on：启用拦截后端SCGI服务器的错误响应。off（默认）：不拦截后端SCGI服务器的错误响应，直接将错误响应传递给客户端。

案例

启用拦截错误

假设我们希望在后端SCGI服务器返回错误时使用自定义的错误页面：

http { server { listen 80; server_name example ; location /dynamic/ { scgi_pass scgi_backend; scgi_intercept_errors on; # 启用拦截后端SCGI服务器的错误响应 error_page 500 502 503 504 /50x.html; } location = /50x.html { root /usr/share/nginx/html; } } }

在这个例子中，当后端SCGI服务器返回500、502、503或504错误时，Nginx会拦截这些错误并返回 /50x.html 页面。

禁用拦截错误

如果我们不希望拦截后端SCGI服务器的错误响应：

http { server { listen 80; server_name example ; location /dynamic/ { scgi_pass scgi_backend; scgi_intercept_errors off; # 不拦截后端SCGI服务器的错误响应 } } }

注意事项

用户体验：通过自定义错误页面可以提供更好的用户体验，而不是直接显示后端服务器的错误信息。维护性：确保自定义错误页面内容简洁且易于维护。 scgi_limit_rate

scgi_limit_rate 指令用于限制从 SCGI 后端服务器发送到客户端的数据传输速率。这有助于控制带宽使用并防止过载。

Syntax: scgi_limit_rate rate; Default: scgi_limit_rate 0; Context: http, server, location This directive appeared in version 1.7.7. rate：数据传输速率，单位为字节/秒（bytes per second）。值为 0 表示不限制速率，默认行为。

案例

基本用法

最简单的 scgi_limit_rate 用法是指定数据传输速率：

http { server { listen 80; server_name example ; location /limit_rate_example/ { # 限制数据传输速率为 100 KB/s scgi_limit_rate 102400; # 其他配置 scgi_pass unix:/tmp/fastcgi.socket; } } }

在这个例子中：

当用户访问 /limit_rate_example/ 路径时，Nginx 将限制从 SCGI 后端服务器发送到客户端的数据传输速率为 100 KB/s。

注意事项

性能影响：限制传输速率可能会增加页面加载时间，特别是在高带宽需求的情况下。带宽管理：合理设置速率限制，以避免过度占用带宽资源，确保服务质量。 scgi_max_temp_file_size

scgi_max_temp_file_size 指令用于指定临时文件的最大大小。当响应数据量超过此大小时，Nginx 会将超出部分写入临时文件，而不是直接存储在内存中。

Syntax: scgi_max_temp_file_size size; Default: scgi_max_temp_file_size 1024m; Context: http, server, location size：临时文件的最大大小，单位为字节（bytes）。默认值为 1024 MB（1 GB）。

案例

基本用法

最简单的 scgi_max_temp_file_size 用法是指定临时文件的最大大小：

http { server { listen 80; server_name example ; location /max_temp_file_example/ { # 设置临时文件的最大大小为 500 MB scgi_max_temp_file_size 524288000; # 500 * 1024 * 1024 bytes # 其他配置 scgi_pass unix:/tmp/fastcgi.socket; } } }

在这个例子中：

当用户访问 /max_temp_file_example/ 路径时，Nginx 将临时文件的最大大小设置为 500 MB。

禁用临时文件

你可以禁用临时文件，强制所有响应数据都存储在内存中：

http { server { listen 80; server_name example ; location /no_temp_file_example/ { # 禁用临时文件 scgi_max_temp_file_size 0; # 其他配置 scgi_pass unix:/tmp/fastcgi.socket; } } }

在这个例子中：

当用户访问 /no_temp_file_example/ 路径时，Nginx 将不使用临时文件，所有响应数据都将存储在内存中。

注意事项

内存使用：禁用临时文件或设置过小的临时文件大小可能导致内存使用过高，特别是在处理大文件时。磁盘 I/O：合理设置临时文件大小，以平衡内存和磁盘 I/O 的使用。 scgi_next_upstream

scgi_next_upstream 指令用于定义在哪些情况下应将请求传递给下一个上游服务器。这有助于提高系统的容错能力和负载均衡效果。

Syntax: scgi_next_upstream error | timeout | invalid_header | http_500 | http_503 | http_403 | http_404 | http_429 | non_idempotent | off ...; Default: scgi_next_up_stream error timeout; Context: http, server, location error：如果与后端服务器的连接发生错误，则尝试下一个上游服务器。timeout：如果与后端服务器的连接超时，则尝试下一个上游服务器。invalid_header：如果后端服务器返回无效的响应头，则尝试下一个上游服务器。http_500：如果后端服务器返回 HTTP 500 错误，则尝试下一个上游服务器。http_503：如果后端服务器返回 HTTP 503 错误，则尝试下一个上游服务器。http_403：如果后端服务器返回 HTTP 403 错误，则尝试下一个上游服务器。http_404：如果后端服务器返回 HTTP 404 错误，则尝试下一个上游服务器。http_429：如果后端服务器返回 HTTP 429 错误（请求过多），则尝试下一个上游服务器。non_idempotent：即使请求不是幂等的（例如 POST 请求），也尝试下一个上游服务器。off：禁用尝试下一个上游服务器的功能。

案例

基本用法

最简单的 scgi_next_upstream 用法是指定哪些情况尝试下一个上游服务器：

http { upstream backend { server backend1.example ; server backend2.example ; } server { listen 80; server_name example ; location /next_upstream_example/ { # 在发生错误或超时时尝试下一个上游服务器 scgi_next_upstream error timeout; # 其他配置 scgi_pass backend; } } }

在这个例子中：

如果与后端服务器的连接发生错误或超时，Nginx 将尝试下一个上游服务器。

更多条件

你可以根据需要添加更多条件：

http { upstream backend { server backend1.example ; server backend2.example ; } server { listen 80; server_name example ; location /extended_next_upstream/ { # 在发生错误、超时、HTTP 500 或 HTTP 503 时尝试下一个上游服务器 scgi_next_upstream error timeout http_500 http_503; # 其他配置 scgi_pass backend; } } }

在这个例子中：

如果与后端服务器的连接发生错误、超时，或者后端服务器返回 HTTP 500 或 HTTP 503 错误，Nginx 将尝试下一个上游服务器。

注意事项

负载均衡：合理配置 scgi_next_upstream 可以提高系统的容错能力和负载均衡效果。幂等性考虑：对于非幂等请求（如 POST 请求），谨慎启用 non_idempotent 选项，以避免重复提交问题。 scgi_next_upstream_timeout

scgi_next_upstream_timeout 指令用于指定尝试下一个上游服务器的总超时时间。这有助于控制请求在多个上游服务器之间重试的时间。

Syntax: scgi_next_upstream_timeout time; Default: scgi_next_upstream_timeout 0; Context: http, server, location This directive appeared in version 1.7.5. time：尝试下一个上游服务器的总超时时间，单位为秒（seconds）。值为 0 表示不限制超时时间，默认行为。

案例

基本用法

最简单的 scgi_next_upstream_timeout 用法是指定尝试下一个上游服务器的总超时时间：

http { upstream backend { server backend1.example ; server backend2.example ; } server { listen 80; server_name example ; location /next_upstream_timeout_example/ { # 设置尝试下一个上游服务器的总超时时间为 5 秒 scgi_next_upstream_timeout 5s; # 其他配置 scgi_pass backend; scgi_next_upstream error timeout; } } }

在这个例子中：

当用户访问 /next_upstream_timeout_example/ 路径时，Nginx 将尝试下一个上游服务器的总超时时间设置为 5 秒。

不限制超时时间

你可以选择不限制超时时间：

http { upstream backend { server backend1.example ; server backend2.example ; } server { listen 80; server_name example ; location /unlimited_timeout_example/ { # 不限制尝试下一个上游服务器的总超时时间 scgi_next_upstream_timeout 0; # 其他配置 scgi_pass backend; scgi_next_upstream error timeout; } } }

在这个例子中：

当用户访问 /unlimited_timeout_example/ 路径时，Nginx 将不限制尝试下一个上游服务器的总超时时间。

注意事项

请求延迟：合理设置超时时间，以避免长时间等待导致的请求延迟。系统资源：确保超时时间不会导致系统资源过度消耗，特别是在高并发场景下。 scgi_next_upstream_tries

scgi_next_upstream_tries 用于设置尝试下一个上游 SCGI 服务器的最大次数。这有助于控制在遇到错误时重试的次数，避免无限重试。

Syntax: scgi_next_upstream_tries number; Default: scgi_next_upstream_tries 0; Context: http, server, location This directive appeared in version 1.7.5. number：指定最大重试次数，默认为 0（表示不限制重试次数）。

案例

基本用法

最简单的 scgi_next_upstream_tries 用法是指定最大重试次数：

server { listen 80; server_name example ; location /scgi_backend/ { scgi_pass scgi_backend; scgi_next_upstream_tries 3; # 最多尝试 3 次 } }

在这个例子中，设置了 scgi_next_upstream_tries 3，这意味着 Nginx 在遇到错误时最多尝试 3 次下一个上游 SCGI 服务器。

调整重试次数

根据实际需求调整尝试下一个上游 SCGI 服务器的最大次数：

upstream scgi_backend { server 192.168.1.10:9000; server 192.168.1.11:9000; } server { listen 80; server_name example ; location /limited_retry_scgi/ { scgi_pass scgi_backend; scgi_next_upstream_tries 2; # 最多尝试 2 次，适用于高可用性要求的场景 } location /no_retry_scgi/ { scgi_pass scgi_backend; scgi_next_upstream_tries 1; # 只尝试一次，适用于低延迟要求的场景 } }

在这个例子中：

对于 /limited_retry_scgi/ 路径下的请求，设置了最多尝试 2 次，适用于对高可用性有较高要求的场景。对于 /no_retry_scgi/ 路径下的请求，只尝试一次，适用于对低延迟有较高要求的场景。

注意事项

系统稳定性：合理的重试次数可以提高系统的稳定性和可靠性，但过多的重试可能会导致资源浪费。性能优化：结合其他指令，如 scgi_next_upstream_timeout，以优化整体性能。 scgi_no_cache

scgi_no_cache 用于指定在哪些情况下不缓存响应。这有助于灵活控制缓存策略，确保某些特定请求不会被缓存。

Syntax: scgi_no_cache string ...; Default: — Context: http, server, location string：指定条件表达式，满足该条件时将不缓存响应。

案例

基本用法

最简单的 scgi_no_cache 用法是指定不缓存的条件：

http { scgi_cache_path /data/nginx/cache levels=1:2 keys_zone=my_cache:10m max_size=1g inactive=60m use_temp_path=off; server { listen 80; server_name example ; location /dynamic_content/ { scgi_pass scgi_backend; scgi_cache my_cache; scgi_no_cache $cookie_nocache $arg_nocache; # 不缓存的条件 } } }

在这个例子中，设置了 scgi_no_cache $cookie_nocache $arg_nocache，这意味着如果请求中包含 nocache 参数或 Cookie，Nginx 将不缓存响应。

复杂条件

根据实际需求设置更复杂的不缓存条件：

http { scgi_cache_path /data/nginx/cache levels=1:2 keys_zone=my_cache:10m max_size=1g inactive=60m use_temp_path=off; server { listen 80; server_name example ; location /conditional_no_cache/ { scgi_pass scgi_backend; scgi_cache my_cache; scgi_no_cache $cookie_nocache $arg_nocache $http_x_purge; # 多个条件组合 } location /force_refresh/ { scgi_pass scgi_backend; scgi_cache my_cache; scgi_no_cache $http_pragma ~*no-cache; # 根据 HTTP 请求头中的 Pragma 字段不缓存 } } }

在这个例子中：

对于 /conditional_no_cache/ 路径下的请求，设置了多个不缓存的条件，包括 nocache 参数、Cookie 和自定义头部 X-Purge。对于 /force_refresh/ 路径下的请求，根据 HTTP 请求头中的 Pragma 字段判断是否不缓存。

注意事项

灵活性：可以根据多种条件灵活地控制哪些请求不被缓存，确保在需要时获取最新数据。性能影响：频繁不缓存可能导致增加后端服务器的负载，需谨慎使用。 scgi_param

scgi_param 用于向 SCGI 后端传递参数。这允许你自定义传递给后端应用程序的请求参数，增强灵活性和可配置性。

Syntax: scgi_param parameter value [if_not_empty]; Default: — Context: http, server, location parameter：指定要传递的参数名称。value：指定参数的值。if_not_empty：可选参数，仅在值非空时传递该参数。

案例

基本用法

最简单的 scgi_param 用法是指定要传递的参数及其值：

server { listen 80; server_name example ; location /scgi_backend/ { scgi_pass scgi_backend; scgi_param SCRIPT_FILENAME /var/ /cgi-bin/script.php; # 传递 SCRIPT_FILENAME 参数 scgi_param QUERY_STRING $query_string; # 传递 QUERY_STRING 参数 } }

在这个例子中，指定了两个参数 SCRIPT_FILENAME 和 QUERY_STRING，并将它们传递给 SCGI 后端。

自定义参数

根据实际需求自定义传递的参数：

server { listen 80; server_name example ; location /custom_params/ { scgi_pass scgi_backend; scgi_param CUSTOM_PARAM "custom_value"; # 传递自定义参数 CUSTOM_PARAM scgi_param REMOTE_ADDR $remote_addr if_not_empty; # 仅在非空时传递 REMOTE_ADDR 参数 } }

在这个例子中：

传递了一个自定义参数 CUSTOM_PARAM，其值为 "custom_value"。传递了 REMOTE_ADDR 参数，但仅在 $remote_addr 非空时才传递。

注意事项

参数传递：确保传递的参数与后端应用程序的需求匹配，避免无效或不一致的参数传递。安全性：注意传递敏感信息时的安全性，避免泄露重要数据。 scgi_pass

scgi_pass 用于指定 SCGI 后端服务器的地址。Nginx 将请求转发到指定的 SCGI 服务器进行处理。

Syntax: scgi_pass address; Default: — Context: location, if in location address：指定 SCGI 后端服务器的地址，可以是 IP 地址和端口、Unix 套接字路径等。

案例

基本用法

最简单的 scgi_pass 用法是指定 SCGI 后端服务器的地址：

server { listen 80; server_name example ; location /scgi_backend/ { scgi_pass 127.0.0.1:9000; # 指定 SCGI 后端服务器的地址和端口 } }

在这个例子中，指定了 SCGI 后端服务器的地址为 127.0.0.1:9000。

使用 Unix 套接字

根据实际需求使用 Unix 套接字作为 SCGI 后端地址：

server { listen 80; server_name example ; location /scgi_unix_socket/ { scgi_pass unix:/var/run/scgi.sock; # 使用 Unix 套接字作为 SCGI 后端地址 } }

在这个例子中，使用了 Unix 套接字 /var/run/scgi.sock 作为 SCGI 后端地址。

结合 upstream 使用

结合 upstream 模块使用 scgi_pass：

upstream scgi_backend { server 192.168.1.10:9000; server 192.168.1.11:9000; } server { listen 80; server_name example ; location /scgi_balanced/ { scgi_pass scgi_backend; # 使用 upstream 定义的 SCGI 后端服务器组 } }

在这个例子中，使用了 upstream 定义的 SCGI 后端服务器组 scgi_backend，并将其传递给 scgi_pass。

注意事项

地址格式：确保使用的地址格式正确，支持 IP 地址和端口、Unix 套接字路径等多种形式。负载均衡：结合 upstream 模块实现负载均衡，提高系统的可靠性和性能。 scgi_pass_header

scgi_pass_header 指令用于允许传递特定的响应头字段给客户端。默认情况下，某些SCGI响应头字段不会传递给客户端，通过该指令可以明确指定需要传递的头字段。

Syntax: scgi_pass_header field; Default: — Context: http, server, location field：指定要传递的响应头字段名称。

案例

基本用法

最简单的 scgi_pass_header 用法是指定一个具体的响应头字段：

server { listen 80; server_name example ; location / { # 允许传递 X-Custom-Header 响应头字段 scgi_pass_header X-Custom-Header; scgi_pass http://backend; } }

在这个例子中：

设置了 scgi_pass_header X-Custom-Header，这意味着Nginx将允许传递名为 X-Custom-Header 的响应头字段给客户端。

动态设置不同配置

你可以根据不同的路径或条件动态设置不同的响应头字段：

server { listen 80; server_name example ; location /api/ { # 对API请求允许传递 X-API-Version 响应头字段 scgi_pass_header X-API-Version; scgi_pass http://backend_api; } location /static/ { # 对静态资源请求允许传递 Cache-Control 响应头字段 scgi_pass_header Cache-Control; scgi_pass http://backend_static; } }

在这个例子中：

对于 /api/ 路径，设置了 scgi_pass_header X-API-Version，适合API请求。对于 /static/ 路径，设置了 scgi_pass_header Cache-Control，适合静态资源请求。

注意事项

安全性：确保只传递必要的响应头字段，以避免泄露敏感信息。适用场景：适用于需要自定义响应头字段的应用场景。例如，在API网关、内容管理系统（CMS）等环境中使用。调试和监控：如果你遇到响应头字段传递问题，可以检查以下几点： 确保响应头字段设置合理，并符合你的需求。查看Nginx的日志文件，确认是否有与此相关的警告或错误信息。使用工具模拟不同负载条件下的请求进行测试，确保在各种情况下都能正常工作。 scgi_pass_request_body

scgi_pass_request_body 指令用于控制是否将请求体传递给SCGI服务器。默认情况下，请求体会被传递给SCGI服务器。

Syntax: scgi_pass_request_body on | off; Default: scgi_pass_request_body on; Context: http, server, location on：启用请求体传递（默认值）。off：禁用请求体传递。

案例

基本用法

最简单的 scgi_pass_request_body 用法是指定是否启用请求体传递：

server { listen 80; server_name example ; location / { # 启用请求体传递 scgi_pass_request_body on; scgi_pass http://backend; } }

在这个例子中：

设置了 scgi_pass_request_body on，这意味着Nginx会将请求体传递给SCGI服务器。

动态设置不同配置

你可以根据不同的路径或条件动态设置是否启用请求体传递：

server { listen 80; server_name example ; location /upload/ { # 对上传请求启用请求体传递 scgi_pass_request_body on; scgi_pass http://backend_upload; } location /ping/ { # 对Ping请求禁用请求体传递 scgi_pass_request_body off; scgi_pass http://backend_ping; } }

在这个例子中：

对于 /upload/ 路径，设置了 scgi_pass_request_body on，适合上传请求。对于 /ping/ 路径，设置了 scgi_pass_request_body off，适合Ping请求。

注意事项

性能与功能平衡：对于不需要请求体的请求，禁用请求体传递可以减少不必要的数据传输，提高性能。适用场景：适用于需要控制请求体传递的应用场景。例如，在文件上传服务、健康检查等环境中使用。调试和监控：如果你遇到请求体传递问题，可以检查以下几点： 确保请求体传递设置合理，并符合你的需求。查看Nginx的日志文件，确认是否有与此相关的警告或错误信息。使用工具模拟不同负载条件下的请求进行测试，确保在各种情况下都能正常工作。 scgi_pass_request_headers

scgi_pass_request_headers 指令用于控制是否将请求头传递给SCGI服务器。默认情况下，请求头会被传递给SCGI服务器。

Syntax: scgi_pass_request_headers on | off; Default: scgi_pass_request_headers on; Context: http, server, location on：启用请求头传递（默认值）。off：禁用请求头传递。

案例

基本用法

最简单的 scgi_pass_request_headers 用法是指定是否启用请求头传递：

server { listen 80; server_name example ; location / { # 启用请求头传递 scgi_pass_request_headers on; scgi_pass http://backend; } }

在这个例子中：

设置了 scgi_pass_request_headers on，这意味着Nginx会将请求头传递给SCGI服务器。

动态设置不同配置

你可以根据不同的路径或条件动态设置是否启用请求头传递：

server { listen 80; server_name example ; location /secure/ { # 对安全请求启用请求头传递 scgi_pass_request_headers on; scgi_pass http://backend_secure; } location /healthcheck/ { # 对健康检查请求禁用请求头传递 scgi_pass_request_headers off; scgi_pass http://backend_healthcheck; } }

在这个例子中：

对于 /secure/ 路径，设置了 scgi_pass_request_headers on，适合安全请求。对于 /healthcheck/ 路径，设置了 scgi_pass_request_headers off，适合健康检查请求。

注意事项

安全性：确保只传递必要的请求头字段，以避免泄露敏感信息。适用场景：适用于需要控制请求头传递的应用场景。例如，在API网关、健康检查等环境中使用。调试和监控：如果你遇到请求头传递问题，可以检查以下几点： 确保请求头传递设置合理，并符合你的需求。查看Nginx的日志文件，确认是否有与此相关的警告或错误信息。使用工具模拟不同负载条件下的请求进行测试，确保在各种情况下都能正常工作。 scgi_read_timeout

scgi_read_timeout 指令用于设置从SCGI服务器读取响应的超时时间。如果在指定时间内没有接收到完整的响应，连接将被关闭。

Syntax: scgi_read_timeout time; Default: scgi_read_timeout 60s; Context: http, server, location time：指定超时时间，默认为 60s。

案例

基本用法

最简单的 scgi_read_timeout 用法是指定一个具体的超时时间：

server { listen 80; server_name example ; location / { # 设置从SCGI服务器读取响应的超时时间为30秒 scgi_read_timeout 30s; scgi_pass http://backend; } }

在这个例子中：

设置了 scgi_read_timeout 30s，这意味着Nginx将在30秒内等待从SCGI服务器读取完整的响应。

动态设置不同配置

你可以根据不同的路径或条件动态设置不同的超时时间：

server { listen 80; server_name example ; location /fast/ { # 对快速响应的服务设置较短的超时时间 scgi_read_timeout 10s; scgi_pass http://backend_fast; } location /slow/ { # 对慢速响应的服务设置较长的超时时间 scgi_read_timeout 120s; scgi_pass http://backend_slow; } }

在这个例子中：

对于 /fast/ 路径，设置了 scgi_read_timeout 10s，适合快速响应的服务。对于 /slow/ 路径，设置了 scgi_read_timeout 120s，适合慢速响应的服务。

注意事项

性能与稳定性平衡：过短的超时时间可能导致频繁的连接中断，而过长的超时时间可能占用过多资源。根据实际需求选择合适的超时时间。适用场景：适用于需要控制从SCGI服务器读取响应超时的应用场景。例如，在高并发应用、长时间处理任务等环境中使用。调试和监控：如果你遇到超时问题，可以检查以下几点： 确保超时时间设置合理，并符合你的需求。查看Nginx的日志文件，确认是否有与此相关的警告或错误信息。使用工具模拟不同负载条件下的请求进行测试，确保在各种情况下都能正常工作。 scgi_request_buffering

scgi_request_buffering 指令用于控制是否对 SCGI 请求进行缓冲。

Syntax: scgi_request_buffering on | off; Default: scgi_request_buffering on; Context: http, server, location This directive appeared in version 1.7.11. on：启用请求缓冲，默认值为 on。off：禁用请求缓冲。

案例

基本用法

最简单的 scgi_request_buffering 用法是指定是否启用请求缓冲：

server { listen 80; server_name example ; location /upload/ { # 禁用请求缓冲，适合流式上传 scgi_request_buffering off; scgi_pass scgi_backend; } }

在这个例子中：

请求缓冲被禁用，适合流式上传场景。

启用请求缓冲

你可以启用请求缓冲：

server { listen 80; server_name example ; location /api/ { # 启用请求缓冲，默认行为 scgi_request_buffering on; scgi_pass scgi_backend; } }

在这个例子中：

请求缓冲被启用，适合常规的 API 请求。

注意事项

性能优化：启用请求缓冲可以提高处理小请求的效率，但在处理大文件上传或流式数据传输时，禁用请求缓冲可以避免内存占用过高和延迟问题。适用场景：适用于需要处理大文件上传或流式数据传输的应用场景。例如，在代理视频上传服务时，可能需要禁用请求缓冲以减少内存使用和提高响应速度。调试和监控：如果你遇到请求缓冲问题，可以检查以下几点： 确保配置符合你的需求（启用或禁用）。查看Nginx的日志文件，确认是否有与此相关的警告或错误信息。 scgi_send_timeout

scgi_send_timeout 指令用于设置将响应发送给客户端的超时时间。

Syntax: scgi_send_timeout time; Default: scgi_send_timeout 60s; Context: http, server, location time：指定超时时间（如 30s 表示 30 秒）。

案例

基本用法

最简单的 scgi_send_timeout 用法是指定一个特定的超时时间：

server { listen 80; server_name example ; location /scgi/ { # 设置发送超时时间为 30 秒 scgi_send_timeout 30s; scgi_pass scgi_backend; } }

在这个例子中：

Nginx 将等待最多 30 秒来完成响应的发送。

动态设置不同配置

你可以根据不同的路径或条件动态设置不同的发送超时时间：

server { listen 80; server_name example ; location /fast_scgi/ { # 设置较短的发送超时时间，适合快速响应的服务 scgi_send_timeout 10s; scgi_pass scgi_backend_fast; } location /slow_scgi/ { # 设置较长的发送超时时间，适合慢速响应的服务 scgi_send_timeout 60s; scgi_pass scgi_backend_slow; } }

在这个例子中：

对于 /fast_scgi/ 路径，设置了 scgi_send_timeout 10s，适合快速响应的服务。对于 /slow_scgi/ 路径，设置了 scgi_send_timeout 60s，适合慢速响应的服务。

注意事项

性能影响：合理的超时时间可以帮助避免长时间等待未响应的连接，但在生产环境中应谨慎调整以确保系统的稳定性和响应性。适用场景：适用于需要控制请求响应时间的应用场景。例如，在代理不同响应速度的服务时，可能需要根据服务特性设置不同的发送超时时间。调试和监控：如果你遇到发送超时问题，可以检查以下几点： 确保超时时间设置合理，并符合你的需求。查看Nginx的日志文件，确认是否有与此相关的警告或错误信息。 scgi_socket_keepalive

scgi_socket_keepalive 指令用于控制是否启用套接字的 keep-alive 功能。

Syntax: scgi_socket_keepalive on | off; Default: scgi_socket_keepalive off; Context: http, server, location This directive appeared in version 1.15.6. on：启用套接字的 keep-alive 功能。off：禁用套接字的 keep-alive 功能，默认值为 off。

案例

基本用法

最简单的 scgi_socket_keepalive 用法是指定是否启用套接字的 keep-alive 功能：

server { listen 80; server_name example ; location /scgi/ { # 启用套接字的 keep-alive 功能 scgi_socket_keepalive on; scgi_pass scgi_backend; } }

在这个例子中：

Nginx 将启用与上游服务器通信时的 TCP keep-alive 功能。

禁用 keep-alive 功能

你可以禁用 keep-alive 功能：

server { listen 80; server_name example ; location /short_requests/ { # 禁用套接字的 keep-alive 功能，适合短请求 scgi_socket_keepalive off; scgi_pass scgi_backend_short; } }

在这个例子中：

禁用了套接字的 keep-alive 功能，适合短请求。

注意事项

性能优化：启用 keep-alive 功能可以帮助检测和处理网络中断问题，特别是在长时间连接的应用场景下。然而，这也可能导致资源占用增加。适用场景：适用于需要保持长连接并检测网络中断的应用场景。例如，在代理 API 服务时，可能需要启用此功能以提高连接的稳定性。调试和监控：如果你遇到套接字 keep-alive 功能问题，可以检查以下几点： 确保上游服务器支持 keep-alive 功能。查看Nginx的日志文件，确认是否有与此相关的警告或错误信息。 scgi_store

scgi_store 指令用于控制是否存储来自 SCGI 服务器的响应到磁盘上。

Syntax: scgi_store on | off | string; Default: scgi_store off; Context: http, server, location on：启用存储响应，默认存储位置由 proxy_temp_path 指令定义。off：禁用存储响应，默认值为 off。string：指定自定义的存储路径。

案例

基本用法

最简单的 scgi_store 用法是指定是否启用响应存储：

server { listen 80; server_name example ; location /store_responses/ { # 启用响应存储，默认存储位置 scgi_store on; scgi_pass scgi_backend; } }

在这个例子中：

来自 SCGI 服务器的响应将被存储到默认的临时目录中。

自定义存储路径

你可以指定自定义的存储路径：

server { listen 80; server_name example ; location /custom_store/ { # 使用自定义路径存储响应 scgi_store /path/to/store; scgi_pass scgi_backend; } }

在这个例子中：

来自 SCGI 服务器的响应将被存储到 /path/to/store 目录中。

禁用存储

你可以选择禁用响应存储：

server { listen 80; server_name example ; location /no_store/ { # 禁用响应存储 scgi_store off; scgi_pass scgi_backend; } }

在这个例子中：

禁用了响应存储。

注意事项

性能优化：启用响应存储可以提高某些场景下的性能，尤其是在需要缓存或后续处理响应内容时。然而，频繁的磁盘 I/O 操作可能会降低性能。适用场景：适用于需要缓存或后续处理 SCGI 响应的应用场景。例如，在代理生成的报告或日志时，可能需要将响应存储到磁盘以便后续分析。调试和监控：如果你遇到响应存储问题，可以检查以下几点： 确保存储路径可写且有足够的磁盘空间。查看Nginx的日志文件，确认是否有与此相关的警告或错误信息。 scgi_store_access

scgi_store_access 指令用于设置存储通过 SCGI 请求生成的文件的访问权限。这有助于控制这些文件在服务器上的访问权限。

Syntax: scgi_store_access users:permissions ...; Default: scgi_store_access user:rw; Context: http, server, location users:permissions：定义哪些用户或用户组可以访问存储的文件及其对应的权限。格式为 user:permissions 或 group:permissions 或 all:permissions。

案例

基本用法

最简单的 scgi_store_access 用法是指定文件的访问权限：

http { server { listen 80; server_name example ; location /store_example/ { # 设置存储文件的访问权限为用户可读写，组可读，其他不可访问 scgi_store_access user:rw group:r; # 其他配置 scgi_store on; scgi_store_path /path/to/store; scgi_pass unix:/tmp/fastcgi.socket; } } }

在这个例子中：

当用户访问 /store_example/ 路径时，Nginx 将存储通过 SCGI 请求生成的文件，并设置文件的访问权限为用户可读写（rw），组可读（r），其他不可访问。

注意事项

权限管理：确保正确设置文件权限，以避免不必要的安全风险。兼容性：根据操作系统和文件系统的要求调整权限设置。 scgi_temp_file_write_size

scgi_temp_file_write_size 指令用于设置临时文件每次写入的最大数据量。这有助于优化大文件处理时的内存使用和性能。

Syntax: scgi_temp_file_write_size size; Default: scgi_temp_file_write_size 8k|16k; Context: http, server, location size：每次写入临时文件的最大数据量，单位为字节（bytes）。默认值通常为 8 KB 或 16 KB。

案例

基本用法

最简单的 scgi_temp_file_write_size 用法是指定每次写入临时文件的最大数据量：

http { server { listen 80; server_name example ; location /temp_file_example/ { # 设置每次写入临时文件的最大数据量为 32 KB scgi_temp_file_write_size 32768; # 32 * 1024 bytes # 其他配置 scgi_pass unix:/tmp/fastcgi.socket; } } }

在这个例子中：

当用户访问 /temp_file_example/ 路径时，Nginx 将每次写入临时文件的最大数据量设置为 32 KB。

注意事项

性能优化：合理设置写入大小，以平衡内存使用和磁盘 I/O 性能。大文件处理：对于处理大文件的情况，适当增加写入大小可以提高性能。 scgi_temp_path

scgi_temp_path 指令用于设置存储临时文件的路径及目录层次结构。这有助于管理和优化临时文件的存储。

Syntax: scgi_temp_path path [level1 [level2 [level3]]]; Default: scgi_temp_path scgi_temp; Context: http, server, location path：临时文件存储的根路径。level1、level2、level3：可选参数，指定临时文件存储的子目录层次结构。每个层次的值表示子目录名称的长度。

案例

基本用法

最简单的 scgi_temp_path 用法是指定临时文件的存储路径：

http { server { listen 80; server_name example ; location /temp_path_example/ { # 设置临时文件的存储路径为 /var/tmp/nginx/scgi_temp scgi_temp_path /var/tmp/nginx/scgi_temp; # 其他配置 scgi_pass unix:/tmp/fastcgi.socket; } } }

在这个例子中：

当用户访问 /temp_path_example/ 路径时，Nginx 将临时文件存储在 /var/tmp/nginx/scgi_temp 目录下。

使用多层目录结构

你可以设置多层目录结构来优化临时文件的存储：

http { server { listen 80; server_name example ; location /multi_level_temp_path/ { # 设置临时文件的存储路径为 /var/tmp/nginx/scgi_temp，并使用两层子目录结构 scgi_temp_path /var/tmp/nginx/scgi_temp 1 2; # 其他配置 scgi_pass unix:/tmp/fastcgi.socket; } } }

在这个例子中：

当用户访问 /multi_level_temp_path/ 路径时，Nginx 将临时文件存储在 /var/tmp/nginx/scgi_temp 目录下，并使用两层子目录结构。第一层子目录名称长度为 1 字符，第二层子目录名称长度为 2 字符。

注意事项

目录管理：合理设置目录层次结构，以避免单个目录下的文件过多导致性能下降。存储空间：确保有足够的存储空间来存放临时文件。 2.7 ngx_http_secure_link_module

ngx_http_secure_link_module 是 Nginx 的一个模块，用于提供安全链接验证功能。这个模块允许你生成带有签名的 URL，确保这些 URL 在特定的时间段内有效，并且只能被预期的用户访问。这对于保护敏感资源（如视频、图片等）非常有用。

主要功能

时间限制：通过签名包含的时间戳，可以设置资源的有效期。访问控制：通过签名验证，确保只有拥有正确密钥的用户才能访问资源。防盗链：防止未经授权的用户直接链接到资源。

常用指令

以下是与 ngx_http_secure_link_module 模块相关的常用配置指令及其简要说明：

secure_link：从请求参数中提取签名和时间戳，并进行验证。secure_link_md5：指定用于生成签名的密钥和算法。secure_link_secret：指定用于生成签名的密钥（旧版本使用）。

使用示例

以下是一些具体的配置示例，展示如何利用 ngx_http_secure_link_module 来实现安全链接验证。

基本配置 - 生成和验证签名

假设你想为某个资源生成带有签名的 URL，并在 Nginx 中验证该签名：

生成签名：你可以使用任何编程语言来生成签名。以下是一个简单的 Python 示例，用于生成签名和时间戳：

import time import hashlib # 密钥 secret = "your_secret_key" # 资源路径 uri = "/protected/resource.jpg" # 当前时间戳（秒） expire_time = int(time.time()) + 3600 # 签名有效期为1小时 # 生成签名 signature = hashlib.md5(f"{expire_time}{uri}{secret}".encode()).hexdigest() # 输出带签名的URL print(f"http://example {uri}?st={signature}&e={expire_time}")

Nginx 配置：在 Nginx 中配置 ngx_http_secure_link_module 来验证签名：

server { listen 80; server_name example ; location /protected/ { secure_link $arg_st,$arg_e; secure_link_md5 "your_secret_key$secure_link_expires$uri"; if ($secure_link = "") { return 403; # 如果签名无效或缺失，返回403错误 } if ($secure_link = "0") { return 410; # 如果签名已过期，返回410 Gone错误 } root /var/ /example /protected; } }

在这个例子中：

secure_link $arg_st,$arg_e; 提取请求参数中的签名 (st) 和时间戳 (e)。secure_link_md5 "your_secret_key$secure_link_expires$uri"; 指定用于生成签名的密钥和格式。if ($secure_link = "") { return 403; } 检查签名是否有效，如果无效或缺失则返回 403 错误。if ($secure_link = "0") { return 410; } 检查签名是否过期，如果过期则返回 410 Gone 错误。

配置重定向

如果你希望在检测到签名无效或过期时将请求重定向到另一个页面（例如一个提示页面），可以使用 rewrite 指令：

server { listen 80; server_name example ; location /protected/ { secure_link $arg_st,$arg_e; secure_link_md5 "your_secret_key$secure_link_expires$uri"; if ($secure_link = "") { rewrite ^ /error/invalid-signature.html break; } if ($secure_link = "0") { rewrite ^ /error/expired-link.html break; } root /var/ /example /protected; } }

在这个例子中：

当检测到签名无效时，使用 rewrite 指令将请求重定向到 /error/invalid-signature.html 页面。当检测到签名过期时，使用 rewrite 指令将请求重定向到 /error/expired-link.html 页面。

组合多个条件

你可以组合多个条件来进一步细化安全策略。例如，根据不同的条件执行不同的操作：

server { listen 80; server_name example ; location /protected/ { secure_link $arg_st,$arg_e; secure_link_md5 "your_secret_key$secure_link_expires$uri"; if ($secure_link = "") { return 403; # 签名无效或缺失 } if ($secure_link = "0") { return 410; # 签名已过期 } if ($request_method = POST) { return 405; # 不允许POST请求 } root /var/ /example /protected; } }

在这个例子中：

检查签名是否有效或过期，并返回相应的 HTTP 状态码。禁止使用 POST 请求访问受保护的资源。

注意事项

安全性：

确保密钥的安全性，避免泄露。建议定期更换密钥。确保生成签名的逻辑与 Nginx 配置一致，以避免验证失败。

性能考虑：

使用 if 指令可能会影响性能，尤其是在高并发场景下。尽量简化条件判断，避免复杂的嵌套逻辑。

日志记录：

合理配置日志级别和格式，便于监控和故障排查。特别是注意记录与签名验证相关的错误信息和访问情况。 2.7.1 指令列表 secure_link

secure_link 指令用于实现安全链接机制，防止未经授权的访问。它通过生成和验证加密签名来保护资源的安全性。

Syntax: secure_link expression; Default: — Context: http, server, location expression：一个表达式，用于生成或验证加密签名。通常与 secure_link_md5 或 secure_link_expires 等指令一起使用。

案例

基本用法

最简单的 secure_link 用法是结合 secure_link_md5 实现加密签名验证：

http { server { listen 80; server_name example ; location /secure_content/ { # 定义加密签名的密钥 secure_link_secret "my_secret_key"; # 验证加密签名 secure_link $arg_md5,$arg_expires; if ($secure_link = "") { return 403; } if ($secure_link = "0") { return 410; } # 其他配置 alias /path/to/secure/content; } } }

在这个例子中：

用户请求 /secure_content/ 路径时，必须提供 md5 和 expires 参数。Nginx 将使用 secure_link_secret 中的密钥验证签名的有效性和过期时间。

结合过期时间

你可以结合 secure_link_expires 实现带过期时间的加密签名：

http { server { listen 80; server_name example ; location /secure_with_expiry/ { # 定义加密签名的密钥 secure_link_secret "my_secret_key"; # 验证加密签名和过期时间 secure_link $arg_md5,$arg_expires; if ($secure_link = "") { return 403; } if ($secure_link = "0") { return 410; } # 其他配置 alias /path/to/secure/content; } } }

在这个例子中：

用户请求 /secure_with_expiry/ 路径时，必须提供 md5 和 expires 参数。Nginx 将验证签名的有效性和过期时间。如果签名无效或已过期，将返回相应的错误代码。

注意事项

安全性：确保使用的密钥足够复杂且妥善保管，以防止未经授权的访问。签名生成：客户端需要生成正确的签名并附加到请求中。确保生成签名的逻辑正确无误。 secure_link_md5

secure_link_md5 用于指定一个表达式，该表达式的结果将与请求中的签名进行比较，以验证请求的合法性。这有助于保护资源不被未经授权的访问。

Syntax: secure_link_md5 expression; Default: — Context: http, server, location expression：指定一个表达式，其结果将用于生成 MD5 哈希值并与请求中的签名进行比较。

案例

基本用法

最简单的 secure_link_md5 用法是指定一个表达式来生成 MD5 哈希值：

server { listen 80; server_name example ; location /protected/ { secure_link $arg_md5,$arg_expires; secure_link_md5 "$secure_link_expires$uri$remote_addr my_secret"; if ($secure_link = "") { return 403; # 签名无效或过期 } if ($secure_link = "0") { return 410; # 签名已过期 } # 如果签名有效，继续处理请求 } }

在这个例子中，secure_link_md5 表达式使用了 $secure_link_expires（过期时间）、$uri（请求的 URI）和 $remote_addr（客户端 IP 地址），并附加了一个密钥 my_secret 来生成 MD5 哈希值。

注意事项

安全性：确保使用的密钥保密且复杂度足够高，避免被轻易猜测。灵活性：可以根据实际需求调整表达式的内容，增加更多的参数或条件。 secure_link_secret

secure_link_secret 用于指定一个静态密钥，该密钥将与请求中的签名进行比较，以验证请求的合法性。它提供了一种简单的方式来实现安全链接保护。

Syntax: secure_link_secret word; Default: — Context: location word：指定一个静态密钥字符串。

案例

基本用法

最简单的 secure_link_secret 用法是指定一个静态密钥：

server { listen 80; server_name example ; location /protected/ { secure_link $arg_md5,$arg_expires; secure_link_secret my_static_secret; if ($secure_link = "") { return 403; # 签名无效或过期 } if ($secure_link = "0") { return 410; # 签名已过期 } # 如果签名有效，继续处理请求 } }

在这个例子中，指定了一个静态密钥 my_static_secret，Nginx 将使用该密钥生成 MD5 哈希值并与请求中的签名进行比较。

注意事项

密钥管理：静态密钥虽然易于配置，但需要定期更新以保持安全性。应用场景：适用于简单的安全链接保护场景，对于更复杂的场景建议使用 secure_link_md5。 2.8 ngx_http_session_log_module

ngx_http_session_log_module 是 Nginx 的一个模块，用于记录 HTTP 会话（即多个 HTTP 请求的聚合）而不是单独的请求。这个模块可以帮助你更好地分析用户行为和服务器性能，因为它提供了更高层次的会话日志记录功能。

主要功能

会话日志记录：将一组相关的 HTTP 请求（会话）聚合在一起进行日志记录。灵活配置：可以根据客户端 IP 地址、User-Agent 等信息来映射请求到会话。自定义格式：支持自定义日志格式，并可以指定超时时间等参数。

示例配置

以下是一些具体的配置示例，展示了如何使用 ngx_http_session_log_module 来记录会话日志。

基本配置

假设你想记录 /media/ 路径下的所有请求，并根据客户端 IP 地址和 User-Agent 将这些请求聚合为会话：

http { # 配置会话日志区域 session_log_zone /var/log/nginx/session.log format=combined zone=one:1m timeout=30s md5=$binary_remote_addr$http_user_agent; server { listen 80; server_name example ; location /media/ { # 启用会话日志 session_log one; } location / { root /var/ /html; index index.html index.htm; } } }

在这个例子中：

session_log_zone /var/log/nginx/session.log format=combined zone=one:1m timeout=30s md5=$binary_remote_addr$http_user_agent; 定义了一个会话日志区域，设置日志文件路径、共享内存区域名称、超时时间和计算 MD5 值的字符串。location /media/ { session_log one; } 启用了会话日志，并引用了之前定义的共享内存区域名称 one。

自定义日志格式

你可以自定义日志格式，以便记录更多有用的信息：

http { # 配置会话日志区域 session_log_zone /var/log/nginx/session.log format=my_custom zone=one:1m timeout=30s md5=$binary_remote_addr$http_user_agent; # 定义自定义日志格式 session_log_format my_custom '$remote_addr - $remote_user [$time_local] "$request" ' '$status $body_bytes_sent "$http_referer" ' '"$http_user_agent" "$session_log_id"'; server { listen 80; server_name example ; location /media/ { # 启用会话日志 session_log one; } location / { root /var/ /html; index index.html index.htm; } } }

在这个例子中：

session_log_format my_custom '...' 定义了一个自定义的日志格式，包含了客户端 IP 地址、用户名、请求时间、请求方法、状态码、发送字节数、来源页面、User-Agent 和会话 ID。session_log_zone ... format=my_custom ... 引用了自定义的日志格式 my_custom。

结合负载均衡

假设你的应用部署在多个后端服务器上，并希望通过会话日志来监控各个服务器的性能：

http { upstream backend { server backend1.example ; server backend2.example ; } # 配置会话日志区域 session_log_zone /var/log/nginx/session.log format=combined zone=one:1m timeout=30s md5=$binary_remote_addr$http_user_agent; server { listen 80; server_name example ; location /media/ { # 启用会话日志 session_log one; # 反向代理到后端服务器 proxy_pass http://backend; } location / { root /var/ /html; index index.html index.htm; } } }

在这个例子中：

upstream backend { ... } 定义了一个上游服务器组，包含两个后端服务器。location /media/ { session_log one; proxy_pass http://backend; } 启用了会话日志，并将请求反向代理到后端服务器组。

注意事项

日志文件管理：确保日志文件不会无限增长，建议定期轮转日志文件或使用日志轮转工具（如 logrotate）。性能影响：会话日志记录可能会带来一定的性能开销，特别是在高并发环境下。建议根据实际需求调整日志记录的频率和详细程度。安全性：确保日志文件的安全性，防止未经授权的访问。可以设置适当的文件权限，并考虑加密敏感数据。测试验证：在部署之前进行全面测试，确保所有配置按预期工作，并检查是否有任何潜在的问题（如日志未正确记录、格式错误等）。 2.8.1 指令列表 session_log

session_log 用于启用或禁用会话日志记录功能。这有助于记录用户会话信息，便于分析和调试。

Syntax: session_log name | off; Default: session_log off; Context: http, server, location name：指定日志文件的名称。off：禁用会话日志记录（默认行为）。

案例

基本用法

最简单的 session_log 用法是指定日志文件名称以启用会话日志记录：

http { session_log_format custom_session "..."; # 定义自定义会话日志格式 server { listen 80; server_name example ; location /logged_session/ { session_log custom_session.log; # 启用会话日志记录，并指定日志文件名称 session_log_format custom_session "..."; # 使用自定义的日志格式 } } }

在这个例子中，启用了会话日志记录，并指定了日志文件名称为 custom_session.log，同时使用了自定义的日志格式。

禁用会话日志记录

根据实际需求禁用会话日志记录：

server { listen 80; server_name example ; location /no_logging/ { session_log off; # 禁用会话日志记录 } }

在这个例子中，禁用了会话日志记录。

注意事项

性能影响：启用会话日志记录可能会对性能产生一定影响，特别是在高并发场景下。日志管理：确保合理管理日志文件，避免占用过多磁盘空间。 session_log_format

session_log_format 用于定义会话日志的格式。这有助于定制化记录会话信息的内容，便于后续分析和调试。

Syntax: session_log_format name string ...; Default: session_log_format combined "..."; Context: http name：指定日志格式的名称。string：指定日志格式的内容，可以包含变量和文本。

案例

基本用法

最简单的 session_log_format 用法是指定日志格式的内容：

http { session_log_format custom_session "$remote_addr - $remote_user [$time_local] \"$request\" $status $body_bytes_sent \"$http_referer\" \"$http_user_agent\""; server { listen 80; server_name example ; location /custom_session_logging/ { session_log custom_session.log; session_log_format custom_session "$remote_addr - $remote_user [$time_local] \"$request\" $status $body_bytes_sent \"$http_referer\" \"$http_user_agent\""; } } }

在这个例子中，定义了一个名为 custom_session 的日志格式，并在 /custom_session_logging/ 路径下启用了该日志格式。

自定义日志格式

根据实际需求自定义日志格式：

http { session_log_format detailed_session "$remote_addr - $remote_user [$time_local] \"$request\" $status $body_bytes_sent \"$http_referer\" \"$http_user_agent\" $upstream_response_time"; server { listen 80; server_name example ; location /detailed_logging/ { session_log detailed_session.log; session_log_format detailed_session "$remote_addr - $remote_user [$time_local] \"$request\" $status $body_bytes_sent \"$http_referer\" \"$http_user_agent\" $upstream_response_time"; } location /simple_logging/ { session_log simple_session.log; session_log_format simple_session "$remote_addr - $remote_user [$time_local] \"$request\" $status"; } } }

在这个例子中：

对于 /detailed_logging/ 路径下的请求，启用了详细的日志格式，包括上游响应时间。对于 /simple_logging/ 路径下的请求，启用了简单的日志格式，仅记录基本的请求信息。

注意事项

日志内容：根据实际需求选择合适的日志内容，确保既能满足分析需求，又不会过于冗长。性能优化：避免记录不必要的信息，减少日志文件大小和处理开销。 session_log_zone

session_log_zone 指令用于定义会话日志记录的共享内存区域。这个指令帮助配置会话日志记录的位置和行为。

Syntax: session_log_zone path zone=name:size [format=format] [timeout=time] [id=id] [md5=md5]; Default: — Context: http path：指定会话日志文件的存储路径。zone：必需参数，指定共享内存区域名称和大小。format：可选参数，指定日志格式，默认为预定义格式。timeout：可选参数，指定会话超时时间。id：可选参数，指定会话ID字段。md5：可选参数，指定是否使用MD5加密会话ID。

案例

基本用法

最简单的 session_log_zone 用法是指定一个具体的共享内存区域和路径：

http { session_log_zone /var/log/nginx/session_logs zone=session_log:10m; server { listen 80; server_name example ; location / { # 使用会话日志记录 session_log on; proxy_pass http://backend; } } }

在这个例子中：

设置了 session_log_zone /var/log/nginx/session_logs zone=session_log:10m，这意味着Nginx将使用 /var/log/nginx/session_logs 路径存储会话日志，并分配10MB的共享内存区域。

动态设置不同配置

你可以根据不同的需求动态设置不同的参数：

http { session_log_zone /var/log/nginx/fast_session_logs zone=fast_sessions:5m format=custom timeout=30m id=session_id md5=on; session_log_zone /var/log/nginx/slow_session_logs zone=slow_sessions:20m format=default timeout=60m; server { listen 80; server_name example ; location /fast/ { # 对快速响应的服务使用特定的日志格式和较短的超时时间 session_log fast_sessions; proxy_pass http://backend_fast; } location /slow/ { # 对慢速响应的服务使用默认的日志格式和较长的超时时间 session_log slow_sessions; proxy_pass http://backend_slow; } } }

在这个例子中：

对于 /fast/ 路径，设置了 session_log fast_sessions，适合快速响应的服务。对于 /slow/ 路径，设置了 session_log slow_sessions，适合慢速响应的服务。

注意事项

日志文件管理：确保有足够的磁盘空间来存放会话日志文件，并定期清理不再需要的文件以避免磁盘满的问题。适用场景：适用于需要记录和分析会话信息的应用场景。例如，在用户行为分析、安全审计等环境中使用。调试和监控：如果你遇到会话日志记录问题，可以检查以下几点： 确保日志记录设置合理，并符合你的需求。查看Nginx的日志文件，确认是否有与此相关的警告或错误信息。使用工具模拟不同负载条件下的请求进行测试，确保在各种情况下都能正常工作。 2.9 ngx_http_slice_module

ngx_http_slice_module 是 Nginx 的一个模块，用于将大文件分割成较小的片段（slice）进行传输。这种技术特别适用于大文件下载场景，如视频流、大文件分发等。通过将文件分割成小块，可以提高下载效率，并允许客户端并行下载多个片段，从而加快整体下载速度。

主要功能

文件切片：将大文件按指定大小分割成多个片段。并行下载：允许客户端同时请求多个片段，提高下载效率。缓存友好：每个片段都可以独立缓存，提高了缓存命中率。

使用示例

以下是一些具体的配置示例，展示了如何使用 ngx_http_slice_module 来实现文件切片和并行下载。

基本配置

假设你有一个大文件服务器，并希望将大文件分割成 1MB 的片段进行传输：

http { server { listen 80; server_name example ; location /downloads/ { # 启用切片功能，并设置每个片段的大小为 1MB slice 1m; # 设置代理到后端服务器 proxy_pass http://backend_server; # 配置代理缓冲区 proxy_buffer_size 4k; proxy_buffers 8 32k; proxy_busy_buffers_size 64k; # 设置代理头信息 proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; } } }

在这个例子中：

slice 1m; 启用了切片功能，并设置了每个片段的大小为 1MB。proxy_pass http://backend_server; 将请求代理到后端服务器。其他 proxy_* 指令用于配置代理缓冲区和头信息。

结合范围请求

为了支持范围请求（即客户端可以请求文件的部分内容），你可以这样配置：

http { server { listen 80; server_name example ; location /downloads/ { # 启用切片功能，并设置每个片段的大小为 1MB slice 1m; # 设置代理到后端服务器 proxy_pass http://backend_server; # 支持范围请求 proxy_set_header Range $http_range; proxy_set_header If-Range $http_if_range; # 处理范围响应 proxy_http_version 1.1; proxy_request_buffering off; # 配置代理缓冲区 proxy_buffer_size 4k; proxy_buffers 8 32k; proxy_busy_buffers_size 64k; # 设置代理头信息 proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; } } }

在这个例子中：

proxy_set_header Range $http_range; 和 proxy_set_header If-Range $http_if_range; 支持范围请求。proxy_http_version 1.1; 和 proxy_request_buffering off; 确保正确处理范围请求和响应。

缓存配置

为了提高性能，可以结合缓存机制来缓存每个片段：

http { proxy_cache_path /var/cache/nginx levels=1:2 keys_zone=my_cache:10m max_size=1g inactive=60m use_temp_path=off; server { listen 80; server_name example ; location /downloads/ { # 启用切片功能，并设置每个片段的大小为 1MB slice 1m; # 设置代理到后端服务器 proxy_pass http://backend_server; # 启用缓存 proxy_cache my_cache; proxy_cache_valid 200 302 10m; proxy_cache_valid 404 1m; # 配置代理缓冲区 proxy_buffer_size 4k; proxy_buffers 8 32k; proxy_busy_buffers_size 64k; # 设置代理头信息 proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; } } }

在这个例子中：

proxy_cache_path ... 定义了缓存路径和其他参数。proxy_cache my_cache; 启用了缓存，并指定了使用的缓存区域。proxy_cache_valid 200 302 10m; 和 proxy_cache_valid 404 1m; 设置了不同 HTTP 状态码的缓存有效期。

注意事项

片段大小选择：片段大小的选择应根据实际需求进行调整。过小的片段可能导致过多的请求开销，而过大的片段则可能无法充分利用并行下载的优势。缓存策略：合理配置缓存策略可以显著提高性能。确保每个片段都能独立缓存，并根据文件更新频率设置合适的缓存有效期。代理缓冲区：适当调整代理缓冲区的大小，以避免频繁的 I/O 操作。特别是在高并发环境下，合理的缓冲区配置尤为重要。测试验证：在部署之前进行全面测试，确保所有配置按预期工作，并检查是否有任何潜在的问题（如片段大小不正确、缓存未生效等）。 2.9.1 指令列表 slice

slice 指令用于启用HTTP范围请求的分片下载功能。这个指令帮助实现大文件的高效下载。

Syntax: slice size; Default: slice 0; Context: http, server, location size：指定每个分片的大小，默认为 0（禁用分片）。

案例

基本用法

最简单的 slice 用法是指定一个具体的分片大小：

server { listen 80; server_name example ; location /downloads/ { # 启用分片下载，每个分片大小为1MB slice 1m; proxy_pass http://backend; } }

在这个例子中：

设置了 slice 1m，这意味着Nginx将启用分片下载功能，并且每个分片的大小为1MB。

动态设置不同配置

你可以根据不同的需求动态设置不同的分片大小：

server { listen 80; server_name example ; location /small_files/ { # 对小文件启用较小的分片大小 slice 512k; proxy_pass http://backend_small_files; } location /large_files/ { # 对大文件启用较大的分片大小 slice 4m; proxy_pass http://backend_large_files; } }

在这个例子中：

对于 /small_files/ 路径，设置了 slice 512k，适合小文件下载。对于 /large_files/ 路径，设置了 slice 4m，适合大文件下载。

注意事项

性能与效率平衡：过小的分片可能导致过多的网络请求，而过大的分片可能导致资源浪费。根据实际需求选择合适的分片大小。适用场景：适用于需要支持大文件高效下载的应用场景。例如，在视频流媒体服务、软件下载站等环境中使用。调试和监控：如果你遇到分片下载问题，可以检查以下几点： 确保分片大小设置合理，并符合你的需求。查看Nginx的日志文件，确认是否有与此相关的警告或错误信息。使用工具模拟不同负载条件下的请求进行测试，确保在各种情况下都能正常工作。 2.10 ngx_http_split_clients_module

ngx_http_split_clients_module 是 Nginx 的一个标准模块，用于根据指定的条件将请求分配到不同的组（如不同的服务器或不同的配置）。这个模块通常用于 A/B 测试、灰度发布等场景，允许你基于某种规则（如用户 IP 地址、请求头等）来划分流量。

主要功能

流量分割：根据指定的条件将请求分配到不同的组。灵活的匹配规则：支持多种匹配方式，包括基于哈希值、IP 地址段、正则表达式等。动态配置：可以在运行时动态调整流量分配策略。

常用指令

以下是与 ngx_http_split_clients_module 模块相关的常用配置指令及其简要说明：

split_clients：定义流量分割规则。该指令通常在 http 上下文中使用，并且可以嵌套在其他指令中（如 map）。

$variable：生成一个变量，用于存储匹配结果。该变量可以在后续的配置中使用。

$request_variable：用于匹配的变量，例如 $remote_addr（客户端 IP 地址）、$http_user_agent（用户代理字符串）等。

使用示例

以下是一些具体的配置示例，展示如何利用 ngx_http_split_clients_module 来实现流量分割。

基本配置 - 根据 IP 地址分割流量

假设你想将 50% 的流量分配给一组服务器，另外 50% 的流量分配给另一组服务器，可以根据客户端 IP 地址进行分割：

http { # 定义 split_clients 规则 split_clients $remote_addr $group { 50% group_a; * group_b; } upstream group_a { server backend1.example :8080; server backend2.example :8080; } upstream group_b { server backend3.example :8080; server backend4.example :8080; } server { listen 80; server_name example ; location / { proxy_pass http://$group; } } }

在这个例子中：

split_clients $remote_addr $group { ... } 定义了一个流量分割规则： 50% 表示 50% 的流量会被分配给 group_a。* 表示剩余的流量（即另外 50%）会被分配给 group_b。 $remote_addr 是用于匹配的变量，表示客户端的 IP 地址。upstream group_a 和 upstream group_b 分别定义了两个后端服务器组。在 location / 中，proxy_pass http://$group; 根据 $group 变量的值选择相应的后端服务器组。

配置 - 根据用户代理字符串分割流量

如果你想根据用户的浏览器类型（通过 User-Agent 头部）来分割流量，可以这样做：

http { # 定义 split_clients 规则 split_clients $http_user_agent $group { "Chrome" group_chrome; "Firefox" group_firefox; * group_other; } upstream group_chrome { server chrome-backend.example :8080; } upstream group_firefox { server firefox-backend.example :8080; } upstream group_other { server other-backend.example :8080; } server { listen 80; server_name example ; location / { proxy_pass http://$group; } } }

在这个例子中：

split_clients $http_user_agent $group { ... } 定义了一个流量分割规则： "Chrome" 表示如果 User-Agent 包含 “Chrome”，流量会被分配给 group_chrome。"Firefox" 表示如果 User-Agent 包含 “Firefox”，流量会被分配给 group_firefox。* 表示所有其他情况下的流量会被分配给 group_other。 $http_user_agent 是用于匹配的变量，表示请求中的 User-Agent 头部。在 location / 中，proxy_pass http://$group; 根据 $group 变量的值选择相应的后端服务器组。

配置 - 使用哈希值分割流量

你可以使用哈希值来确保同一用户的请求总是被分配到同一个组中。这对于需要保持会话一致性的场景非常有用：

http { # 定义 split_clients 规则 split_clients "${remote_addr}AAA" $group { 50% group_a; * group_b; } upstream group_a { server backend1.example :8080; server backend2.example :8080; } upstream group_b { server backend3.example :8080; server backend4.example :8080; } server { listen 80; server_name example ; location / { proxy_pass http://$group; } } }

在这个例子中：

split_clients "${remote_addr}AAA" $group { ... } 使用 ${remote_addr}AAA 作为哈希源，确保同一 IP 地址的请求总是被分配到相同的组中。50% 和 * 分别表示 50% 的流量分配给 group_a 和 group_b。在 location / 中，proxy_pass http://$group; 根据 $group 变量的值选择相应的后端服务器组。

注意事项

一致性：使用哈希值时，确保哈希源的一致性，以避免同一用户的请求被分配到不同的组中。

性能考虑：尽量简化匹配规则，避免复杂的嵌套逻辑，尤其是在高并发场景下。

日志记录：合理配置日志级别和格式，便于监控和故障排查。特别是注意记录与流量分割相关的错误信息和访问情况。

2.10.1 指令列表 split_clients

split_clients 指令用于根据客户端请求字符串的不同值将请求分配到不同的变量值。这个指令帮助实现A/B测试、灰度发布等功能。

Syntax: split_clients string $variable { ... } Default: — Context: http string：指定用于分割的字符串。$variable：指定要设置的变量名称。{ ... }：包含分割规则和对应的变量值。

案例

基本用法

最简单的 split_clients 用法是指定一个具体的字符串和变量，并定义分割规则：

http { split_clients "${remote_addr}AAA" $variant { 0.5% variant_a; 99.5% variant_b; } server { listen 80; server_name example ; location / { # 根据客户端IP地址和固定字符串，将请求分配到不同的变体 if ($variant = "variant_a") { rewrite ^ /variant_a last; } if ($variant = "variant_b") { rewrite ^ /variant_b last; } } location /variant_a { proxy_pass http://backend_variant_a; } location /variant_b { proxy_pass http://backend_variant_b; } } }

在这个例子中：

设置了 split_clients "${remote_addr}AAA" $variant { 0.5% variant_a; 99.5% variant_b; }，这意味着Nginx将根据客户端IP地址和固定字符串 "AAA" 将请求分配到 $variant 变量，并且有0.5%的概率分配到 variant_a，99.5%的概率分配到 variant_b。

动态设置不同配置

你可以根据不同的需求动态设置不同的分割规则：

http { split_clients "${request_uri}BBB" $test_group { 10% group_1; 90% group_2; } server { listen 80; server_name example ; location / { # 根据请求URI和固定字符串，将请求分配到不同的测试组 if ($test_group = "group_1") { rewrite ^ /test_group_1 last; } if ($test_group = "group_2") { rewrite ^ /test_group_2 last; } } location /test_group_1 { proxy_pass http://backend_test_group_1; } location /test_group_2 { proxy_pass http://backend_test_group_2; } } }

在这个例子中：

设置了 split_clients "${request_uri}BBB" $test_group { 10% group_1; 90% group_2; }，这意味着Nginx将根据请求URI和固定字符串 "BBB" 将请求分配到 $test_group 变量，并且有10%的概率分配到 group_1，90%的概率分配到 group_2。

注意事项

公平性与准确性：确保分割规则能够公平地分配请求，并且满足你的测试或发布需求。适用场景：适用于需要实现A/B测试、灰度发布等功能的应用场景。例如，在新功能上线前的小规模测试、用户体验优化等环境中使用。调试和监控：如果你遇到分割规则问题，可以检查以下几点： 确保分割规则设置合理，并符合你的需求。查看Nginx的日志文件，确认是否有与此相关的警告或错误信息。使用工具模拟不同负载条件下的请求进行测试，确保在各种情况下都能正常工作。