ngx_stream_proxy_module 模块

配置示例
指令
     proxy_bind
     proxy_buffer_size
     proxy_connect_timeout
     proxy_download_rate
     proxy_half_close
     proxy_next_upstream
     proxy_next_upstream_timeout
     proxy_next_upstream_tries
     proxy_pass
     proxy_protocol
     proxy_requests
     proxy_responses
     proxy_session_drop
     proxy_socket_keepalive
     proxy_ssl
     proxy_ssl_certificate
     proxy_ssl_certificate_cache
     proxy_ssl_certificate_key
     proxy_ssl_ciphers
     proxy_ssl_conf_command
     proxy_ssl_crl
     proxy_ssl_key_log
     proxy_ssl_name
     proxy_ssl_password_file
     proxy_ssl_protocols
     proxy_ssl_server_name
     proxy_ssl_session_reuse
     proxy_ssl_trusted_certificate
     proxy_ssl_verify
     proxy_ssl_verify_depth
     proxy_timeout
     proxy_upload_rate

ngx_stream_proxy_module 模块 (1.9.0) 允许通过 TCP、UDP (1.9.13) 和 UNIX 域套接字代理数据流。

配置示例

server {
    listen 127.0.0.1:12345;
    proxy_pass 127.0.0.1:8080;
}

server {
    listen 12345;
    proxy_connect_timeout 1s;
    proxy_timeout 1m;
    proxy_pass example.com:12345;
}

server {
    listen 53 udp reuseport;
    proxy_timeout 20s;
    proxy_pass dns.example.com:53;
}

server {
    listen [::1]:12345;
    proxy_pass unix:/tmp/stream.socket;
}

指令

语法 proxy_bind address [transparent] | off;
默认值
上下文 stream, server

此指令出现在 1.9.2 版本中。

使到被代理服务器的出站连接源自指定的本地 IP 地址。参数值可以包含变量 (1.11.2)。特殊值 off 取消继承自上一级配置的 proxy_bind 指令的效果,允许系统自动分配本地 IP 地址。

transparent 参数 (1.11.0) 允许到被代理服务器的出站连接源自非本地 IP 地址,例如客户端的真实 IP 地址

proxy_bind $remote_addr transparent;

为了使此参数生效,通常需要以 超级用户 权限运行 nginx worker 进程。在 Linux 上,这并非必需 (1.13.8),因为如果指定了 transparent 参数,worker 进程会从 master 进程继承 CAP_NET_RAW 能力。此外,还需要配置内核路由表以拦截来自被代理服务器的网络流量。

语法 proxy_buffer_size size;
默认值
proxy_buffer_size 16k;
上下文 stream, server

此指令出现在 1.9.4 版本中。

设置用于读取被代理服务器数据的缓冲区 大小。同时也设置用于读取客户端数据的缓冲区 大小

语法 proxy_connect_timeout time;
默认值
proxy_connect_timeout 60s;
上下文 stream, server

定义与被代理服务器建立连接的超时时间。

语法 proxy_download_rate rate;
默认值
proxy_download_rate 0;
上下文 stream, server

此指令出现在 1.9.3 版本中。

限制从被代理服务器读取数据的速度。rate 以字节/秒为单位指定。零值禁用速率限制。限制是针对每个连接设置的,因此如果 nginx 同时向被代理服务器打开两个连接,总速率将是指定限制的两倍。

参数值可以包含变量 (1.17.0)。这在需要根据特定条件限制速率的情况下可能有用

map $slow $rate {
    1     4k;
    2     8k;
}

proxy_download_rate $rate;

语法 proxy_half_close on | off;
默认值
proxy_half_close off;
上下文 stream, server

此指令出现在 1.21.4 版本中。

启用或禁用独立关闭 TCP 连接的每个方向(“TCP 半关闭”)。如果启用,TCP 代理将保持活动状态,直到双方都关闭连接。

语法 proxy_next_upstream on | off;
默认值
proxy_next_upstream on;
上下文 stream, server

当无法与被代理服务器建立连接时,确定客户端连接是否会传递给下一个服务器。

将连接传递到下一个服务器可以受 尝试次数时间 限制。

语法 proxy_next_upstream_timeout time;
默认值
proxy_next_upstream_timeout 0;
上下文 stream, server

限制将连接传递给 下一个服务器 所允许的时间。0 值关闭此限制。

语法 proxy_next_upstream_tries number;
默认值
proxy_next_upstream_tries 0;
上下文 stream, server

限制将连接传递给 下一个服务器 的可能尝试次数。0 值关闭此限制。

语法 proxy_pass address;
默认值
上下文 server

设置被代理服务器的地址。地址可以指定为域名、IP 地址和端口

proxy_pass localhost:12345;

或作为 UNIX 域套接字路径

proxy_pass unix:/tmp/stream.socket;

如果域名解析到多个地址,所有地址将以轮询方式使用。此外,地址可以指定为 服务器组

地址也可以使用变量指定 (1.11.3)

proxy_pass $upstream;

在这种情况下,会在已描述的 服务器组 中搜索服务器名称,如果找不到,则使用 解析器 确定。

语法 proxy_protocol on | off;
默认值
proxy_protocol off;
上下文 stream, server

此指令出现在 1.9.2 版本中。

为与被代理服务器的连接启用 PROXY 协议

语法 proxy_requests number;
默认值
proxy_requests 0;
上下文 stream, server

此指令出现在 1.15.7 版本中。

设置客户端数据报数量,达到此数量时,客户端与现有 UDP 流会话的绑定将被丢弃。收到指定数量的数据报后,同一客户端的下一个数据报将开始新的会话。当所有客户端数据报都传输到被代理服务器并接收到预期数量的 响应,或达到 超时 时,会话终止。

语法 proxy_responses number;
默认值
上下文 stream, server

此指令出现在 1.9.13 版本中。

如果使用 UDP 协议,则设置被代理服务器针对客户端数据报预期发送的数据报数量。此数量作为会话终止的提示。默认情况下,数据报数量不受限制。

如果指定零值,则不期望任何响应。但是,如果收到了响应并且会话尚未结束,该响应将得到处理。

语法 proxy_session_drop on | off;
默认值
proxy_session_drop off;
上下文 stream, server

此指令出现在 1.15.8 版本中。

在被代理服务器从组中移除或被标记为永久不可用后,启用终止所有与其相关的会话。这可能因为 重新解析 或 API DELETE 命令而发生。如果服务器被认为是 不健康 的或通过 API PATCH 命令,它可能被标记为永久不可用。当客户端或被代理服务器的下一个读或写事件被处理时,每个会话都会被终止。

此指令作为我们的 商业订阅 的一部分提供。

语法 proxy_socket_keepalive on | off;
默认值
proxy_socket_keepalive off;
上下文 stream, server

此指令出现在 1.15.6 版本中。

为到被代理服务器的出站连接配置“TCP keepalive”行为。默认情况下,套接字使用操作系统的设置。如果指令值设置为“on”,则套接字上的 SO_KEEPALIVE 选项将被开启。

语法 proxy_ssl on | off;
默认值
proxy_ssl off;
上下文 stream, server

为与被代理服务器的连接启用 SSL/TLS 协议。

语法 proxy_ssl_certificate file;
默认值
上下文 stream, server

指定一个 file,其中包含用于向被代理服务器进行身份验证的 PEM 格式证书。

自 1.21.0 版本起,可以在 file 名称中使用变量。

语法 proxy_ssl_certificate_cache off;
proxy_ssl_certificate_cache max=N [inactive=time] [valid=time];
默认值
proxy_ssl_certificate_cache off;
上下文 stream, server

此指令出现在 1.27.4 版本中。

定义一个缓存,用于存储使用 变量 指定的 SSL 证书密钥

此指令有以下参数

max
设置缓存中的最大元素数量;当缓存溢出时,将移除最近最少使用的 (LRU) 元素;
inactive
定义一个时间,在此时间内未访问过的元素将被从缓存中移除;默认值为 10 秒;
valid
定义缓存中元素被视为有效且可重用的时间;默认值为 60 秒。超过此时间的证书将被重新加载或重新验证;
off
禁用缓存。

示例

proxy_ssl_certificate       $proxy_ssl_server_name.crt;
proxy_ssl_certificate_key   $proxy_ssl_server_name.key;
proxy_ssl_certificate_cache max=1000 inactive=20s valid=1m;

语法 proxy_ssl_certificate_key file;
默认值
上下文 stream, server

指定一个 file,其中包含用于向被代理服务器进行身份验证的 PEM 格式密钥。

自 1.21.0 版本起,可以在 file 名称中使用变量。

语法 proxy_ssl_ciphers ciphers;
默认值
proxy_ssl_ciphers DEFAULT;
上下文 stream, server

指定与被代理服务器连接所启用的密码套件。密码套件使用 OpenSSL 库能理解的格式指定。

可以使用“openssl ciphers”命令查看完整列表。

语法 proxy_ssl_conf_command name value;
默认值
上下文 stream, server

此指令出现在 1.19.4 版本中。

在与被代理服务器建立连接时,设置任意 OpenSSL 配置 命令

使用 OpenSSL 1.0.2 或更高版本时支持此指令。

可以在同一层级指定多个 proxy_ssl_conf_command 指令。当且仅当当前层级未定义 proxy_ssl_conf_command 指令时,这些指令才会从上一级配置继承。

请注意,直接配置 OpenSSL 可能会导致意外行为。

语法 proxy_ssl_crl file;
默认值
上下文 stream, server

指定一个 file,其中包含用于 验证 被代理服务器证书的 PEM 格式撤销证书列表 (CRL)。

语法 proxy_ssl_key_log path;
默认值
上下文 stream, server

此指令出现在 1.27.2 版本中。

启用记录被代理服务器连接的 SSL 密钥,并指定密钥日志文件的路径。密钥以与 Wireshark 兼容的 SSLKEYLOGFILE 格式记录。

此指令作为我们的 商业订阅 的一部分提供。

语法 proxy_ssl_name name;
默认值
proxy_ssl_name host from proxy_pass;
上下文 stream, server

允许覆盖用于 验证 被代理服务器证书,并在与被代理服务器建立连接时通过 SNI 传递的服务器名称。服务器名称也可以使用变量指定 (1.11.3)。

默认情况下,使用 proxy_pass 地址的主机部分。

语法 proxy_ssl_password_file file;
默认值
上下文 stream, server

指定一个 file,其中包含 密钥 的密码短语,每个密码短语位于单独一行。加载密钥时会依次尝试密码短语。

语法 proxy_ssl_protocols [SSLv2] [SSLv3] [TLSv1] [TLSv1.1] [TLSv1.2] [TLSv1.3];
默认值
proxy_ssl_protocols TLSv1.2 TLSv1.3;
上下文 stream, server

为与被代理服务器的连接启用指定的协议。

自 1.23.4 版本起,默认使用 TLSv1.3 参数。

语法 proxy_ssl_server_name on | off;
默认值
proxy_ssl_server_name off;
上下文 stream, server

在与被代理服务器建立连接时,启用或禁用通过 TLS 服务器名称指示扩展(SNI, RFC 6066)传递服务器名称。

语法 proxy_ssl_session_reuse on | off;
默认值
proxy_ssl_session_reuse on;
上下文 stream, server

确定在与被代理服务器工作时是否可以重用 SSL 会话。如果在日志中出现“digest check failed”错误,请尝试禁用会话重用。

语法 proxy_ssl_trusted_certificate file;
默认值
上下文 stream, server

指定一个 file,其中包含用于 验证 被代理服务器证书的 PEM 格式的可信 CA 证书。

语法 proxy_ssl_verify on | off;
默认值
proxy_ssl_verify off;
上下文 stream, server

启用或禁用验证被代理服务器证书。

语法 proxy_ssl_verify_depth number;
默认值
proxy_ssl_verify_depth 1;
上下文 stream, server

设置被代理服务器证书链中的验证深度。

语法 proxy_timeout timeout;
默认值
proxy_timeout 10m;
上下文 stream, server

设置客户端或被代理服务器连接上两次连续读写操作之间的 超时时间。如果在此时间内没有数据传输,连接将关闭。

语法 proxy_upload_rate rate;
默认值
proxy_upload_rate 0;
上下文 stream, server

此指令出现在 1.9.3 版本中。

限制从客户端读取数据的速度。rate 以字节/秒为单位指定。零值禁用速率限制。限制是针对每个连接设置的,因此如果客户端同时打开两个连接,总速率将是指定限制的两倍。

参数值可以包含变量 (1.17.0)。这在需要根据特定条件限制速率的情况下可能有用

map $slow $rate {
    1     4k;
    2     8k;
}

proxy_upload_rate $rate;