一、模块定位与引入
-
模块名称：
ngx_stream_upstream_module -
首次引入：NGINX 1.9.0（2015-08-04）
-
编译选项：启用
--with-stream（含此模块） -
作用：
- 定义后端服务器组（
upstream块） - 配置各服务器参数（权重、失败判断、DNS 动态解析等）
- 通过多种算法分配客户端连接
- 支持商业版的动态可配置与健康检查
- 定义后端服务器组（
二、核心指令与参数
1. 定义上游组
upstream <name> {[负载均衡算法指令]server <address> [参数];[更多 server ...][zone <zone_name> <size>;][state /path/to/state.file;]
}
upstream name { … }：声明一个后端组，供proxy_pass引用。zone name size（1.9.0 商业版可动态）：在共享内存中保存配置与运行状态，用于多 worker 共享与热更新。state file（1.9.7 商业版可用）：外部持久化服务器列表与参数，Nginx 重载或升级可保留状态。
2. 定义后端服务器
server <domain|IP:port>|unix:/path [参数];
常用参数：
| 参数 | 含义 |
|---|---|
weight=n | 权重，默认 1，轮询时按比例分配 |
max_conns=n | 最大并发连接数（1.11.5） |
max_fails=n | 在 fail_timeout 时间内允许的失败次数，超过则标记为不可用 |
fail_timeout=time | 标记失败及恢复时间，默认 10s |
backup | 备份服务器，只有主服务器都不可用时才会被调用 |
down | 永久禁用该服务器 |
resolve | 开启动态 DNS 解析，需配合 resolver |
service=name | 基于 DNS SRV 记录解析（1.9.13） |
| 商业版 | slow_start、健康检查 (health_check)、动态修改、API 控制 |
3. 负载均衡算法
在 upstream 块中，可任选一种或多种算法指令；若不指定，默认为加权轮询。
-
hash <key> [consistent]（1.11.2）
基于<key>的哈希值分配，consistent开启一致性哈希，减少因节点变动导致的重映射。 -
least_conn
将连接分配给活动连接数最少的服务器，多个最少则按权重轮询。 -
least_time <connect|first_byte|last_byte> [inflight]（商业版）
按平均响应时间（建立连接/首字节/全量）和活动连接数综合考量。 -
random [two [method]]（1.15.1）
随机挑选服务器，two参数从两台中再按least_conn等方法选出最佳。
4. DNS 解析支持
resolver 10.0.0.1 [valid=30s] [ipv4=off|ipv6=off] [status_zone=zone];
resolver_timeout 5s;
resolve：配合server ... resolve，自动在后台定期刷新域名 IP 列表。service=name：支持 SRV 记录，自动按优先级与权重构建主/备服务器。resolver_timeout（1.27.3）：解析超时时间。
三、最小可运行示例
stream {resolver 127.0.0.1 valid=10s;upstream backend {zone backend_zone 64k;hash $remote_addr consistent;server backend1.example.com:12345 weight=5 resolve;server backend2.example.com:12345 resolve;server unix:/tmp/backend3;server backup1.example.com:12345 backup;}server {listen 12346;# 轮询之外：也可在此加 health_check;proxy_pass backend;}
}
-
说明：
- 使用一致性哈希，让相同客户端 IP 总落到同一台后端；
resolve动态更新 DNS，结合zone共享配置；backup只在所有主服务器均失效时才启用。
四、嵌入式变量
ngx_stream_upstream_module 自 1.11.4 起提供监控与日志埋点变量：
| 变量 | 含义 |
|---|---|
$upstream_addr | 实际连接的后端地址列表，多个用逗号分隔 |
$upstream_bytes_received | 从后端接收的字节数，多个连接用逗号分隔 |
$upstream_bytes_sent | 向后端发送的字节数 |
$upstream_connect_time | 建立连接耗时（秒，毫秒精度） |
$upstream_first_byte_time | 等待首字节耗时 |
$upstream_session_time | 整个会话持续时间 |
可在 access_log、map、if 等指令中灵活引用，监控后端性能与故障。
五、实战优化与注意事项
- 共享 zone 大小：
zone name 64k一般可容纳数百条服务器配置。 - DNS TTL 与 valid：
resolver valid覆盖 DNS TTL，推荐设置为 5–30 秒。 - 一致性哈希：节点增删需配合
consistent，否则大规模重映射影响缓存或会话。 - 备份与故障切换：
backup参数只在主节点全挂时生效；可配合max_fails、fail_timeout精细调整。 - 商业版特性：如需在线健康检查、慢启动、API 动态修改，请评估 NGINX Plus 或商业订阅。
六、总结
ngx_stream_upstream_module 是构建高可用、高性能 TCP/UDP 代理的核心模块。通过灵活的服务器组定义、多样的负载均衡算法、动态 DNS 支持与丰富的监控变量，它能够满足从简单轮询到金融级一致性哈希、从静态配置到动态热更新的全方位需求。升级至 NGINX ≥1.9.0，结合商业版特性，更能在不间断部署与流量管控上发挥巨大价值。
立即部署：根据业务特点选择合适的负载均衡策略与参数，让您的四层流量稳定、高效、可观测！
