模組 ngx_stream_upstream_module

ngx_stream_upstream_module 模組 (1.9.0) 用於定義伺服器群組，這些群組可以被 proxy_pass 指令引用。

upstream backend {
    hash $remote_addr consistent;

    server backend1.example.com:12345  weight=5;
    server backend2.example.com:12345;
    server unix:/tmp/backend3;

    server backup1.example.com:12345   backup;
    server backup2.example.com:12345   backup;
}

server {
    listen 12346;
    proxy_pass backend;
}

具有定期健康檢查的動態可配置群組，可作為我們的商業訂閱一部分。

resolver 10.0.0.1;

upstream dynamic {
    zone upstream_dynamic 64k;

    server backend1.example.com:12345 weight=5;
    server backend2.example.com:12345 fail_timeout=5s slow_start=30s;
    server 192.0.2.1:12345            max_fails=3;
    server backend3.example.com:12345 resolve;
    server backend4.example.com       service=http resolve;

    server backup1.example.com:12345  backup;
    server backup2.example.com:12345  backup;
}

server {
    listen 12346;
    proxy_pass dynamic;
    health_check;
}

定義伺服器群組。伺服器可以監聽不同的連接埠。此外，可以混合監聽 TCP 和 UNIX 網域套接字的伺服器。

範例

upstream backend {
    server backend1.example.com:12345 weight=5;
    server 127.0.0.1:12345            max_fails=3 fail_timeout=30s;
    server unix:/tmp/backend2;
    server backend3.example.com:12345 resolve;

    server backup1.example.com:12345  backup;
}

預設情況下，連線會使用加權循環配置方法在伺服器之間分配。在上面的範例中，每 7 個連線將按如下方式分配：5 個連線傳送到 backend1.example.com:12345，而第二個和第三個伺服器各傳送一個連線。如果在與伺服器通訊時發生錯誤，連線將傳遞到下一個伺服器，依此類推，直到嘗試所有正常運作的伺服器為止。如果與所有伺服器的通訊都失敗，連線將關閉。

定義伺服器的 address 和其他 parameters。地址可以指定為網域名稱或帶有必要連接埠的 IP 地址，或者指定為在 “unix:” 前綴之後指定的 UNIX 網域套接字路徑。解析為多個 IP 地址的網域名稱會同時定義多個伺服器。

可以定義以下參數

weight=number

設定伺服器的權重，預設為 1。

max_conns=number

限制同時到代理伺服器的最大連線number (1.11.5)。預設值為零，表示沒有限制。如果伺服器群組未駐留在共用記憶體中，則限制適用於每個工作程序。

在 1.11.5 版本之前，此參數可作為我們商業訂閱的一部分。

max_fails=number

設定在由 fail_timeout 參數設定的時間內應發生的與伺服器通訊的失敗嘗試次數，以考慮在也由 fail_timeout 參數設定的時間內伺服器不可用。預設情況下，失敗嘗試次數設定為 1。零值會停用嘗試次數的計算。在此，失敗的嘗試是指在與伺服器建立連線時發生錯誤或逾時。

fail_timeout=time

設定

• 在該時間內應發生指定的與伺服器通訊的失敗嘗試次數，以考慮伺服器不可用；
• 以及伺服器將被視為不可用的時間段。

預設情況下，參數設定為 10 秒。

backup

將伺服器標記為備份伺服器。當主要伺服器不可用時，將連線傳遞到備份伺服器。

此參數不能與 hash 和 random 負載平衡方法一起使用。

down

將伺服器標記為永久不可用。

此外，以下參數可作為我們的 商業訂閱一部分

resolve

監控與伺服器網域名稱對應的 IP 位址的變更，並自動修改上游設定，而無需重新啟動 nginx。伺服器群組必須駐留在共用記憶體中。

為了使此參數正常工作，必須在 stream 區塊或相應的 upstream 區塊中指定 resolver 指令。

service=name

啟用 DNS SRV 記錄的解析並設定服務 name (1.9.13)。為了使此參數正常工作，有必要為伺服器指定 resolve 參數並指定沒有連接埠號碼的主機名稱。

如果服務名稱不包含點號（“.”），則會建構符合 RFC 的名稱，並且 TCP 通訊協定會新增至服務前綴。例如，要查找 _http._tcp.backend.example.com SRV 記錄，必須指定指令

server backend.example.com service=http resolve;

如果服務名稱包含一個或多個點，則名稱會通過聯結服務前綴和伺服器名稱來建構。例如，要查找 _http._tcp.backend.example.com 和 server1.backend.example.com SRV 記錄，必須指定指令

server backend.example.com service=_http._tcp resolve;
server example.com service=server1.backend resolve;

最高優先順序 SRV 記錄（具有相同最小數值優先順序值的記錄）會解析為主要伺服器，其餘 SRV 記錄會解析為備份伺服器。如果為伺服器指定 backup 參數，則高優先順序 SRV 記錄會解析為備份伺服器，其餘 SRV 記錄會被忽略。

slow_start=time

設定在伺服器從零恢復其權重到標稱值期間的 time，當不健康的伺服器變為健康時，或者當伺服器在被視為不可用一段時間後變為可用時。預設值為零，即停用慢速啟動。

此參數不能與 hash 和 random 負載平衡方法一起使用。

如果群組中只有一個伺服器，則會忽略 max_fails、fail_timeout 和 slow_start 參數，並且該伺服器永遠不會被視為不可用。

定義共用記憶體區的 name 和 size，該記憶體區保留群組的設定和工作程序之間共用的執行時間狀態。多個群組可以共用同一個區。在這種情況下，只需指定一次 size 即可。

此外，作為我們商業訂閱的一部分，此類群組允許變更群組成員資格或修改特定伺服器的設定，而無需重新啟動 nginx。設定可通過 API 模組 (1.13.3) 存取。

在 1.13.3 版本之前，設定只能通過由 upstream_conf 處理的特殊位置存取。

指定保留動態可配置群組狀態的 file。

範例

state /var/lib/nginx/state/servers.conf; # path for Linux
state /var/db/nginx/state/servers.conf;  # path for FreeBSD

目前狀態僅限於包含其參數的伺服器列表。在剖析設定時讀取檔案，並且每次變更上游設定時都會更新檔案。應避免直接變更檔案內容。此指令不能與 server 指令一起使用。

在設定重新載入或二進位升級期間進行的變更可能會遺失。

此指令可作為我們的商業訂閱一部分。

指定伺服器群組的負載平衡方法，其中用戶端-伺服器對應關係基於雜湊的 key 值。key 可以包含文字、變數及其組合 (1.11.2)。使用範例

hash $remote_addr;

請注意，從群組新增或移除伺服器可能會導致將大多數金鑰重新對應到不同的伺服器。此方法與 Cache::Memcached Perl 程式庫相容。

如果指定 consistent 參數，則將改用 ketama 一致雜湊方法。此方法確保在將伺服器新增到群組或從群組移除伺服器時，只有少數金鑰會重新對應到不同的伺服器。這有助於為快取伺服器實現更高的快取命中率。此方法與 Cache::Memcached::Fast Perl 程式庫相容，其中 ketama_points 參數設定為 160。

指定群組應使用負載平衡方法，其中連線會傳遞到具有最少有效連線數的伺服器，同時考慮伺服器的權重。如果有數個此類伺服器，則會使用加權循環配置方法依序嘗試它們。

指定群組應使用負載平衡方法，其中連線會傳遞到具有最少平均時間和最少有效連線數的伺服器，同時考慮伺服器的權重。如果有數個此類伺服器，則會使用加權循環配置方法依序嘗試它們。

如果指定 connect 參數，則使用連線到上游伺服器的時間 connect。如果指定 first_byte 參數，則使用接收資料的第一個位元組的時間。如果指定 last_byte，則使用接收資料最後一個位元組的時間。如果指定 inflight 參數 (1.11.6)，則也會考慮不完整的連線。

在 1.11.6 版本之前，預設會考慮不完整的連線。

此指令可作為我們的商業訂閱一部分。

指定群組應使用負載平衡方法，其中連線會傳遞到隨機選擇的伺服器，同時考慮伺服器的權重。

選用的 two 參數會指示 nginx 隨機選擇 兩個伺服器，然後使用指定的 method 選擇伺服器。預設方法是 least_conn，它會將連線傳遞到具有最少有效連線數的伺服器。

least_time 方法會將連線傳遞到具有最少平均時間和最少有效連線數的伺服器。如果指定 least_time=connect 參數，則使用連線到上游伺服器的時間 connect。如果指定 least_time=first_byte 參數，則使用接收資料的第一個位元組的時間。如果指定 least_time=last_byte，則使用接收資料最後一個位元組的時間。

least_time 方法可作為我們商業訂閱的一部分。

設定用來將上游伺服器的名稱解析為位址的名稱伺服器，例如：

resolver 127.0.0.1 [::1]:5353;

位址可以指定為網域名稱或 IP 位址，並可選擇性地加上埠號。如果沒有指定埠號，則使用埠號 53。名稱伺服器會以循環方式查詢。

預設情況下，nginx 在解析時會同時查找 IPv4 和 IPv6 位址。如果不需要查找 IPv4 或 IPv6 位址，可以指定 ipv4=off (1.23.1) 或 ipv6=off 參數。

預設情況下，nginx 會使用回應的 TTL 值來快取答案。可選的 valid 參數允許覆寫此值。

resolver 127.0.0.1 [::1]:5353 valid=30s;

為了防止 DNS 欺騙，建議在適當安全的可信任本地網路中設定 DNS 伺服器。

可選的 status_zone 參數啟用在指定的 zone 中收集 DNS 伺服器請求和回應的統計資訊。

此指令可作為我們的商業訂閱一部分。

resolver_timeout 30s;

設定名稱解析的逾時時間，例如：

resolver_timeout 5s;

此指令可作為我們的商業訂閱一部分。

ngx_stream_upstream_module 模組支援以下嵌入變數：

$upstream_addr

保留上游伺服器的 IP 位址和埠號，或是 UNIX 網域 socket 的路徑 (1.11.4)。如果在代理期間接觸了多個伺服器，它們的位址會以逗號分隔，例如：「192.168.1.1:12345, 192.168.1.2:12345, unix:/tmp/sock」。如果無法選擇伺服器，則變數會保留伺服器群組的名稱。

$upstream_bytes_received

從上游伺服器接收的位元組數 (1.11.4)。來自多個連線的值會以逗號分隔，就像 $upstream_addr 變數中的位址一樣。

$upstream_bytes_sent

傳送至上游伺服器的位元組數 (1.11.4)。來自多個連線的值會以逗號分隔，就像 $upstream_addr 變數中的位址一樣。

$upstream_connect_time

連線到上游伺服器的時間 (1.11.4)；時間以秒為單位，精確到毫秒。多個連線的時間會以逗號分隔，就像 $upstream_addr 變數中的位址一樣。

$upstream_first_byte_time

接收到第一個資料位元組的時間 (1.11.4)；時間以秒為單位，精確到毫秒。多個連線的時間會以逗號分隔，就像 $upstream_addr 變數中的位址一樣。

$upstream_session_time

以秒為單位，精確到毫秒的會話持續時間 (1.11.4)。多個連線的時間會以逗號分隔，就像 $upstream_addr 變數中的位址一樣。