NGINX 四层上游模块`ngx_stream_upstream_module` 实战指南

一、模块定位与引入

模块名称 ：ngx_stream_upstream_module
首次引入：NGINX 1.9.0（2015-08-04）
编译选项 ：启用 --with-stream（含此模块）
作用：
1. 定义后端服务器组（upstream 块）
2. 配置各服务器参数（权重、失败判断、DNS 动态解析等）
3. 通过多种算法分配客户端连接
4. 支持商业版的动态可配置与健康检查

二、核心指令与参数

1. 定义上游组

nginx 复制代码

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. 定义后端服务器

nginx 复制代码

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 解析支持

nginx 复制代码

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）：解析超时时间。

三、最小可运行示例

nginx 复制代码

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;
    }
}

说明：
1. 使用一致性哈希，让相同客户端 IP 总落到同一台后端；
2. resolve 动态更新 DNS，结合 zone 共享配置；
3. 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，结合商业版特性，更能在不间断部署与流量管控上发挥巨大价值。

立即部署：根据业务特点选择合适的负载均衡策略与参数，让您的四层流量稳定、高效、可观测！