模組 ngx_http_upstream_module

ngx_http_upstream_module 模組用於定義伺服器群組，這些群組可由 proxy_pass、fastcgi_pass、uwsgi_pass、scgi_pass、memcached_pass 和 grpc_pass 指令引用。

upstream backend {
    server backend1.example.com       weight=5;
    server backend2.example.com:8080;
    server unix:/tmp/backend3;

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

server {
    location / {
        proxy_pass http://backend;
    }
}

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

resolver 10.0.0.1;

upstream dynamic {
    zone upstream_dynamic 64k;

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

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

server {
    location / {
        proxy_pass http://dynamic;
        health_check;
    }
}

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

範例

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

    server backup1.example.com  backup;
}

預設情況下，請求會在伺服器之間使用加權循環配置方法進行分配。在上面的範例中，每 7 個請求將按如下方式分配：5 個請求發送到 backend1.example.com，第二個和第三個伺服器各發送一個請求。如果在與伺服器通訊期間發生錯誤，請求將傳遞到下一個伺服器，依此類推，直到嘗試所有正常運作的伺服器。如果無法從任何伺服器獲得成功的回應，客戶端將收到與最後一個伺服器通訊的結果。

定義伺服器的 address 和其他 parameters。 位址可以指定為網域名稱或 IP 位址，可選擇指定埠，也可以指定為 “unix:” 前綴後面的 UNIX 網域套接字路徑。如果未指定埠，則使用埠 80。解析為多個 IP 位址的網域名稱會一次定義多個伺服器。

可以定義以下參數

weight=number

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

max_conns=number

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

如果啟用閒置 keepalive 連線、多個工作程序和共享記憶體，則連線到代理伺服器的作用中和閒置連線總數可能會超過 max_conns 值。

自 1.5.9 版以來和在 1.11.5 版之前，此參數可作為我們商業訂閱的一部分。

max_fails=number

設定在 fail_timeout 參數設定的持續時間內，與伺服器通訊時應發生的不成功嘗試次數，以將伺服器視為在 fail_timeout 參數也設定的持續時間內不可用。預設情況下，不成功嘗試次數設定為 1。零值會停用嘗試次數的計算。什麼被視為不成功的嘗試由 proxy_next_upstream、fastcgi_next_upstream、uwsgi_next_upstream、scgi_next_upstream、memcached_next_upstream 和 grpc_next_upstream 指令定義。

fail_timeout=time

設定

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

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

backup

將伺服器標記為備份伺服器。當主伺服器不可用時，請求會傳遞給它。

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

down

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

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

resolve

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

為了使此參數起作用，必須在http 區塊或相應的upstream 區塊中指定 resolver 指令。

route=string

設定伺服器路由名稱。

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、ip_hash 和 random 負載平衡方法一起使用。

drain

將伺服器置於「drain」模式 (1.13.6)。在此模式下，只有繫結到伺服器的請求會被代理到它。

在 1.13.6 版之前，參數只能使用 API 模組變更。

如果群組中只有一個伺服器，則會忽略 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 可以包含文字、變數及其組合。請注意，從群組新增或移除伺服器可能會導致將大部分金鑰重新對應到不同的伺服器。此方法與 Cache::Memcached Perl 程式庫相容。

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

指定群組應使用負載平衡方法，根據用戶端 IP 位址在伺服器之間分配請求。用戶端 IPv4 位址的前三個八位元組，或整個 IPv6 位址，將用作雜湊鍵。此方法確保來自同一用戶端的請求將始終傳遞到同一伺服器，除非該伺服器不可用。在後一種情況下，用戶端請求將傳遞到另一個伺服器。最有可能的情況是，它也將始終是同一伺服器。

從 1.3.2 和 1.2.2 版本開始支援 IPv6 位址。

如果需要暫時移除其中一台伺服器，則應使用 down 參數標記，以保留目前用戶端 IP 位址的雜湊。

範例

upstream backend {
    ip_hash;

    server backend1.example.com;
    server backend2.example.com;
    server backend3.example.com down;
    server backend4.example.com;
}

在 1.3.1 和 1.2.2 版本之前，無法使用 ip_hash 負載平衡方法為伺服器指定權重。

啟用與上游伺服器的連線快取。

connections 參數設定每個工作程序快取中保留的閒置 keepalive 連線到上游伺服器的最大數量。當超過此數字時，最近最少使用的連線將會關閉。

應特別注意的是，keepalive 指令不會限制 nginx 工作程序可以開啟到上游伺服器的連線總數。connections 參數應設定為一個足夠小的數字，以讓上游伺服器也能處理新的連入連線。

當使用預設的輪詢方法以外的負載平衡方法時，必須在 keepalive 指令之前啟用它們。

使用 keepalive 連線的 memcached 上游範例組態

upstream memcached_backend {
    server 127.0.0.1:11211;
    server 10.0.0.2:11211;

    keepalive 32;
}

server {
    ...

    location /memcached/ {
        set $memcached_key $uri;
        memcached_pass memcached_backend;
    }

}

對於 HTTP，應將 proxy_http_version 指令設定為「1.1」，並且應清除「Connection」標頭欄位。

upstream http_backend {
    server 127.0.0.1:8080;

    keepalive 16;
}

server {
    ...

    location /http/ {
        proxy_pass http://http_backend;
        proxy_http_version 1.1;
        proxy_set_header Connection "";
        ...
    }
}

或者，可以使用 HTTP/1.0 持續連線，方法是將「Connection: Keep-Alive」標頭欄位傳遞到上游伺服器，但此方法不建議使用。

對於 FastCGI 伺服器，需要設定 fastcgi_keep_conn 才能使 keepalive 連線生效。

upstream fastcgi_backend {
    server 127.0.0.1:9000;

    keepalive 8;
}

server {
    ...

    location /fastcgi/ {
        fastcgi_pass fastcgi_backend;
        fastcgi_keep_conn on;
        ...
    }
}

SCGI 和 uwsgi 通訊協定沒有 keepalive 連線的概念。

keepalive_requests 1000;

設定可透過一個 keepalive 連線提供的最大請求數。在達到最大請求數後，連線將會關閉。

定期關閉連線是釋放每個連線記憶體配置所必需的。因此，使用過高的最大請求數可能會導致過多的記憶體使用，不建議使用。

在 1.19.10 版本之前，預設值為 100。

keepalive_time 1h;

限制透過一個 keepalive 連線處理請求的最大時間。達到此時間後，連線將在後續請求處理後關閉。

keepalive_timeout 60s;

設定閒置 keepalive 連線到上游伺服器的開啟時間逾時。

允許使用 NTLM 驗證 代理請求。當用戶端發送一個「Authorization」標頭欄位值以「Negotiate」或「NTLM」開頭的請求時，上游連線將會繫結到用戶端連線。後續的用戶端請求將會透過相同的上游連線代理，保持驗證內容。

為了使 NTLM 驗證生效，必須啟用與上游伺服器的 keepalive 連線。應將 proxy_http_version 指令設定為「1.1」，並且應清除「Connection」標頭欄位。

upstream http_backend {
    server 127.0.0.1:8080;

    ntlm;
}

server {
    ...

    location /http/ {
        proxy_pass http://http_backend;
        proxy_http_version 1.1;
        proxy_set_header Connection "";
        ...
    }
}

當使用預設輪詢方法以外的負載平衡方法時，必須在 ntlm 指令之前啟用它們。

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

指定群組應使用負載平衡方法，將請求傳遞到具有最少活動連線數的伺服器，同時考慮伺服器的權重。如果有多個此類伺服器，則會使用加權輪詢平衡方法依次嘗試它們。

指定群組應使用負載平衡方法，將請求傳遞到平均回應時間最少且活動連線數最少的伺服器，同時考慮伺服器的權重。如果有多個此類伺服器，則會使用加權輪詢平衡方法依次嘗試它們。

如果指定 header 參數，則使用接收 回應標頭 的時間。如果指定 last_byte 參數，則使用接收 完整回應 的時間。如果指定 inflight 參數（1.11.6），則也會考慮未完成的請求。

在 1.11.6 版本之前，預設情況下會考慮未完成的請求。

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

如果在處理請求時無法立即選擇上游伺服器，則請求將會被放入佇列。此指令指定佇列中可以同時存在的最大請求 number。如果佇列已滿，或者在 timeout 參數中指定的時間段內無法選取要將請求傳遞到的伺服器，則會將 502（錯誤的閘道）錯誤傳回用戶端。

timeout 參數的預設值為 60 秒。

當使用預設輪詢方法以外的負載平衡方法時，必須在 queue 指令之前啟用它們。

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

指定群組應使用負載平衡方法，將請求傳遞到隨機選取的伺服器，同時考慮伺服器的權重。

可選的 two 參數指示 nginx 隨機選取 兩個 伺服器，然後使用指定的 method 選取伺服器。預設方法為 least_conn，它將請求傳遞到具有最少活動連線數的伺服器。

least_time 方法會將請求傳遞到平均回應時間最少且活動連線數最少的伺服器。如果指定了 least_time=header，則使用接收 回應標頭 的時間。如果指定了 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;

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

啟用會話親和性，這會導致來自同一用戶端的請求被傳遞到伺服器群組中的同一伺服器。提供三種方法

cookie

當使用 cookie 方法時，有關指定伺服器的資訊將會傳遞到由 nginx 產生的 HTTP cookie 中。

upstream backend {
    server backend1.example.com;
    server backend2.example.com;

    sticky cookie srv_id expires=1h domain=.example.com path=/;
}

來自尚未繫結到特定伺服器的用戶端的請求將會傳遞到由已設定平衡方法選取的伺服器。後續帶有此 cookie 的請求將會傳遞到指定的伺服器。如果指定的伺服器無法處理請求，則會選取新的伺服器，如同用戶端尚未繫結一樣。

由於負載平衡方法始終嘗試平均分配負載，同時考慮已繫結的請求，因此具有較多活動繫結請求的伺服器獲得新未繫結請求的可能性較小。

第一個參數設定要設定或檢查的 cookie 名稱。cookie 值是 IP 位址和連接埠，或 UNIX 網域 Socket 路徑的 MD5 雜湊的十六進位表示形式。但是，如果指定了 server 指令的「route」參數，則 cookie 值將會是「route」參數的值。

upstream backend {
    server backend1.example.com route=a;
    server backend2.example.com route=b;

    sticky cookie srv_id expires=1h domain=.example.com path=/;
}

在此情況下，「srv_id」cookie 的值將會是 a 或 b。

其他參數可能如下所示

expires=time

設定瀏覽器應保留 cookie 的 time。特殊值 max 將會導致 cookie 在「31 Dec 2037 23:55:55 GMT」時過期。如果未指定此參數，則會導致 cookie 在瀏覽器會話結束時過期。

domain=domain

定義設定 cookie 的 domain。參數值可以包含變數 (1.11.5)。

httponly

將 HttpOnly 屬性新增至 cookie (1.7.11)。

samesite=strict | lax | none | $variable

將 SameSite (1.19.4) 屬性加入到 Cookie 中，其值可為以下其中之一：Strict、Lax、None，或使用變數 (1.23.3)。在後者的情況下，如果變數值為空，則不會將 SameSite 屬性加入 Cookie 中；如果值解析為 Strict、Lax 或 None，則會賦予對應的值；否則將賦予 Strict 值。

secure

將 Secure 屬性加入到 Cookie 中 (1.7.11)。

path=路徑

定義設定 Cookie 的 路徑。

如果省略任何參數，則不會設定對應的 Cookie 欄位。

route

當使用 route 方法時，被代理的伺服器會在收到第一個請求時為客戶端分配路由。來自此客戶端的所有後續請求都將在 Cookie 或 URI 中攜帶路由資訊。此資訊會與 server 指令的 “route” 參數進行比較，以識別應該將請求代理到哪個伺服器。如果未指定 “route” 參數，則路由名稱將是 IP 位址和埠，或 UNIX 網域套接字路徑的 MD5 雜湊值的十六進位表示。如果指定的伺服器無法處理請求，則會像請求中沒有路由資訊一樣，透過配置的負載平衡方法選擇新的伺服器。

route 方法的參數指定可能包含路由資訊的變數。第一個非空的變數會用於尋找匹配的伺服器。

範例

map $cookie_jsessionid $route_cookie {
    ~.+\.(?P<route>\w+)$ $route;
}

map $request_uri $route_uri {
    ~jsessionid=.+\.(?P<route>\w+)$ $route;
}

upstream backend {
    server backend1.example.com route=a;
    server backend2.example.com route=b;

    sticky route $route_cookie $route_uri;
}

這裡，路由會從請求中存在的 “JSESSIONID” Cookie 中取得。否則，將使用 URI 中的路由。

learn

當使用 learn 方法 (1.7.1) 時，nginx 會分析上游伺服器的回應，並學習伺服器啟動的會話，這些會話通常在 HTTP Cookie 中傳遞。

upstream backend {
   server backend1.example.com:8080;
   server backend2.example.com:8081;

   sticky learn
          create=$upstream_cookie_examplecookie
          lookup=$cookie_examplecookie
          zone=client_sessions:1m;
}

在範例中，上游伺服器透過在回應中設定 Cookie “EXAMPLECOOKIE” 來建立會話。後續帶有此 Cookie 的請求將傳遞到同一伺服器。如果伺服器無法處理請求，則會像尚未綁定客戶端一樣選擇新的伺服器。

參數 create 和 lookup 分別指定變數，這些變數指示如何建立新會話和搜尋現有會話。兩個參數都可以指定多次，在這種情況下，將使用第一個非空的變數。

會話儲存在共享記憶體區域中，其 名稱 和 大小 由 zone 參數配置。在 64 位元平台上，1 MB 的區域可以儲存約 4000 個會話。在 timeout 參數指定的時間內未存取的會話會從該區域中移除。預設情況下，timeout 設定為 10 分鐘。

header 參數 (1.13.1) 允許在從上游伺服器接收回應標頭後立即建立會話。

sync 參數 (1.13.8) 啟用共享記憶體區域的 同步。

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

此指令自 1.5.7 版本起已過時。應使用具有新語法的等效 sticky 指令。

sticky cookie 名稱 [expires=時間] [domain=網域] [path=路徑];

ngx_http_upstream_module 模組支援以下內嵌變數

$upstream_addr

保留上游伺服器的 IP 位址和埠，或 UNIX 網域套接字的路徑。如果在請求處理期間聯繫了多個伺服器，則它們的位址會用逗號分隔，例如 “192.168.1.1:80, 192.168.1.2:80, unix:/tmp/sock”。如果發生從一個伺服器群組到另一個伺服器群組的內部重新導向，由 “X-Accel-Redirect” 或 error_page 發起，則來自不同群組的伺服器位址會用冒號分隔，例如 “192.168.1.1:80, 192.168.1.2:80, unix:/tmp/sock : 192.168.10.1:80, 192.168.10.2:80”。如果無法選擇伺服器，則變數會保留伺服器群組的名稱。

$upstream_bytes_received

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

$upstream_bytes_sent

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

$upstream_cache_status

保留存取回應快取的狀態 (0.8.3)。狀態可以是 “MISS”、“BYPASS”、“EXPIRED”、“STALE”、“UPDATING”、“REVALIDATED” 或 “HIT”。

$upstream_connect_time

保留與上游伺服器建立連線所花費的時間 (1.9.1)；時間以秒為單位，精確到毫秒。在 SSL 的情況下，包含握手所花費的時間。多個連線的時間會像 $upstream_addr 變數中的位址一樣，用逗號和冒號分隔。

$upstream_cookie_名稱

上游伺服器在 “Set-Cookie” 回應標頭欄位中傳送的指定 名稱 的 Cookie (1.7.1)。只會儲存最後一個伺服器回應中的 Cookie。

$upstream_header_time

保留從上游伺服器接收回應標頭所花費的時間 (1.7.10)；時間以秒為單位，精確到毫秒。多個回應的時間會像 $upstream_addr 變數中的位址一樣，用逗號和冒號分隔。

$upstream_http_名稱

保留伺服器回應標頭欄位。例如，“Server” 回應標頭欄位可透過 $upstream_http_server 變數取得。將標頭欄位名稱轉換為變數名稱的規則與以 “$http_” 前綴開頭的變數相同。只會儲存最後一個伺服器回應中的標頭欄位。

$upstream_last_server_name

保留最後選擇的上游伺服器的名稱 (1.25.3)；允許透過 SNI 傳遞

proxy_ssl_server_name on;
proxy_ssl_name        $upstream_last_server_name;

此變數可作為我們 商業訂閱 的一部分。

$upstream_queue_time

保留請求在上游 佇列 中所花費的時間 (1.13.9)；時間以秒為單位，精確到毫秒。多個回應的時間會像 $upstream_addr 變數中的位址一樣，用逗號和冒號分隔。

$upstream_response_length

保留從上游伺服器取得的回應長度 (0.7.27)；長度以位元組為單位。多個回應的長度會像 $upstream_addr 變數中的位址一樣，用逗號和冒號分隔。

$upstream_response_time

保留從上游伺服器接收回應所花費的時間；時間以秒為單位，精確到毫秒。多個回應的時間會像 $upstream_addr 變數中的位址一樣，用逗號和冒號分隔。

$upstream_status

保留從上游伺服器取得的回應的狀態碼。多個回應的狀態碼會像 $upstream_addr 變數中的位址一樣，用逗號和冒號分隔。如果無法選擇伺服器，則變數會保留 502 (Bad Gateway) 狀態碼。

$upstream_trailer_名稱

保留從上游伺服器取得的回應結尾的欄位 (1.13.10)。