ngx_http_grpc_module 模組

ngx_http_grpc_module 模組允許將請求傳遞至 gRPC 伺服器 (1.13.10)。此模組需要 ngx_http_v2_module 模組。

server {
    listen 9000;

    http2 on;

    location / {
        grpc_pass 127.0.0.1:9000;
    }
}

使傳出至 gRPC 伺服器的連線，從指定的本機 IP 位址（可選擇埠號）發起。參數值可包含變數。特殊值 off 會取消從先前的組態層級繼承的 grpc_bind 指令效果，允許系統自動指派本機 IP 位址和埠號。

transparent 參數允許傳出至 gRPC 伺服器的連線，從非本機 IP 位址發起，例如，從用戶端的真實 IP 位址發起。

grpc_bind $remote_addr transparent;

為了使此參數生效，通常需要使用超級使用者權限執行 nginx 工作程序。在 Linux 上則不需要，因為如果指定 transparent 參數，工作程序會從主要程序繼承 CAP_NET_RAW 功能。此外，還需要設定核心路由表，以攔截來自 gRPC 伺服器的網路流量。

grpc_buffer_size 4k|8k;

設定用於讀取從 gRPC 伺服器收到的回應的緩衝區大小。一旦收到回應，就會同步傳遞給用戶端。

grpc_connect_timeout 60s;

定義與 gRPC 伺服器建立連線的逾時時間。應該注意的是，此逾時時間通常不能超過 75 秒。

預設情況下，nginx 不會將 gRPC 伺服器的回應中的標頭欄位「Date」、「Server」和「X-Accel-...」傳遞給用戶端。grpc_hide_header 指令會設定其他不傳遞的欄位。相反地，如果需要允許傳遞欄位，可以使用 grpc_pass_header 指令。

停用處理來自 gRPC 伺服器的特定回應標頭欄位。可以忽略下列欄位：「X-Accel-Redirect」和「X-Accel-Charset」。

如果未停用，則處理這些標頭欄位會有以下效果：

• 「X-Accel-Redirect」會執行內部重新導向至指定的 URI；
• 「X-Accel-Charset」會設定回應所需的 字元集。

grpc_intercept_errors off;

決定是否應將代碼大於或等於 300 的 gRPC 伺服器回應傳遞給用戶端，或者攔截並重新導向至 nginx 以使用 error_page 指令進行處理。

grpc_next_upstream error timeout;

指定在哪些情況下應將請求傳遞至下一個伺服器

error

在與伺服器建立連線、將請求傳遞給伺服器或讀取回應標頭時發生錯誤；

timeout

在與伺服器建立連線、將請求傳遞給伺服器或讀取回應標頭時發生逾時；

invalid_header

伺服器傳回空或無效的回應；

http_500

伺服器傳回代碼為 500 的回應；

http_502

伺服器傳回代碼為 502 的回應；

http_503

伺服器傳回代碼為 503 的回應；

http_504

伺服器傳回代碼為 504 的回應；

http_403

伺服器傳回代碼為 403 的回應；

http_404

伺服器傳回代碼為 404 的回應；

http_429

伺服器傳回代碼為 429 的回應；

non_idempotent

通常，如果已將請求傳送至上游伺服器，則不會將使用非等冪方法（POST、LOCK、PATCH）的請求傳遞至下一個伺服器；啟用此選項可明確允許重試此類請求；

off

停用將請求傳遞至下一個伺服器。

應該記住，只有在尚未傳送任何內容給用戶端時，才能將請求傳遞至下一個伺服器。也就是說，如果在傳輸回應的過程中發生錯誤或逾時，則無法修正此問題。

此指令也定義了什麼是與伺服器通訊的不成功嘗試。error、timeout 和 invalid_header 的情況始終被視為不成功嘗試，即使它們未在指令中指定。只有在指令中指定 http_500、http_502、http_503、http_504 和 http_429 的情況下，才視為不成功嘗試。http_403 和 http_404 的情況永遠不會被視為不成功嘗試。

將請求傳遞至下一個伺服器可以受到嘗試次數和時間的限制。

grpc_next_upstream_timeout 0;

限制請求可以傳遞至下一個伺服器的時間。0 值會關閉此限制。

grpc_next_upstream_tries 0;

限制將請求傳遞至下一個伺服器的可能嘗試次數。0 值會關閉此限制。

設定 gRPC 伺服器位址。位址可以指定為網域名稱或 IP 位址，以及埠號

grpc_pass localhost:9000;

或作為 UNIX 網域通訊端路徑

grpc_pass unix:/tmp/grpc.socket;

或者，可以使用 "grpc://" 配置。

grpc_pass grpc://127.0.0.1:9000;

若要透過 SSL 使用 gRPC，應使用 "grpcs://" 配置。

grpc_pass grpcs://127.0.0.1:443;

如果網域名稱解析為多個位址，則會以循環方式使用所有位址。此外，位址可以指定為伺服器群組。

參數值可以包含變數 (1.17.8)。在這種情況下，如果位址指定為網域名稱，則會在所述的 伺服器群組中搜尋名稱，如果找不到，則會使用解析程式判斷。

允許將否則停用的標頭欄位從 gRPC 伺服器傳遞至用戶端。

grpc_read_timeout 60s;

定義從 gRPC 伺服器讀取回應的逾時時間。逾時時間僅在兩個連續的讀取作業之間設定，而非整個回應的傳輸。如果 gRPC 伺服器在此時間內未傳輸任何內容，則連線會關閉。

grpc_send_timeout 60s;

設定將請求傳輸至 gRPC 伺服器的逾時時間。逾時時間僅在兩個連續的寫入作業之間設定，而非整個請求的傳輸。如果 gRPC 伺服器在此時間內未收到任何內容，則連線會關閉。

grpc_set_header Content-Length $content_length;

允許重新定義或附加欄位至傳遞至 gRPC 伺服器的請求標頭。value 可以包含文字、變數及其組合。如果目前的層級上沒有定義 grpc_set_header 指令，則這些指令會從先前的組態層級繼承。

如果標頭欄位的值為空字串，則此欄位不會傳遞至 gRPC 伺服器

grpc_set_header Accept-Encoding "";

grpc_socket_keepalive off;

設定傳出至 gRPC 伺服器的連線的「TCP keepalive」行為。預設情況下，作業系統的設定對通訊端生效。如果指令設定為 "on" 值，則會針對通訊端啟用 SO_KEEPALIVE 通訊端選項。

指定一個 file，其中包含 PEM 格式的憑證，用於驗證 gRPC SSL 伺服器。

自 1.21.0 版起，可以在 file 名稱中使用變數。

指定一個 file，其中包含 PEM 格式的秘密金鑰，用於驗證 gRPC SSL 伺服器。

可以指定 engine:name:id 值來取代 file，這會從 OpenSSL 引擎 name 載入具有指定 id 的秘密金鑰。

自 1.21.0 版起，可以在 file 名稱中使用變數。

grpc_ssl_ciphers DEFAULT;

指定對 gRPC SSL 伺服器請求啟用的密碼。密碼以 OpenSSL 程式庫理解的格式指定。

可以使用 "openssl ciphers" 命令檢視完整清單。

在與 gRPC SSL 伺服器建立連線時，設定任意的 OpenSSL 組態命令。

當使用 OpenSSL 1.0.2 或更高版本時，支援此指令。

可以在相同層級上指定多個 grpc_ssl_conf_command 指令。如果目前的層級上沒有定義 grpc_ssl_conf_command 指令，則這些指令會從先前的組態層級繼承。

請注意，直接設定 OpenSSL 可能會導致非預期的行為。

指定一個 file，其中包含 PEM 格式的已撤銷憑證 (CRL)，用於驗證 gRPC SSL 伺服器的憑證。

啟用 gRPC SSL 伺服器連線 SSL 金鑰的記錄，並指定金鑰記錄檔的路徑。金鑰會以與 Wireshark 相容的 SSLKEYLOGFILE 格式記錄。

此指令是我們商業訂閱的一部分。

grpc_ssl_name host from grpc_pass;

允許覆寫用於驗證 gRPC SSL 伺服器憑證的伺服器名稱，以及在與 gRPC SSL 伺服器建立連線時透過 SNI 傳遞的名稱。

預設情況下，會使用 grpc_pass 中的主機部分。

指定一個 file，其中包含私密金鑰的密碼，每個密碼都指定在不同的行上。載入金鑰時會依次嘗試這些密碼。

grpc_ssl_protocols TLSv1 TLSv1.1 TLSv1.2 TLSv1.3;

為 gRPC SSL 伺服器的請求啟用指定的協定。

自 1.23.4 版本起，預設使用 TLSv1.3 參數。

grpc_ssl_server_name off;

在與 gRPC SSL 伺服器建立連線時，啟用或停用透過 TLS 伺服器名稱指示擴展（SNI，RFC 6066）傳遞伺服器名稱。

grpc_ssl_session_reuse on;

決定在使用 gRPC 伺服器時是否可以重複使用 SSL 會話。如果日誌中出現錯誤 “SSL3_GET_FINISHED:digest check failed”，請嘗試停用會話重用。

指定一個 file，其中包含用於驗證 gRPC SSL 伺服器憑證的 PEM 格式的受信任 CA 憑證。

grpc_ssl_verify off;

啟用或停用 gRPC SSL 伺服器憑證的驗證。

grpc_ssl_verify_depth 1;

設定 gRPC SSL 伺服器憑證鏈中的驗證深度。