nginx ngx_http_module(8) 指令详解

相关链接

一、目录

1.1 模块简介

ngx_http_ssi_module：服务器端包含（SSI）模块，允许在HTML页面中插入其他内容或动态生成的内容。通过特殊的SSI指令（如 ），可以在响应返回给客户端之前将指定文件的内容插入到页面中。
ngx_http_ssl_module：SSL/TLS支持模块，为Nginx提供加密连接的能力。它允许配置HTTPS服务，确保数据在客户端和服务器之间的传输是安全的。常用的配置指令包括 ssl_certificate 和 ssl_certificate_key 来指定证书和私钥文件。
ngx_http_stub_status_module：状态信息模块，提供Nginx的基本运行状态统计信息，如活跃连接数、请求处理情况等。通常通过访问特定URL（如 /nginx_status）来获取这些信息，便于监控和调试。
ngx_http_sub_module：替换响应内容模块，允许在响应返回给客户端之前对响应体进行文本替换操作。使用 sub_filter 指令可以指定需要替换的文本和替换后的文本，适用于简单的文本替换需求。
ngx_http_upstream_module：上游服务器模块，定义一组后端服务器，并控制如何将请求分发给这些服务器。支持多种负载均衡策略（如轮询、最少连接等），并提供了健康检查等功能。
ngx_http_upstream_conf_module：上游服务器配置模块，允许动态加载和修改上游服务器的配置。这对于需要频繁更新后端服务器列表或配置的应用场景非常有用。
ngx_http_upstream_hc_module：上游服务器健康检查模块，用于检测后端服务器的健康状态。可以根据设定的条件（如HTTP响应码、响应时间等）判断服务器是否可用，并自动从负载均衡池中移除不健康的服务器。
ngx_http_userid_module：用户标识模块，通过设置和读取cookie来跟踪用户的会话。它可以为每个用户分配一个唯一的标识符，并在后续请求中识别该用户，适用于需要用户追踪和分析的场景。

1.2 指令目录

1.2.48 ngx_http_ssi_module

ssi
ssi_last_modified
ssi_min_file_chunk
ssi_silent_errors
ssi_types
ssi_value_length

1.2.49 ngx_http_ssl_module

ssl
ssl_buffer_size
ssl_certificate
ssl_certificate_cache
ssl_certificate_key
ssl_ciphers
ssl_client_certificate
ssl_conf_command
ssl_crl
ssl_dhparam
ssl_early_data
ssl_ecdh_curve
ssl_key_log
ssl_ocsp
ssl_ocsp_cache
ssl_ocsp_responder
ssl_password_file
ssl_prefer_server_ciphers
ssl_protocols
ssl_reject_handshake
ssl_session_cache
ssl_session_ticket_key
ssl_session_tickets
ssl_session_timeout
ssl_stapling
ssl_stapling_file
ssl_stapling_responder
ssl_stapling_verify
ssl_trusted_certificate
ssl_verify_client
ssl_verify_depth

1.2.50 ngx_http_status_module

status
status_format
status_zone

1.2.51 ngx_http_stub_status_module

stub_status

1.2.52 ngx_http_sub_module

sub_filter
sub_filter_last_modified
sub_filter_once
sub_filter_types

1.2.53 ngx_http_upstream_module

upstream
server
zone
state
hash
ip_hash
keepalive
keepalive_requests
keepalive_time
keepalive_timeout
ntlm
least_conn
least_time
queue
random
resolver
resolver_timeout
sticky
sticky_cookie_insert

1.2.54 ngx_http_upstream_conf_module

upstream_conf

1.2.55 ngx_http_upstream_hc_module

health_check
match

1.2.56 ngx_http_userid_module

userid
userid_domain
userid_expires
userid_flags
userid_mark
userid_name
userid_p3p
userid_path
userid_service

二、解释

2.48 ngx_http_ssi_module

ngx_http_ssi_module 是 Nginx 的一个标准模块，用于支持服务器端包含（Server Side Includes, SSI）。SSI 是一种简单的模板系统，允许你将多个文件组合成一个页面，或者在页面中动态插入内容。这使得你可以更容易地维护和更新静态网页，而不需要每次都重新生成整个页面。

主要功能

文件包含：在 HTML 文件中通过 SSI 指令包含其他文件的内容。
变量处理：支持在 SSI 指令中使用环境变量、请求头和其他变量。
条件执行：根据条件选择性地包含或排除某些内容。
时间控制：显示当前时间或其他格式化的时间信息。

常用指令

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

ssi on | off：启用或禁用 SSI 处理，默认是关闭的。
ssi_types mime-type [mime-type ...]：指定哪些 MIME 类型的文件需要进行 SSI 处理，默认是 text/html。
ssi_silent_errors on | off：是否在发生错误时静默处理，默认是关闭的（即会输出错误信息）。
ssi_last_modified on | off：是否设置响应的 Last-Modified 头为最近修改的子文件的修改时间，默认是关闭的。

SSI 指令

SSI 指令通常嵌入在 HTML 文件中，并以  注释的形式出现。以下是一些常用的 SSI 指令：

include：包含另一个文件的内容。
- 语法： 或 
set：设置一个变量。
- 语法：
if：条件判断。
- 语法： ... 
echo：输出变量的值。
- 语法：
config：配置 SSI 输出的格式。
- 语法：

使用示例

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

基本配置

假设你想启用 SSI 并允许在 HTML 文件中包含其他文件的内容：

server {listen 80;server_name example.com;location / {# 启用 SSIssi on;# 设置处理的 MIME 类型ssi_types text/html;# 反向代理到后端服务器或直接提供静态文件root /var/www/html;}
}

在这个例子中：

ssi on; 启用了 SSI 处理。
ssi_types text/html; 指定了只有 MIME 类型为 text/html 的文件才会被处理。

包含文件

假设你有一个主页面 index.html，其中包含一些公共部分如头部和底部：

<!-- index.html -->
<!DOCTYPE html>
<html>
<head><title>My Website</title>
</head>
<body><!--# include file="header.html" --><h1>Welcome to My Website</h1><p>This is a paragraph of content.</p><!--# include file="footer.html" -->
</body>
</html>

同时，你有两个单独的文件 header.html 和 footer.html：

<!-- header.html -->
<header><nav><a href="/">Home</a><a href="/about">About</a><a href="/contact">Contact</a></nav>
</header>

<!-- footer.html -->
<footer><p>&copy; 2025 My Company. All rights reserved.</p>
</footer>

当用户访问 index.html 页面时，Nginx 会自动将 header.html 和 footer.html 的内容插入到相应的位置。

设置变量和条件判断

你可以使用 SSI 指令来设置变量并在页面中进行条件判断：

<!-- dynamic_page.html -->
<!DOCTYPE html>
<html>
<head><title>Dynamic Page</title>
</head>
<body><!--# set var="user" value="$HTTP_USER_AGENT" --><h1>Welcome!</h1><!--# if expr="${user} = /Chrome/" --><p>You are using Google Chrome.</p><!--# elif expr="${user} = /Firefox/" --><p>You are using Mozilla Firefox.</p><!--# else --><p>You are using another browser.</p><!--# endif -->
</body>
</html>

在这个例子中：

 设置了一个名为 user 的变量，其值为客户端的 User-Agent 字符串。
 根据 User-Agent 判断并输出不同的消息。

输出时间和格式化

你可以使用 config 和 echo 指令来输出当前时间和格式化时间信息：

<!-- current_time.html -->
<!DOCTYPE html>
<html>
<head><title>Current Time</title>
</head>
<body><!--# config timefmt="%Y-%m-%d %H:%M:%S" --><p>The current server time is: <!--# echo var="DATE_LOCAL" --></p>
</body>
</html>

在这个例子中：

 设置了时间格式。
 输出当前服务器时间。

错误处理

你可以通过设置 ssi_silent_errors 来控制在发生错误时的行为：

server {listen 80;server_name example.com;location / {ssi on;ssi_types text/html;ssi_silent_errors on;  # 静默处理错误，不输出错误信息root /var/www/html;}
}

在这个例子中：

ssi_silent_errors on; 设置了在发生 SSI 错误时静默处理，不会输出错误信息到客户端。

注意事项

性能考虑：
- 尽量减少 SSI 指令的数量和复杂度，避免对性能产生较大影响。
- 如果有大量动态内容，考虑使用更强大的模板引擎或后端服务来生成页面。
安全性：
- 确保包含的文件路径正确且安全，避免包含敏感文件或目录遍历攻击。
- 对用户输入的数据进行适当的验证和清理，防止注入攻击。
日志记录：
- 合理配置日志级别和格式，便于监控和故障排查。特别是注意记录 SSI 处理中的错误信息。

通过合理配置 ngx_http_ssi_module，你可以轻松地在静态页面中包含其他文件的内容，实现简单的动态功能。这对于构建易于维护和扩展的静态网站非常有用。

2.48.1 指令列表

ssi

ssi 指令用于启用或禁用服务器端包含（Server Side Includes）。SSI 允许在 HTML 文件中嵌入动态内容。

Syntax:	ssi on | off;
Default: ssi off;
Context: http, server, location, if in location

on：启用 SSI。
off：禁用 SSI，默认行为。

案例

基本用法

最简单的 ssi 用法是启用或禁用 SSI 功能：

http {server {listen 80;server_name example.com;location /ssi_example/ {# 启用 SSIssi on;# 其他配置root /var/www/html;}}
}

在这个例子中：

当用户访问 /ssi_example/ 路径时，Nginx 将启用 SSI 功能。HTML 文件中的 SSI 指令将被处理。

注意事项

文件扩展名：确保 Nginx 正确识别并处理需要使用 SSI 的文件类型（如 .shtml），通常需要配置正确的 MIME 类型。
性能考虑：SSI 处理会增加一定的计算开销，特别是在高流量网站上需要注意性能影响。

ssi_last_modified

ssi_last_modified 指令用于控制是否在响应头中添加 Last-Modified 字段。这有助于客户端缓存机制更好地工作。

Syntax:	ssi_last_modified on | off;
Default: ssi_last_modified off;
Context: http, server, location
This directive appeared in version 1.5.1.

on：在响应头中添加 Last-Modified 字段。
off：不在响应头中添加 Last-Modified 字段，默认行为。

案例

基本用法

最简单的 ssi_last_modified 用法是启用或禁用在响应头中添加 Last-Modified 字段：

http {server {listen 80;server_name example.com;location /last_modified_example/ {# 启用 SSIssi on;# 在响应头中添加 Last-Modified 字段ssi_last_modified on;# 其他配置root /var/www/html;}}
}

在这个例子中：

当用户访问 /last_modified_example/ 路径时，Nginx 将在响应头中添加 Last-Modified 字段，帮助客户端进行更有效的缓存管理。

注意事项

缓存机制：合理使用 Last-Modified 字段可以提高缓存效率，减少不必要的请求。
时间戳准确性：确保文件的时间戳准确无误，以避免缓存失效问题。

ssi_min_file_chunk

ssi_min_file_chunk 指令用于设置 SSI 包含的最小文件块大小。这有助于优化小文件的处理性能。

Syntax:	ssi_min_file_chunk size;
Default: ssi_min_file_chunk 1k;
Context: http, server, location

size：SSI 包含的最小文件块大小，单位为字节（bytes）。默认值为 1 KB。

案例

基本用法

最简单的 ssi_min_file_chunk 用法是指定 SSI 包含的最小文件块大小：

http {server {listen 80;server_name example.com;location /min_file_chunk_example/ {# 启用 SSIssi on;# 设置 SSI 包含的最小文件块大小为 2 KBssi_min_file_chunk 2048;  # 2 * 1024 bytes# 其他配置root /var/www/html;}}
}

在这个例子中：

当用户访问 /min_file_chunk_example/ 路径时，Nginx 将设置 SSI 包含的最小文件块大小为 2 KB。

注意事项

性能优化：适当调整最小文件块大小可以优化处理性能，特别是对于小文件较多的情况。
资源平衡：确保设置的大小不会导致过多的小文件处理开销。

ssi_silent_errors

ssi_silent_errors 指令用于控制是否在遇到 SSI 错误时不输出错误信息。这有助于提高用户体验和安全性。

Syntax:	ssi_silent_errors on | off;
Default: ssi_silent_errors off;
Context: http, server, location

on：在遇到 SSI 错误时不输出错误信息。
****off**：在遇到 SSI 错误时输出错误信息，默认行为。

案例

基本用法

最简单的 ssi_silent_errors 用法是启用或禁用在遇到 SSI 错误时不输出错误信息：

http {server {listen 80;server_name example.com;location /silent_errors_example/ {# 启用 SSIssi on;# 在遇到 SSI 错误时不输出错误信息ssi_silent_errors on;# 其他配置root /var/www/html;}}
}

在这个例子中：

当用户访问 /silent_errors_example/ 路径时，如果 SSI 遇到错误，Nginx 将不会输出错误信息，而是继续处理其他部分。

输出错误信息

你可以选择输出错误信息以便调试：

http {server {listen 80;server_name example.com;location /verbose_errors_example/ {# 启用 SSIssi on;# 在遇到 SSI 错误时输出错误信息ssi_silent_errors off;# 其他配置root /var/www/html;}}
}

在这个例子中：

当用户访问 /verbose_errors_example/ 路径时，如果 SSI 遇到错误，Nginx 将输出错误信息，方便调试和问题排查。

注意事项

用户体验：在生产环境中建议启用 ssi_silent_errors on，以避免向用户暴露敏感信息。
调试模式：在开发或调试阶段，可以选择输出错误信息以便快速定位和解决问题。

ssi_types

ssi_types 用于指定哪些 MIME 类型的文件可以使用服务器端包含（SSI, Server Side Includes）。这允许你控制哪些类型的文件在被请求时会进行 SSI 处理。

Syntax: ssi_types mime-type ...;
Default: ssi_types text/html;
Context: http, server, location

mime-type：指定一个或多个 MIME 类型，这些类型的文件将启用 SSI 处理。默认值为 text/html。

案例

基本用法

最简单的 ssi_types 用法是指定要启用 SSI 处理的 MIME 类型：

server {listen 80;server_name example.com;location / {ssi on;  # 启用 SSIssi_types text/html text/plain;  # 允许 text/html 和 text/plain 类型的文件进行 SSI 处理}
}

在这个例子中，除了默认的 text/html，还启用了 text/plain 类型的文件进行 SSI 处理。

扩展 MIME 类型

根据实际需求扩展支持的 MIME 类型：

server {listen 80;server_name example.com;location /ssi_content/ {ssi on;ssi_types text/html text/plain application/xhtml+xml;  # 支持多种 MIME 类型}location /html_only/ {ssi on;ssi_types text/html;  # 仅支持 HTML 文件}
}

在这个例子中：

对于 /ssi_content/ 路径下的请求，启用了 text/html、text/plain 和 application/xhtml+xml 类型的文件进行 SSI 处理。
对于 /html_only/ 路径下的请求，仅启用了 text/html 类型的文件进行 SSI 处理。

注意事项

性能影响：启用 SSI 处理可能会对性能产生一定影响，特别是在处理大量文件时。
文件类型：确保只对需要的文件类型启用 SSI 处理，避免不必要的开销。

ssi_value_length

ssi_value_length 用于设置 SSI 变量的最大长度。这有助于防止变量过长导致的问题，并控制内存使用。

Syntax: ssi_value_length length;
Default: ssi_value_length 256;
Context: http, server, location

length：指定 SSI 变量的最大长度，默认为 256 字节。

案例

基本用法

最简单的 ssi_value_length 用法是指定变量的最大长度：

server {listen 80;server_name example.com;location / {ssi on;ssi_value_length 512;  # 设置 SSI 变量的最大长度为 512 字节}
}

在这个例子中，设置了 ssi_value_length 512，这意味着 SSI 变量的最大长度为 512 字节。

调整变量长度

根据实际需求调整变量长度：

server {listen 80;server_name example.com;location /small_vars/ {ssi on;ssi_value_length 128;  # 设置较小的变量长度，适用于简单场景}location /large_vars/ {ssi on;ssi_value_length 1024;  # 设置较大的变量长度，适用于复杂场景}
}

在这个例子中：

对于 /small_vars/ 路径下的请求，设置了较小的变量长度（128 字节），适用于简单的 SSI 场景。
对于 /large_vars/ 路径下的请求，设置了较大的变量长度（1024 字节），适用于复杂的 SSI 场景。

注意事项

内存管理：合理设置变量长度，避免因变量过大导致内存溢出或其他问题。
应用需求：根据实际应用场景的需求调整变量长度，确保既能满足需求，又不会浪费资源。

2.49 ngx_http_ssl_module

ngx_http_ssl_module 是 Nginx 的一个核心模块，用于支持 HTTPS 协议。通过该模块，Nginx 可以处理 SSL/TLS 加密连接，确保客户端与服务器之间的通信安全。这个模块提供了多种配置选项，允许你设置证书、私钥、加密算法以及其他与 SSL/TLS 相关的参数。

主要功能

SSL/TLS 支持：启用和配置 SSL/TLS 加密连接。
证书管理：加载和验证服务器证书及私钥。
加密套件配置：选择和配置使用的加密套件，提高安全性。
会话缓存和重用：优化 SSL/TLS 连接性能，减少握手时间。

常用指令

ssl_certificate：指定服务器证书文件路径。
ssl_certificate_key：指定服务器私钥文件路径。
ssl_protocols：指定支持的 SSL/TLS 协议版本。
ssl_ciphers：指定支持的加密套件列表。
ssl_session_cache：配置 SSL 会话缓存，提高性能。
ssl_session_timeout：设置 SSL 会话超时时间。

使用示例

以下是一些简化的配置示例，展示了如何使用 ngx_http_ssl_module 来启用和配置 SSL/TLS。

基本 HTTPS 配置

假设你希望为你的网站启用 HTTPS：

server {listen 443 ssl;server_name example.com;# 指定服务器证书和私钥ssl_certificate /etc/nginx/ssl/example_com.crt;ssl_certificate_key /etc/nginx/ssl/example_com.key;# 指定支持的协议和加密套件ssl_protocols TLSv1.2 TLSv1.3;ssl_ciphers HIGH:!aNULL:!MD5;location / {root /var/www/html;index index.html index.htm;}
}

在这个例子中：

listen 443 ssl; 启用了 SSL/TLS 监听端口 443。
ssl_certificate 和 ssl_certificate_key 分别指定了服务器证书和私钥文件的路径。
ssl_protocols 和 ssl_ciphers 设置了支持的协议和加密套件。

启用会话缓存

为了提高 SSL/TLS 连接的性能，可以启用会话缓存：

server {listen 443 ssl;server_name example.com;ssl_certificate /etc/nginx/ssl/example_com.crt;ssl_certificate_key /etc/nginx/ssl/example_com.key;ssl_protocols TLSv1.2 TLSv1.3;ssl_ciphers HIGH:!aNULL:!MD5;# 配置 SSL 会话缓存ssl_session_cache shared:SSL:10m;ssl_session_timeout 10m;location / {root /var/www/html;index index.html index.htm;}
}

在这个例子中：

ssl_session_cache shared:SSL:10m; 启用了共享会话缓存，大小为 10MB。
ssl_session_timeout 10m; 设置了会话超时时间为 10 分钟。

强制重定向 HTTP 到 HTTPS

为了确保所有请求都通过 HTTPS 处理，可以配置 HTTP 请求自动重定向到 HTTPS：

server {listen 80;server_name example.com;# 强制重定向到 HTTPSreturn 301 https://$host$request_uri;
}server {listen 443 ssl;server_name example.com;ssl_certificate /etc/nginx/ssl/example_com.crt;ssl_certificate_key /etc/nginx/ssl/example_com.key;ssl_protocols TLSv1.2 TLSv1.3;ssl_ciphers HIGH:!aNULL:!MD5;ssl_session_cache shared:SSL:10m;ssl_session_timeout 10m;location / {root /var/www/html;index index.html index.htm;}
}

在这个例子中：

第一个 server 块监听 HTTP 端口 80，并将所有请求重定向到 HTTPS。
第二个 server 块监听 HTTPS 端口 443，并配置了 SSL/TLS 参数。

启用 OCSP Stapling

OCSP Stapling 可以提高 SSL/TLS 证书的验证效率，减少客户端与 CA 服务器之间的交互：

server {listen 443 ssl;server_name example.com;ssl_certificate /etc/nginx/ssl/example_com.crt;ssl_certificate_key /etc/nginx/ssl/example_com.key;ssl_protocols TLSv1.2 TLSv1.3;ssl_ciphers HIGH:!aNULL:!MD5;ssl_session_cache shared:SSL:10m;ssl_session_timeout 10m;# 启用 OCSP Staplingssl_stapling on;ssl_stapling_verify on;resolver 8.8.8.8 8.8.4.4 valid=300s;resolver_timeout 5s;location / {root /var/www/html;index index.html index.htm;}
}

在这个例子中：

ssl_stapling on; 启用了 OCSP Stapling。
ssl_stapling_verify on; 启用了 OCSP Stapling 的验证。
resolver 和 resolver_timeout 指令设置了 DNS 解析器和超时时间。

注意事项

证书和私钥的安全性：确保证书和私钥文件的安全存储，防止未经授权的访问。通常，这些文件应具有严格的权限设置（例如 600）并由 Web 服务器用户拥有。
```
chmod 600 /etc/nginx/ssl/example_com.crt
chmod 600 /etc/nginx/ssl/example_com.key
chown www-data:www-data /etc/nginx/ssl/example_com.crt
chown www-data:www-data /etc/nginx/ssl/example_com.key
```

加密套件的选择：选择合适的加密套件非常重要，既要保证安全性，也要考虑兼容性。推荐使用现代加密套件，并避免使用已知不安全的算法。

ssl_ciphers 'ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256';

SSL 会话缓存：合理配置 SSL 会话缓存可以显著提高性能，尤其是在高并发环境中。建议根据服务器资源和负载情况调整缓存大小和超时时间。
```
ssl_session_cache shared:SSL:10m;
ssl_session_timeout 10m;
```
日志记录：为了方便调试和监控，建议启用详细的日志记录，特别是在配置 SSL/TLS 时。
```
error_log /var/log/nginx/error.log warn;
access_log /var/log/nginx/access.log main;
```
测试配置：在生产环境中部署前，务必进行充分的测试，确保 SSL/TLS 配置正确无误。可以使用工具如 SSL Labs 来评估你的 SSL/TLS 配置。

2.49.1 指令列表

ssl

ssl 用于启用或禁用 SSL/TLS 加密。这有助于保护传输中的数据，防止中间人攻击和其他安全威胁。

Syntax: ssl on | off;
Default: ssl off;
Context: http, server

on：启用 SSL/TLS 加密。
off：禁用 SSL/TLS 加密（默认行为）。

案例

基本用法

最简单的 ssl 用法是启用或禁用 SSL/TLS 加密：

server {listen 443 ssl;server_name example.com;ssl_certificate /etc/nginx/ssl/example.com.crt;ssl_certificate_key /etc/nginx/ssl/example.com.key;ssl on;  # 启用 SSL/TLS 加密
}

在这个例子中，启用了 SSL/TLS 加密，并指定了证书和私钥的位置。

禁用 SSL

根据实际需求禁用 SSL/TLS 加密：

server {listen 80;server_name example.com;ssl off;  # 禁用 SSL/TLS 加密
}

在这个例子中，禁用了 SSL/TLS 加密。

注意事项

安全性：建议在生产环境中始终启用 SSL/TLS 加密，以确保数据传输的安全性。
配置细节：确保正确配置证书和私钥路径，以及其他相关 SSL 配置项，如 ssl_protocols 和 ssl_ciphers。

ssl_buffer_size

ssl_buffer_size 用于设置 SSL 缓冲区的大小。这有助于优化 SSL/TLS 数据传输的性能，平衡延迟和吞吐量。

Syntax: ssl_buffer_size size;
Default: ssl_buffer_size 16k;
Context: http, server
This directive appeared in version 1.5.9.

size：指定 SSL 缓冲区的大小，默认为 16KB。

案例

基本用法

最简单的 ssl_buffer_size 用法是指定缓冲区大小：

server {listen 443 ssl;server_name example.com;ssl_certificate /etc/nginx/ssl/example.com.crt;ssl_certificate_key /etc/nginx/ssl/example.com.key;ssl_buffer_size 8k;  # 设置 SSL 缓冲区大小为 8KB
}

在这个例子中，设置了 ssl_buffer_size 8k，这意味着 SSL 缓冲区的大小为 8KB。

调整缓冲区大小

根据实际需求调整缓冲区大小：

server {listen 443 ssl;server_name example.com;ssl_certificate /etc/nginx/ssl/example.com.crt;ssl_certificate_key /etc/nginx/ssl/example.com.key;location /low_latency/ {ssl_buffer_size 4k;  # 较小的缓冲区大小，适用于低延迟要求}location /high_throughput/ {ssl_buffer_size 32k;  # 较大的缓冲区大小，适用于高吞吐量要求}
}

在这个例子中：

对于 /low_latency/ 路径下的请求，设置了较小的缓冲区大小（4KB），适用于对低延迟有较高要求的场景。
对于 /high_throughput/ 路径下的请求，设置了较大的缓冲区大小（32KB），适用于对高吞吐量有较高要求的场景。

注意事项

性能优化：合理设置缓冲区大小，平衡延迟和吞吐量，确保最佳性能。
应用场景：根据具体的应用场景选择合适的缓冲区大小，例如实时通信应用可能需要较低的延迟，而大文件传输应用则可能需要更高的吞吐量。

ssl_certificate

ssl_certificate 指令用于指定SSL证书文件的路径。这个指令是配置HTTPS服务的关键部分。

Syntax:	ssl_certificate file;
Default:	—
Context:	http, server

file：指定SSL证书文件的路径。

案例

基本用法

最简单的 ssl_certificate 用法是指定一个具体的证书文件路径：

server {listen 443 ssl;server_name example.com;ssl_certificate /etc/nginx/ssl/example.com.crt;ssl_certificate_key /etc/nginx/ssl/example.com.key;location / {proxy_pass http://backend;}
}

在这个例子中：

设置了 ssl_certificate /etc/nginx/ssl/example.com.crt，这意味着Nginx将使用 /etc/nginx/ssl/example.com.crt 文件作为SSL证书。

动态设置不同配置

你可以根据不同的域名或服务器块动态设置不同的证书文件：

server {listen 443 ssl;server_name example1.com;ssl_certificate /etc/nginx/ssl/example1.com.crt;ssl_certificate_key /etc/nginx/ssl/example1.com.key;location / {proxy_pass http://backend_example1;}
}server {listen 443 ssl;server_name example2.com;ssl_certificate /etc/nginx/ssl/example2.com.crt;ssl_certificate_key /etc/nginx/ssl/example2.com.key;location / {proxy_pass http://backend_example2;}
}

在这个例子中：

对于 example1.com，设置了 ssl_certificate /etc/nginx/ssl/example1.com.crt。
对于 example2.com，设置了 ssl_certificate /etc/nginx/ssl/example2.com.crt。

注意事项

证书有效性：确保证书文件有效且未过期，并与域名匹配。
适用场景：适用于需要启用HTTPS服务的应用场景。例如，在电子商务网站、社交媒体平台等环境中使用。
调试和监控：如果你遇到证书问题，可以检查以下几点：
- 确保证书文件路径正确，并符合你的需求。
- 查看Nginx的日志文件，确认是否有与此相关的警告或错误信息。
- 使用工具（如SSL Labs SSL Test）验证证书的有效性和安全性。

ssl_certificate_cache

ssl_certificate_cache 指令用于控制SSL证书缓存的行为。这个指令帮助优化SSL握手过程中的性能。

Syntax:	ssl_certificate_cache off;
ssl_certificate_cache max=N [inactive=time] [valid=time];
Default:	ssl_certificate_cache off;
Context:	http, server
This directive appeared in version 1.27.4.

off：禁用证书缓存（默认值）。
max=N：指定缓存的最大条目数。
inactive=time：指定条目的非活动时间。
valid=time：指定条目的有效时间。

案例

基本用法

最简单的 ssl_certificate_cache 用法是指定是否启用证书缓存：

server {listen 443 ssl;server_name example.com;ssl_certificate /etc/nginx/ssl/example.com.crt;ssl_certificate_key /etc/nginx/ssl/example.com.key;# 启用证书缓存，最大条目数为1000，非活动时间为5分钟ssl_certificate_cache max=1000 inactive=5m;location / {proxy_pass http://backend;}
}

在这个例子中：

设置了 ssl_certificate_cache max=1000 inactive=5m，这意味着Nginx将启用证书缓存，最多缓存1000个条目，条目在5分钟内没有活动时将被移除。

动态设置不同配置

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

server {listen 443 ssl;server_name example1.com;ssl_certificate /etc/nginx/ssl/example1.com.crt;ssl_certificate_key /etc/nginx/ssl/example1.com.key;# 启用证书缓存，最大条目数为500，非活动时间为10分钟ssl_certificate_cache max=500 inactive=10m;location / {proxy_pass http://backend_example1;}
}server {listen 443 ssl;server_name example2.com;ssl_certificate /etc/nginx/ssl/example2.com.crt;ssl_certificate_key /etc/nginx/ssl/example2.com.key;# 启用证书缓存，最大条目数为2000，非活动时间为1小时ssl_certificate_cache max=2000 inactive=1h;location / {proxy_pass http://backend_example2;}
}

在这个例子中：

对于 example1.com，设置了 ssl_certificate_cache max=500 inactive=10m。
对于 example2.com，设置了 ssl_certificate_cache max=2000 inactive=1h。

注意事项

性能优化：合理设置缓存大小和非活动时间可以提高SSL握手的性能，但要注意内存占用。
适用场景：适用于需要优化SSL握手性能的应用场景。例如，在高并发网站、API网关等环境中使用。
调试和监控：如果你遇到证书缓存问题，可以检查以下几点：
- 确保缓存参数设置合理，并符合你的需求。
- 查看Nginx的日志文件，确认是否有与此相关的警告或错误信息。
- 使用工具模拟不同负载条件下的请求进行测试，确保在各种情况下都能正常工作。

ssl_certificate_key

ssl_certificate_key 指令用于指定SSL私钥文件的路径。这个指令是配置HTTPS服务的关键部分，必须与 ssl_certificate 一起使用。

Syntax:	ssl_certificate_key file;
Default:	—
Context:	http, server

file：指定SSL私钥文件的路径。

案例

基本用法

最简单的 ssl_certificate_key 用法是指定一个具体的私钥文件路径：

server {listen 443 ssl;server_name example.com;ssl_certificate /etc/nginx/ssl/example.com.crt;ssl_certificate_key /etc/nginx/ssl/example.com.key;location / {proxy_pass http://backend;}
}

在这个例子中：

设置了 ssl_certificate_key /etc/nginx/ssl/example.com.key，这意味着Nginx将使用 /etc/nginx/ssl/example.com.key 文件作为SSL私钥。

动态设置不同配置

你可以根据不同的域名或服务器块动态设置不同的私钥文件：

server {listen 443 ssl;server_name example1.com;ssl_certificate /etc/nginx/ssl/example1.com.crt;ssl_certificate_key /etc/nginx/ssl/example1.com.key;location / {proxy_pass http://backend_example1;}
}server {listen 443 ssl;server_name example2.com;ssl_certificate /etc/nginx/ssl/example2.com.crt;ssl_certificate_key /etc/nginx/ssl/example2.com.key;location / {proxy_pass http://backend_example2;}
}

在这个例子中：

对于 example1.com，设置了 ssl_certificate_key /etc/nginx/ssl/example1.com.key。
对于 example2.com，设置了 ssl_certificate_key /etc/nginx/ssl/example2.com.key。

注意事项

私钥安全性：确保私钥文件的安全性，避免泄露。
适用场景：适用于需要启用HTTPS服务的应用场景。例如，在电子商务网站、社交媒体平台等环境中使用。
调试和监控：如果你遇到私钥问题，可以检查以下几点：
- 确保私钥文件路径正确，并符合你的需求。
- 查看Nginx的日志文件，确认是否有与此相关的警告或错误信息。
- 使用工具（如OpenSSL命令行工具）验证私钥文件的有效性和完整性。

ssl_ciphers

ssl_ciphers 指令用于指定允许使用的加密套件列表。这个指令帮助增强SSL/TLS连接的安全性。

Syntax:	ssl_ciphers ciphers;
Default:	ssl_ciphers HIGH:!aNULL:!MD5;
Context:	http, server

ciphers：指定允许使用的加密套件列表。

案例

基本用法

最简单的 ssl_ciphers 用法是指定一个具体的加密套件列表：

server {listen 443 ssl;server_name example.com;ssl_certificate /etc/nginx/ssl/example.com.crt;ssl_certificate_key /etc/nginx/ssl/example.com.key;# 设置加密套件列表ssl_ciphers ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-AES256-GCM-SHA384;location / {proxy_pass http://backend;}
}

在这个例子中：

设置了 ssl_ciphers ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-AES256-GCM-SHA384，这意味着Nginx将仅使用这些加密套件。

动态设置不同配置

你可以根据不同的需求动态设置不同的加密套件列表：

server {listen 443 ssl;server_name example1.com;ssl_certificate /etc/nginx/ssl/example1.com.crt;ssl_certificate_key /etc/nginx/ssl/example1.com.key;# 设置较为严格的加密套件列表ssl_ciphers ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES128-GCM-SHA256;location / {proxy_pass http://backend_example1;}
}server {listen 443 ssl;server_name example2.com;ssl_certificate /etc/nginx/ssl/example2.com.crt;ssl_certificate_key /etc/nginx/ssl/example2.com.key;# 设置较为宽松的加密套件列表ssl_ciphers HIGH:!aNULL:!MD5;location / {proxy_pass http://backend_example2;}
}

在这个例子中：

对于 example1.com，设置了较为严格的加密套件列表。
对于 example2.com，设置了较为宽松的加密套件列表。

注意事项

安全性与兼容性平衡：过于严格的加密套件列表可能导致某些旧客户端无法连接，而过于宽松的列表可能降低安全性。根据实际需求选择合适的加密套件。
适用场景：适用于需要增强SSL/TLS连接安全性的应用场景。例如，在金融网站、政府机构网站等环境中使用。
调试和监控：如果你遇到加密套件问题，可以检查以下几点：
- 确保加密套件列表设置合理，并符合你的需求。
- 查看Nginx的日志文件，确认是否有与此相关的警告或错误信息。
- 使用工具（如SSL Labs SSL Test）验证加密套件的有效性和安全性。

ssl_client_certificate

ssl_client_certificate 指令用于指定客户端证书链文件，该文件包含 CA 证书，用于验证客户端提供的证书。

Syntax:	ssl_client_certificate file;
Default:	—
Context:	http, server

file：指定包含 CA 证书的文件路径。

案例

基本用法

最简单的 ssl_client_certificate 用法是指定一个包含 CA 证书的文件：

server {listen 443 ssl;server_name example.com;# 启用双向 SSL/TLS 认证ssl_client_certificate /etc/nginx/ssl/ca.crt;# 客户端证书和私钥ssl_certificate /etc/nginx/ssl/server.crt;ssl_certificate_key /etc/nginx/ssl/server.key;location /secure/ {proxy_pass http://backend.example.com;}
}

在这个例子中：

Nginx 将使用 /etc/nginx/ssl/ca.crt 文件中的 CA 证书来验证客户端提供的证书。

注意事项

安全性：确保 CA 证书文件的安全存储和管理，避免泄露敏感信息。
适用场景：适用于需要双向 SSL/TLS 认证的应用场景。例如，在安全的 API 服务中，可能需要验证客户端证书以确保通信的安全性。
调试和监控：如果你遇到客户端证书验证问题，可以检查以下几点：
- 确保证书文件路径正确且文件可访问。
- 查看Nginx的日志文件，确认是否有与此相关的警告或错误信息。

ssl_conf_command

ssl_conf_command 指令用于传递自定义的 OpenSSL 配置命令。

Syntax:	ssl_conf_command name value;
Default:	—
Context:	http, server
This directive appeared in version 1.19.4.

name：指定 OpenSSL 配置命令的名称。
value：指定配置命令的值。

案例

基本用法

最简单的 ssl_conf_command 用法是指定一个自定义的 OpenSSL 配置命令：

server {listen 443 ssl;server_name example.com;ssl_certificate /etc/nginx/ssl/server.crt;ssl_certificate_key /etc/nginx/ssl/server.key;# 自定义 OpenSSL 配置命令ssl_conf_command Options PrioritizeChaCha;location / {proxy_pass http://backend.example.com;}
}

在这个例子中：

使用了 Options PrioritizeChaCha 命令来优先选择 ChaCha20-Poly1305 加密套件。

多个自定义命令

你可以根据需要添加多个自定义命令：

server {listen 443 ssl;server_name example.com;ssl_certificate /etc/nginx/ssl/server.crt;ssl_certificate_key /etc/nginx/ssl/server.key;# 添加多个自定义 OpenSSL 配置命令ssl_conf_command Options PrioritizeChaCha;ssl_conf_command ECDHParameters secp384r1;location / {proxy_pass http://backend.example.com;}
}

在这个例子中：

使用了 Options PrioritizeChaCha 和 ECDHParameters secp384r1 两个自定义命令。

注意事项

高级配置：ssl_conf_command 提供了对 OpenSSL 的直接控制，适合有特定需求的高级用户。不正确的配置可能会导致兼容性问题或安全风险。
适用场景：适用于需要对加密套件或协议进行微调的应用场景。例如，在优化移动设备上的加密性能时，可能需要优先选择 ChaCha20-Poly1305 加密套件。
调试和监控：如果你遇到自定义命令问题，可以检查以下几点：
- 确保命令名称和值正确无误。
- 查看Nginx的日志文件，确认是否有与此相关的警告或错误信息。

ssl_crl

ssl_crl 指令用于指定证书吊销列表（CRL）文件，用于验证客户端证书的有效性。

Syntax:	ssl_crl file;
Default:	—
Context:	http, server
This directive appeared in version 0.8.7.

file：指定 CRL 文件的路径。

案例

基本用法

最简单的 ssl_crl 用法是指定一个包含 CRL 的文件：

server {listen 443 ssl;server_name example.com;# 启用双向 SSL/TLS 认证ssl_client_certificate /etc/nginx/ssl/ca.crt;ssl_verify_client on;# 指定 CRL 文件ssl_crl /etc/nginx/ssl/crl.pem;ssl_certificate /etc/nginx/ssl/server.crt;ssl_certificate_key /etc/nginx/ssl/server.key;location /secure/ {proxy_pass http://backend.example.com;}
}

在这个例子中：

Nginx 将使用 /etc/nginx/ssl/crl.pem 文件中的 CRL 来验证客户端提供的证书是否已被吊销。

注意事项

安全性：确保 CRL 文件的安全存储和管理，避免泄露敏感信息。
适用场景：适用于需要双向 SSL/TLS 认证并希望验证客户端证书有效性的应用场景。例如，在金融行业或高安全性要求的服务中，可能需要定期更新 CRL 文件以确保证书的有效性。
调试和监控：如果你遇到 CRL 文件问题，可以检查以下几点：
- 确保 CRL 文件路径正确且文件可访问。
- 查看Nginx的日志文件，确认是否有与此相关的警告或错误信息。

ssl_dhparam

ssl_dhparam 指令用于指定 Diffie-Hellman 参数文件，用于增强 SSL/TLS 连接的安全性。

Syntax:	ssl_dhparam file;
Default:	—
Context:	http, server
This directive appeared in version 0.7.2.

file：指定 DH 参数文件的路径。

案例

基本用法

最简单的 ssl_dhparam 用法是指定一个包含 DH 参数的文件：

server {listen 443 ssl;server_name example.com;ssl_certificate /etc/nginx/ssl/server.crt;ssl_certificate_key /etc/nginx/ssl/server.key;# 指定 DH 参数文件ssl_dhparam /etc/nginx/ssl/dhparam.pem;location / {proxy_pass http://backend.example.com;}
}

在这个例子中：

Nginx 将使用 /etc/nginx/ssl/dhparam.pem 文件中的 DH 参数来增强 SSL/TLS 连接的安全性。

生成 DH 参数文件

你可以使用 OpenSSL 生成一个 DH 参数文件：

openssl dhparam -out /etc/nginx/ssl/dhparam.pem 2048

注意事项

安全性：使用强 DH 参数可以显著提高 SSL/TLS 连接的安全性，特别是在前向保密（Forward Secrecy）方面。建议使用至少 2048 位的参数。
适用场景：适用于需要增强 SSL/TLS 连接安全性的应用场景。例如，在处理敏感数据或需要高安全性的服务中，建议使用 DH 参数文件。
调试和监控：如果你遇到 DH 参数文件问题，可以检查以下几点：
- 确保 DH 参数文件路径正确且文件可访问。
- 查看Nginx的日志文件，确认是否有与此相关的警告或错误信息。

ssl_early_data

ssl_early_data 指令用于控制是否启用TLS 1.3的早期数据（也称为0-RTT数据）功能。这对于减少TLS握手延迟非常有用，特别是在重复连接时。

Syntax:	ssl_early_data on | off;
Default:	ssl_early_data off;
Context:	http, server
This directive appeared in version 1.15.3.

on：启用TLS 1.3的早期数据功能。
off（默认）：禁用TLS 1.3的早期数据功能。

案例

启用早期数据

假设我们希望启用TLS 1.3的早期数据功能：

http {server {listen 443 ssl;server_name example.com;ssl_certificate /etc/nginx/ssl/example.crt;ssl_certificate_key /etc/nginx/ssl/example.key;ssl_early_data on;  # 启用TLS 1.3的早期数据功能}
}

禁用早期数据

如果我们希望禁用TLS 1.3的早期数据功能：

http {server {listen 443 ssl;server_name example.com;ssl_certificate /etc/nginx/ssl/example.crt;ssl_certificate_key /etc/nginx/ssl/example.key;ssl_early_data off;  # 默认行为，禁用TLS 1.3的早期数据功能}
}

注意事项

安全性：早期数据可能会带来重放攻击的风险，因此需要谨慎使用。
性能优化：启用早期数据可以减少握手时间，提高用户体验，但需要确保后端应用能够正确处理早期数据。

ssl_ecdh_curve

ssl_ecdh_curve 指令用于指定用于ECDH密钥交换的椭圆曲线。这对于选择合适的加密算法以增强安全性非常重要。

Syntax:	ssl_ecdh_curve curve;
Default:	ssl_ecdh_curve auto;
Context:	http, server
This directive appeared in versions 1.1.0 and 1.0.6.

curve：指定要使用的椭圆曲线名称，如 prime256v1、secp384r1 或 auto（自动选择）。

案例

基本用法

假设我们希望使用 prime256v1 曲线：

http {server {listen 443 ssl;server_name example.com;ssl_certificate /etc/nginx/ssl/example.crt;ssl_certificate_key /etc/nginx/ssl/example.key;ssl_ecdh_curve prime256v1;  # 使用 prime256v1 曲线}
}

使用自动选择

如果我们希望让Nginx自动选择合适的椭圆曲线：

http {server {listen 443 ssl;server_name example.com;ssl_certificate /etc/nginx/ssl/example.crt;ssl_certificate_key /etc/nginx/ssl/example.key;ssl_ecdh_curve auto;  # 自动选择椭圆曲线}
}

注意事项

安全性：选择高强度的椭圆曲线可以增强加密的安全性。
兼容性：确保所选椭圆曲线与客户端兼容，避免握手失败。

ssl_key_log

ssl_key_log 指令用于指定密钥日志文件的路径。这对于调试和分析TLS连接非常有用，尤其是在使用Wireshark等工具进行抓包分析时。

Syntax:	ssl_key_log path;
Default:	—
Context:	http, server
This directive appeared in version 1.27.2.

path：指定密钥日志文件的路径。

案例

基本用法

假设我们希望记录TLS连接的密钥信息到 /var/log/nginx/tls-key.log 文件：

http {server {listen 443 ssl;server_name example.com;ssl_certificate /etc/nginx/ssl/example.crt;ssl_certificate_key /etc/nginx/ssl/example.key;ssl_key_log /var/log/nginx/tls-key.log;  # 指定密钥日志文件路径}
}

注意事项

调试用途：密钥日志文件主要用于调试和分析目的，不应在生产环境中长期启用，以避免泄露敏感信息。
安全性：确保密钥日志文件的安全存储，避免未经授权的访问。

ssl_ocsp

ssl_ocsp 指令用于控制OCSP（在线证书状态协议）检查的行为。这对于验证服务器证书的状态，确保其未被吊销非常重要。

Syntax:	ssl_ocsp on | off | leaf;
Default:	ssl_ocsp off;
Context:	http, server
This directive appeared in version 1.19.0.

on：启用OCSP检查，并对整个证书链进行验证。
off（默认）：禁用OCSP检查。
leaf：仅对服务器证书进行OCSP检查，不包括中间证书。

案例

启用OCSP检查

假设我们希望启用OCSP检查，并对整个证书链进行验证：

http {server {listen 443 ssl;server_name example.com;ssl_certificate /etc/nginx/ssl/example.crt;ssl_certificate_key /etc/nginx/ssl/example.key;ssl_ocsp on;  # 启用OCSP检查，验证整个证书链}
}

仅对服务器证书进行OCSP检查

如果我们希望仅对服务器证书进行OCSP检查：

http {server {listen 443 ssl;server_name example.com;ssl_certificate /etc/nginx/ssl/example.crt;ssl_certificate_key /etc/nginx/ssl/example.key;ssl_ocsp leaf;  # 仅对服务器证书进行OCSP检查}
}

禁用OCSP检查

如果我们希望禁用OCSP检查：

http {server {listen 443 ssl;server_name example.com;ssl_certificate /etc/nginx/ssl/example.crt;ssl_certificate_key /etc/nginx/ssl/example.key;ssl_ocsp off;  # 默认行为，禁用OCSP检查}
}

注意事项

安全性：启用OCSP检查可以确保证书的有效性和未被吊销，提高安全性。
性能影响：OCSP检查可能会增加握手时间，特别是在OCSP响应服务器响应较慢时。

ssl_ocsp_cache

ssl_ocsp_cache 指令用于配置 OCSP（在线证书状态协议）响应缓存。这有助于减少对 OCSP 响应服务器的请求次数，提高性能和响应速度。

Syntax:	ssl_ocsp_cache off | [shared:name:size];
Default: ssl_ocsp_cache off;
Context: http, server
This directive appeared in version 1.19.0.

off：禁用 OCSP 缓存，默认行为。
[shared:name:size]：启用共享内存中的 OCSP 缓存。name 是缓存区的名称，size 是缓存区的大小（单位为字节）。

案例

基本用法

最简单的 ssl_ocsp_cache 用法是启用或禁用 OCSP 缓存：

http {server {listen 443 ssl;server_name example.com;ssl_certificate /etc/nginx/ssl/example.crt;ssl_certificate_key /etc/nginx/ssl/example.key;# 启用 OCSP 缓存ssl_ocsp_cache shared:ocsp_cache:10m;# 其他 SSL 配置ssl_protocols TLSv1.2 TLSv1.3;ssl_ciphers HIGH:!aNULL:!MD5;}
}

在这个例子中：

当用户访问 example.com 时，Nginx 将启用 OCSP 缓存，并使用名为 ocsp_cache 的共享内存区域，大小为 10 MB。

注意事项

性能优化：合理设置缓存大小以避免频繁请求 OCSP 响应服务器，但也要注意不要占用过多内存。
缓存失效：确保缓存策略能够及时更新，以反映最新的证书状态。

ssl_ocsp_responder

ssl_ocsp_responder 指令用于指定 OCSP 响应服务器的 URL。这允许 Nginx 直接查询指定的 OCSP 服务器来验证证书的状态。

Syntax:	ssl_ocsp_responder url;
Default: —
Context: http, server
This directive appeared in version 1.19.0.

url：OCSP 响应服务器的 URL。

案例

基本用法

最简单的 ssl_ocsp_responder 用法是指定 OCSP 响应服务器的 URL：

http {server {listen 443 ssl;server_name example.com;ssl_certificate /etc/nginx/ssl/example.crt;ssl_certificate_key /etc/nginx/ssl/example.key;# 指定 OCSP 响应服务器的 URLssl_ocsp_responder http://ocsp.example.com;# 其他 SSL 配置ssl_protocols TLSv1.2 TLSv1.3;ssl_ciphers HIGH:!aNULL:!MD5;}
}

在这个例子中：

当用户访问 example.com 时，Nginx 将直接查询 http://ocsp.example.com 来验证证书的状态。

注意事项

可用性：确保指定的 OCSP 响应服务器始终可用，以避免影响 HTTPS 连接的建立。
安全性：使用 HTTPS 协议来与 OCSP 响应服务器通信，以确保数据传输的安全性。

ssl_password_file

ssl_password_file 指令用于指定包含 SSL 私钥密码的文件路径。这使得 Nginx 能够自动解密受密码保护的私钥文件。

Syntax:	ssl_password_file file;
Default: —
Context: http, server
This directive appeared in version 1.7.3.

file：包含 SSL 私钥密码的文件路径。

案例

基本用法

最简单的 ssl_password_file 用法是指定包含 SSL 私钥密码的文件路径：

http {server {listen 443 ssl;server_name example.com;ssl_certificate /etc/nginx/ssl/example.crt;ssl_certificate_key /etc/nginx/ssl/example.key;# 指定包含 SSL 私钥密码的文件路径ssl_password_file /etc/nginx/ssl/passwords;# 其他 SSL 配置ssl_protocols TLSv1.2 TLSv1.3;ssl_ciphers HIGH:!aNULL:!MD5;}
}

在这个例子中：

当 Nginx 启动时，它将从 /etc/nginx/ssl/passwords 文件中读取私钥密码，并自动解密 example.key。

注意事项

安全性：确保密码文件具有严格的访问权限，防止未经授权的访问。
自动化管理：对于需要频繁重启的服务，考虑使用自动化工具来管理密码文件。

ssl_prefer_server_ciphers

ssl_prefer_server_ciphers 指令用于控制在 SSL/TLS 握手过程中是否优先使用服务器端定义的加密套件列表。这有助于增强安全性并确保最佳的加密算法选择。

Syntax:	ssl_prefer_server_ciphers on | off;
Default: ssl_prefer_server_ciphers off;
Context: http, server

on：优先使用服务器端定义的加密套件列表。
off：不优先使用服务器端定义的加密套件列表，默认行为。

案例

基本用法

最简单的 ssl_prefer_server_ciphers 用法是启用或禁用优先使用服务器端定义的加密套件列表：

http {server {listen 443 ssl;server_name example.com;ssl_certificate /etc/nginx/ssl/example.crt;ssl_certificate_key /etc/nginx/ssl/example.key;# 启用优先使用服务器端定义的加密套件列表ssl_prefer_server_ciphers on;# 定义加密套件列表ssl_ciphers HIGH:!aNULL:!MD5;# 其他 SSL 配置ssl_protocols TLSv1.2 TLSv1.3;}
}

在这个例子中：

当用户访问 example.com 时，Nginx 将优先使用服务器端定义的加密套件列表（如 HIGH:!aNULL:!MD5），而不是客户端提供的列表。

注意事项

安全性：优先使用服务器端定义的加密套件列表可以确保使用更安全的加密算法。
兼容性：某些旧客户端可能不支持服务器端定义的所有加密套件，需确保兼容性。

ssl_protocols

ssl_protocols 用于指定启用的 SSL/TLS 协议版本。这有助于确保只使用安全的协议版本，避免已知的安全漏洞。

Syntax: ssl_protocols [SSLv2] [SSLv3] [TLSv1] [TLSv1.1] [TLSv1.2] [TLSv1.3];
Default: ssl_protocols TLSv1.2 TLSv1.3;
Context: http, server

[SSLv2] [SSLv3] [TLSv1] [TLSv1.1] [TLSv1.2] [TLSv1.3]：指定要启用的 SSL/TLS 协议版本，默认启用 TLSv1.2 和 TLSv1.3。

案例

基本用法

最简单的 ssl_protocols 用法是指定要启用的协议版本：

server {listen 443 ssl;server_name example.com;ssl_certificate /etc/nginx/ssl/example.com.crt;ssl_certificate_key /etc/nginx/ssl/example.com.key;ssl_protocols TLSv1.2 TLSv1.3;  # 启用 TLSv1.2 和 TLSv1.3
}

在这个例子中，启用了 TLSv1.2 和 TLSv1.3，这是默认设置。

禁用旧协议

根据实际需求禁用不安全的协议版本：

server {listen 443 ssl;server_name example.com;ssl_certificate /etc/nginx/ssl/example.com.crt;ssl_certificate_key /etc/nginx/ssl/example.com.key;ssl_protocols TLSv1.3;  # 仅启用 TLSv1.3，禁用所有其他协议
}

在这个例子中，仅启用了 TLSv1.3，以确保更高的安全性。

注意事项

安全性：建议禁用不安全的协议版本（如 SSLv2, SSLv3, TLSv1, TLSv1.1），以防止中间人攻击和其他安全威胁。
兼容性：确保禁用的协议不会影响现有客户端的连接，特别是对于老旧客户端的支持。

ssl_reject_handshake

ssl_reject_handshake 用于控制是否在握手阶段立即拒绝连接。这有助于防止恶意连接尝试和资源浪费。

Syntax: ssl_reject_handshake on | off;
Default: ssl_reject_handshake off;
Context: http, server
This directive appeared in version 1.19.4.

on：在握手阶段立即拒绝连接。
off：正常进行握手过程（默认行为）。

案例

基本用法

最简单的 ssl_reject_handshake 用法是启用或禁用握手拒绝：

server {listen 443 ssl;server_name example.com;ssl_certificate /etc/nginx/ssl/example.com.crt;ssl_certificate_key /etc/nginx/ssl/example.com.key;ssl_reject_handshake on;  # 在握手阶段立即拒绝连接
}

在这个例子中，设置了 ssl_reject_handshake on，这意味着 Nginx 将在握手阶段立即拒绝连接。

动态拒绝握手

根据实际需求动态配置握手拒绝策略：

server {listen 443 ssl;server_name example.com;ssl_certificate /etc/nginx/ssl/example.com.crt;ssl_certificate_key /etc/nginx/ssl/example.com.key;location /reject_handshake/ {ssl_reject_handshake on;  # 对此路径下的请求立即拒绝握手}location /allow_handshake/ {ssl_reject_handshake off;  # 正常进行握手过程}
}

在这个例子中：

对于 /reject_handshake/ 路径下的请求，在握手阶段立即拒绝连接。
对于 /allow_handshake/ 路径下的请求，正常进行握手过程。

注意事项

安全性：适用于需要阻止特定请求的情况，例如防止恶意扫描或攻击。
性能优化：可以减少不必要的握手过程，提高服务器性能。

ssl_session_cache

ssl_session_cache 用于配置 SSL 会话缓存的类型和大小。这有助于提高 SSL/TLS 连接的性能，减少重复握手的开销。

Syntax: ssl_session_cache off | none | [builtin[:size]] [shared:name:size];
Default: ssl_session_cache none;
Context: http, server

off：禁用会话缓存。
none：不使用会话缓存（默认行为）。
builtin[:size]：使用内置缓存，可选指定大小。
shared:name:size：使用共享缓存，指定名称和大小。

案例

基本用法

最简单的 ssl_session_cache 用法是指定缓存类型和大小：

server {listen 443 ssl;server_name example.com;ssl_certificate /etc/nginx/ssl/example.com.crt;ssl_certificate_key /etc/nginx/ssl/example.com.key;ssl_session_cache shared:SSL:10m;  # 使用共享缓存，大小为 10MB
}

在这个例子中，使用了共享缓存 shared:SSL:10m，大小为 10MB。

组合缓存

根据实际需求组合使用不同类型的缓存：

server {listen 443 ssl;server_name example.com;ssl_certificate /etc/nginx/ssl/example.com.crt;ssl_certificate_key /etc/nginx/ssl/example.com.key;ssl_session_cache builtin:1000 shared:SSL:10m;  # 使用内置缓存和共享缓存
}

在这个例子中，同时使用了内置缓存 builtin:1000 和共享缓存 shared:SSL:10m。

注意事项

性能优化：合理配置缓存大小和类型，以平衡内存使用和性能提升。
应用场景：根据具体的应用场景选择合适的缓存策略，例如高并发场景下建议使用共享缓存。

ssl_session_ticket_key

ssl_session_ticket_key 用于指定用于加密和解密会话票据的密钥文件。这有助于支持会话恢复功能，提高 SSL/TLS 连接的效率。

Syntax: ssl_session_ticket_key file;
Default: —
Context: http, server
This directive appeared in version 1.5.7.

file：指定包含密钥的文件路径。

案例

基本用法

最简单的 ssl_session_ticket_key 用法是指定密钥文件路径：

server {listen 443 ssl;server_name example.com;ssl_certificate /etc/nginx/ssl/example.com.crt;ssl_certificate_key /etc/nginx/ssl/example.com.key;ssl_session_ticket_key /etc/nginx/ssl/session_ticket.key;  # 指定密钥文件路径
}

在这个例子中，指定了会话票据密钥文件路径 /etc/nginx/ssl/session_ticket.key。

生成密钥文件

根据实际需求生成密钥文件：

openssl rand 80 > /etc/nginx/ssl/session_ticket.key

然后在 Nginx 配置中引用该密钥文件：

server {listen 443 ssl;server_name example.com;ssl_certificate /etc/nginx/ssl/example.com.crt;ssl_certificate_key /etc/nginx/ssl/example.com.key;ssl_session_ticket_key /etc/nginx/ssl/session_ticket.key;  # 使用生成的密钥文件
}

注意事项

安全性：确保密钥文件的安全性，避免泄露和未经授权的访问。
会话恢复：支持会话恢复功能，减少重复握手的开销，提高性能。

ssl_session_tickets

ssl_session_tickets 指令用于控制是否启用TLS会话票据（Session Tickets）。这个指令帮助优化SSL/TLS握手过程中的性能。

Syntax:	ssl_session_tickets on | off;
Default:	ssl_session_tickets on;
Context:	http, server
This directive appeared in version 1.5.9.

on：启用TLS会话票据（默认值）。
off：禁用TLS会话票据。

案例

基本用法

最简单的 ssl_session_tickets 用法是指定是否启用会话票据：

server {listen 443 ssl;server_name example.com;ssl_certificate /etc/nginx/ssl/example.com.crt;ssl_certificate_key /etc/nginx/ssl/example.com.key;# 启用TLS会话票据ssl_session_tickets on;location / {proxy_pass http://backend;}
}

在这个例子中：

设置了 ssl_session_tickets on，这意味着Nginx将启用TLS会话票据以加速后续连接的建立。

动态设置不同配置

你可以根据不同的域名或服务器块动态设置是否启用会话票据：

server {listen 443 ssl;server_name example1.com;ssl_certificate /etc/nginx/ssl/example1.com.crt;ssl_certificate_key /etc/nginx/ssl/example1.com.key;# 对example1.com启用TLS会话票据ssl_session_tickets on;location / {proxy_pass http://backend_example1;}
}server {listen 443 ssl;server_name example2.com;ssl_certificate /etc/nginx/ssl/example2.com.crt;ssl_certificate_key /etc/nginx/ssl/example2.com.key;# 对example2.com禁用TLS会话票据ssl_session_tickets off;location / {proxy_pass http://backend_example2;}
}

在这个例子中：

对于 example1.com，设置了 ssl_session_tickets on。
对于 example2.com，设置了 ssl_session_tickets off。

注意事项

安全性与性能平衡：虽然会话票据可以提高性能，但在某些情况下可能会带来安全风险（如会话票据泄露）。根据实际需求选择是否启用。
适用场景：适用于需要优化SSL/TLS握手性能的应用场景。例如，在高并发网站、API网关等环境中使用。
调试和监控：如果你遇到会话票据问题，可以检查以下几点：
- 确保会话票据设置合理，并符合你的需求。
- 查看Nginx的日志文件，确认是否有与此相关的警告或错误信息。
- 使用工具模拟不同负载条件下的请求进行测试，确保在各种情况下都能正常工作。

ssl_session_timeout

ssl_session_timeout 指令用于指定SSL会话缓存的有效时间。这个指令帮助控制客户端和服务器之间的SSL会话保持的时间长度。

Syntax:	ssl_session_timeout time;
Default:	ssl_session_timeout 5m;
Context:	http, server

time：指定SSL会话缓存的有效时间，默认为 5m（5分钟）。

案例

基本用法

最简单的 ssl_session_timeout 用法是指定一个具体的有效时间：

server {listen 443 ssl;server_name example.com;ssl_certificate /etc/nginx/ssl/example.com.crt;ssl_certificate_key /etc/nginx/ssl/example.com.key;# 设置SSL会话缓存的有效时间为10分钟ssl_session_timeout 10m;location / {proxy_pass http://backend;}
}

在这个例子中：

设置了 ssl_session_timeout 10m，这意味着SSL会话缓存的有效时间为10分钟。

动态设置不同配置

你可以根据不同的域名或服务器块动态设置不同的有效时间：

server {listen 443 ssl;server_name example1.com;ssl_certificate /etc/nginx/ssl/example1.com.crt;ssl_certificate_key /etc/nginx/ssl/example1.com.key;# 对example1.com设置较短的有效时间ssl_session_timeout 5m;location / {proxy_pass http://backend_example1;}
}server {listen 443 ssl;server_name example2.com;ssl_certificate /etc/nginx/ssl/example2.com.crt;ssl_certificate_key /etc/nginx/ssl/example2.com.key;# 对example2.com设置较长的有效时间ssl_session_timeout 1h;location / {proxy_pass http://backend_example2;}
}

在这个例子中：

对于 example1.com，设置了 ssl_session_timeout 5m。
对于 example2.com，设置了 ssl_session_timeout 1h。

注意事项

性能与内存占用平衡：过长的有效时间可能导致内存占用增加，而过短的有效时间可能降低性能。根据实际需求选择合适的时间。
适用场景：适用于需要控制SSL会话缓存有效期的应用场景。例如，在高并发网站、API网关等环境中使用。
调试和监控：如果你遇到会话缓存问题，可以检查以下几点：
- 确保有效时间设置合理，并符合你的需求。
- 查看Nginx的日志文件，确认是否有与此相关的警告或错误信息。
- 使用工具模拟不同负载条件下的请求进行测试，确保在各种情况下都能正常工作。

ssl_stapling

ssl_stapling 指令用于控制是否启用OCSP（在线证书状态协议）装订。这个指令帮助增强SSL/TLS连接的安全性和隐私性。

Syntax:	ssl_stapling on | off;
Default:	ssl_stapling off;
Context:	http, server
This directive appeared in version 1.3.7.

on：启用OCSP装订。
off：禁用OCSP装订（默认值）。

案例

基本用法

最简单的 ssl_stapling 用法是指定是否启用OCSP装订：

server {listen 443 ssl;server_name example.com;ssl_certificate /etc/nginx/ssl/example.com.crt;ssl_certificate_key /etc/nginx/ssl/example.com.key;# 启用OCSP装订ssl_stapling on;ssl_trusted_certificate /etc/nginx/ssl/trusted_ca_certificates.pem;location / {proxy_pass http://backend;}
}

在这个例子中：

设置了 ssl_stapling on，这意味着Nginx将启用OCSP装订，并且需要指定一个受信任的CA证书文件。

动态设置不同配置

你可以根据不同的域名或服务器块动态设置是否启用OCSP装订：

server {listen 443 ssl;server_name example1.com;ssl_certificate /etc/nginx/ssl/example1.com.crt;ssl_certificate_key /etc/nginx/ssl/example1.com.key;# 对example1.com启用OCSP装订ssl_stapling on;ssl_trusted_certificate /etc/nginx/ssl/trusted_ca_certificates.pem;location / {proxy_pass http://backend_example1;}
}server {listen 443 ssl;server_name example2.com;ssl_certificate /etc/nginx/ssl/example2.com.crt;ssl_certificate_key /etc/nginx/ssl/example2.com.key;# 对example2.com禁用OCSP装订ssl_stapling off;location / {proxy_pass http://backend_example2;}
}

在这个例子中：

对于 example1.com，设置了 ssl_stapling on。
对于 example2.com，设置了 ssl_stapling off。

注意事项

安全性增强：OCSP装订可以减少客户端对CA服务器的直接访问，从而提高隐私性和响应速度。
适用场景：适用于需要增强SSL/TLS连接安全性和隐私性的应用场景。例如，在金融网站、政府机构网站等环境中使用。
调试和监控：如果你遇到OCSP装订问题，可以检查以下几点：
- 确保OCSP装订设置合理，并符合你的需求。
- 查看Nginx的日志文件，确认是否有与此相关的警告或错误信息。
- 使用工具（如SSL Labs SSL Test）验证OCSP装订的有效性和正确性。

ssl_stapling_file

ssl_stapling_file 指令用于指定OCSP响应文件的路径。这个指令通常与 ssl_stapling 一起使用，以便手动提供OCSP响应。

Syntax:	ssl_stapling_file file;
Default:	—
Context:	http, server
This directive appeared in version 1.3.7.

file：指定OCSP响应文件的路径。

案例

基本用法

最简单的 ssl_stapling_file 用法是指定一个具体的OCSP响应文件路径：

server {listen 443 ssl;server_name example.com;ssl_certificate /etc/nginx/ssl/example.com.crt;ssl_certificate_key /etc/nginx/ssl/example.com.key;# 启用OCSP装订并指定OCSP响应文件ssl_stapling on;ssl_stapling_file /etc/nginx/ssl/ocsp_response.der;ssl_trusted_certificate /etc/nginx/ssl/trusted_ca_certificates.pem;location / {proxy_pass http://backend;}
}

在这个例子中：

设置了 ssl_stapling_file /etc/nginx/ssl/ocsp_response.der，这意味着Nginx将使用 /etc/nginx/ssl/ocsp_response.der 文件作为OCSP响应。

动态设置不同配置

你可以根据不同的域名或服务器块动态设置不同的OCSP响应文件路径：

server {listen 443 ssl;server_name example1.com;ssl_certificate /etc/nginx/ssl/example1.com.crt;ssl_certificate_key /etc/nginx/ssl/example1.com.key;# 对example1.com启用OCSP装订并指定OCSP响应文件ssl_stapling on;ssl_stapling_file /etc/nginx/ssl/ocsp_response_example1.der;ssl_trusted_certificate /etc/nginx/ssl/trusted_ca_certificates.pem;location / {proxy_pass http://backend_example1;}
}server {listen 443 ssl;server_name example2.com;ssl_certificate /etc/nginx/ssl/example2.com.crt;ssl_certificate_key /etc/nginx/ssl/example2.com.key;# 对example2.com启用OCSP装订并指定不同的OCSP响应文件ssl_stapling on;ssl_stapling_file /etc/nginx/ssl/ocsp_response_example2.der;ssl_trusted_certificate /etc/nginx/ssl/trusted_ca_certificates.pem;location / {proxy_pass http://backend_example2;}
}

在这个例子中：

对于 example1.com，设置了 ssl_stapling_file /etc/nginx/ssl/ocsp_response_example1.der。
对于 example2.com，设置了 ssl_stapling_file /etc/nginx/ssl/ocsp_response_example2.der。

注意事项

手动管理：手动提供OCSP响应文件需要定期更新，确保其有效性。
适用场景：适用于需要手动管理OCSP响应的应用场景。例如，在无法自动获取OCSP响应或需要更高控制权的情况下使用。
调试和监控：如果你遇到OCSP响应文件问题，可以检查以下几点：
- 确保OCSP响应文件路径正确，并符合你的需求。
- 查看Nginx的日志文件，确认是否有与此相关的警告或错误信息。
- 使用工具（如OpenSSL命令行工具）验证OCSP响应文件的有效性和完整性。

ssl_stapling_responder

ssl_stapling_responder 指令用于指定 OCSP（在线证书状态协议）响应者的 URL。

Syntax:	ssl_stapling_responder url;
Default:	—
Context:	http, server
This directive appeared in version 1.3.7.

url：指定 OCSP 响应者的 URL。

案例

基本用法

最简单的 ssl_stapling_responder 用法是指定一个 OCSP 响应者的 URL：

server {listen 443 ssl;server_name example.com;ssl_certificate /etc/nginx/ssl/server.crt;ssl_certificate_key /etc/nginx/ssl/server.key;# 启用 OCSP 装订并指定响应者 URLssl_stapling on;ssl_stapling_responder http://ocsp.example.com;location / {proxy_pass http://backend.example.com;}
}

在这个例子中：

Nginx 将使用 http://ocsp.example.com 获取 OCSP 响应，并将其装订到 SSL/TLS 握手中。

注意事项

性能优化：启用 OCSP 装订可以减少客户端对 OCSP 服务器的直接查询，从而提高连接速度和安全性。
适用场景：适用于需要增强 SSL/TLS 连接安全性的应用场景。例如，在处理敏感数据或需要高安全性的服务中，建议使用 OCSP 装订。
调试和监控：如果你遇到 OCSP 装订问题，可以检查以下几点：
- 确保 OCSP 响应者的 URL 正确且可访问。
- 查看Nginx的日志文件，确认是否有与此相关的警告或错误信息。

ssl_stapling_verify

ssl_stapling_verify 指令用于控制是否验证 OCSP 响应的有效性。

Syntax:	ssl_stapling_verify on | off;
Default:	ssl_stapling_verify off;
Context:	http, server
This directive appeared in version 1.3.7.

on：启用 OCSP 响应的验证，默认值为 off。
off：禁用 OCSP 响应的验证。

案例

基本用法

最简单的 ssl_stapling_verify 用法是指定是否启用 OCSP 响应的验证：

server {listen 443 ssl;server_name example.com;ssl_certificate /etc/nginx/ssl/server.crt;ssl_certificate_key /etc/nginx/ssl/server.key;# 启用 OCSP 装订并验证响应ssl_stapling on;ssl_stapling_verify on;# 指定可信证书文件ssl_trusted_certificate /etc/nginx/ssl/trusted_ca.crt;location / {proxy_pass http://backend.example.com;}
}

在这个例子中：

启用了 OCSP 响应的验证，并指定了可信证书文件 /etc/nginx/ssl/trusted_ca.crt。

禁用验证

你可以选择禁用 OCSP 响应的验证：

server {listen 443 ssl;server_name example.com;ssl_certificate /etc/nginx/ssl/server.crt;ssl_certificate_key /etc/nginx/ssl/server.key;# 启用 OCSP 装订但不验证响应ssl_stapling on;ssl_stapling_verify off;location / {proxy_pass http://backend.example.com;}
}

在这个例子中：

启用了 OCSP 装订，但未启用响应验证。

注意事项

安全性：启用 OCSP 响应的验证可以确保收到的 OCSP 响应是有效的，从而进一步提高安全性。然而，这也可能导致额外的延迟。
适用场景：适用于需要增强 SSL/TLS 连接安全性的应用场景。例如，在处理敏感数据或需要高安全性的服务中，建议启用 OCSP 响应验证。
调试和监控：如果你遇到 OCSP 响应验证问题，可以检查以下几点：
- 确保可信证书文件路径正确且文件可访问。
- 查看Nginx的日志文件，确认是否有与此相关的警告或错误信息。

ssl_trusted_certificate

ssl_trusted_certificate 指令用于指定可信 CA 证书文件，用于验证 OCSP 响应的有效性。

Syntax:	ssl_trusted_certificate file;
Default:	—
Context:	http, server
This directive appeared in version 1.3.7.

file：指定包含可信 CA 证书的文件路径。

案例

基本用法

最简单的 ssl_trusted_certificate 用法是指定一个包含可信 CA 证书的文件：

server {listen 443 ssl;server_name example.com;ssl_certificate /etc/nginx/ssl/server.crt;ssl_certificate_key /etc/nginx/ssl/server.key;# 启用 OCSP 装订并验证响应ssl_stapling on;ssl_stapling_verify on;# 指定可信证书文件ssl_trusted_certificate /etc/nginx/ssl/trusted_ca.crt;location / {proxy_pass http://backend.example.com;}
}

在这个例子中：

使用 /etc/nginx/ssl/trusted_ca.crt 文件中的可信 CA 证书来验证 OCSP 响应的有效性。

注意事项

安全性：确保可信 CA 证书文件的安全存储和管理，避免泄露敏感信息。
适用场景：适用于需要验证 OCSP 响应有效性的应用场景。例如，在处理敏感数据或需要高安全性的服务中，建议使用可信 CA 证书文件来验证 OCSP 响应。
调试和监控：如果你遇到可信 CA 证书问题，可以检查以下几点：
- 确保证书文件路径正确且文件可访问。
- 查看Nginx的日志文件，确认是否有与此相关的警告或错误信息。

ssl_verify_client

ssl_verify_client 指令用于控制是否要求客户端提供证书进行验证。

Syntax:	ssl_verify_client on | off | optional | optional_no_ca;
Default:	ssl_verify_client off;
Context:	http, server

on：要求客户端提供证书并进行验证。
off：不要求客户端提供证书，默认值为 off。
optional：允许客户端提供证书但不强制要求。
optional_no_ca：允许客户端提供证书但不验证其有效性。

案例

基本用法

最简单的 ssl_verify_client 用法是指定是否要求客户端提供证书：

server {listen 443 ssl;server_name example.com;ssl_certificate /etc/nginx/ssl/server.crt;ssl_certificate_key /etc/nginx/ssl/server.key;# 启用双向认证并要求客户端提供证书ssl_verify_client on;# 指定 CA 证书文件ssl_client_certificate /etc/nginx/ssl/ca.crt;location /secure/ {proxy_pass http://backend.example.com;}
}

在这个例子中：

客户端必须提供证书并进行验证。

允许但不强制客户端提供证书

你可以允许但不强制客户端提供证书：

server {listen 443 ssl;server_name example.com;ssl_certificate /etc/nginx/ssl/server.crt;ssl_certificate_key /etc/nginx/ssl/server.key;# 允许客户端提供证书但不强制要求ssl_verify_client optional;# 指定 CA 证书文件ssl_client_certificate /etc/nginx/ssl/ca.crt;location /secure/ {proxy_pass http://backend.example.com;}
}

在这个例子中：

客户端可以选择提供证书，但不是必需的。

不验证客户端证书的有效性

你可以允许客户端提供证书但不验证其有效性：

server {listen 443 ssl;server_name example.com;ssl_certificate /etc/nginx/ssl/server.crt;ssl_certificate_key /etc/nginx/ssl/server.key;# 允许客户端提供证书但不验证其有效性ssl_verify_client optional_no_ca;# 指定 CA 证书文件ssl_client_certificate /etc/nginx/ssl/ca.crt;location /secure/ {proxy_pass http://backend.example.com;}
}

在这个例子中：

客户端可以选择提供证书，但不会验证其有效性。

注意事项

安全性：启用双向认证可以显著提高通信的安全性，特别是在需要验证客户端身份的情况下。然而，这也增加了配置的复杂性和维护成本。
适用场景：适用于需要双向 SSL/TLS 认证的应用场景。例如，在金融行业或高安全性要求的服务中，可能需要启用双向认证。
调试和监控：如果你遇到客户端证书验证问题，可以检查以下几点：
- 确保证书文件路径正确且文件可访问。
- 查看Nginx的日志文件，确认是否有与此相关的警告或错误信息。

ssl_verify_depth

ssl_verify_depth 指令用于指定在验证客户端证书时，Nginx将检查的证书链的最大深度。这对于确保客户端证书的有效性和信任链完整性非常重要。

Syntax:	ssl_verify_depth number;
Default:	ssl_verify_depth 1;
Context:	http, server

number：指定要检查的证书链的最大深度，默认值为1，表示仅验证客户端证书本身而不检查其上级证书。

案例

基本用法

假设我们希望验证客户端证书及其整个证书链（例如，最多检查3层）：

http {server {listen 443 ssl;server_name example.com;ssl_certificate /etc/nginx/ssl/example.crt;ssl_certificate_key /etc/nginx/ssl/example.key;ssl_client_certificate /etc/nginx/ssl/ca.crt;  # 客户端证书颁发机构ssl_verify_client on;  # 启用客户端证书验证ssl_verify_depth 3;  # 验证客户端证书及其整个证书链，最多检查3层}
}

使用默认值

如果我们只希望验证客户端证书本身：

http {server {listen 443 ssl;server_name example.com;ssl_certificate /etc/nginx/ssl/example.crt;ssl_certificate_key /etc/nginx/ssl/example.key;ssl_client_certificate /etc/nginx/ssl/ca.crt;  # 客户端证书颁发机构ssl_verify_client on;  # 启用客户端证书验证# 默认情况下，ssl_verify_depth 是1}
}

注意事项

安全性：适当设置验证深度以确保客户端证书的有效性，同时避免不必要的性能开销。
兼容性：确保服务器能够处理较长的证书链，特别是在使用复杂的PKI基础设施时。

2.50 ngx_http_status_module

ngx_http_status_module 是 Nginx 官方提供的一个模块，主要用于提供各种状态信息的访问。不过，这个模块在较早的商业订阅版本中可用，并且已经被 ngx_http_api_module 模块取代。

主要功能

当前活动连接数
请求总数
等待连接数
正在读取请求头的连接数
正在发送响应的连接数
空闲等待新请求的连接数

示例配置

以下是一个简单的配置示例，展示了如何启用并访问 ngx_http_status_module 提供的状态信息：

server {listen 80;server_name example.com;location /nginx_status {# 启用 stub_status 模块（类似于 ngx_http_status_module 的基本功能）stub_status;# 限制访问权限（可选）allow 127.0.0.1;  # 允许本地访问deny all;         # 拒绝其他所有IP访问}
}

访问 http://example.com/nginx_status 将返回类似如下的状态信息：

Active connections: 291 
server accepts handled requests363470 363470 1561980 
Reading: 0 Writing: 6 Waiting: 285

解释：

Active connections: 当前活跃的连接数。
accepts: 已接受的连接总数。
handled: 已处理的连接总数（通常等于 accepts）。
requests: 总请求数。
Reading: 正在读取客户端请求头的连接数。
Writing: 正在向客户端发送响应的连接数。
Waiting: 空闲客户端连接数（等待新请求）。

2.50.1 指令列表

status

status 指令用于启用和配置Nginx的状态页面，通常用于监控和调试目的。状态页面可以显示当前连接数、请求处理情况等信息。

Syntax:	status;
Default:	—
Context:	location

案例

基本用法

假设我们希望启用状态页面，并将其放置在 /status 路径下：

http {server {listen 80;server_name example.com;location /status {status;  # 启用状态页面}}
}

访问 http://example.com/status 将显示Nginx的状态信息。

注意事项

权限控制：建议对状态页面进行访问控制，以防止未经授权的访问。
监控工具：可以结合第三方监控工具使用状态页面数据，实现更全面的监控和报警功能。

status_format

status_format 指令用于指定状态页面输出的格式。这对于与不同的监控系统集成非常有用，可以根据需要选择JSON或JSONP格式。

Syntax:	status_format json;
status_format jsonp [callback];
Default:	status_format json;
Context:	http, server, location

json：输出JSON格式的数据。
jsonp [callback]：输出JSONP格式的数据，可选参数 callback 用于指定回调函数名称。

案例

输出JSON格式

假设我们希望状态页面输出JSON格式的数据：

http {server {listen 80;server_name example.com;location /status {status;status_format json;  # 输出JSON格式的数据}}
}

输出JSONP格式

如果我们希望状态页面输出JSONP格式的数据，并指定回调函数名称 myCallback：

http {server {listen 80;server_name example.com;location /status {status;status_format jsonp myCallback;  # 输出JSONP格式的数据，回调函数名为 myCallback}}
}

注意事项

跨域支持：JSONP格式常用于跨域请求，确保在需要跨域访问时使用。
灵活性：根据实际需求选择合适的输出格式，以便更好地与监控系统集成。

status_zone

status_zone 指令用于定义一个用于收集特定服务器块状态信息的共享内存区域。这对于监控和统计每个虚拟主机的性能指标非常有用。

Syntax:	status_zone zone;
Default:	—
Context:	server

zone：指定共享内存区域的名称。

案例

基本用法

假设我们希望为 example.com 定义一个名为 example_zone 的状态区域：

http {server {listen 80;server_name example.com;status_zone example_zone;  # 定义名为 example_zone 的状态区域}server {listen 80;server_name another-example.com;status_zone another_example_zone;  # 定义另一个状态区域}
}

注意事项

资源管理：合理分配共享内存区域大小，避免过度消耗系统资源。
监控工具：结合第三方监控工具使用状态区域数据，实现更详细的性能分析和优化。

2.51 ngx_http_stub_status_module

ngx_http_stub_status_module 是 Nginx 的一个标准模块，用于提供服务器状态的基本统计信息。通过这个模块，你可以获取当前 Nginx 服务器的连接数、请求数等关键性能指标，这对于监控和调试非常有用。

主要功能

基本统计信息：提供关于活跃连接、请求数、处理中的请求等的统计信息。
实时监控：可以配置为只允许特定 IP 地址访问，以保护敏感信息不被公开。

常用指令

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

stub_status：启用并配置状态页面。

使用示例

以下是一些具体的配置示例，展示如何利用 ngx_http_stub_status_module 来获取 Nginx 服务器的状态信息。

基本配置

假设你想在 /status 路径下启用状态页面，并限制只能从本地访问：

server {listen 80;server_name example.com;location /status {# 启用 stub_status 模块stub_status;# 仅允许来自 localhost 的访问allow 127.0.0.1;deny all;}
}

在这个例子中：

stub_status; 启用了状态页面。
allow 127.0.0.1; 和 deny all; 限制只有来自 localhost 的请求才能访问该页面，防止外部用户访问敏感信息。

访问状态页面

一旦配置完成，你可以通过访问 http://example.com/status 来查看 Nginx 服务器的状态信息。输出的内容将类似于以下格式：

Active connections: 291 
server accepts handled requests46309 46309 89328 
Reading: 6 Writing: 179 Waiting: 106

这些数据的具体含义如下：

Active connections：当前活跃的连接数。
accepts：Nginx 自启动以来接受的总连接数。
handled：Nginx 自启动以来成功处理的连接数（通常与 accepts 相同，除非达到系统资源限制）。
requests：Nginx 自启动以来处理的总请求数。
Reading：当前正在读取客户端请求头的连接数。
Writing：当前正在向客户端发送响应或正在写入客户端请求体的连接数。
Waiting：当前处于空闲等待状态的连接数（通常是保持连接的连接）。

结合认证进行安全访问

为了进一步提高安全性，你可以结合 HTTP 基本身份验证来限制对状态页面的访问：

server {listen 80;server_name example.com;location /status {# 启用 stub_status 模块stub_status;# 仅允许来自特定 IP 地址的访问allow 127.0.0.1;allow 192.168.1.0/24;  # 允许子网内的所有 IP 地址deny all;# 配置基本身份验证auth_basic "Restricted Access";auth_basic_user_file /etc/nginx/.htpasswd;}
}

在这个例子中：

auth_basic "Restricted Access"; 启用了基本身份验证，并设置了提示消息。
auth_basic_user_file /etc/nginx/.htpasswd; 指定了包含用户名和密码的文件路径。你可以使用工具如 htpasswd 来生成这个文件。

例如，生成 .htpasswd 文件的命令：

sudo htpasswd -c /etc/nginx/.htpasswd username

然后根据提示输入密码。

禁用状态页面缓存

为了避免状态页面被浏览器或其他代理缓存，你可以添加适当的响应头：

server {listen 80;server_name example.com;location /status {# 启用 stub_status 模块stub_status;# 禁用缓存add_header Cache-Control no-cache;add_header Pragma no-cache;expires off;# 仅允许来自特定 IP 地址的访问allow 127.0.0.1;deny all;}
}

在这个例子中：

add_header Cache-Control no-cache; 和 add_header Pragma no-cache; 设置了响应头，防止页面被缓存。
expires off; 确保页面不会被缓存。

注意事项

性能考虑：
- 状态页面提供的信息是实时的，但频繁访问可能会对性能产生一定影响。建议不要过于频繁地轮询状态页面。
安全性：
- 严格控制对状态页面的访问权限，避免敏感信息泄露。
- 如果启用了 HTTP 基本身份验证，确保 .htpasswd 文件的安全性，并定期更新密码。
日志记录：
- 可以配置访问日志，记录对状态页面的访问情况，便于后续审计和故障排查。

通过合理配置 ngx_http_stub_status_module，你可以轻松地获取 Nginx 服务器的关键性能指标，这对于监控和调试非常重要。这对于构建高可用性和高性能的应用系统非常有帮助。

2.51.1 指令列表

stub_status

stub_status 指令用于启用 Nginx 的状态页面，该页面提供了关于当前 Nginx 工作状态的统计信息。这对于监控和调试非常有用。

Syntax:	stub_status;
Default: —
Context: server, location

案例

基本用法

最简单的 stub_status 用法是在特定位置启用状态页面：

http {server {listen 80;server_name example.com;location /nginx_status {# 启用 stub_statusstub_status;# 限制访问（可选）allow 127.0.0.1;  # 允许本地访问deny all;         # 拒绝其他所有 IP 访问}}
}

在这个例子中：

当用户访问 http://example.com/nginx_status 时，Nginx 将返回一个包含当前工作状态统计信息的页面。例如：

Active connections: 291 
server accepts handled requests16630948 16630948 31070465 
Reading: 6 Writing: 179 Waiting: 106

Active connections：当前活跃的连接数。
accepts：服务器总共接受的连接数。
handled：服务器成功处理的连接数。
requests：服务器总共处理的请求数。
Reading：正在读取请求头的连接数。
Writing：正在写入响应给客户端的连接数。
Waiting：处于空闲等待状态的连接数。

注意事项

安全性：建议对 /nginx_status 路径进行访问控制，仅允许受信任的 IP 地址访问。
性能影响：启用状态页面本身对性能影响较小，但在高流量环境下应谨慎使用。

2.52 ngx_http_sub_module

ngx_http_sub_module 是 Nginx 的一个模块，用于在响应内容中进行字符串替换。这个模块允许你在将响应发送给客户端之前，动态地修改响应体中的特定字符串或模式。这对于需要对响应内容进行简单编辑（如替换广告代码、修复链接等）的场景非常有用。

主要功能

字符串替换：在响应内容中查找并替换指定的字符串。
正则表达式支持：可以使用正则表达式进行更复杂的匹配和替换。
灵活应用：适用于多种场景，包括广告替换、链接修复等。

常用指令

sub_filter：定义要查找和替换的字符串或正则表达式。
sub_filter_once：控制是否仅替换第一次出现的匹配项。默认值为 on，即只替换第一个匹配项；设置为 off 则替换所有匹配项
sub_filter_types：指定哪些 MIME 类型的响应内容应被处理。默认情况下，只有 text/html 类型的内容会被处理。

使用示例

以下是一些简化的配置示例，展示了如何使用 ngx_http_sub_module 来实现响应内容的字符串替换。

基本字符串替换

假设你希望将 HTML 页面中的某个旧字符串替换为新字符串：

server {listen 80;server_name example.com;location / {proxy_pass http://backend_server;# 替换响应中的 "old_string" 为 "new_string"sub_filter 'old_string' 'new_string';}
}

在这个例子中：

proxy_pass 指令将请求代理到后端服务器 backend_server。
sub_filter 指令指定了要查找的字符串 "old_string" 和替换后的字符串 "new_string"。

替换所有匹配项

如果你希望替换响应中的所有匹配项而不是仅替换第一个匹配项：

server {listen 80;server_name example.com;location / {proxy_pass http://backend_server;# 替换所有匹配项sub_filter 'old_string' 'new_string';sub_filter_once off;}
}

在这个例子中：

sub_filter_once off; 确保所有的匹配项都会被替换，而不仅仅是第一个。

使用正则表达式

如果你想使用正则表达式进行更复杂的匹配和替换：

server {listen 80;server_name example.com;location / {proxy_pass http://backend_server;# 使用正则表达式进行替换sub_filter 'href="http://(.*?)"' 'href="https://$1"';}
}

在这个例子中：

sub_filter 指令使用了正则表达式来匹配所有以 href="http:// 开头的链接，并将其替换为 HTTPS 链接。

处理多种 MIME 类型

默认情况下，sub_filter 只会处理 text/html 类型的响应。如果你希望处理其他类型的响应（例如 text/css 或 application/javascript），可以使用 sub_filter_types 指令：

server {listen 80;server_name example.com;location / {proxy_pass http://backend_server;# 处理多种 MIME 类型的响应sub_filter_types text/html text/css application/javascript;# 替换响应中的 "old_string" 为 "new_string"sub_filter 'old_string' 'new_string';}
}

在这个例子中：

sub_filter_types 指令指定了要处理的 MIME 类型列表，包括 text/html、text/css 和 application/javascript。

组合多个 sub_filter 指令

你可以组合多个 sub_filter 指令来实现更复杂的替换操作：

server {listen 80;server_name example.com;location / {proxy_pass http://backend_server;# 替换多个不同的字符串sub_filter 'old_string_1' 'new_string_1';sub_filter 'old_string_2' 'new_string_2';sub_filter 'old_string_3' 'new_string_3';# 替换所有匹配项sub_filter_once off;}
}

在这个例子中：

多个 sub_filter 指令分别替换了不同的字符串。
sub_filter_once off; 确保每个匹配项都被替换，而不仅仅是第一个。

注意事项

性能影响：ngx_http_sub_module 在处理大文件或高并发流量时可能会对性能产生一定影响，因为它需要解析和修改响应内容。建议仅在必要时使用，并尽量减少不必要的替换操作。
缓存问题：如果启用了缓存机制（如代理缓存或浏览器缓存），请确保缓存的内容不会包含未替换的字符串。可以通过适当的缓存策略（如禁用缓存或使用版本化 URL）来解决这个问题。
调试与测试：在生产环境中部署前，务必进行充分的测试，确保替换操作按预期工作。可以使用工具如 curl 或浏览器开发者工具来检查响应内容。
```
curl -v http://example.com
```
安全性：避免使用过于宽泛的正则表达式，以免意外替换不应修改的内容。确保替换操作不会引入安全漏洞或破坏页面结构。

通过合理配置 ngx_http_sub_module，你可以在将响应发送给客户端之前对其进行必要的修改，这对于某些特定的应用场景非常有帮助。

2.52.1 指令列表

sub_filter

sub_filter 指令用于替换响应内容中的字符串。这可以用于修改网页内容，例如替换旧域名或修复错误链接等。

Syntax:	sub_filter string replacement;
Default: —
Context: http, server, location

string：需要被替换的字符串。
replacement：替换后的字符串。

案例

基本用法

最简单的 sub_filter 用法是替换响应内容中的特定字符串：

http {server {listen 80;server_name example.com;location / {# 替换响应内容中的 "old_domain" 为 "new_domain"sub_filter 'old_domain' 'new_domain';# 确保只替换一次（可选）sub_filter_once on;# 其他配置proxy_pass http://backend_server;}}
}

在这个例子中：

当用户访问 example.com 时，Nginx 将代理请求到 backend_server，并在响应内容中将所有出现的 "old_domain" 替换为 "new_domain"。

注意事项

多次替换：默认情况下，sub_filter 只会替换第一次匹配的字符串。如果需要替换所有匹配项，请设置 sub_filter_once off。
编码问题：确保响应内容的字符编码与替换字符串一致，以避免乱码问题。

sub_filter_last_modified

sub_filter_last_modified 指令用于控制是否在替换响应内容后更新 Last-Modified 响应头。这有助于确保缓存机制能够正确识别内容的变化。

Syntax:	sub_filter_last_modified on | off;
Default: sub_filter_last_modified off;
Context: http, server, location
This directive appeared in version 1.5.1.

on：在替换响应内容后更新 Last-Modified 响应头。
off：不更新 Last-Modified 响应头，默认行为。

案例

基本用法

最简单的 sub_filter_last_modified 用法是启用或禁用在替换响应内容后更新 Last-Modified 响应头：

http {server {listen 80;server_name example.com;location / {# 替换响应内容中的 "old_domain" 为 "new_domain"sub_filter 'old_domain' 'new_domain';# 在替换响应内容后更新 Last-Modified 响应头sub_filter_last_modified on;# 其他配置proxy_pass http://backend_server;}}
}

在这个例子中：

当用户访问 example.com 时，Nginx 将代理请求到 backend_server，并在响应内容中将所有出现的 "old_domain" 替换为 "new_domain"。如果启用了 sub_filter_last_modified on，则会在替换完成后更新 Last-Modified 响应头。

注意事项

缓存机制：合理使用 Last-Modified 响应头可以提高缓存效率，减少不必要的请求。
时间戳准确性：确保更新后的 Last-Modified 时间戳准确无误，以避免缓存失效问题。

sub_filter_once

sub_filter_once 用于控制替换过滤器是否仅执行一次。这有助于决定在响应体中找到第一个匹配项后是否继续查找其他匹配项。

Syntax: sub_filter_once on | off;
Default: sub_filter_once on;
Context: http, server, location

on：仅替换第一个匹配项（默认行为）。
off：替换所有匹配项。

案例

基本用法

最简单的 sub_filter_once 用法是启用或禁用多次替换：

server {listen 80;server_name example.com;location / {sub_filter 'old_text' 'new_text';sub_filter_once off;  # 替换所有匹配项}
}

在这个例子中，设置了 sub_filter_once off，这意味着 Nginx 将替换所有匹配 'old_text' 的文本为 'new_text'。

单次替换

根据实际需求进行单次替换：

server {listen 80;server_name example.com;location /single_replace/ {sub_filter 'old_text' 'new_text';sub_filter_once on;  # 仅替换第一个匹配项}location /multiple_replace/ {sub_filter 'old_text' 'new_text';sub_filter_once off;  # 替换所有匹配项}
}

在这个例子中：

对于 /single_replace/ 路径下的请求，仅替换第一个匹配 'old_text' 的文本为 'new_text'。
对于 /multiple_replace/ 路径下的请求，替换所有匹配 'old_text' 的文本为 'new_text'。

注意事项

性能优化：如果只需要替换一个匹配项，设置 sub_filter_once on 可以提高处理速度。
应用场景：根据具体的应用场景选择合适的替换策略，确保既能满足需求，又不会浪费资源。

sub_filter_types

sub_filter_types 用于指定哪些 MIME 类型的文件可以使用替换过滤器。这有助于控制哪些类型的文件在被请求时会进行内容替换。

Syntax: sub_filter_types mime-type ...;
Default: sub_filter_types text/html;
Context: http, server, location

mime-type：指定一个或多个 MIME 类型，这些类型的文件将启用替换过滤器。默认值为 text/html。

案例

基本用法

最简单的 sub_filter_types 用法是指定要启用替换过滤器的 MIME 类型：

server {listen 80;server_name example.com;location / {sub_filter 'old_text' 'new_text';sub_filter_types text/html text/plain;  # 允许 text/html 和 text/plain 类型的文件进行替换}
}

在这个例子中，除了默认的 text/html，还启用了 text/plain 类型的文件进行替换。

扩展 MIME 类型

根据实际需求扩展支持的 MIME 类型：

server {listen 80;server_name example.com;location /replace_content/ {sub_filter 'old_text' 'new_text';sub_filter_types text/html text/plain application/xhtml+xml;  # 支持多种 MIME 类型}location /html_only/ {sub_filter 'old_text' 'new_text';sub_filter_types text/html;  # 仅支持 HTML 文件}
}

在这个例子中：

对于 /replace_content/ 路径下的请求，启用了 text/html、text/plain 和 application/xhtml+xml 类型的文件进行替换。
对于 /html_only/ 路径下的请求，仅启用了 text/html 类型的文件进行替换。

注意事项

性能影响：启用替换过滤器可能会对性能产生一定影响，特别是在处理大量文件时。
文件类型：确保只对需要的文件类型启用替换过滤器，避免不必要的开销。

2.53 ngx_http_upstream_module

ngx_http_upstream_module 是 Nginx 中用于定义和管理一组上游服务器（即后端服务器）的模块。通过这个模块，你可以配置负载均衡、健康检查、会话持久性等功能，从而提高系统的可用性和性能。

主要功能

负载均衡：支持多种负载均衡算法（如轮询、最少连接、哈希等），将请求分发到多个后端服务器。
健康检查：可以自动检测后端服务器的健康状态，并将请求只发送给健康的服务器。
会话持久性：支持会话粘滞性，确保同一客户端的请求始终被路由到同一个后端服务器。
故障转移：当某个后端服务器不可用时，自动将请求转发到其他可用的服务器。

常用指令

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

定义上游服务器组

upstream backend {# 定义一组后端服务器server backend1.example.com;server backend2.example.com;server backend3.example.com;# 负载均衡策略（默认是轮询）least_conn;  # 最少连接数# ip_hash;   # 基于客户端 IP 的哈希# hash $request_uri consistent;  # 基于 URI 的一致性哈希
}

配置负载均衡策略

轮询（默认）：每个请求按顺序分配到不同的后端服务器。

upstream backend {server backend1.example.com;server backend2.example.com;
}

最少连接：将请求分配给当前连接数最少的服务器。

upstream backend {least_conn;server backend1.example.com;server backend2.example.com;
}

基于 IP 的哈希：根据客户端 IP 地址进行哈希，确保同一客户端的请求总是被发送到同一台服务器。
```
upstream backend {ip_hash;server backend1.example.com;server backend2.example.com;
}
```

一致性哈希：基于某个变量（如 $request_uri）进行一致性哈希，适合缓存场景。

upstream backend {hash $request_uri consistent;server backend1.example.com;server backend2.example.com;
}

配置单个服务器

server: 定义一个后端服务器，并可以指定各种参数：
- weight: 设置权重，默认为1。权重高的服务器将处理更多的请求。
- max_fails: 在指定时间内（由 fail_timeout 参数设置）允许的最大失败次数，默认为1。
- fail_timeout: 设置服务器被认为不可用的时间间隔，默认为10秒。
- backup: 标记该服务器为备用服务器，只有在所有主服务器都不可用时才会使用。
- down: 标记该服务器为永久不可用。
示例：
```
upstream backend {server backend1.example.com weight=3 max_fails=3 fail_timeout=30s;server backend2.example.com weight=1 max_fails=3 fail_timeout=30s;server backend3.example.com backup;
}
```

使用示例

以下是一个完整的配置示例，展示了如何使用 ngx_http_upstream_module 来实现负载均衡和健康检查：

http {upstream backend {# 使用最少连接数算法least_conn;# 定义后端服务器server backend1.example.com weight=3 max_fails=3 fail_timeout=30s;server backend2.example.com weight=1 max_fails=3 fail_timeout=30s;server backend3.example.com backup;# 启用健康检查（需要安装第三方模块或使用商业版）# health_check uri=/health_check;}server {listen 80;server_name example.com;location / {# 将请求代理到 upstream backendproxy_pass http://backend;# 设置代理头信息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;}}
}

在这个例子中：

upstream backend 定义了一组后端服务器，并使用 least_conn 算法进行负载均衡。
server 指令定义了具体的后端服务器及其参数，包括权重、最大失败次数和失效时间。
proxy_pass http://backend; 将请求代理到定义的 backend 上游服务器组。
proxy_set_header 指令设置了代理请求头信息，确保后端服务器能够获取正确的客户端信息。

高级功能

健康检查

Nginx 开源版不直接支持健康检查功能，但可以通过第三方模块（如 nginx_upstream_check_module）或使用商业版 Nginx Plus 来实现。

示例（假设你已经安装了 nginx_upstream_check_module）：

upstream backend {server backend1.example.com;server backend2.example.com;# 启用健康检查check interval=3000 rise=2 fall=5 timeout=1000 type=http;check_http_send "HEAD /health_check HTTP/1.0\r\n\r\n";check_http_expect_alive http_2xx http_3xx;
}

解释：

interval=3000: 检查间隔时间为 3 秒。
rise=2: 至少连续 2 次成功响应才认为服务器恢复正常。
fall=5: 连续 5 次失败响应才认为服务器不可用。
timeout=1000: 超时时间为 1 秒。
type=http: 使用 HTTP 协议进行健康检查。

会话持久性

如果你希望同一客户端的请求总是被路由到同一台服务器（例如为了保持会话数据），可以使用 ip_hash 或 sticky 模块（如果使用商业版 Nginx Plus）。

示例：

upstream backend {ip_hash;server backend1.example.com;server backend2.example.com;
}

或者使用 Nginx Plus 的 sticky 模块：

upstream backend {sticky cookie srv_id expires=1h domain=.example.com path=/;server backend1.example.com;server backend2.example.com;
}

注意事项

负载均衡策略选择：根据实际需求选择合适的负载均衡策略。常见的策略包括轮询、最少连接、基于 IP 的哈希等。每种策略都有其适用场景，选择不当可能会影响性能或用户体验。
健康检查：虽然 Nginx 开源版不直接支持健康检查，但可以通过第三方模块或升级到商业版来实现。健康检查对于确保服务高可用性非常重要。
测试验证：在部署之前进行全面测试，确保所有配置按预期工作，并检查是否有任何潜在的问题（如负载不均、健康检查失败等）。

通过合理配置 ngx_http_upstream_module，你可以有效地实现负载均衡和高可用性，提升系统的稳定性和性能。这对于构建可靠的服务架构非常关键。

2.53.1 指令列表

upstream

upstream 用于定义一组服务器，并将其作为一个整体来处理请求。这有助于实现负载均衡和高可用性。

Syntax: upstream name { ... }
Default: —
Context: http

name：指定上游服务器组的名称。
{ ... }：包含上游服务器的配置。

案例

基本用法

最简单的 upstream 用法是指定一组服务器：

http {upstream backend {server 192.168.1.10:8080;server 192.168.1.11:8080;}server {listen 80;server_name example.com;location / {proxy_pass http://backend;  # 将请求转发到 upstream 定义的 backend 组}}
}

在这个例子中，定义了一个名为 backend 的上游服务器组，并将请求转发到该组中的服务器。

负载均衡策略

根据实际需求添加负载均衡策略：

http {upstream backend {ip_hash;  # 使用 IP 哈希算法进行负载均衡server 192.168.1.10:8080;server 192.168.1.11:8080;}server {listen 80;server_name example.com;location / {proxy_pass http://backend;}}
}

在这个例子中，使用了 ip_hash 算法来分配请求，确保来自同一客户端的请求总是被发送到相同的服务器。

注意事项

负载均衡：合理选择负载均衡策略（如轮询、IP 哈希等），以确保最佳的资源利用和用户体验。
健康检查：结合健康检查机制，确保上游服务器的可用性。

server

server 指令用于定义上游服务器组中的单个服务器。这有助于详细配置每个服务器的行为和参数。

Syntax: server address [parameters];
Default: —
Context: upstream

address：指定服务器的地址（IP 地址和端口或域名）。
[parameters]：可选参数，如权重、最大失败次数等。

案例

基本用法

最简单的 server 用法是指定服务器地址：

http {upstream backend {server 192.168.1.10:8080;server 192.168.1.11:8080;}server {listen 80;server_name example.com;location / {proxy_pass http://backend;}}
}

在这个例子中，定义了两个上游服务器 192.168.1.10:8080 和 192.168.1.11:8080。

配置参数

根据实际需求配置服务器参数：

http {upstream backend {server 192.168.1.10:8080 weight=3 max_fails=2 fail_timeout=10s;server 192.168.1.11:8080 weight=1 max_fails=2 fail_timeout=10s backup;}server {listen 80;server_name example.com;location / {proxy_pass http://backend;}}
}

在这个例子中：

192.168.1.10:8080 服务器的权重为 3，最大失败次数为 2，失败超时时间为 10 秒。
192.168.1.11:8080 服务器的权重为 1，最大失败次数为 2，失败超时时间为 10 秒，并且作为备份服务器。

注意事项

权重：合理设置服务器权重，确保资源利用更加均衡。
容错机制：通过设置 max_fails 和 fail_timeout 参数，增强系统的容错能力。

zone

zone 指令用于定义共享内存区域的名称和大小，主要用于上游服务器组（upstream）。这个指令帮助优化Nginx的性能，特别是在负载均衡场景中。

Syntax:	zone name [size];
Default:	—
Context:	upstream
This directive appeared in version 1.9.0.

name：指定共享内存区域的名称。
size：指定共享内存区域的大小。

案例

基本用法

最简单的 zone 用法是指定一个具体的共享内存区域名称和大小：

upstream backend {zone backend_zone 64k;server backend1.example.com;server backend2.example.com;
}server {listen 80;server_name example.com;location / {proxy_pass http://backend;}
}

在这个例子中：

设置了 zone backend_zone 64k，这意味着Nginx将使用名为 backend_zone 的共享内存区域，大小为64KB。

动态设置不同配置

你可以根据不同的需求动态设置不同的共享内存区域名称和大小：

upstream backend_small {zone small_zone 32k;server backend1.example.com;server backend2.example.com;
}upstream backend_large {zone large_zone 128k;server backend3.example.com;server backend4.example.com;
}server {listen 80;server_name example.com;location /small/ {proxy_pass http://backend_small;}location /large/ {proxy_pass http://backend_large;}
}

在这个例子中：

对于 /small/ 路径，设置了 zone small_zone 32k。
对于 /large/ 路径，设置了 zone large_zone 128k。

注意事项

内存管理：合理设置共享内存区域的大小，避免浪费或不足。过小可能导致频繁的内存交换，过大则可能浪费资源。
适用场景：适用于需要优化负载均衡性能的应用场景。例如，在高并发网站、API网关等环境中使用。
调试和监控：如果你遇到共享内存问题，可以检查以下几点：
- 确保共享内存区域设置合理，并符合你的需求。
- 查看Nginx的日志文件，确认是否有与此相关的警告或错误信息。
- 使用工具模拟不同负载条件下的请求进行测试，确保在各种情况下都能正常工作。

state

state 指令用于指定上游服务器的状态文件路径。这个指令帮助动态管理上游服务器的状态，如启用、禁用等。

Syntax:	state file;
Default:	—
Context:	upstream
This directive appeared in version 1.9.7.

file：指定状态文件的路径。

案例

基本用法

最简单的 state 用法是指定一个具体的状态文件路径：

upstream backend {state /etc/nginx/conf.d/backend.state;server backend1.example.com;server backend2.example.com;
}server {listen 80;server_name example.com;location / {proxy_pass http://backend;}
}

在这个例子中：

设置了 state /etc/nginx/conf.d/backend.state，这意味着Nginx将使用 /etc/nginx/conf.d/backend.state 文件来管理上游服务器的状态。

动态设置不同配置

你可以根据不同的需求动态设置不同的状态文件路径：

upstream backend_group1 {state /etc/nginx/conf.d/group1.state;server backend1.example.com;server backend2.example.com;
}upstream backend_group2 {state /etc/nginx/conf.d/group2.state;server backend3.example.com;server backend4.example.com;
}server {listen 80;server_name example.com;location /group1/ {proxy_pass http://backend_group1;}location /group2/ {proxy_pass http://backend_group2;}
}

在这个例子中：

对于 backend_group1，设置了 state /etc/nginx/conf.d/group1.state。
对于 backend_group2，设置了 state /etc/nginx/conf.d/group2.state。

注意事项

文件管理：确保状态文件路径正确，并定期维护和更新状态文件。
适用场景：适用于需要动态管理上游服务器状态的应用场景。例如，在需要灵活控制服务器上线、下线的情况下使用。
调试和监控：如果你遇到状态文件问题，可以检查以下几点：
- 确保状态文件路径正确，并符合你的需求。
- 查看Nginx的日志文件，确认是否有与此相关的警告或错误信息。
- 使用工具模拟不同负载条件下的请求进行测试，确保在各种情况下都能正常工作。

hash

hash 指令用于基于指定键值对请求进行哈希分配。这个指令帮助实现会话保持（session persistence）等功能。

Syntax:	hash key [consistent];
Default:	—
Context:	upstream
This directive appeared in version 1.7.2.

key：指定用于哈希的键值。
consistent：可选参数，指定是否使用一致性哈希算法。

案例

基本用法

最简单的 hash 用法是指定一个具体的键值：

upstream backend {hash $request_uri;server backend1.example.com;server backend2.example.com;
}server {listen 80;server_name example.com;location / {proxy_pass http://backend;}
}

在这个例子中：

设置了 hash $request_uri，这意味着Nginx将基于请求URI进行哈希分配。

动态设置不同配置

你可以根据不同的需求动态设置不同的哈希键值：

upstream backend_by_ip {hash $remote_addr consistent;server backend1.example.com;server backend2.example.com;
}upstream backend_by_uri {hash $request_uri;server backend3.example.com;server backend4.example.com;
}server {listen 80;server_name example.com;location /by_ip/ {proxy_pass http://backend_by_ip;}location /by_uri/ {proxy_pass http://backend_by_uri;}
}

在这个例子中：

对于 /by_ip/ 路径，设置了 hash $remote_addr consistent，基于客户端IP地址进行一致性哈希分配。
对于 /by_uri/ 路径，设置了 hash $request_uri，基于请求URI进行哈希分配。

注意事项

一致性与分布均匀性：一致性哈希有助于减少服务器增减时的影响，但可能不如普通哈希分布均匀。根据实际需求选择合适的哈希策略。
适用场景：适用于需要实现会话保持或特定请求分配的应用场景。例如，在购物车系统、用户会话管理等环境中使用。
调试和监控：如果你遇到哈希分配问题，可以检查以下几点：
- 确保哈希键值设置合理，并符合你的需求。
- 查看Nginx的日志文件，确认是否有与此相关的警告或错误信息。
- 使用工具模拟不同负载条件下的请求进行测试，确保在各种情况下都能正常工作。

ip_hash

ip_hash 指令用于基于客户端IP地址对请求进行哈希分配。这个指令是实现简单会话保持的一种方式。

Syntax:	ip_hash;
Default:	—
Context:	upstream

无参数：直接使用客户端IP地址进行哈希分配。

案例

基本用法

最简单的 ip_hash 用法是直接在上游服务器组中启用：

upstream backend {ip_hash;server backend1.example.com;server backend2.example.com;
}server {listen 80;server_name example.com;location / {proxy_pass http://backend;}
}

在这个例子中：

设置了 ip_hash，这意味着Nginx将基于客户端IP地址进行哈希分配，从而实现简单的会话保持。

动态设置不同配置

你可以根据不同的需求动态设置是否启用 ip_hash：

upstream backend_with_ip_hash {ip_hash;server backend1.example.com;server backend2.example.com;
}upstream backend_without_ip_hash {server backend3.example.com;server backend4.example.com;
}server {listen 80;server_name example.com;location /with_ip_hash/ {proxy_pass http://backend_with_ip_hash;}location /without_ip_hash/ {proxy_pass http://backend_without_ip_hash;}
}

在这个例子中：

对于 /with_ip_hash/ 路径，启用了 ip_hash。
对于 /without_ip_hash/ 路径，未启用 ip_hash。

注意事项

简单与局限性：ip_hash 实现简单，但存在局限性，如当多个客户端通过同一代理服务器访问时，所有这些请求都会被分配到同一个后端服务器。
适用场景：适用于需要简单会话保持的应用场景。例如，在不需要复杂会话管理的小型应用中使用。
调试和监控：如果你遇到 ip_hash 相关问题，可以检查以下几点：
- 确保 ip_hash 设置合理，并符合你的需求。
- 查看Nginx的日志文件，确认是否有与此相关的警告或错误信息。
- 使用工具模拟不同负载条件下的请求进行测试，确保在各种情况下都能正常工作。

keepalive

keepalive 指令用于设置与上游服务器保持的空闲连接数。

Syntax:	keepalive connections;
Default:	—
Context:	upstream
This directive appeared in version 1.1.4.

connections：指定要保持的空闲连接数。

案例

基本用法

最简单的 keepalive 用法是指定要保持的空闲连接数：

upstream backend {server backend1.example.com;server backend2.example.com;# 设置与上游服务器保持的空闲连接数为 32keepalive 32;
}server {listen 80;server_name example.com;location / {proxy_pass http://backend;proxy_http_version 1.1;proxy_set_header Connection "";}
}

在这个例子中：

Nginx 将保持最多 32 个与上游服务器的空闲连接。

注意事项

性能优化：启用和配置适当的空闲连接数可以显著减少连接建立的时间，特别是在高并发场景下。
适用场景：适用于需要频繁与上游服务器通信的应用场景。例如，在代理 API 服务或负载均衡时，保持一定数量的空闲连接可以提高响应速度。
调试和监控：如果你遇到空闲连接问题，可以检查以下几点：
- 确保 proxy_http_version 1.1 和 proxy_set_header Connection "" 已正确配置。
- 查看Nginx的日志文件，确认是否有与此相关的警告或错误信息。

keepalive_requests

keepalive_requests 指令用于设置每个保持连接的最大请求数。

Syntax:	keepalive_requests number;
Default:	keepalive_requests 1000;
Context:	upstream
This directive appeared in version 1.15.3.

number：指定每个保持连接的最大请求数，默认值为 1000。

案例

基本用法

最简单的 keepalive_requests 用法是指定每个保持连接的最大请求数：

upstream backend {server backend1.example.com;server backend2.example.com;# 设置每个保持连接的最大请求数为 500keepalive_requests 500;# 设置与上游服务器保持的空闲连接数为 32keepalive 32;
}server {listen 80;server_name example.com;location / {proxy_pass http://backend;proxy_http_version 1.1;proxy_set_header Connection "";}
}

在这个例子中：

每个保持连接最多处理 500 个请求。

使用默认值

你可以选择使用默认值：

upstream backend {server backend1.example.com;server backend2.example.com;# 使用默认的最大请求数（1000）keepalive_requests 1000;# 设置与上游服务器保持的空闲连接数为 32keepalive 32;
}server {listen 80;server_name example.com;location / {proxy_pass http://backend;proxy_http_version 1.1;proxy_set_header Connection "";}
}

在这个例子中：

每个保持连接最多处理 1000 个请求（默认值）。

注意事项

性能优化：合理设置最大请求数可以平衡资源使用和性能需求。过多的请求数可能导致资源耗尽，而过少的请求数可能增加连接建立的频率。
适用场景：适用于需要管理资源使用的应用场景。例如，在高并发场景下，适当调整最大请求数可以避免资源过载。
调试和监控：如果你遇到最大请求数问题，可以检查以下几点：
- 确保 proxy_http_version 1.1 和 proxy_set_header Connection "" 已正确配置。
- 查看Nginx的日志文件，确认是否有与此相关的警告或错误信息。

keepalive_time

keepalive_time 指令用于设置保持连接的有效时间。

Syntax:	keepalive_time time;
Default:	keepalive_time 1h;
Context:	upstream
This directive appeared in version 1.19.10.

time：指定保持连接的有效时间，默认值为 1 小时（1h）。

案例

基本用法

最简单的 keepalive_time 用法是指定保持连接的有效时间：

upstream backend {server backend1.example.com;server backend2.example.com;# 设置保持连接的有效时间为 30 分钟keepalive_time 30m;# 设置与上游服务器保持的空闲连接数为 32keepalive 32;# 设置每个保持连接的最大请求数为 500keepalive_requests 500;
}server {listen 80;server_name example.com;location / {proxy_pass http://backend;proxy_http_version 1.1;proxy_set_header Connection "";}
}

在这个例子中：

保持连接的有效时间为 30 分钟。

使用默认值

你可以选择使用默认值：

upstream backend {server backend1.example.com;server backend2.example.com;# 使用默认的有效时间（1小时）keepalive_time 1h;# 设置与上游服务器保持的空闲连接数为 32keepalive 32;# 设置每个保持连接的最大请求数为 500keepalive_requests 500;
}server {listen 80;server_name example.com;location / {proxy_pass http://backend;proxy_http_version 1.1;proxy_set_header Connection "";}
}

在这个例子中：

保持连接的有效时间为 1 小时（默认值）。

注意事项

性能优化：合理设置有效时间可以平衡资源使用和连接稳定性。过长的有效时间可能导致资源浪费，而过短的有效时间可能导致频繁的连接重建。
适用场景：适用于需要管理长时间运行的连接和资源释放的应用场景。例如，在高并发场景下，适当调整有效时间可以避免资源浪费。
调试和监控：如果你遇到有效时间问题，可以检查以下几点：
- 确保 proxy_http_version 1.1 和 proxy_set_header Connection "" 已正确配置。
- 查看Nginx的日志文件，确认是否有与此相关的警告或错误信息。

keepalive_timeout

keepalive_timeout 指令用于设置保持连接的超时时间。

Syntax:	keepalive_timeout timeout;
Default:	keepalive_timeout 60s;
Context:	upstream
This directive appeared in version 1.15.3.

timeout：指定保持连接的超时时间，默认值为 60 秒（60s）。

案例

基本用法

最简单的 keepalive_timeout 用法是指定保持连接的超时时间：

upstream backend {server backend1.example.com;server backend2.example.com;# 设置保持连接的超时时间为 30 秒keepalive_timeout 30s;# 设置与上游服务器保持的空闲连接数为 32keepalive 32;# 设置每个保持连接的最大请求数为 500keepalive_requests 500;# 设置保持连接的有效时间为 30 分钟keepalive_time 30m;
}server {listen 80;server_name example.com;location / {proxy_pass http://backend;proxy_http_version 1.1;proxy_set_header Connection "";}
}

在这个例子中：

保持连接的超时时间为 30 秒。

使用默认值

你可以选择使用默认值：

upstream backend {server backend1.example.com;server backend2.example.com;# 使用默认的超时时间（60秒）keepalive_timeout 60s;# 设置与上游服务器保持的空闲连接数为 32keepalive 32;# 设置每个保持连接的最大请求数为 500keepalive_requests 500;# 设置保持连接的有效时间为 30 分钟keepalive_time 30m;
}server {listen 80;server_name example.com;location / {proxy_pass http://backend;proxy_http_version 1.1;proxy_set_header Connection "";}
}

在这个例子中：

保持连接的超时时间为 60 秒（默认值）。

注意事项

性能优化：合理设置超时时间可以平衡资源使用和连接稳定性。过长的超时时间可能导致资源浪费，而过短的超时时间可能导致频繁的连接重建。
适用场景：适用于需要管理连接的生命周期和资源释放的应用场景。例如，在高并发场景下，适当调整超时时间可以避免资源浪费。
调试和监控：如果你遇到超时时间问题，可以检查以下几点：
- 确保 proxy_http_version 1.1 和 proxy_set_header Connection "" 已正确配置。
- 查看Nginx的日志文件，确认是否有与此相关的警告或错误信息。

ntlm

ntlm 指令用于在上游服务器组中启用NTLM（NT LAN Manager）身份验证。这对于需要与支持NTLM协议的后端服务器进行集成的场景非常有用。

Syntax:	ntlm;
Default:	—
Context:	upstream
This directive appeared in version 1.9.2.

无参数：此指令不需要参数，只需在上游服务器组配置中添加即可启用NTLM身份验证。

案例

基本用法

假设我们有一个需要NTLM身份验证的后端服务器组：

http {upstream backend_ntlm {server backend1.example.com;server backend2.example.com;ntlm;  # 启用NTLM身份验证}server {listen 80;server_name example.com;location /secure/ {proxy_pass http://backend_ntlm;}}
}

在这个例子中，ntlm 指令启用了对上游服务器组 backend_ntlm 的NTLM身份验证支持。

注意事项

兼容性：确保后端服务器支持并正确配置了NTLM身份验证。
安全性：使用NTLM时需要注意其潜在的安全风险，并考虑使用更安全的身份验证机制如Kerberos。

least_conn

least_conn 指令用于在上游服务器组中启用最少连接负载均衡算法。这对于平衡各服务器之间的连接数，特别是在处理长连接或高并发请求时非常有用。

Syntax:	least_conn;
Default:	—
Context:	upstream
This directive appeared in versions 1.3.1 and 1.2.2.

无参数：此指令不需要参数，只需在上游服务器组配置中添加即可启用最少连接负载均衡算法。

案例

基本用法

假设我们希望使用最少连接负载均衡算法来分配请求：

http {upstream backend_least_conn {least_conn;  # 启用最少连接负载均衡算法server backend1.example.com;server backend2.example.com;}server {listen 80;server_name example.com;location / {proxy_pass http://backend_least_conn;}}
}

在这个例子中，least_conn 指令启用了对上游服务器组 backend_least_conn 的最少连接负载均衡算法。

注意事项

性能优化：适合处理长连接和高并发请求，有助于平衡各服务器的负载。
公平分配：确保每个服务器上的连接数尽量均衡，避免某些服务器过载。

least_time

least_time 指令用于在上游服务器组中启用基于响应时间的负载均衡算法。这可以帮助选择响应时间最短的服务器，从而提高整体性能。

Syntax:	least_time header | last_byte [inflight];
Default:	—
Context:	upstream
This directive appeared in version 1.7.10.

header：根据从服务器接收到第一个字节的时间来选择服务器。
last_byte：根据从服务器接收到最后一个字节的时间来选择服务器。
[inflight]（可选）：考虑当前正在处理的请求数量。

案例

基于首字节时间选择

假设我们希望根据从服务器接收到第一个字节的时间来选择服务器：

http {upstream backend_least_time_header {least_time header;  # 根据首字节时间选择服务器server backend1.example.com;server backend2.example.com;}server {listen 80;server_name example.com;location / {proxy_pass http://backend_least_time_header;}}
}

基于最后一个字节时间选择

如果我们希望根据从服务器接收到最后一个字节的时间来选择服务器：

http {upstream backend_least_time_lastbyte {least_time last_byte;  # 根据最后一个字节时间选择服务器server backend1.example.com;server backend2.example.com;}server {listen 80;server_name example.com;location / {proxy_pass http://backend_least_time_lastbyte;}}
}

考虑当前正在处理的请求数量

如果我们希望在选择服务器时同时考虑当前正在处理的请求数量：

http {upstream backend_least_time_inflight {least_time last_byte inflight;  # 根据最后一个字节时间和当前正在处理的请求数量选择服务器server backend1.example.com;server backend2.example.com;}server {listen 80;server_name example.com;location / {proxy_pass http://backend_least_time_inflight;}}
}

注意事项

性能优化：适合需要快速响应的应用场景，通过选择响应时间最短的服务器来提高用户体验。
复杂度管理：结合其他负载均衡策略一起使用，以达到最佳效果。

queue

queue 指令用于在上游服务器组中启用请求排队机制。这对于在所有上游服务器都忙时暂时存储请求，并在服务器变得可用时处理这些请求非常有用。

Syntax:	queue number [timeout=time];
Default:	—
Context:	upstream
This directive appeared in version 1.5.12.

number：指定可以排队的最大请求数。
timeout=time（可选）：指定请求在队列中的最大等待时间，默认为60秒。

案例

基本用法

假设我们希望设置一个可以容纳最多10个请求的队列，并且每个请求在队列中的最大等待时间为30秒：

http {upstream backend_queue {queue 10 timeout=30s;  # 设置最大排队请求数为10，超时时间为30秒server backend1.example.com;server backend2.example.com;}server {listen 80;server_name example.com;location / {proxy_pass http://backend_queue;}}
}

使用默认超时时间

如果我们希望使用默认的超时时间（60秒），只需要指定最大排队请求数：

http {upstream backend_queue_default_timeout {queue 10;  # 设置最大排队请求数为10，使用默认超时时间server backend1.example.com;server backend2.example.com;}server {listen 80;server_name example.com;location / {proxy_pass http://backend_queue_default_timeout;}}
}

注意事项

资源管理：合理设置最大排队请求数和超时时间，避免过度消耗系统资源。
用户体验：适当配置队列机制可以改善用户体验，防止请求直接被拒绝，但需注意长时间排队可能导致用户流失。

random

random 指令用于在负载均衡策略中随机选择上游服务器。这有助于实现更均匀的流量分布。

Syntax:	random [two [method]];
Default: —
Context: upstream
This directive appeared in version 1.15.1.

two [method]：可选参数，启用两阶段随机选择方法。method 可以是 least_conn 或 least_time=header|last_byte。

案例

基本用法

最简单的 random 用法是在上游服务器组中启用随机选择策略：

http {upstream backend {# 启用随机选择策略random;server backend1.example.com;server backend2.example.com;server backend3.example.com;}server {listen 80;server_name example.com;location / {proxy_pass http://backend;}}
}

在这个例子中：

当用户访问 example.com 时，Nginx 将从 backend 组中的三个服务器中随机选择一个进行请求转发。

使用两阶段随机选择

你可以使用两阶段随机选择方法来进一步优化负载均衡：

http {upstream backend {# 启用两阶段随机选择策略，并使用 least_conn 方法random two least_conn;server backend1.example.com;server backend2.example.com;server backend3.example.com;}server {listen 80;server_name example.com;location / {proxy_pass http://backend;}}
}

在这个例子中：

Nginx 首先随机选择两个服务器，然后根据 least_conn 方法从中选择一个连接数较少的服务器进行请求转发。

注意事项

均匀分布：随机选择策略有助于实现更均匀的流量分布，但在某些情况下可能不如其他策略（如 least_conn）高效。
性能考虑：对于高并发环境，建议结合其他负载均衡策略一起使用。

resolver

resolver 指令用于配置 DNS 解析器，使 Nginx 能够解析域名并进行反向代理或负载均衡。

Syntax:	resolver address ... [valid=time] [ipv4=on|off] [ipv6=on|off] [status_zone=zone];
Default: —
Context: upstream
This directive appeared in version 1.27.3.

address：DNS 服务器的 IP 地址。
valid=time：缓存 DNS 解析结果的有效时间，默认为 5 分钟。
ipv4=on|off：是否解析 IPv4 地址。
ipv6=on|off：是否解析 IPv6 地址。
status_zone=zone：为解析器设置状态区，用于监控和统计。

案例

基本用法

最简单的 resolver 用法是指定 DNS 服务器地址：

http {upstream backend {# 使用 Google 的公共 DNS 服务器resolver 8.8.8.8 8.8.4.4;server backend.example.com;}server {listen 80;server_name example.com;location / {proxy_pass http://backend;}}
}

在这个例子中：

Nginx 将使用 Google 的公共 DNS 服务器（8.8.8.8 和 8.8.4.4）解析 backend.example.com 的 IP 地址，并将其用于反向代理。

设置有效时间和解析选项

你可以进一步配置解析器的行为：

http {upstream backend {# 使用 Google 的公共 DNS 服务器，缓存结果 10 分钟，仅解析 IPv4 地址resolver 8.8.8.8 8.8.4.4 valid=10m ipv4=on ipv6=off;server backend.example.com;}server {listen 80;server_name example.com;location / {proxy_pass http://backend;}}
}

在这个例子中：

Nginx 将缓存 DNS 解析结果 10 分钟，并且只解析 IPv4 地址。

注意事项

DNS 缓存：合理设置 valid 参数以平衡 DNS 查询频率和响应速度。
IP 版本：根据实际需求选择是否解析 IPv4 和/或 IPv6 地址。

resolver_timeout

resolver_timeout 指令用于设置 DNS 解析的超时时间。这有助于防止长时间等待导致的性能问题。

Syntax:	resolver_timeout time;
Default: resolver_timeout 30s;
Context: upstream
This directive appeared in version 1.27.3.

time：DNS 解析的超时时间，默认为 30 秒。

案例

基本用法

最简单的 resolver_timeout 用法是指定 DNS 解析的超时时间：

http {upstream backend {resolver 8.8.8.8 8.8.4.4;resolver_timeout 10s;  # 设置 DNS 解析超时时间为 10 秒server backend.example.com;}server {listen 80;server_name example.com;location / {proxy_pass http://backend;}}
}

在这个例子中：

如果 DNS 解析超过 10 秒仍未完成，Nginx 将放弃解析并返回错误。

注意事项

性能影响：过长的超时时间可能导致请求延迟，过短的超时时间可能导致频繁失败。
可靠性：确保 DNS 服务器的可用性和响应速度，以避免不必要的超时。

sticky

sticky 指令用于实现会话粘滞性（Session Affinity），确保来自同一客户端的请求始终被转发到同一个上游服务器。这对于需要保持会话状态的应用非常有用。

Syntax:	sticky cookie name [expires=time] [domain=domain] [httponly] [samesite=strict|lax|none|$variable] [secure] [path=path];
sticky route $variable ...;
sticky learn create=$variable lookup=$variable zone=name:size [timeout=time] [header] [sync];
Default: —
Context: upstream
This directive appeared in version 1.5.7.

sticky cookie

name：Cookie 的名称。
expires=time：Cookie 的有效期。
domain=domain：Cookie 的域。
httponly：标记 Cookie 为 HttpOnly。
samesite=strict|lax|none|$variable：设置 SameSite 属性。
secure：标记 Cookie 为 Secure。
path=path：设置 Cookie 的路径。

案例

使用 sticky cookie

最简单的 sticky cookie 用法是通过 Cookie 实现会话粘滞性：

http {upstream backend {server backend1.example.com;server backend2.example.com;# 使用 sticky cookie 实现会话粘滞性sticky cookie srv_id expires=1h domain=.example.com httponly secure path=/;}server {listen 80;server_name example.com;location / {proxy_pass http://backend;}}
}

在这个例子中：

Nginx 将通过名为 srv_id 的 Cookie 实现会话粘滞性，Cookie 的有效期为 1 小时，并且设置了 HttpOnly、Secure 和 Path 属性。

sticky route

$variable：用于路由的变量。

案例

使用 sticky route

最简单的 sticky route 用法是通过变量实现会话粘滞性：

http {upstream backend {server backend1.example.com route=a;server backend2.example.com route=b;# 使用 sticky route 实现会话粘滞性sticky route $route;}server {listen 80;server_name example.com;location / {proxy_pass http://backend;proxy_set_header Route $route;}}
}

在这个例子中：

Nginx 将根据 $route 变量的值将请求路由到相应的服务器。

sticky learn

create=$variable：创建会话标识符的变量。
lookup=$variable：查找会话标识符的变量。
zone=name:size：共享内存区域的名称和大小。
timeout=time：会话超时时间。
header：从请求头中提取会话标识符。
sync：同步会话信息。

案例

使用 sticky learn

最复杂的 sticky learn 用法是通过学习机制实现会话粘滞性：

http {upstream backend {server backend1.example.com;server backend2.example.com;# 使用 sticky learn 实现会话粘滞性sticky learn create=$upstream_cookie_sessionid lookup=$cookie_sessionid zone=client_sessions:1m timeout=1h;}server {listen 80;server_name example.com;location / {proxy_pass http://backend;proxy_set_header Cookie $http_cookie;}}
}

在这个例子中：

Nginx 将根据 $upstream_cookie_sessionid 创建会话标识符，并根据 $cookie_sessionid 查找已有的会话标识符。会话信息存储在 client_sessions 区域中，大小为 1 MB，超时时间为 1 小时。

注意事项

会话管理：确保会话信息的安全性和有效性，特别是在分布式环境中。
扩展性：对于大规模应用，考虑使用更高级的会话管理解决方案，如 Redis 或数据库。

sticky_cookie_insert

sticky_cookie_insert 用于在响应中插入一个粘性会话 Cookie，确保来自同一客户端的请求总是被发送到同一个上游服务器。这有助于实现会话亲和性（session affinity）。

Syntax: sticky_cookie_insert name [expires=time] [domain=domain] [path=path];
Default: —
Context: upstream

name：指定 Cookie 的名称。
[expires=time]：可选参数，设置 Cookie 的过期时间。
[domain=domain]：可选参数，设置 Cookie 的域名。
[path=path]：可选参数，设置 Cookie 的路径。

案例

基本用法

最简单的 sticky_cookie_insert 用法是指定 Cookie 名称：

http {upstream backend {server 192.168.1.10:8080;server 192.168.1.11:8080;sticky_cookie_insert my_session_cookie;  # 插入名为 my_session_cookie 的 Cookie}server {listen 80;server_name example.com;location / {proxy_pass http://backend;}}
}

在这个例子中，插入了一个名为 my_session_cookie 的 Cookie。

配置详细参数

根据实际需求配置详细的 Cookie 参数：

http {upstream backend {server 192.168.1.10:8080;server 192.168.1.11:8080;sticky_cookie_insert session expires=1h domain=example.com path=/;  # 设置详细的 Cookie 参数}server {listen 80;server_name example.com;location / {proxy_pass http://backend;}}
}

在这个例子中：

设置了 Cookie 的过期时间为 1 小时 (expires=1h)。
设置了 Cookie 的域为 example.com (domain=example.com)。
设置了 Cookie 的路径为 / (path=/)。

注意事项

会话亲和性：确保粘性会话的有效性和持久性，避免用户频繁切换服务器导致的问题。
Cookie 安全：合理设置 Cookie 的过期时间和路径，增强安全性。

2.54 ngx_http_upstream_conf_module

ngx_http_upstream_conf_module 是 Nginx 的一个模块，用于动态配置和管理上游服务器组（upstream）。这个模块允许你在运行时动态修改上游服务器的配置，而不需要重新加载或重启 Nginx。这对于需要灵活调整负载均衡策略的应用场景非常有用。

主要功能

动态配置：在运行时添加、删除或修改上游服务器。
健康检查：结合其他模块（如 ngx_http_upstream_module 和 ngx_http_upstream_hc_module）实现对上游服务器的健康检查。
共享内存：使用共享内存存储上游服务器的状态信息，确保多实例之间的同步。

常用指令

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

upstream_conf：定义一个处理上游服务器配置的接口地址。
zone：指定共享内存区域名称和大小，用于存储上游服务器的状态信息。
server：定义上游服务器的地址和端口。
health_check：启用健康检查功能。

使用示例

以下是一些具体的配置示例，展示如何利用 ngx_http_upstream_conf_module 来实现动态配置和管理上游服务器组。

基本配置

假设你想在 /upstream_conf 路径下提供一个接口来动态管理上游服务器，并将上游服务器的状态信息存储在共享内存中：

http {# 定义共享内存区域upstream backend {zone backend_zone 64k;# 初始上游服务器列表server backend1.example.com:8080;server backend2.example.com:8080;}server {listen 80;server_name example.com;location / {proxy_pass http://backend;}# 配置 upstream_conf 接口location /upstream_conf {upstream_conf;allow 127.0.0.1;  # 仅允许来自 localhost 的访问deny all;}}
}

在这个例子中：

upstream backend 定义了一个名为 backend 的上游服务器组，并指定了共享内存区域 backend_zone，大小为 64KB。
server backend1.example.com:8080; 和 server backend2.example.com:8080; 定义了初始的上游服务器列表。
location /upstream_conf 提供了一个接口，允许通过 HTTP 请求动态管理上游服务器。
allow 127.0.0.1; 和 deny all; 限制只有来自 localhost 的请求才能访问该接口，防止外部用户篡改配置。

动态添加和删除上游服务器

你可以通过发送 HTTP 请求到 /upstream_conf 接口来动态添加或删除上游服务器。例如，使用 curl 工具：

添加一个新的上游服务器：

curl -X POST "http://example.com/upstream_conf?add=&server=backend3.example.com:8080"

删除一个现有的上游服务器：

curl -X POST "http://example.com/upstream_conf?remove=&server=backend2.example.com:8080"

这些请求会实时更新上游服务器组的配置，而不需要重新加载或重启 Nginx。

启用健康检查

结合 ngx_http_upstream_hc_module 模块，可以启用健康检查功能，确保只将请求转发给健康的上游服务器：

http {upstream backend {zone backend_zone 64k;# 初始上游服务器列表server backend1.example.com:8080;server backend2.example.com:8080;# 启用健康检查health_check interval=10 fails=3 passes=2;}server {listen 80;server_name example.com;location / {proxy_pass http://backend;}location /upstream_conf {upstream_conf;allow 127.0.0.1;deny all;}}
}

在这个例子中：

health_check interval=10 fails=3 passes=2; 启用了健康检查，默认情况下每 10 秒检查一次，连续失败 3 次即认为服务器不可用，连续成功 2 次即认为服务器恢复可用。

查看当前上游服务器状态

你可以通过发送 HTTP 请求到 /upstream_conf 接口来查看当前上游服务器的状态：

curl http://example.com/upstream_conf

响应内容将包含当前上游服务器组的详细配置信息，例如：

upstream backend {zone backend_zone 64k;server backend1.example.com:8080 weight=1 max_fails=1 fail_timeout=10s;server backend2.example.com:8080 weight=1 max_fails=1 fail_timeout=10s;server backend3.example.com:8080 weight=1 max_fails=1 fail_timeout=10s;
}

这表明当前有三个上游服务器在组中，并且它们的权重、最大失败次数和失败超时时间等参数也被显示出来。

结合身份验证进行安全访问

为了进一步提高安全性，你可以结合 HTTP 基本身份验证来限制对 /upstream_conf 接口的访问：

http {upstream backend {zone backend_zone 64k;server backend1.example.com:8080;server backend2.example.com:8080;}server {listen 80;server_name example.com;location / {proxy_pass http://backend;}location /upstream_conf {upstream_conf;allow 127.0.0.1;deny all;# 配置基本身份验证auth_basic "Restricted Access";auth_basic_user_file /etc/nginx/.htpasswd;}}
}

在这个例子中：

auth_basic "Restricted Access"; 启用了基本身份验证，并设置了提示消息。
auth_basic_user_file /etc/nginx/.htpasswd; 指定了包含用户名和密码的文件路径。你可以使用工具如 htpasswd 来生成这个文件。

例如，生成 .htpasswd 文件的命令：

sudo htpasswd -c /etc/nginx/.htpasswd username

然后根据提示输入密码。

注意事项

性能考虑：
- 动态配置操作可能会带来一定的开销，尤其是在高并发场景下。建议尽量减少频繁的操作。
安全性：
- 严格控制对 /upstream_conf 接口的访问权限，避免敏感配置被篡改。
- 如果启用了 HTTP 基本身份验证，确保 .htpasswd 文件的安全性，并定期更新密码。
日志记录：
- 可以配置访问日志，记录对 /upstream_conf 接口的访问情况，便于后续审计和故障排查。

通过合理配置 ngx_http_upstream_conf_module，你可以在运行时动态管理和调整上游服务器组的配置，这对于构建高可用性和灵活性的应用系统非常有帮助。这对于需要快速响应变化的环境尤其重要。

2.54.1 指令列表

upstream_conf

upstream_conf 用于动态配置上游服务器组。这允许通过 HTTP 请求动态修改上游服务器的状态和配置。

Syntax: upstream_conf;
Default: —
Context: location

无参数：此指令通常与特定模块或第三方模块结合使用，以提供动态配置功能。

案例

基本用法

假设你已经安装了支持 upstream_conf 的模块（如 ngx_http_upstream_conf_module），可以这样配置：

http {upstream backend {server 192.168.1.10:8080;server 192.168.1.11:8080;}server {listen 80;server_name example.com;location /upstream_conf {upstream_conf;  # 提供动态配置上游服务器的功能}location / {proxy_pass http://backend;}}
}

在这个例子中，访问 /upstream_conf 路径可以动态修改上游服务器组的配置。

注意事项

动态管理：确保模块正确安装并配置，以便能够动态管理上游服务器。
安全性：限制对 /upstream_conf 路径的访问权限，避免未经授权的修改。

2.55 ngx_http_upstream_hc_module

ngx_http_upstream_hc_module 是 Nginx 的一个模块，用于为上游服务器（upstream servers）提供健康检查（Health Check）功能。通过该模块，Nginx 可以定期检查上游服务器的健康状态，并根据检查结果动态调整负载均衡策略，从而提高系统的可靠性和可用性。

主要功能

健康检查：定期检测上游服务器的状态，判断其是否可用。
自动故障转移：当某个上游服务器不可用时，自动将其从负载均衡池中移除，并将流量分配给其他健康的服务器。
灵活配置：支持多种健康检查方式和参数配置，包括 HTTP、TCP 等协议的健康检查。

常用指令

health_check：启用健康检查并配置相关参数。
health_check_interval：设置健康检查的时间间隔，默认值为 5 秒。
health_check_timeout：设置健康检查的超时时间，默认值为 1 秒。
health_check_fails：设置连续失败多少次后认为服务器不可用，默认值为 2 次。
health_check_passes：设置连续成功多少次后认为服务器恢复可用，默认值为 1 次。
match：定义自定义的健康检查匹配规则，可以基于响应内容进行更复杂的检查。

使用示例

以下是一些简化的配置示例，展示了如何使用 ngx_http_upstream_hc_module 来实现上游服务器的健康检查。

基本健康检查

假设你希望对一组上游服务器进行简单的健康检查：

http {upstream backend {server backend1.example.com;server backend2.example.com;# 启用健康检查health_check;}server {listen 80;location / {proxy_pass http://backend;}}
}

在这个例子中：

health_check; 启用了默认的健康检查配置，Nginx 会定期发送请求到每个上游服务器，并根据响应判断其健康状态。

自定义健康检查参数

假设你希望自定义健康检查的时间间隔、超时时间和失败次数：

http {upstream backend {server backend1.example.com;server backend2.example.com;# 自定义健康检查参数health_check interval=10s timeout=3s fails=3 passes=2;}server {listen 80;location / {proxy_pass http://backend;}}
}

在这个例子中：

interval=10s 设置了健康检查的时间间隔为 10 秒。
timeout=3s 设置了健康检查的超时时间为 3 秒。
fails=3 设置了连续失败 3 次后认为服务器不可用。
passes=2 设置了连续成功 2 次后认为服务器恢复可用。

基于响应内容的健康检查

假设你希望基于响应内容进行更复杂的健康检查，例如检查响应状态码、响应头和响应体中的特定字符串：

http {# 定义自定义匹配规则match my_match {status 200-399;header Content-Type = text/html;body ~ "Welcome to nginx!";}upstream backend {server backend1.example.com;server backend2.example.com;# 使用自定义匹配规则进行健康检查health_check match=my_match;}server {listen 80;location / {proxy_pass http://backend;}}
}

在这个例子中：

match my_match 定义了一个自定义的匹配规则，要求响应状态码在 200 到 399 之间，响应头 Content-Type 必须是 text/html，并且响应体中必须包含 "Welcome to nginx!" 字符串。
health_check match=my_match; 使用该自定义匹配规则进行健康检查。

TCP 健康检查

除了 HTTP 健康检查外，ngx_http_upstream_hc_module 还支持 TCP 健康检查。假设你有一个 TCP 服务需要进行健康检查：

http {upstream tcp_backend {server 192.168.1.1:8080;server 192.168.1.2:8080;# 启用 TCP 健康检查check interval=3000 rise=2 fall=3 timeout=1000 type=tcp;}server {listen 80;location / {proxy_pass http://tcp_backend;}}
}

在这个例子中：

check interval=3000 rise=2 fall=3 timeout=1000 type=tcp; 启用了 TCP 健康检查，每隔 3 秒发送一次 TCP 请求，如果连续两次成功则认为服务器恢复可用，如果连续三次失败则认为服务器不可用，每次检查的超时时间为 1 秒。

注意事项

性能影响：健康检查会增加额外的网络开销，尤其是在高并发环境中。建议根据实际需求合理设置检查频率和超时时间，避免过度频繁的检查影响系统性能。
日志记录：为了方便调试和监控，建议启用详细的日志记录，特别是在配置健康检查时。
```
error_log /var/log/nginx/error.log warn;
access_log /var/log/nginx/access.log main;
```
安全性：确保健康检查请求不会暴露敏感信息或被恶意利用。可以通过限制访问或加密传输来增强安全性。
兼容性：某些上游服务器可能不支持健康检查所需的响应格式或协议。在这种情况下，可以考虑使用自定义的健康检查脚本或其他机制来替代内置的健康检查功能。

通过合理配置 ngx_http_upstream_hc_module，你可以有效监控上游服务器的健康状态，并根据检查结果动态调整负载均衡策略，从而提高系统的可靠性和可用性。

2.55.1 指令列表

health_check

health_check 用于配置健康检查机制，定期检查上游服务器的健康状态，并根据结果决定是否将流量转发给该服务器。

Syntax: health_check [parameters];
Default: —
Context: location

[parameters]：可选参数，如间隔时间、失败次数等。

案例

基本用法

最简单的 health_check 用法是启用默认的健康检查：

http {upstream backend {server 192.168.1.10:8080;server 192.168.1.11:8080;}server {listen 80;server_name example.com;location / {proxy_pass http://backend;health_check;  # 启用默认的健康检查}}
}

在这个例子中，启用了默认的健康检查机制。

配置详细参数

根据实际需求配置详细的健康检查参数：

http {upstream backend {server 192.168.1.10:8080;server 192.168.1.11:8080;}server {listen 80;server_name example.com;location / {proxy_pass http://backend;health_check interval=10s fails=3 passes=2 uri=/health_status;  # 自定义健康检查参数}}
}

在这个例子中：

设置了健康检查的时间间隔为 10 秒 (interval=10s)。
设置了连续失败 3 次后标记服务器为不可用 (fails=3)。
设置了连续成功 2 次后重新启用服务器 (passes=2)。
设置了健康检查的 URI 为 /health_status (uri=/health_status)。

注意事项

监控频率：合理设置检查间隔和失败/成功阈值，平衡资源消耗和及时性。
URI 选择：确保健康检查 URI 返回正确的状态码，以便准确判断服务器健康状态。

match

match 用于定义匹配规则，这些规则可以在健康检查或其他上下文中使用。这有助于灵活地定义检查条件。

Syntax: match name { ... }
Default: —
Context: http

name：指定匹配规则的名称。
{ ... }：包含匹配规则的定义。

案例

基本用法

最简单的 match 用法是定义一个匹配规则：

http {match healthy {status 200-399;  # 匹配状态码范围 200-399header Content-Type = text/html;  # 匹配响应头中的 Content-Type}upstream backend {server 192.168.1.10:8080;server 192.168.1.11:8080;}server {listen 80;server_name example.com;location / {proxy_pass http://backend;health_check match=healthy;  # 使用自定义的匹配规则进行健康检查}}
}

在这个例子中，定义了一个名为 healthy 的匹配规则，并将其应用于健康检查。

复杂匹配规则

根据实际需求定义更复杂的匹配规则：

http {match complex_match {status 200-299;  # 匹配状态码范围 200-299header X-Custom-Header = "custom_value";  # 匹配自定义响应头body ~ "success";  # 匹配响应体中的字符串 "success"}upstream backend {server 192.168.1.10:8080;server 192.168.1.11:8080;}server {listen 80;server_name example.com;location / {proxy_pass http://backend;health_check match=complex_match;  # 使用复杂的匹配规则进行健康检查}}
}

在这个例子中：

匹配状态码范围为 200-299。
匹配响应头 X-Custom-Header 等于 "custom_value"。
匹配响应体中包含字符串 "success"。

注意事项

灵活性：通过定义不同的匹配规则，可以灵活应对各种健康检查需求。
准确性：确保匹配规则的定义准确无误，避免误判服务器健康状态。

2.56 ngx_http_userid_module

ngx_http_userid_module 是 Nginx 的一个模块，用于在客户端浏览器中设置和读取唯一标识符（通常是一个 Cookie）。这个模块可以帮助你识别和跟踪用户会话，尽管它不提供像完整用户管理系统那样的复杂功能，但在某些场景下非常有用，比如简单的用户行为分析或会话管理。

主要功能

设置唯一标识符：通过设置一个 Cookie 来为每个客户端生成并存储唯一的用户 ID。
读取唯一标识符：从请求中读取该 Cookie，并将其传递给后端服务或记录在日志中。
可配置的 Cookie 参数：可以自定义 Cookie 的名称、路径、过期时间等属性。

常用指令

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

userid: 启用用户 ID 生成和设置。可以在 http、server 或 location 上下文中使用。
userid_name: 设置用于存储用户 ID 的 Cookie 名称，默认值是 uid。
userid_domain: 设置 Cookie 的域名，确保在多个子域之间共享 Cookie。
userid_path: 设置 Cookie 的路径，默认是 /。
userid_expires: 设置 Cookie 的过期时间。可以是一个具体的日期时间字符串，也可以是一个相对的时间间隔（如 1h 表示一小时）。
userid_service: 设置服务名称，用于生成用户 ID。如果你有多个不同的应用需要独立的用户 ID，可以通过这个参数来区分。
userid_mark: 在响应头中添加一个标记，表示用户 ID 已经被设置。这对于调试和确认是否正确设置了用户 ID 很有帮助。

使用示例

以下是一些具体的配置示例，展示了如何使用 ngx_http_userid_module 来设置和读取用户 ID。

基本配置

假设你想为每个访问者设置一个唯一的用户 ID，并将其存储在一个名为 user_id 的 Cookie 中：

http {# 启用用户 ID 生成和设置userid on;# 设置 Cookie 名称为 user_iduserid_name user_id;# 设置 Cookie 的过期时间为 30 天userid_expires 30d;server {listen 80;server_name example.com;location / {# 根目录设置root /var/www/html;index index.html index.htm;}}
}

在这个例子中：

userid on; 启用了用户 ID 的生成和设置。
userid_name user_id; 将 Cookie 名称设置为 user_id。
userid_expires 30d; 设置了 Cookie 的过期时间为 30 天。

跨子域共享 Cookie

如果你想在多个子域之间共享用户 ID，可以设置 userid_domain 参数：

http {# 启用用户 ID 生成和设置userid on;# 设置 Cookie 名称为 user_iduserid_name user_id;# 设置 Cookie 的过期时间为 30 天userid_expires 30d;# 设置 Cookie 的域名为 .example.com，以便在所有子域间共享userid_domain .example.com;server {listen 80;server_name example.com;location / {# 根目录设置root /var/www/html;index index.html index.htm;}}
}

在这个例子中：

userid_domain .example.com; 设置了 Cookie 的域名为 .example.com，这样所有的子域都可以访问这个 Cookie。

在响应头中添加标记

为了方便调试和确认用户 ID 是否已正确设置，可以在响应头中添加一个标记：

http {# 启用用户 ID 生成和设置userid on;# 设置 Cookie 名称为 user_iduserid_name user_id;# 设置 Cookie 的过期时间为 30 天userid_expires 30d;# 在响应头中添加标记userid_mark on;server {listen 80;server_name example.com;location / {# 根目录设置root /var/www/html;index index.html index.htm;}}
}

在这个例子中：

userid_mark on; 在响应头中添加了一个标记，表示用户 ID 已经被设置。你可以通过查看响应头来确认这一点。

注意事项

安全性：虽然 ngx_http_userid_module 提供了基本的用户标识功能，但它并不提供加密或签名机制。如果你需要更高的安全性，建议结合其他安全措施（如 HTTPS、签名 Cookie 等）来保护用户数据。
隐私合规：在某些地区（如欧盟），收集和存储用户标识符可能受到隐私法规（如 GDPR）的限制。请确保你的使用符合相关法律法规，并在必要时获得用户的同意。
性能影响：设置和读取 Cookie 对性能的影响很小，但如果在高并发环境下频繁操作大量 Cookie，可能会增加一定的负载。因此，在高并发环境下，请根据实际情况调整配置。
测试验证：在部署之前进行全面测试，确保所有配置按预期工作，并检查是否有任何潜在的问题（如 Cookie 未正确设置、跨域问题等）。

2.56.1 指令列表

userid

userid 指令用于控制用户标识（User ID）的生成和使用。这个指令帮助识别和跟踪客户端请求。

Syntax:	userid on | v1 | log | off;
Default:	userid off;
Context:	http, server, location

on：启用用户标识功能。
v1：启用并使用旧版本的用户标识功能。
log：仅记录用户标识信息而不实际启用用户标识功能。
off：禁用用户标识功能（默认值）。

案例

基本用法

最简单的 userid 用法是指定是否启用用户标识功能：

http {userid on;server {listen 80;server_name example.com;location / {proxy_pass http://backend;}}
}

在这个例子中：

设置了 userid on，这意味着Nginx将启用用户标识功能。

动态设置不同配置

你可以根据不同的域名或服务器块动态设置不同的用户标识选项：

server {listen 80;server_name example1.com;# 对example1.com启用用户标识功能userid on;location / {proxy_pass http://backend_example1;}
}server {listen 80;server_name example2.com;# 对example2.com仅记录用户标识信息userid log;location / {proxy_pass http://backend_example2;}
}

在这个例子中：

对于 example1.com，设置了 userid on。
对于 example2.com，设置了 userid log。

注意事项

隐私与安全：确保用户标识功能的使用符合隐私政策和安全要求。
适用场景：适用于需要识别和跟踪客户端请求的应用场景。例如，在分析用户行为、个性化内容推荐等环境中使用。
调试和监控：如果你遇到用户标识问题，可以检查以下几点：
- 确保用户标识设置合理，并符合你的需求。
- 查看Nginx的日志文件，确认是否有与此相关的警告或错误信息。
- 使用工具模拟不同负载条件下的请求进行测试，确保在各种情况下都能正常工作。

userid_domain

userid_domain 指令用于指定用户标识的域名。这个指令帮助在跨域环境下管理用户标识。

Syntax:	userid_domain name | none;
Default:	userid_domain none;
Context:	http, server, location

name：指定用户标识的域名。
none：不指定用户标识的域名（默认值）。

案例

基本用法

最简单的 userid_domain 用法是指定一个具体的域名：

http {userid on;userid_domain example.com;server {listen 80;server_name example.com;location / {proxy_pass http://backend;}}
}

在这个例子中：

设置了 userid_domain example.com，这意味着Nginx将在用户标识中使用 example.com 域名。

动态设置不同配置

你可以根据不同的域名或服务器块动态设置不同的用户标识域名：

server {listen 80;server_name example1.com;userid on;userid_domain example1.com;location / {proxy_pass http://backend_example1;}
}server {listen 80;server_name example2.com;userid on;userid_domain example2.com;location / {proxy_pass http://backend_example2;}
}

在这个例子中：

对于 example1.com，设置了 userid_domain example1.com。
对于 example2.com，设置了 userid_domain example2.com。

注意事项

跨域管理：确保在跨域环境下正确配置用户标识域名，避免冲突和混乱。
适用场景：适用于需要在跨域环境下管理用户标识的应用场景。例如，在多域名网站、分布式系统等环境中使用。
调试和监控：如果你遇到用户标识域名问题，可以检查以下几点：
- 确保用户标识域名设置合理，并符合你的需求。
- 查看Nginx的日志文件，确认是否有与此相关的警告或错误信息。
- 使用工具模拟不同负载条件下的请求进行测试，确保在各种情况下都能正常工作。

userid_expires

userid_expires 指令用于指定用户标识的有效期。这个指令帮助控制用户标识的生命周期。

Syntax:	userid_expires time | max | off;
Default:	userid_expires off;
Context:	http, server, location

time：指定用户标识的有效期，如 1h 表示1小时。
max：设置最大有效期。
off：禁用用户标识的有效期（默认值）。

案例

基本用法

最简单的 userid_expires 用法是指定一个具体的有效期：

http {userid on;userid_expires 1h;server {listen 80;server_name example.com;location / {proxy_pass http://backend;}}
}

在这个例子中：

设置了 userid_expires 1h，这意味着用户标识的有效期为1小时。

动态设置不同配置

你可以根据不同的域名或服务器块动态设置不同的用户标识有效期：

server {listen 80;server_name example1.com;userid on;userid_expires 1h;location / {proxy_pass http://backend_example1;}
}server {listen 80;server_name example2.com;userid on;userid_expires 24h;location / {proxy_pass http://backend_example2;}
}

在这个例子中：

对于 example1.com，设置了 userid_expires 1h。
对于 example2.com，设置了 userid_expires 24h。

注意事项

有效期管理：合理设置用户标识的有效期，避免过长导致的安全风险或过短影响用户体验。
适用场景：适用于需要控制用户标识生命周期的应用场景。例如，在需要短期会话跟踪的临时活动、短期促销等环境中使用。
调试和监控：如果你遇到用户标识有效期问题，可以检查以下几点：
- 确保用户标识有效期设置合理，并符合你的需求。
- 查看Nginx的日志文件，确认是否有与此相关的警告或错误信息。
- 使用工具模拟不同负载条件下的请求进行测试，确保在各种情况下都能正常工作。

userid_flags

userid_flags 指令用于指定用户标识的附加标志。这个指令帮助进一步定制用户标识的行为。

Syntax:	userid_flags off | flag ...;
Default:	userid_flags off;
Context:	http, server, location
This directive appeared in version 1.19.3.

off：禁用所有附加标志（默认值）。
flag：指定一个或多个附加标志，如 secure、httponly 等。

案例

基本用法

最简单的 userid_flags 用法是指定一个或多个附加标志：

http {userid on;userid_flags secure httponly;server {listen 80;server_name example.com;location / {proxy_pass http://backend;}}
}

在这个例子中：

设置了 userid_flags secure httponly，这意味着用户标识将带有 Secure 和 HttpOnly 标志。

动态设置不同配置

你可以根据不同的域名或服务器块动态设置不同的用户标识标志：

server {listen 80;server_name example1.com;userid on;userid_flags secure;location / {proxy_pass http://backend_example1;}
}server {listen 80;server_name example2.com;userid on;userid_flags httponly;location / {proxy_pass http://backend_example2;}
}

在这个例子中：

对于 example1.com，设置了 userid_flags secure。
对于 example2.com，设置了 userid_flags httponly。

注意事项

安全性增强：通过设置适当的标志，可以增强用户标识的安全性，防止潜在的安全威胁。
适用场景：适用于需要增强用户标识安全性的应用场景。例如，在金融网站、电子商务平台等环境中使用。
调试和监控：如果你遇到用户标识标志问题，可以检查以下几点：
- 确保用户标识标志设置合理，并符合你的需求。
- 查看Nginx的日志文件，确认是否有与此相关的警告或错误信息。
- 使用工具模拟不同负载条件下的请求进行测试，确保在各种情况下都能正常工作。

userid_mark

userid_mark 指令用于设置用户 ID 标记字符，该字符用于分隔用户 ID 和其他信息。

Syntax:	userid_mark letter | digit | = | off;
Default:	userid_mark off;
Context:	http, server, location

letter：使用字母作为标记字符。
digit：使用数字作为标记字符。
=：使用等号（=）作为标记字符。
off：禁用标记字符，默认值为 off。

案例

基本用法

最简单的 userid_mark 用法是指定一个标记字符：

server {listen 80;server_name example.com;# 使用等号作为标记字符userid_mark =;# 设置用户 ID 的名称userid_name user_id;location / {proxy_pass http://backend.example.com;}
}

在这个例子中：

使用等号（=）作为标记字符。

禁用标记字符

你可以选择禁用标记字符：

server {listen 80;server_name example.com;# 禁用标记字符userid_mark off;# 设置用户 ID 的名称userid_name user_id;location / {proxy_pass http://backend.example.com;}
}

在这个例子中：

禁用了标记字符。

注意事项

兼容性：确保所选的标记字符与现有系统和应用兼容，避免冲突或解析错误。
适用场景：适用于需要在生成的 Cookie 或其他上下文中区分用户 ID 和其他信息的应用场景。例如，在处理多用户会话时，可能需要明确的标记字符来区分不同部分。
调试和监控：如果你遇到标记字符问题，可以检查以下几点：
- 确保标记字符未与其他符号冲突。
- 查看Nginx的日志文件，确认是否有与此相关的警告或错误信息。

userid_name

userid_name 指令用于设置用户 ID 的名称。

Syntax:	userid_name name;
Default:	userid_name uid;
Context:	http, server, location

name：指定用户 ID 的名称，默认值为 uid。

案例

基本用法

最简单的 userid_name 用法是指定用户 ID 的名称：

server {listen 80;server_name example.com;# 使用等号作为标记字符userid_mark =;# 设置用户 ID 的名称为 user_iduserid_name user_id;location / {proxy_pass http://backend.example.com;}
}

在这个例子中：

用户 ID 的名称设置为 user_id。

使用默认值

你可以选择使用默认值：

server {listen 80;server_name example.com;# 使用等号作为标记字符userid_mark =;# 使用默认的用户 ID 名称（uid）userid_name uid;location / {proxy_pass http://backend.example.com;}
}

在这个例子中：

用户 ID 的名称为默认值 uid。

注意事项

命名规范：确保用户 ID 名称符合应用的命名规范，并且不与其他变量冲突。
适用场景：适用于需要在 Cookie 或其他上下文中标识用户 ID 的应用场景。例如，在处理用户会话时，明确的用户 ID 名称有助于管理和跟踪用户活动。
调试和监控：如果你遇到用户 ID 名称问题，可以检查以下几点：
- 确保名称未与其他变量冲突。
- 查看Nginx的日志文件，确认是否有与此相关的警告或错误信息。

userid_p3p

userid_p3p 指令用于设置 P3P（Platform for Privacy Preferences Project）策略头。

Syntax:	userid_p3p string | none;
Default:	userid_p3p none;
Context:	http, server, location

string：指定要发送的 P3P 策略字符串。
none：不发送 P3P 策略头，默认值为 none。

案例

基本用法

最简单的 userid_p3p 用法是指定 P3P 策略字符串：

server {listen 80;server_name example.com;# 设置用户 ID 的名称为 user_iduserid_name user_id;# 使用等号作为标记字符userid_mark =;# 设置 P3P 策略头userid_p3p 'CP="IDC DSP COR ADM DEVi TAIi PSA PSD IVAi IVDi CONi HIS OUR IND CNT"';location / {proxy_pass http://backend.example.com;}
}

在这个例子中：

设置了 P3P 策略头为 'CP="IDC DSP COR ADM DEVi TAIi PSA PSD IVAi IVDi CONi HIS OUR IND CNT"'。

不发送 P3P 策略头

你可以选择不发送 P3P 策略头：

server {listen 80;server_name example.com;# 设置用户 ID 的名称为 user_iduserid_name user_id;# 使用等号作为标记字符userid_mark =;# 不发送 P3P 策略头userid_p3p none;location / {proxy_pass http://backend.example.com;}
}

在这个例子中：

不发送 P3P 策略头。

注意事项

隐私合规：确保你的 P3P 策略字符串准确反映了网站的实际隐私政策，以遵守相关法规和标准。
适用场景：适用于需要处理跨域请求和第三方 Cookie 的应用场景。例如，在涉及多个子域名或外部服务的集成时，适当的 P3P 策略头可以帮助浏览器更好地处理这些请求。
调试和监控：如果你遇到 P3P 策略头问题，可以检查以下几点：
- 确保策略字符串正确无误。
- 查看Nginx的日志文件，确认是否有与此相关的警告或错误信息。

userid_path

userid_path 指令用于设置用户 ID 的路径。

Syntax:	userid_path path;
Default:	userid_path /;
Context:	http, server, location

path：指定用户 ID 的路径，默认值为 /。

案例

基本用法

最简单的 userid_path 用法是指定用户 ID 的路径：

server {listen 80;server_name example.com;# 设置用户 ID 的名称为 user_iduserid_name user_id;# 使用等号作为标记字符userid_mark =;# 设置用户 ID 的路径为 /secureuserid_path /secure;location / {proxy_pass http://backend.example.com;}
}

在这个例子中：

用户 ID 的路径设置为 /secure。

使用默认值

你可以选择使用默认值：

server {listen 80;server_name example.com;# 设置用户 ID 的名称为 user_iduserid_name user_id;# 使用等号作为标记字符userid_mark =;# 使用默认的用户 ID 路径（/）userid_path /;location / {proxy_pass http://backend.example.com;}
}

在这个例子中：

用户 ID 的路径为默认值 /。

注意事项

路径控制：确保路径设置符合实际需求，避免不必要的路径限制导致用户 ID 无法正常使用。
适用场景：适用于需要限制用户 ID 作用范围的应用场景。例如，在处理安全区域或敏感数据时，可以将用户 ID 的作用范围限制在特定路径下。
调试和监控：如果你遇到用户 ID 路径问题，可以检查以下几点：
- 确保路径设置正确无误。
- 查看Nginx的日志文件，确认是否有与此相关的警告或错误信息。

userid_service

userid_service 指令用于指定用户ID服务的地址，通常与Nginx的用户跟踪模块（如ngx_http_userid_module）一起使用。这个模块可以帮助识别和跟踪用户的会话，通过设置和读取HTTP cookie来实现。

Syntax:	userid_service number;
Default:	userid_service IP address of the server;
Context:	http, server, location

number：可以是一个具体的数字或IP地址，表示用户ID服务的地址。
默认值：通常是服务器的IP地址。

案例

基本用法

假设我们希望将用户ID服务的地址设置为特定的IP地址（例如 192.168.1.100）：

http {userid_service 192.168.1.100;  # 设置用户ID服务的地址为 192.168.1.100server {listen 80;server_name example.com;location / {root /usr/share/nginx/html;index index.html;}}
}

使用默认值

如果我们希望使用服务器自身的IP地址作为用户ID服务的地址：

http {# 默认情况下，userid_service 使用服务器自身的IP地址server {listen 80;server_name example.com;location / {root /usr/share/nginx/html;index index.html;}}
}

注意事项

用户跟踪：确保正确配置用户ID服务地址，以便能够有效跟踪用户的会话。
安全性：确保用户ID服务的安全性，避免未经授权的访问。