一、模塊定位與引入

• 模塊名稱：ngx_stream_upstream_module

• 首次引入：NGINX 1.9.0（2015-08-04）

• 編譯選項：啟用 --with-stream（含此模塊）

• 作用：

  1. 定義后端服務器組（upstream 塊）
  2. 配置各服務器參數（權重、失敗判斷、DNS 動態解析等）
  3. 通過多種算法分配客戶端連接
  4. 支持商業版的動態可配置與健康檢查

二、核心指令與參數

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

• 說明：

  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 等指令中靈活引用，監控后端性能與故障。

五、實戰優化與注意事項

1. 共享 zone 大小：zone name 64k 一般可容納數百條服務器配置。
2. DNS TTL 與 valid：resolver valid 覆蓋 DNS TTL，推薦設置為 5–30 秒。
3. 一致性哈希：節點增刪需配合 consistent，否則大規模重映射影響緩存或會話。
4. 備份與故障切換：backup 參數只在主節點全掛時生效；可配合 max_fails、fail_timeout 精細調整。
5. 商業版特性：如需在線健康檢查、慢啟動、API 動態修改，請評估 NGINX Plus 或商業訂閱。

六、總結

ngx_stream_upstream_module 是構建高可用、高性能 TCP/UDP 代理的核心模塊。通過靈活的服務器組定義、多樣的負載均衡算法、動態 DNS 支持與豐富的監控變量，它能夠滿足從簡單輪詢到金融級一致性哈希、從靜態配置到動態熱更新的全方位需求。升級至 NGINX ≥1.9.0，結合商業版特性，更能在不間斷部署與流量管控上發揮巨大價值。

立即部署：根據業務特點選擇合適的負載均衡策略與參數，讓您的四層流量穩定、高效、可觀測！