nginxngx_stream_module(3)指令详解

nginx ngx_stream_module(3) 指令详解

nginx 模块目录

nginx 全指令目录

一、目录 1.1 模块简介

ngx_stream_upstream_module：上游服务器模块，允许定义一组后端服务器，并控制如何将TCP/UDP连接分发给这些服务器。支持多种负载均衡策略（如轮询、最少连接等），并提供了健康检查等功能。常用的指令包括 upstream 块用于定义后端服务器组，以及 server 指令指定具体的服务器地址和端口。

ngx_stream_upstream_hc_module：上游服务器健康检查模块，用于检测后端服务器的健康状态。可以根据设定的条件（如响应时间、成功/失败次数等）判断服务器是否可用，并自动从负载均衡池中移除不健康的服务器。这有助于提高系统的可靠性和稳定性。

ngx_stream_zone_sync_module：区域同步模块，允许在多个Nginx实例之间同步共享内存区域（zone）的数据。这对于需要跨多台服务器保持一致状态的应用场景非常有用，例如会话粘滞、限流规则等。通过配置同步机制，可以确保所有Nginx实例都能访问到最新的状态信息。

ngx_google_perftools_module：Google性能工具模块，提供与Google的性能分析工具（如tcmalloc、CPU Profiler等）的集成。这个模块可以帮助开发者进行内存管理和性能分析，识别潜在的性能瓶颈。需要注意的是，该模块通常不是标准Nginx的一部分，可能需要额外编译或安装。

ngx_mgmt_module：管理模块，提供对Nginx运行时配置和状态的管理接口。它允许通过API动态修改配置、查看状态信息、重启工作进程等操作。这对于实现自动化运维和监控非常有用。请注意，该模块并不是标准Nginx的一部分，可能需要特定版本或插件支持。

ngx_otel_module：OpenTelemetry支持模块，允许Nginx与OpenTelemetry生态系统集成，进行分布式追踪和监控。通过收集和发送跟踪数据，可以帮助开发者更好地理解应用的性能和行为，特别是在微服务架构中。该模块支持生成和传输符合OpenTelemetry标准的追踪数据，便于与其他监控系统集成。

1.2 指令目录 1.2.1 ngx_stream_upstream_module upstreamserverzonestatehashleast_connleast_timerandomresolverresolver_timeout 1.2.2 ngx_stream_upstream_hc_module health_checkmatch 1.2.3 ngx_stream_zone_sync_module zone_synczone_sync_bufferszone_sync_connect_retry_intervalzone_sync_connect_timeoutzone_sync_intervalzone_sync_recv_buffer_sizezone_sync_serverzone_sync_sslzone_sync_ssl_certificatezone_sync_ssl_certificate_keyzone_sync_ssl_cipherszone_sync_ssl_conf_commandzone_sync_ssl_crlzone_sync_ssl_namezone_sync_ssl_password_filezone_sync_ssl_protocolszone_sync_ssl_server_namezone_sync_ssl_trusted_certificatezone_sync_ssl_verifyzone_sync_ssl_verify_depthzone_sync_timeout 1.2.4 ngx_google_perftools_module google_perftools_profiles 1.2.5 ngx_mgmt_module mgmtenforce_initial_reportlicense_tokenresolverssl_crlssl_trusted_certificatessl_verifystate_pathusage_report 1.2.6 ngx_otel_module otel_exporterotel_service_nameotel_traceotel_trace_contextotel_span_nameotel_span_attr 二、解释 2.1 ngx_stream_upstream_module

ngx_stream_upstream_module 是 Nginx 的一个核心模块，用于定义和管理后端服务器组（称为上游服务器组），以便在处理 TCP 和 UDP 流量时进行负载均衡。这个模块允许你配置多个后端服务器，并提供多种负载均衡算法和其他高级功能，如健康检查、会话持久化等。

主要功能

负载均衡：支持多种负载均衡算法，如轮询（默认）、最少连接、哈希等。健康检查：可以监控后端服务器的状态，自动剔除不可用的服务器。会话持久化：通过哈希算法确保同一客户端的请求总是被分配到同一个后端服务器。动态配置：支持动态添加或移除后端服务器。

常用指令

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

upstream：定义一个后端服务器组，包含多个服务器。

server：指定一个后端服务器的地址和端口，支持附加参数如权重、最大失败次数等。

least_conn：使用最少连接算法进行负载均衡。

hash：基于哈希值进行会话持久化。

ip_hash：基于客户端 IP 地址进行哈希计算，实现会话持久化。

health_check：启用健康检查，监控后端服务器的状态。

使用示例

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

定义和使用上游服务器组

假设你想将所有到达 192.168.1.1:12345 的 TCP 流量代理到一组后端服务器：

stream { upstream backend_servers { server backend1.example :12345; server backend2.example :12345; } server { listen 12345; proxy_pass backend_servers; } }

在这个例子中：

upstream backend_servers { ... } 定义了一个名为 backend_servers 的上游服务器组，包含两个后端服务器。server { ... } 监听在 12345 端口上的流量，并将其代理到 backend_servers 组中的服务器。

负载均衡算法

你可以使用不同的负载均衡算法来分配流量。例如，使用最少连接算法：

stream { upstream backend_servers { least_conn; # 使用最少连接算法 server backend1.example :12345; server backend2.example :12345; } server { listen 12345; proxy_pass backend_servers; } }

在这个例子中：

least_conn; 启用了最少连接算法，Nginx 会将新请求分配给当前连接数最少的服务器。

会话持久化

为了确保同一客户端的请求总是被分配到同一个后端服务器，可以使用哈希算法进行会话持久化：

stream { upstream backend_servers { hash $remote_addr consistent; # 使用客户端 IP 地址进行哈希计算 server backend1.example :12345; server backend2.example :12345; } server { listen 12345; proxy_pass backend_servers; } }

在这个例子中：

hash $remote_addr consistent; 使用客户端 IP 地址进行哈希计算，确保同一客户端的请求总是被分配到相同的后端服务器。

如果你希望使用更简单的基于 IP 地址的哈希算法，可以使用 ip_hash：

stream { upstream backend_servers { ip_hash; # 使用 IP 地址进行哈希计算 server backend1.example :12345; server backend2.example :12345; } server { listen 12345; proxy_pass backend_servers; } }

注意事项

性能考虑：

根据实际需求选择合适的负载均衡算法和会话持久化策略，避免不必要的资源浪费。对于高并发场景，合理设置超时时间和重试机制，减少延迟和资源消耗。

安全性：

确保后端服务器的安全性，避免未经授权的访问。对敏感数据进行加密传输，防止中间人攻击。

日志记录：

合理配置日志级别和格式，便于监控和故障排查。特别是注意记录与负载均衡和健康检查相关的错误信息和性能指标。 2.1.1 指令列表 upstream server zone state hash least_conn least_time random resolver resolver_timeout 2.2 ngx_stream_upstream_hc_module

ngx_stream_upstream_hc_module 是 Nginx 的一个模块，用于在流（stream）上下文中为上游服务器提供健康检查功能。这个模块可以帮助你确保只有健康的后端服务器接收客户端请求，从而提高系统的可用性和可靠性。

主要功能

健康检查：可以配置不同的健康检查方法来监控后端服务器的状态。自动剔除不可用的服务器：当检测到某个后端服务器不可用时，Nginx 会自动将其从负载均衡池中移除，并在恢复后重新加入。灵活的配置选项：支持多种健康检查参数，如检查间隔、超时时间、失败次数等。

使用示例

基本健康检查

假设你希望为一组后端服务器启用基本的健康检查：

stream { upstream backend { server backend1.example :12345; server backend2.example :12345; # 启用健康检查 health_check; } server { listen 12345; proxy_pass backend; } }

在这个例子中：

upstream backend 定义了一个包含两个后端服务器的组。health_check; 启用了默认的健康检查配置。

自定义健康检查参数

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

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

在这个例子中：

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

基于特定端口的健康检查

假设你希望为每个后端服务器指定不同的健康检查端口：

stream { upstream backend { server backend1.example :12345; server backend2.example :12345; # 基于特定端口的健康检查 health_check port=8080; } server { listen 12345; proxy_pass backend; } }

在这个例子中：

health_check port=8080; 指定了健康检查使用的端口号为 8080，而不是 upstream 中定义的端口号。

高级健康检查匹配规则

假设你希望定义更复杂的健康检查匹配规则，例如通过发送特定数据并检查返回的数据：

首先定义一个匹配规则：

stream { match healthy { send "HEALTH_CHECK\r\n"; expect ~* "OK"; } upstream backend { server backend1.example :12345; server backend2.example :12345; # 使用自定义匹配规则进行健康检查 health_check match=healthy; } server { listen 12345; proxy_pass backend; } }

在这个例子中：

match healthy 定义了一个名为 healthy 的匹配规则，要求发送字符串 "HEALTH_CHECK\r\n" 并期望接收到包含 "OK" 的响应。health_check match=healthy; 使用该匹配规则进行健康检查。

结合 SSL/TLS 加密

假设你希望在启用 SSL/TLS 加密的同时进行健康检查：

stream { upstream backend { server backend1.example :12345; server backend2.example :12345; # 启用健康检查 health_check; # SSL 证书和私钥 ssl_certificate /etc/nginx/ssl/example_com.crt; ssl_certificate_key /etc/nginx/ssl/example_com.key; # 支持的 SSL/TLS 协议版本 ssl_protocols TLSv1.2 TLSv1.3; # 支持的加密套件 ssl_ciphers HIGH:!aNULL:!MD5; } server { listen 12345 ssl; proxy_pass backend; } }

在这个例子中：

ssl_certificate 和 ssl_certificate_key 分别指定了服务器证书和私钥文件的路径。ssl_protocols TLSv1.2 TLSv1.3; 指定了支持的 SSL/TLS 协议版本。ssl_ciphers HIGH:!aNULL:!MD5; 指定了支持的加密套件。

注意事项

健康检查频率：合理设置健康检查的频率，避免过于频繁的检查对后端服务器造成额外负担，同时确保及时发现不可用的服务器。

超时时间：根据实际网络情况调整健康检查的超时时间，避免因网络延迟导致误判。

匹配规则：如果需要更复杂的健康检查逻辑，可以通过定义 match 规则来精确控制健康检查的行为。

SSL/TLS 加密：如果后端服务器启用了 SSL/TLS 加密，请确保健康检查也使用相应的加密配置，以保证安全通信。

2.2.1 指令列表 health_check match 2.3 ngx_stream_zone_sync_module

ngx_stream_zone_sync_module 是 Nginx 的一个模块，用于在多个 Nginx 实例之间同步共享内存区域（zones）中的数据。这个模块特别适用于需要跨多个服务器实例共享会话状态、限速信息或其他需要保持一致性的数据的场景。

主要功能

数据同步：在多个 Nginx 实例之间同步共享内存区域中的数据。高可用性：通过数据同步实现负载均衡和故障转移时的数据一致性。灵活配置：支持多种同步策略和配置选项，以满足不同的应用场景需求。

使用示例

以下是一些具体的配置示例，展示了如何使用 ngx_stream_zone_sync_module 来同步共享内存区域中的数据。

基本配置

假设你有两个 Nginx 实例，并希望在这两个实例之间同步一个名为 my_zone 的共享内存区域：

stream { upstream sync_servers { server 192.168.1.10:12345; server 192.168.1.11:12345; } # 定义共享内存区域 zone my_zone 64k; server { listen 12345; proxy_pass backend_server; # 启用同步并指定同步的目标服务器和共享内存区域 zone_sync { sync_server sync_servers; zone my_zone; } } }

在这个例子中：

upstream sync_servers { ... } 定义了同步的目标服务器组。zone my_zone 64k; 定义了一个名为 my_zone 的共享内存区域，大小为 64KB。在 server 块中，启用了数据同步，并指定了同步的目标服务器和共享内存区域。

结合限速功能

假设你想在多个 Nginx 实例之间同步限速信息：

stream { upstream sync_servers { server 192.168.1.10:12345; server 192.168.1.11:12345; } # 定义共享内存区域 limit_conn_zone $binary_remote_addr zone=addr:10m; limit_conn addr 10; # 定义另一个共享内存区域用于同步 zone my_zone 64k; server { listen 12345; proxy_pass backend_server; # 启用同步并指定同步的目标服务器和共享内存区域 zone_sync { sync_server sync_servers; zone my_zone; } # 应用限速规则 limit_conn addr; } }

在这个例子中：

limit_conn_zone $binary_remote_addr zone=addr:10m; 定义了一个限速共享内存区域 addr，用于存储客户端 IP 地址的连接数。limit_conn addr 10; 设置每个客户端 IP 地址最多允许 10 个并发连接。zone my_zone 64k; 定义了另一个共享内存区域 my_zone，用于同步其他类型的数据。在 server 块中，启用了数据同步，并指定了同步的目标服务器和共享内存区域，同时应用了限速规则。

多区域同步

假设你想同步多个不同类型的共享内存区域：

stream { upstream sync_servers { server 192.168.1.10:12345; server 192.168.1.11:12345; } # 定义多个共享内存区域 zone rate_limit_zone 64k; zone session_data_zone 128k; server { listen 12345; proxy_pass backend_server; # 启用同步并指定同步的目标服务器和共享内存区域 zone_sync { sync_server sync_servers; zone rate_limit_zone; zone session_data_zone; } # 其他配置... } }

在这个例子中：

zone rate_limit_zone 64k; 和 zone session_data_zone 128k; 分别定义了两个不同的共享内存区域。在 server 块中，启用了数据同步，并指定了同步的目标服务器和多个共享内存区域。

注意事项

性能优化： 尽量减少不必要的同步操作，以避免增加网络负担和延迟。根据实际需求合理设置共享内存区域的大小，避免浪费资源。 安全性： 确保同步目标服务器的安全性，防止未经授权的访问。可以考虑使用 TLS 加密连接。确保共享内存区域的数据安全，防止数据泄露或篡改。 测试验证：在部署之前进行全面测试，确保所有配置按预期工作，并检查是否有任何潜在的问题（如同步失败、数据不一致等）。 2.3.1 指令列表 zone_sync

zone_sync 指令用于启用或禁用 Nginx 流模块中的区域同步功能。区域同步功能允许不同 Nginx 实例之间共享状态信息，这对于负载均衡和高可用性场景非常有用。

Syntax: zone_sync; Default: — Context: server 无参数：启用区域同步功能。

案例

基本用法

最简单的 zone_sync 用法是启用区域同步功能：

stream { upstream backend { server 192.168.1.1:12345; server 192.168.1.2:12345; } server { listen 12345; proxy_pass backend; # 启用区域同步功能 zone_sync; } }

在这个例子中：

当 Nginx 处理到 backend 的连接时，将启用区域同步功能，以便与其他 Nginx 实例共享状态信息。

注意事项

配置一致性：确保所有参与同步的 Nginx 实例具有相同的配置，以避免不一致的问题。性能影响：区域同步可能会增加网络流量和处理开销，特别是在高并发环境下。 zone_sync_buffers

zone_sync_buffers 指令用于设置用于区域同步的缓冲区数量和大小。这有助于优化同步数据的传输效率。

Syntax: zone_sync_buffers number size; Default: zone_sync_buffers 8 4k|8k; Context: stream, server number：用于区域同步的缓冲区数量，默认为 8。size：每个缓冲区的大小，默认为 4 KB 或 8 KB（取决于平台）。

案例

基本用法

最简单的 zone_sync_buffers 用法是指定缓冲区数量和大小：

stream { upstream backend { server 192.168.1.1:12345; server 192.168.1.2:12345; } server { listen 12345; proxy_pass backend; # 设置区域同步的缓冲区数量为 16，每个缓冲区大小为 8 KB zone_sync_buffers 16 8k; } }

在这个例子中：

区域同步功能将使用 16 个缓冲区，每个缓冲区大小为 8 KB。

复杂用法

根据不同的应用场景调整缓冲区数量和大小：

stream { upstream backend_tcp { server 192.168.1.1:12345; } upstream backend_udp { server 192.168.1.1:54321; } server { listen 12345; proxy_pass backend_tcp; # 对 TCP 流量设置较大的缓冲区 zone_sync_buffers 32 16k; } server { listen 54321 udp; proxy_pass backend_udp; # 对 UDP 流量设置较小的缓冲区 zone_sync_buffers 8 4k; } }

在这个例子中：

对于 TCP 流量，设置了 32 个缓冲区，每个缓冲区大小为 16 KB；对于 UDP 流量，设置了 8 个缓冲区，每个缓冲区大小为 4 KB。

注意事项

内存使用：合理设置缓冲区数量和大小，避免占用过多内存。传输效率：较大的缓冲区可以提高传输效率，但在高并发环境下可能会增加延迟。 zone_sync_connect_retry_interval

zone_sync_connect_retry_interval 指令用于设置区域同步连接失败后的重试间隔时间。这有助于在连接问题发生时自动恢复同步功能。

Syntax: zone_sync_connect_retry_interval time; Default: zone_sync_connect_retry_interval 1s; Context: stream, server time：连接失败后的重试间隔时间，默认为 1 秒。

案例

基本用法

最简单的 zone_sync_connect_retry_interval 用法是指定重试间隔时间：

stream { upstream backend { server 192.168.1.1:12345; server 192.168.1.2:12345; } server { listen 12345; proxy_pass backend; # 设置连接失败后的重试间隔时间为 2 秒 zone_sync_connect_retry_interval 2s; } }

在这个例子中：

如果区域同步连接失败，Nginx 将在 2 秒后重试连接。

复杂用法

根据不同的应用场景调整重试间隔时间：

stream { upstream backend_tcp { server 192.168.1.1:12345; } upstream backend_udp { server 192.168.1.1:54321; } server { listen 12345; proxy_pass backend_tcp; # 对 TCP 流量设置较长的重试间隔时间 zone_sync_connect_retry_interval 5s; } server { listen 54321 udp; proxy_pass backend_udp; # 对 UDP 流量设置较短的重试间隔时间 zone_sync_connect_retry_interval 1s; } }

在这个例子中：

对于 TCP 流量，设置了 5 秒的重试间隔时间；对于 UDP 流量，设置了 1 秒的重试间隔时间。

注意事项

重试频率：过短的重试间隔可能导致频繁的无效重试，增加服务器负载；过长则可能导致长时间无法恢复同步。网络状况：根据实际网络状况调整重试间隔时间，以平衡恢复速度和资源消耗。 zone_sync_connect_timeout

zone_sync_connect_timeout 指令用于设置区域同步连接的超时时间。这有助于防止长时间等待导致的性能问题。

Syntax: zone_sync_connect_timeout time; Default: zone_sync_connect_timeout 5s; Context: stream, server time：连接超时时间，默认为 5 秒。

案例

基本用法

最简单的 zone_sync_connect_timeout 用法是指定连接超时时间：

stream { upstream backend { server 192.168.1.1:12345; server 192.168.1.2:12345; } server { listen 12345; proxy_pass backend; # 设置连接超时时间为 10 秒 zone_sync_connect_timeout 10s; } }

在这个例子中：

如果区域同步连接未能在 10 秒内建立，Nginx 将返回错误。

复杂用法

根据不同的应用场景调整连接超时时间：

stream { upstream backend_tcp { server 192.168.1.1:12345; } upstream backend_udp { server 192.168.1.1:54321; } server { listen 12345; proxy_pass backend_tcp; # 对 TCP 流量设置较长的连接超时时间 zone_sync_connect_timeout 15s; } server { listen 54321 udp; proxy_pass backend_udp; # 对 UDP 流量设置较短的连接超时时间 zone_sync_connect_timeout 5s; } }

在这个例子中：

对于 TCP 流量，设置了 15 秒的连接超时时间；对于 UDP 流量，设置了 5 秒的连接超时时间。

注意事项

超时设置：合理的超时时间可以避免不必要的长时间等待，同时确保连接尝试有足够的时间完成。网络延迟：根据实际网络延迟情况调整超时时间，以确保在高延迟环境下的正常工作。 zone_sync_interval

zone_sync_interval 用于指定流模块中共享内存区域同步的时间间隔。这有助于控制数据同步的频率，从而平衡系统资源使用和数据一致性。

Syntax: zone_sync_interval time; Default: zone_sync_interval 1s; Context: stream, server time：指定同步时间间隔，默认值为 1 秒。

案例

基本用法

最简单的 zone_sync_interval 用法是指定同步时间间隔：

stream { upstream backend { zone backend_zone 64k; server backend1.example :12345; server backend2.example :12345; } server { listen 12345; proxy_pass backend; zone_sync_interval 500ms; # 设置同步时间间隔为 500 毫秒 } }

调整同步频率

根据实际需求调整同步频率：

stream { upstream backend { zone backend_zone 64k; server backend1.example :12345; server backend2.example :12345; } server { listen 12345; proxy_pass backend; # 较长的同步间隔 zone_sync_interval 2s; # 设置同步时间间隔为 2 秒 # 较短的同步间隔 # zone_sync_interval 100ms; # 设置同步时间间隔为 100 毫秒 } }

注意事项

性能优化：较短的同步间隔可以提高数据一致性，但会增加系统开销；较长的同步间隔则相反。适用场景：适用于需要在高并发环境下平衡数据一致性和系统性能的场景。 zone_sync_recv_buffer_size

zone_sync_recv_buffer_size 用于指定流模块中共享内存区域同步时接收缓冲区的大小。这有助于控制接收数据时的缓冲区容量，以适应不同的网络条件和负载情况。

Syntax: zone_sync_recv_buffer_size size; Default: zone_sync_recv_buffer_size 4k|8k; Context: stream, server size：指定接收缓冲区的大小，默认值为 4KB 或 8KB（取决于平台）。

案例

基本用法

最简单的 zone_sync_recv_buffer_size 用法是指定接收缓冲区的大小：

stream { upstream backend { zone backend_zone 64k; server backend1.example :12345; server backend2.example :12345; } server { listen 12345; proxy_pass backend; zone_sync_recv_buffer_size 8k; # 设置接收缓冲区大小为 8 KB } }

调整接收缓冲区大小

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

stream { upstream backend { zone backend_zone 64k; server backend1.example :12345; server backend2.example :12345; } server { listen 12345; proxy_pass backend; # 较小的接收缓冲区 # zone_sync_recv_buffer_size 4k; # 设置接收缓冲区大小为 4 KB # 较大的接收缓冲区 zone_sync_recv_buffer_size 16k; # 设置接收缓冲区大小为 16 KB } }

注意事项

网络条件：较大的接收缓冲区可以更好地处理高带宽或不稳定网络环境，但会占用更多内存。内存管理：合理设置接收缓冲区大小，避免因过大而浪费内存，或因过小而导致频繁的缓冲区溢出。 zone_sync_server

zone_sync_server 用于指定流模块中共享内存区域同步的服务器地址。这允许你将共享内存区域的数据同步到指定的远程服务器上。

Syntax: zone_sync_server address [resolve]; Default: — Context: server address：指定同步服务器的地址。[resolve]：可选参数，指示 Nginx 在启动时解析该地址，并在后续运行中动态更新解析结果。

案例

基本用法

最简单的 zone_sync_server 用法是指定同步服务器地址：

stream { upstream backend { zone backend_zone 64k; server backend1.example :12345; server backend2.example :12345; } server { listen 12345; proxy_pass backend; zone_sync_server 192.168.1.100:12345; # 设置同步服务器地址 } }

动态解析地址

根据实际需求启用动态解析功能：

stream { upstream backend { zone backend_zone 64k; server backend1.example :12345; server backend2.example :12345; } server { listen 12345; proxy_pass backend; zone_sync_server backend-sync.example :12345 resolve; # 启用动态解析 } }

注意事项

地址解析：启用动态解析功能可以在地址变化时自动更新，确保同步服务器的可用性。配置灵活性：通过指定同步服务器地址，可以实现跨服务器的数据同步，提升系统的容错性和扩展性。 zone_sync_ssl

zone_sync_ssl 用于控制是否在共享内存区域同步过程中使用 SSL/TLS 加密。这有助于增强数据传输的安全性，特别是在公网或不可信网络环境中。

Syntax: zone_sync_ssl on | off; Default: zone_sync_ssl off; Context: stream, server on：启用 SSL/TLS 加密。off：禁用 SSL/TLS 加密（默认值）。

案例

启用 SSL/TLS 加密

最简单的 zone_sync_ssl 用法是启用 SSL/TLS 加密：

stream { upstream backend { zone backend_zone 64k; server backend1.example :12345; server backend2.example :12345; } server { listen 12345 ssl; proxy_pass backend; ssl_certificate /etc/nginx/ssl/server.crt; ssl_certificate_key /etc/nginx/ssl/server.key; zone_sync_ssl on; # 启用 SSL/TLS 加密 zone_sync_server 192.168.1.100:12345; } }

禁用 SSL/TLS 加密

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

stream { upstream backend { zone backend_zone 64k; server backend1.example :12345; server backend2.example :12345; } server { listen 12345; proxy_pass backend; zone_sync_ssl off; # 禁用 SSL/TLS 加密 zone_sync_server 192.168.1.100:12345; } }

注意事项

安全性：启用 SSL/TLS 加密可以防止中间人攻击等安全问题，尤其是在公网或不可信网络中。性能影响：SSL/TLS 加密会带来一定的性能开销，在高并发场景下需权衡性能与安全性的平衡。 zone_sync_ssl_certificate

zone_sync_ssl_certificate 指令用于指定用于区域同步的SSL证书文件路径。这个指令帮助配置Nginx以使用特定的SSL证书进行安全的区域同步。

Syntax: zone_sync_ssl_certificate file; Default: — Context: stream, server file：指定SSL证书文件的路径。

案例

基本用法

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

stream { server { listen 12345 ssl; zone_sync_ssl_certificate /etc/nginx/ssl/zone_sync.crt; proxy_pass backend_zone_sync; } }

在这个例子中：

设置了 zone_sync_ssl_certificate /etc/nginx/ssl/zone_sync.crt，这意味着Nginx将使用该路径下的证书文件进行区域同步。

动态设置不同配置

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

stream { server { listen 12345 ssl; zone_sync_ssl_certificate /etc/nginx/ssl/zone_sync_1.crt; proxy_pass backend_zone_sync_1; } server { listen 12346 ssl; zone_sync_ssl_certificate /etc/nginx/ssl/zone_sync_2.crt; proxy_pass backend_zone_sync_2; } }

在这个例子中：

对于监听端口12345的服务器块，设置了 zone_sync_ssl_certificate /etc/nginx/ssl/zone_sync_1.crt。对于监听端口12346的服务器块，设置了 zone_sync_ssl_certificate /etc/nginx/ssl/zone_sync_2.crt。

注意事项

证书管理：确保指定的证书文件路径正确，并且证书是有效的。适用场景：适用于需要通过SSL加密进行区域同步的应用场景。例如，在高可用性集群中进行安全的数据同步。调试和监控：如果你遇到证书问题，可以检查以下几点： 确保证书文件路径正确，并符合你的需求。查看Nginx的日志文件，确认是否有与此相关的警告或错误信息。使用工具模拟不同负载条件下的请求进行测试，确保在各种情况下都能正常工作。 zone_sync_ssl_certificate_key

zone_sync_ssl_certificate_key 指令用于指定用于区域同步的SSL证书密钥文件路径。这个指令帮助配置Nginx以使用特定的SSL证书密钥进行安全的区域同步。

Syntax: zone_sync_ssl_certificate_key file; Default: — Context: stream, server file：指定SSL证书密钥文件的路径。

案例

基本用法

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

stream { server { listen 12345 ssl; zone_sync_ssl_certificate /etc/nginx/ssl/zone_sync.crt; zone_sync_ssl_certificate_key /etc/nginx/ssl/zone_sync.key; proxy_pass backend_zone_sync; } }

在这个例子中：

设置了 zone_sync_ssl_certificate_key /etc/nginx/ssl/zone_sync.key，这意味着Nginx将使用该路径下的密钥文件进行区域同步。

动态设置不同配置

你可以根据不同的服务器块动态设置不同的密钥文件路径：

stream { server { listen 12345 ssl; zone_sync_ssl_certificate /etc/nginx/ssl/zone_sync_1.crt; zone_sync_ssl_certificate_key /etc/nginx/ssl/zone_sync_1.key; proxy_pass backend_zone_sync_1; } server { listen 12346 ssl; zone_sync_ssl_certificate /etc/nginx/ssl/zone_sync_2.crt; zone_sync_ssl_certificate_key /etc/nginx/ssl/zone_sync_2.key; proxy_pass backend_zone_sync_2; } }

在这个例子中：

对于监听端口12345的服务器块，设置了 zone_sync_ssl_certificate_key /etc/nginx/ssl/zone_sync_1.key。对于监听端口12346的服务器块，设置了 zone_sync_ssl_certificate_key /etc/nginx/ssl/zone_sync_2.key。

注意事项

密钥管理：确保指定的密钥文件路径正确，并且密钥是有效的。适用场景：适用于需要通过SSL加密进行区域同步的应用场景。例如，在高可用性集群中进行安全的数据同步。调试和监控：如果你遇到密钥问题，可以检查以下几点： 确保密钥文件路径正确，并符合你的需求。查看Nginx的日志文件，确认是否有与此相关的警告或错误信息。使用工具模拟不同负载条件下的请求进行测试，确保在各种情况下都能正常工作。 zone_sync_ssl_ciphers

zone_sync_ssl_ciphers 指令用于指定用于区域同步的SSL/TLS加密套件。这个指令帮助配置Nginx以使用特定的加密套件进行安全的区域同步。

Syntax: zone_sync_ssl_ciphers ciphers; Default: zone_sync_ssl_ciphers DEFAULT; Context: stream, server ciphers：指定一个或多个加密套件，可以用冒号分隔多个套件。默认值为 DEFAULT。

案例

基本用法

最简单的 zone_sync_ssl_ciphers 用法是指定具体的加密套件：

stream { server { listen 12345 ssl; zone_sync_ssl_certificate /etc/nginx/ssl/zone_sync.crt; zone_sync_ssl_certificate_key /etc/nginx/ssl/zone_sync.key; zone_sync_ssl_ciphers HIGH:!aNULL:!MD5; proxy_pass backend_zone_sync; } }

在这个例子中：

设置了 zone_sync_ssl_ciphers HIGH:!aNULL:!MD5，这意味着Nginx将使用这些加密套件进行区域同步。

动态设置不同配置

你可以根据不同的服务器块动态设置不同的加密套件：

stream { server { listen 12345 ssl; zone_sync_ssl_certificate /etc/nginx/ssl/zone_sync_1.crt; zone_sync_ssl_certificate_key /etc/nginx/ssl/zone_sync_1.key; zone_sync_ssl_ciphers HIGH:!aNULL:!MD5; proxy_pass backend_zone_sync_1; } server { listen 12346 ssl; zone_sync_ssl_certificate /etc/nginx/ssl/zone_sync_2.crt; zone_sync_ssl_certificate_key /etc/nginx/ssl/zone_sync_2.key; zone_sync_ssl_ciphers ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES128-GCM-SHA256; proxy_pass backend_zone_sync_2; } }

在这个例子中：

对于监听端口12345的服务器块，设置了 zone_sync_ssl_ciphers HIGH:!aNULL:!MD5。对于监听端口12346的服务器块，设置了 zone_sync_ssl_ciphers ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES128-GCM-SHA256。

注意事项

加密套件选择：合理选择加密套件，确保安全性和兼容性。适用场景：适用于需要通过SSL加密进行区域同步的应用场景。例如，在高可用性集群中进行安全的数据同步。调试和监控：如果你遇到加密套件问题，可以检查以下几点： 确保加密套件设置合理，并符合你的需求。查看Nginx的日志文件，确认是否有与此相关的警告或错误信息。使用工具模拟不同负载条件下的请求进行测试，确保在各种情况下都能正常工作。 zone_sync_ssl_conf_command

zone_sync_ssl_conf_command 指令用于传递额外的SSL配置命令给OpenSSL。这个指令帮助进一步自定义SSL配置。

Syntax: zone_sync_ssl_conf_command name value; Default: — Context: stream, server This directive appeared in version 1.19.4. name：指定SSL配置命令的名称。value：指定SSL配置命令的值。

案例

基本用法

最简单的 zone_sync_ssl_conf_command 用法是指定具体的配置命令和值：

stream { server { listen 12345 ssl; zone_sync_ssl_certificate /etc/nginx/ssl/zone_sync.crt; zone_sync_ssl_certificate_key /etc/nginx/ssl/zone_sync.key; zone_sync_ssl_conf_command Options Mode=TLSv1.2; proxy_pass backend_zone_sync; } }

在这个例子中：

设置了 zone_sync_ssl_conf_command Options Mode=TLSv1.2，这意味着Nginx将使用TLSv1.2模式进行SSL配置。

动态设置不同配置

你可以根据不同的服务器块动态设置不同的SSL配置命令：

stream { server { listen 12345 ssl; zone_sync_ssl_certificate /etc/nginx/ssl/zone_sync_1.crt; zone_sync_ssl_certificate_key /etc/nginx/ssl/zone_sync_1.key; zone_sync_ssl_conf_command Options Mode=TLSv1.2; proxy_pass backend_zone_sync_1; } server { listen 12346 ssl; zone_sync_ssl_certificate /etc/nginx/ssl/zone_sync_2.crt; zone_sync_ssl_certificate_key /etc/nginx/ssl/zone_sync_2.key; zone_sync_ssl_conf_command Options Mode=TLSv1.3; proxy_pass backend_zone_sync_2; } }

在这个例子中：

对于监听端口12345的服务器块，设置了 zone_sync_ssl_conf_command Options Mode=TLSv1.2。对于监听端口12346的服务器块，设置了 zone_sync_ssl_conf_command Options Mode=TLSv1.3。

注意事项

配置命令选择：合理选择并使用SSL配置命令，确保满足特定的安全需求。适用场景：适用于需要进一步自定义SSL配置的应用场景。例如，在需要严格控制TLS版本或启用特定功能的环境中使用。调试和监控：如果你遇到配置命令问题，可以检查以下几点： 确保配置命令设置合理，并符合你的需求。查看Nginx的日志文件，确认是否有与此相关的警告或错误信息。使用工具模拟不同负载条件下的请求进行测试，确保在各种情况下都能正常工作。 zone_sync_ssl_crl

zone_sync_ssl_crl 指令用于指定包含吊销证书列表（CRL）的文件路径，适用于流模块中的区域同步配置。

Syntax: zone_sync_ssl_crl file; Default: — Context: stream, server file：指定包含 CRL 的文件路径。

案例

基本用法

最简单的 zone_sync_ssl_crl 用法是指定包含 CRL 的文件路径：

stream { upstream backend { zone_sync_server backend1.example :12345; zone_sync_server backend2.example :12345; } server { listen 12345; proxy_pass backend; # 启用 SSL 并指定 CRL 文件 zone_sync_ssl_certificate /etc/nginx/ssl/zone_sync.crt; zone_sync_ssl_certificate_key /etc/nginx/ssl/zone_sync.key; zone_sync_ssl_crl /etc/nginx/ssl/crl.pem; } }

在这个例子中：

使用 /etc/nginx/ssl/crl.pem 文件作为 CRL 文件，以确保连接到区域同步服务器时验证客户端证书的有效性。

注意事项

安全性：确保 CRL 文件是最新的，并定期更新以保持系统的安全性。适用场景：适用于需要对客户端证书进行严格验证的应用场景。例如，在企业级应用或需要高安全性的环境中，使用 CRL 可以防止使用已吊销的证书。调试和监控：如果你遇到 CRL 文件问题，可以检查以下几点： 确保文件路径正确且具有适当的权限。查看Nginx的日志文件，确认是否有与此相关的警告或错误信息。 zone_sync_ssl_name

zone_sync_ssl_name 指令用于指定用于 SSL 握手的主机名，适用于流模块中的区域同步配置。

Syntax: zone_sync_ssl_name name; Default: zone_sync_ssl_name host from zone_sync_server; Context: stream, server This directive appeared in version 1.15.7. name：指定用于 SSL 握手的主机名，默认值为从 zone_sync_server 中提取的主机名。

案例

基本用法

最简单的 zone_sync_ssl_name 用法是指定用于 SSL 握手的主机名：

stream { upstream backend { zone_sync_server backend1.example :12345; zone_sync_server backend2.example :12345; } server { listen 12345; proxy_pass backend; # 启用 SSL 并指定用于 SSL 握手的主机名 zone_sync_ssl_certificate /etc/nginx/ssl/zone_sync.crt; zone_sync_ssl_certificate_key /etc/nginx/ssl/zone_sync.key; zone_sync_ssl_name backend.example ; } }

在这个例子中：

使用 backend.example 作为用于 SSL 握手的主机名。

使用默认值

你可以选择使用默认值（从 zone_sync_server 提取的主机名）：

stream { upstream backend { zone_sync_server backend1.example :12345; zone_sync_server backend2.example :12345; } server { listen 12345; proxy_pass backend; # 启用 SSL 并使用默认的主机名 zone_sync_ssl_certificate /etc/nginx/ssl/zone_sync.crt; zone_sync_ssl_certificate_key /etc/nginx/ssl/zone_sync.key; } }

在这个例子中：

使用从 zone_sync_server 提取的主机名作为用于 SSL 握手的主机名（默认值）。

注意事项

主机名匹配：确保指定的主机名与 SSL 证书中的主机名匹配，以避免 SSL 验证失败。适用场景：适用于需要明确指定用于 SSL 握手的主机名的应用场景。例如，在多域名或多服务器环境中，明确指定主机名可以确保正确的 SSL 配置。调试和监控：如果你遇到主机名问题，可以检查以下几点： 确保主机名正确无误，并与 SSL 证书中的主机名匹配。查看Nginx的日志文件，确认是否有与此相关的警告或错误信息。 zone_sync_ssl_password_file

zone_sync_ssl_password_file 指令用于指定包含 SSL 私钥密码的文件路径，适用于流模块中的区域同步配置。

Syntax: zone_sync_ssl_password_file file; Default: — Context: stream, server file：指定包含 SSL 私钥密码的文件路径。

案例

基本用法

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

stream { upstream backend { zone_sync_server backend1.example :12345; zone_sync_server backend2.example :12345; } server { listen 12345; proxy_pass backend; # 启用 SSL 并指定私钥密码文件 zone_sync_ssl_certificate /etc/nginx/ssl/zone_sync.crt; zone_sync_ssl_certificate_key /etc/nginx/ssl/zone_sync.key; zone_sync_ssl_password_file /etc/nginx/ssl/zone_sync_password.txt; } }

在这个例子中：

使用 /etc/nginx/ssl/zone_sync_password.txt 文件中的密码来解密 SSL 私钥。

注意事项

安全性：确保私钥密码文件存储在一个安全的位置，并限制访问权限，以防止密码泄露。适用场景：适用于需要加密私钥并使用密码保护的应用场景。例如，在生产环境中，使用加密的私钥和密码可以增加额外的安全层。调试和监控：如果你遇到私钥密码文件问题，可以检查以下几点： 确保文件路径正确且具有适当的权限。查看Nginx的日志文件，确认是否有与此相关的警告或错误信息。 zone_sync_ssl_protocols

zone_sync_ssl_protocols 指令用于指定支持的 SSL/TLS 协议版本，适用于流模块中的区域同步配置。

Syntax: zone_sync_ssl_protocols [SSLv2] [SSLv3] [TLSv1] [TLSv1.1] [TLSv1.2] [TLSv1.3]; Default: zone_sync_ssl_protocols TLSv1.2 TLSv1.3; Context: stream, server [SSLv2]：启用 SSLv2 协议（不推荐）。[SSLv3]：启用 SSLv3 协议（不推荐）。[TLSv1]：启用 TLSv1 协议。[TLSv1.1]：启用 TLSv1.1 协议。[TLSv1.2]：启用 TLSv1.2 协议（默认）。[TLSv1.3]：启用 TLSv1.3 协议（默认）。

案例

基本用法

最简单的 zone_sync_ssl_protocols 用法是指定支持的协议版本：

stream { upstream backend { zone_sync_server backend1.example :12345; zone_sync_server backend2.example :12345; } server { listen 12345; proxy_pass backend; # 启用 SSL 并指定支持的协议版本 zone_sync_ssl_certificate /etc/nginx/ssl/zone_sync.crt; zone_sync_ssl_certificate_key /etc/nginx/ssl/zone_sync.key; zone_sync_ssl_protocols TLSv1.2 TLSv1.3; } }

在这个例子中：

支持 TLSv1.2 和 TLSv1.3 协议（默认值）。

启用更多协议

你可以选择启用更多的协议版本：

stream { upstream backend { zone_sync_server backend1.example :12345; zone_sync_server backend2.example :12345; } server { listen 12345; proxy_pass backend; # 启用 SSL 并指定支持的协议版本 zone_sync_ssl_certificate /etc/nginx/ssl/zone_sync.crt; zone_sync_ssl_certificate_key /etc/nginx/ssl/zone_sync.key; zone_sync_ssl_protocols TLSv1 TLSv1.1 TLSv1.2 TLSv1.3; } }

在这个例子中：

支持 TLSv1、TLSv1.1、TLSv1.2 和 TLSv1.3 协议。

注意事项

安全性：避免启用过时或不安全的协议（如 SSLv2 和 SSLv3），以确保连接的安全性。兼容性：根据客户端的支持情况，适当调整支持的协议版本，以确保兼容性。适用场景：适用于需要控制支持的 SSL/TLS 协议版本的应用场景。例如，在高安全性要求的环境中，仅启用最新的协议版本可以提高安全性。调试和监控：如果你遇到协议版本问题，可以检查以下几点： 确保支持的协议版本合理，不会导致不兼容或安全隐患。查看Nginx的日志文件，确认是否有与此相关的警告或错误信息。 zone_sync_ssl_server_name

zone_sync_ssl_server_name 指令用于控制在与后端服务器建立SSL连接时是否发送服务器名称指示（SNI）。这对于多域名环境中的正确SSL证书匹配非常有用。

Syntax: zone_sync_ssl_server_name on | off; Default: zone_sync_ssl_server_name off; Context: stream, server This directive appeared in version 1.15.7. on：启用SNI，将在SSL握手时发送服务器名称。off（默认）：禁用SNI，不会发送服务器名称。

案例

启用SNI

假设我们在一个多域名环境中需要启用SNI：

stream { server { listen 12345; proxy_pass backend.example :12345; # 启用SNI zone_sync_ssl_server_name on; } }

禁用SNI

如果我们不需要或不希望发送服务器名称：

stream { server { listen 12345; proxy_pass backend.example :12345; # 禁用SNI zone_sync_ssl_server_name off; } }

注意事项

多域名支持：在多域名环境下，启用SNI可以确保正确的SSL证书匹配，避免证书错误。兼容性：确保后端服务器支持SNI，特别是在处理多个域名时。 zone_sync_ssl_trusted_certificate

zone_sync_ssl_trusted_certificate 指令用于指定信任的CA证书文件路径。这对于验证后端服务器的SSL证书非常有用，确保通信的安全性。

Syntax: zone_sync_ssl_trusted_certificate file; Default: — Context: stream, server file：指定包含信任的CA证书的文件路径。

案例

配置信任的CA证书

假设我们需要配置一个信任的CA证书文件 /etc/nginx/trusted_ca.crt：

stream { server { listen 12345; proxy_pass backend.example :12345; # 配置信任的CA证书文件 zone_sync_ssl_trusted_certificate /etc/nginx/trusted_ca.crt; } }

注意事项

安全性：确保配置的CA证书文件是可信的，以防止中间人攻击。路径管理：确保提供的文件路径正确且Nginx进程有权限读取该文件。 zone_sync_ssl_verify

zone_sync_ssl_verify 指令用于控制是否验证后端服务器的SSL证书。这有助于确保与后端服务器之间的通信安全。

Syntax: zone_sync_ssl_verify on | off; Default: zone_sync_ssl_verify off; Context: stream, server on：启用SSL证书验证。off（默认）：禁用SSL证书验证。

案例

启用SSL证书验证

假设我们希望启用SSL证书验证以确保通信安全：

stream { server { listen 12345; proxy_pass backend.example :12345; # 启用SSL证书验证 zone_sync_ssl_verify on; } }

禁用SSL证书验证

如果我们出于某些原因（如调试或测试）需要禁用SSL证书验证：

stream { server { listen 12345; proxy_pass backend.example :12345; # 禁用SSL证书验证 zone_sync_ssl_verify off; } }

注意事项

安全性：启用SSL证书验证可以显著提高通信的安全性，防止中间人攻击。调试和测试：在开发和测试阶段，可能需要暂时禁用证书验证，但应尽快恢复到启用状态。 zone_sync_ssl_verify_depth

zone_sync_ssl_verify_depth 指令用于设置SSL证书链验证的最大深度。这影响着对证书链的信任级别和验证过程。

Syntax: zone_sync_ssl_verify_depth number; Default: zone_sync_ssl_verify_depth 1; Context: stream, server number：指定最大验证深度，默认值为 1。

案例

设置较大的验证深度

假设我们需要增加SSL证书链的验证深度以支持更复杂的证书链：

stream { server { listen 12345; proxy_pass backend.example :12345; # 增加SSL证书链的验证深度到 3 zone_sync_ssl_verify_depth 3; } }

使用默认的验证深度

如果我们希望使用默认的1级验证深度：

stream { server { listen 12345; proxy_pass backend.example :12345; # 使用默认的 1 级验证深度 zone_sync_ssl_verify_depth 1; } }

注意事项

证书链长度：根据实际证书链的长度调整验证深度，确保所有必要的证书都能被验证。性能考虑：增加验证深度可能会增加验证时间，需权衡安全性和性能。 zone_sync_timeout

zone_sync_timeout 指令用于设置区域同步操作的超时时间。这有助于防止长时间等待导致的性能问题。

Syntax: zone_sync_timeout timeout; Default: zone_sync_timeout 5s; Context: stream, server timeout：区域同步操作的超时时间，默认为 5 秒。

案例

基本用法

最简单的 zone_sync_timeout 用法是指定同步操作的超时时间：

stream { upstream backend { server 192.168.1.1:12345; server 192.168.1.2:12345; } server { listen 12345; proxy_pass backend; # 设置区域同步操作的超时时间为 10 秒 zone_sync_timeout 10s; } }

在这个例子中：

如果区域同步操作未能在 10 秒内完成，Nginx 将返回错误。

注意事项

超时设置：合理的超时时间可以避免不必要的长时间等待，同时确保同步操作有足够的时间完成。网络延迟：根据实际网络延迟情况调整超时时间，以确保在高延迟环境下的正常工作。 2.4 ngx_google_perftools_module

ngx_google_perftools_module 是一个 Nginx 模块，旨在通过集成 Google Performance Tools（gperftools）来帮助开发者进行性能分析和内存管理优化。

主要功能

性能分析：利用 pprof 进行 CPU 和堆栈分析。内存分配优化：通过 tcmalloc 提供更高效的内存分配和释放机制。堆栈跟踪：支持生成详细的堆栈跟踪信息，便于调试和性能调优。

使用示例

以下是一些具体的配置示例，展示如何利用 ngx_google_perftools_module 来进行性能分析和内存管理优化。

启用性能分析

假设你想启用性能分析并将数据保存到 /tmp/nginx.prof 文件中：

http { # 其他配置... google_perftools_profiles /tmp/nginx.prof; server { listen 80; server_name example ; location / { root /var/ /html; index index.html; } } }

在这个例子中：

google_perftools_profiles /tmp/nginx.prof; 指定了性能分析数据的输出路径。

Nginx 启动后，你会在 /tmp 目录下看到类似 nginx.prof.<worker_pid> 的文件，其中包含了各个工作进程的性能分析数据。

记录多个工作进程的性能数据

如果你有多个工作进程，你可以通过不同的文件名区分它们的性能数据：

http { # 其他配置... google_perftools_profiles /tmp/nginx_prof_$pid; server { listen 80; server_name example ; location / { root /var/ /html; index index.html; } } }

在这个例子中：

google_perftools_profiles /tmp/nginx_prof_$pid; 使用 $pid 变量来区分不同工作进程的性能数据文件。

注意事项

性能影响：

启用性能分析功能可能会对 Nginx 的性能产生一定影响，特别是在高负载环境下。建议仅在调试和调优阶段启用这些功能。

安全性：

由于性能分析数据可能包含敏感信息，建议仅在受信任的环境中运行，并确保相关文件的安全性。

日志记录：

合理配置日志级别和格式，便于监控和故障排查。特别是注意记录与性能分析相关的错误信息和性能指标。 2.4.1 指令列表 google_perftools_profiles

google_perftools_profiles 指令用于配置 Google Performance Tools 的性能分析文件路径。这个工具可以帮助进行内存分配和 CPU 使用情况的分析。

Syntax: google_perftools_profiles file; Default: — Context: main file：性能分析文件的路径。

案例

基本用法

最简单的 google_perftools_profiles 用法是指定性能分析文件的路径：

main { # 配置性能分析文件路径 google_perftools_profiles /var/log/nginx/perf.prof; }

在这个例子中：

性能分析数据将被写入 /var/log/nginx/perf.prof 文件中。

注意事项

文件权限：确保 Nginx 进程对指定文件路径具有写权限。性能影响：启用性能分析可能会增加一定的系统开销，建议仅在需要时启用。 2.5 ngx_mgmt_module

ngx_mgmt_module 模块使 NGINX Plus 实例能够进行许可证验证和使用报告。这是每个 NGINX Plus 实例所必需的功能。该模块会定期向 F5（NGINX Plus 的母公司）发送使用报告，以确保许可证的有效性和合规性。

主要功能

许可证验证：确保 NGINX Plus 实例使用的许可证是有效的。使用报告：每小时通过安全连接将使用情况报告发送到 F5 许可证端点。网络受限环境支持：在受限网络环境中，可以通过 F5 NGINX Instance Manager 发送报告。

使用场景

基本配置

一个简单的 ngx_mgmt_module 配置示例如下：

mgmt { # 默认路径下的 JWT 许可证文件 license_token /etc/nginx/license.jwt; # 设置使用报告端点地址和时间间隔 usage_report endpoint=product.connect.nginx interval=1h; }

自定义路径和报告端点

如果你需要自定义许可证文件路径并指定不同的报告端点：

mgmt { # 自定义路径下的 JWT 许可证文件 license_token /custom/path/to/license.jwt; # 设置使用报告端点地址和时间间隔 usage_report endpoint=my.custom.endpoint interval=30m; }

网络受限环境

在受限网络环境中，你可以配置 NGINX Instance Manager 来发送报告：

mgmt { # 自定义路径下的 JWT 许可证文件 license_token /custom/path/to/license.jwt; # 设置使用报告端点为 NGINX Instance Manager usage_report endpoint=NIM_FQDN; }

注意事项

许可证文件位置：确保许可证文件位于正确的位置，并且具有正确的权限。网络连接：确保 NGINX 实例可以访问 F5 许可证端点，尤其是在受限网络环境中。日志记录：建议启用日志记录以便于调试和监控许可证验证及使用报告的状态。 2.5.1 指令列表 mgmt

mgmt 指令块用于定义管理相关的配置选项。这些配置通常用于管理和监控 Nginx 实例。

Syntax: mgmt { ... } Default: — Context: main

案例

基本用法

一个典型的 mgmt 配置示例如下：

main { mgmt { # 启用初始报告 enforce_initial_report on; # 其他管理相关配置 # ... } }

在这个例子中：

定义了一个 mgmt 指令块，并启用了初始报告功能。

复杂用法

结合其他管理配置选项使用 mgmt 指令块：

main { mgmt { # 启用初始报告 enforce_initial_report on; # 配置其他管理选项 some_other_option value; } # 其他全局配置 google_perftools_profiles /var/log/nginx/perf.prof; }

在这个例子中：

mgmt 指令块中包含了多个管理配置选项，包括启用了初始报告和其他自定义选项。

注意事项

配置完整性：确保所有必要的管理配置都已包含在 mgmt 指令块中。日志记录：启用适当的日志记录和监控机制，以便及时发现和解决问题。 enforce_initial_report

enforce_initial_report 指令用于控制是否强制生成初始报告。初始报告提供了启动时的状态信息，对于调试和监控非常有用。

Syntax: enforce_initial_report on | off; Default: enforce_initial_report on; Context: mgmt This directive appeared in version 1.27.2. on：启用初始报告，默认行为。off：禁用初始报告。

案例

基本用法

最简单的 enforce_initial_report 用法是启用或禁用初始报告：

main { mgmt { # 启用初始报告 enforce_initial_report on; } }

在这个例子中：

启动时将生成初始报告，提供有关 Nginx 实例状态的信息。

复杂用法

根据不同的应用场景启用或禁用初始报告：

main { mgmt { if ($debug_mode = "true") { # 在调试模式下启用初始报告 enforce_initial_report on; } else { # 在非调试模式下禁用初始报告 enforce_initial_report off; } } }

在这个例子中：

如果 $debug_mode 变量值为 "true"，则启用初始报告；否则，禁用初始报告。

注意事项

调试需求：在开发和调试阶段，启用初始报告有助于快速发现问题；但在生产环境中，可能不需要生成初始报告以减少开销。日志管理：确保初始报告的日志文件得到妥善管理，避免占用过多磁盘空间。 license_token

license_token 用于指定管理模块中使用的许可证令牌文件路径。该令牌通常是一个 JWT（JSON Web Token），用于验证和授权管理功能的使用。

Syntax: license_token file; Default: license_token license.jwt; Context: mgmt This directive appeared in version 1.27.2. file：指定许可证令牌文件的路径，默认值为 license.jwt。

案例

基本用法

最简单的 license_token 用法是指定许可证令牌文件路径：

mgmt { license_token /etc/nginx/licenses/my_license.jwt; # 指定自定义许可证令牌文件路径 }

使用默认路径

如果使用默认路径，可以省略具体路径：

mgmt { # 默认路径为 'license.jwt' license_token; # 等同于 license_token license.jwt }

注意事项

权限管理：确保 Nginx 进程有读取许可证令牌文件的权限。安全性：将许可证令牌文件存储在安全位置，防止未经授权的访问。 resolver ssl_crl ssl_trusted_certificate ssl_verify

ssl_verify 用于控制是否在管理模块中启用 SSL/TLS 验证。启用该选项可以增强安全性，防止中间人攻击等安全问题。

Syntax: ssl_verify on | off; Default: ssl_verify on; Context: mgmt on：启用 SSL/TLS 验证（默认值）。off：禁用 SSL/TLS 验证。

案例

启用 SSL/TLS 验证

最简单的 ssl_verify 用法是启用 SSL/TLS 验证：

mgmt { ssl_verify on; # 启用 SSL/TLS 验证 }

禁用 SSL/TLS 验证

根据实际需求禁用 SSL/TLS 验证（不推荐用于生产环境）：

mgmt { ssl_verify off; # 禁用 SSL/TLS 验证 }

注意事项

安全性：启用 SSL/TLS 验证可以防止中间人攻击等安全问题，尤其是在公网或不可信网络中。开发调试：在开发和调试环境中，有时会临时禁用 SSL/TLS 验证以简化配置，但应避免在生产环境中这样做。 state_path

state_path 用于指定管理模块的状态文件存储路径。这有助于管理和持久化管理模块的状态信息。

Syntax: state_path path; Default: — Context: mgmt This directive appeared in version 1.27.2. path：指定状态文件存储路径。

案例

基本用法

最简单的 state_path 用法是指定状态文件存储路径：

mgmt { state_path /var/lib/nginx/state; # 指定状态文件存储路径 }

示例配置

结合其他指令进行完整配置：

mgmt { state_path /var/lib/nginx/state; # 指定状态文件存储路径 license_token /etc/nginx/licenses/my_license.jwt; # 指定许可证令牌文件路径 ssl_verify on; # 启用 SSL/TLS 验证 }

注意事项

路径正确性：确保指定的状态文件存储路径存在，并且 Nginx 进程有写入权限。数据持久性：合理设置状态文件存储路径，确保状态信息能够被正确保存和恢复。 usage_report

usage_report 用于配置管理模块中的使用报告功能。这允许你向指定的端点发送使用报告，并设置报告的发送间隔。

Syntax: usage_report [endpoint=address] [interval=time]; Default: usage_report endpoint=product.connect.nginx interval=1h; Context: mgmt endpoint=address：指定接收使用报告的服务器地址，默认值为 product.connect.nginx 。interval=time：指定发送使用报告的时间间隔，默认值为 1h（1小时）。

案例

基本用法

最简单的 usage_report 用法是指定接收使用报告的服务器地址和时间间隔：

mgmt { usage_report endpoint=my_usage_server interval=30m; # 自定义接收服务器和时间间隔 }

使用默认配置

如果使用默认配置，可以省略具体参数：

mgmt { # 使用默认配置 usage_report; # 等同于 usage_report endpoint=product.connect.nginx interval=1h }

示例配置

结合其他指令进行完整配置：

mgmt { state_path /var/lib/nginx/state; # 指定状态文件存储路径 license_token /etc/nginx/licenses/my_license.jwt; # 指定许可证令牌文件路径 ssl_verify on; # 启用 SSL/TLS 验证 usage_report endpoint=my_usage_server interval=15m; # 自定义使用报告配置 }

注意事项

数据隐私：确保接收使用报告的服务器是可信的，避免敏感数据泄露。性能影响：合理设置报告发送间隔，避免频繁发送报告对系统性能产生负面影响。 2.6 ngx_otel_module

ngx_otel_module 是 Nginx 的一个模块，用于支持 OpenTelemetry（OTel）协议，以实现分布式追踪和监控。以下是基于官方文档的详细解析。

主要功能

分布式追踪：生成并发送追踪数据，帮助理解跨多个服务的请求路径。度量数据：收集并发送度量数据，如请求时间、成功率等。灵活配置：支持多种导出器配置，以便将数据发送到不同的后端系统（如 OTLP/gRPC、Jaeger、Zipkin 等）。

使用示例

以下是一些具体的配置示例，展示了如何使用 ngx_otel_module 来实现分布式追踪和度量数据的收集。

基本配置

假设你想启用 OpenTelemetry 支持并将数据发送到本地的 OTLP gRPC 端点：

http { load_module modules/ngx_otel_module.so; otel_exporter { endpoint "localhost:4317"; } otel_service_name "my_nginx_service"; server { listen 80; location / { otel_trace on; otel_trace_context inject; proxy_pass http://backend; } } }

在这个例子中：

load_module modules/ngx_otel_module.so; 加载 ngx_otel_module 模块。otel_exporter 块配置了 OTLP/gRPC 导出器，目标地址为 localhost:4317。otel_service_name "my_nginx_service"; 设置了服务名称。在 location 块中，启用了追踪，并设置了追踪上下文注入策略，然后将请求代理到后端服务器。

结合限速功能

假设你想在限速的同时收集度量数据：

http { limit_req_zone $binary_remote_addr zone=one:10m rate=1r/s; otel_exporter { endpoint "localhost:4317"; } otel_service_name "my_nginx_service"; server { listen 80; location / { limit_req zone=one burst=5; otel_trace on; otel_trace_context inject; proxy_pass http://backend; } } }

在这个例子中：

limit_req_zone 定义了一个限速共享内存区域。otel_exporter 块配置了 OTLP/gRPC 导出器，目标地址为 localhost:4317。在 location 块中，应用了限速规则，并启用了追踪和上下文注入策略，然后将请求代理到后端服务器。

多导出器配置

假设你想同时将数据发送到多个后端系统：

http { otel_exporter { endpoint "localhost:4317"; interval 5s; batch_size 512; batch_count 4; } otel_service_name "my_nginx_service"; server { listen 80; location / { otel_trace on; otel_trace_context inject; proxy_pass http://backend; } } }

在这个例子中：

otel_exporter 块配置了 OTLP/gRPC 导出器，目标地址为 localhost:4317，并设置了导出间隔、批量大小和批次数量。otel_service_name "my_nginx_service"; 设置了服务名称。在 location 块中，启用了追踪和上下文注入策略，然后将请求代理到后端服务器。

注意事项

性能优化： 尽量减少不必要的追踪和度量数据采集，以避免增加系统负担。根据实际需求合理设置采样率，避免过度采集导致性能下降。 安全性： 确保导出器目标服务器的安全性，防止未经授权的访问。可以考虑使用 TLS 加密连接。确保传输过程中的数据安全，防止中间人攻击。 测试验证：在部署之前进行全面测试，确保所有配置按预期工作，并检查是否有任何潜在的问题（如数据丢失、采样不准确等）。 2.6.1 指令列表 otel_exporter

otel_exporter 指令用于配置OpenTelemetry导出器的相关设置。这个指令帮助将跟踪数据导出到指定的后端服务。

Syntax: otel_exporter { ... } Default: — Context: http { ... }：包含导出器的具体配置项，例如导出目标地址、协议等。

案例

基本用法

最简单的 otel_exporter 用法是指定导出器的目标地址和协议：

http { otel_exporter { endpoint "http://localhost:4317"; protocol "grpc"; } server { listen 80; location / { proxy_pass http://backend; } } }

在这个例子中：

设置了 otel_exporter 的 endpoint 为 "http://localhost:4317"，protocol 为 "grpc"，这意味着Nginx将通过gRPC协议将跟踪数据导出到该地址。

动态设置不同配置

你可以根据不同的需求动态设置不同的导出器配置：

http { otel_exporter { endpoint "http://collector1.example :4317"; protocol "grpc"; } server { listen 80; location /service1 { proxy_pass http://backend1; } } otel_exporter { endpoint "http://collector2.example :4317"; protocol "http/protobuf"; } server { listen 80; location /service2 { proxy_pass http://backend2; } } }

在这个例子中：

对于 /service1 路径，设置了 otel_exporter 的 endpoint 为 "http://collector1.example :4317"，protocol 为 "grpc".对于 /service2 路径，设置了 otel_exporter 的 endpoint 为 "http://collector2.example :4317"，protocol 为 "http/protobuf".

注意事项

导出器配置：确保导出器的配置正确，包括目标地址和协议。适用场景：适用于需要将跟踪数据导出到特定后端服务的应用场景。例如，在分布式系统中进行性能监控和故障排查。调试和监控：如果你遇到导出器问题，可以检查以下几点： 确保导出器配置合理，并符合你的需求。查看Nginx的日志文件，确认是否有与此相关的警告或错误信息。使用工具模拟不同负载条件下的请求进行测试，确保在各种情况下都能正常工作。 otel_service_name

otel_service_name 指令用于指定OpenTelemetry服务名称。这个指令帮助标识Nginx实例在跟踪数据中的身份。

Syntax: otel_service_name name; Default: otel_service_name unknown_service:nginx; Context: http name：指定服务名称，默认值为 unknown_service:nginx。

案例

基本用法

最简单的 otel_service_name 用法是指定具体的服务名称：

http { otel_service_name my_nginx_service; server { listen 80; location / { proxy_pass http://backend; } } }

在这个例子中：

设置了 otel_service_name my_nginx_service，这意味着Nginx将在跟踪数据中标记为 my_nginx_service。

动态设置不同配置

你可以根据不同的服务器块动态设置不同的服务名称：

http { otel_service_name service1; server { listen 80; location /service1 { proxy_pass http://backend1; } } otel_service_name service2; server { listen 80; location /service2 { proxy_pass http://backend2; } } }

在这个例子中：

对于 /service1 路径，设置了 otel_service_name service1.对于 /service2 路径，设置了 otel_service_name service2.

注意事项

服务名称管理：确保服务名称明确且唯一，便于后续监控和分析。适用场景：适用于需要明确标识Nginx实例的服务名称的应用场景。例如，在分布式系统中进行服务级别的性能监控。调试和监控：如果你遇到服务名称问题，可以检查以下几点： 确保服务名称设置合理，并符合你的需求。查看Nginx的日志文件，确认是否有与此相关的警告或错误信息。使用工具模拟不同负载条件下的请求进行测试，确保在各种情况下都能正常工作。 otel_trace

otel_trace 指令用于启用或禁用OpenTelemetry跟踪功能。这个指令帮助控制是否记录和导出跟踪数据。

Syntax: otel_trace on | off | $variable; Default: otel_trace off; Context: http, server, location on：启用跟踪功能。off：禁用跟踪功能（默认值）。$variable：使用变量动态控制跟踪状态。

案例

基本用法

最简单的 otel_trace 用法是指定是否启用跟踪功能：

http { otel_trace on; server { listen 80; location / { proxy_pass http://backend; } } }

在这个例子中：

设置了 otel_trace on，这意味着Nginx将启用跟踪功能并记录跟踪数据。

动态设置不同配置

你可以根据不同的服务器块动态设置跟踪状态：

http { otel_trace on; server { listen 80; location /service1 { proxy_pass http://backend1; } } otel_trace off; server { listen 80; location /service2 { proxy_pass http://backend2; } } }

在这个例子中：

对于 /service1 路径，启用了跟踪功能。对于 /service2 路径，禁用了跟踪功能。

你也可以使用变量动态控制跟踪状态：

http { map $request_uri $should_trace { default off; ~^/trace-enabled on; } otel_trace $should_trace; server { listen 80; location / { proxy_pass http://backend; } } }

在这个例子中：

根据 $request_uri 的值动态决定是否启用跟踪功能。

注意事项

跟踪控制：合理选择跟踪状态，避免不必要的资源消耗或遗漏关键跟踪数据。适用场景：适用于需要灵活控制跟踪功能的应用场景。例如，在开发环境中启用跟踪以进行调试，在生产环境中禁用以节省资源。调试和监控：如果你遇到跟踪问题，可以检查以下几点： 确保跟踪状态设置合理，并符合你的需求。查看Nginx的日志文件，确认是否有与此相关的警告或错误信息。使用工具模拟不同负载条件下的请求进行测试，确保在各种情况下都能正常工作。 otel_trace_context

otel_trace_context 指令用于配置OpenTelemetry跟踪上下文的行为。这个指令帮助控制如何处理传入和传出的跟踪上下文。

Syntax: otel_trace_context extract | inject | propagate | ignore; Default: otel_trace_context ignore; Context: http, server, location extract：从传入请求中提取跟踪上下文。inject：将跟踪上下文注入传出请求。propagate：同时执行提取和注入操作。ignore：忽略跟踪上下文（默认值）。

案例

基本用法

最简单的 otel_trace_context 用法是指定具体的上下文处理方式：

http { otel_trace on; otel_trace_context propagate; server { listen 80; location / { proxy_pass http://backend; } } }

在这个例子中：

设置了 otel_trace_context propagate，这意味着Nginx将同时从传入请求中提取跟踪上下文，并将其注入传出请求。

动态设置不同配置

你可以根据不同的服务器块动态设置上下文处理方式：

http { otel_trace on; server { listen 80; location /service1 { otel_trace_context extract; proxy_pass http://backend1; } } server { listen 80; location /service2 { otel_trace_context inject; proxy_pass http://backend2; } } server { listen 80; location /service3 { otel_trace_context propagate; proxy_pass http://backend3; } } server { listen 80; location /service4 { otel_trace_context ignore; proxy_pass http://backend4; } } }

在这个例子中：

对于 /service1 路径，设置了 otel_trace_context extract。对于 /service2 路径，设置了 otel_trace_context inject。对于 /service3 路径，设置了 otel_trace_context propagate。对于 /service4 路径，设置了 otel_trace_context ignore。

注意事项

上下文处理：合理选择上下文处理方式，确保跟踪数据能够正确传递。适用场景：适用于需要精确控制跟踪上下文的应用场景。例如，在微服务架构中进行跨服务的跟踪数据传递。调试和监控：如果你遇到上下文处理问题，可以检查以下几点： 确保上下文处理方式设置合理，并符合你的需求。查看Nginx的日志文件，确认是否有与此相关的警告或错误信息。使用工具模拟不同负载条件下的请求进行测试，确保在各种情况下都能正常工作。 otel_span_name

otel_span_name 指令用于指定 OpenTelemetry 跟踪中的 Span 名称，适用于 HTTP 请求的跟踪。

Syntax: otel_span_name name; Default: — Context: http, server, location name：指定 Span 的名称。

案例

基本用法

最简单的 otel_span_name 用法是指定 Span 的名称：

server { listen 80; server_name example ; location /api/ { # 设置 Span 名称为 "API Request" otel_span_name "API Request"; proxy_pass http://backend.example ; } }

在这个例子中：

设置了 Span 名称为 "API Request"，这将帮助你在跟踪工具中更容易地识别该请求。

动态 Span 名称

你可以使用变量来动态生成 Span 名称：

server { listen 80; server_name example ; location /api/ { # 使用 $request_method 变量动态生成 Span 名称 otel_span_name "$request_method API Request"; proxy_pass http://backend.example ; } }

在这个例子中：

使用 $request_method 变量动态生成 Span 名称，例如 "GET API Request" 或 "POST API Request"。

注意事项

命名规范：确保 Span 名称具有描述性，以便更容易识别和追踪。适用场景：适用于需要对特定请求进行详细追踪的应用场景。例如，在微服务架构中，明确的 Span 名称可以帮助快速定位问题和优化性能。调试和监控：如果你遇到 Span 名称问题，可以检查以下几点： 确保名称字符串正确无误，并且变量（如果使用）被正确解析。查看Nginx的日志文件，确认是否有与此相关的警告或错误信息。 otel_span_attr

otel_span_attr 指令用于为 OpenTelemetry 跟踪中的 Span 添加属性，适用于 HTTP 请求的跟踪。

Syntax: otel_span_attr name value; Default: — Context: http, server, location name：指定属性的名称。value：指定属性的值。

案例

基本用法

最简单的 otel_span_attr 用法是添加一个属性：

server { listen 80; server_name example ; location /api/ { # 设置 Span 名称为 "API Request" otel_span_name "API Request"; # 添加一个属性 "user_id"，其值为从请求头中提取的用户 ID otel_span_attr "user_id" $http_x_user_id; proxy_pass http://backend.example ; } }

在这个例子中：

添加了一个名为 "user_id" 的属性，其值是从请求头中提取的 $http_x_user_id。

多个属性

你可以添加多个属性：

server { listen 80; server_name example ; location /api/ { # 设置 Span 名称为 "API Request" otel_span_name "API Request"; # 添加多个属性 otel_span_attr "user_id" $http_x_user_id; otel_span_attr "client_ip" $remote_addr; otel_span_attr "method" $request_method; proxy_pass http://backend.example ; } }

在这个例子中：

添加了三个属性："user_id"、"client_ip" 和 "method"，分别对应从请求头中提取的用户 ID、客户端 IP 地址和请求方法。

注意事项

属性命名：确保属性名称具有描述性，并且与应用逻辑一致。适用场景：适用于需要记录额外上下文信息的应用场景。例如，在日志分析或性能监控中，添加属性可以帮助更好地理解请求行为和性能瓶颈。调试和监控：如果你遇到属性问题，可以检查以下几点： 确保属性名称和值正确无误，并且变量（如果使用）被正确解析。查看Nginx的日志文件，确认是否有与此相关的警告或错误信息。