Module ngx_http_grpc_module

• Example Configuration
• Directives
  • grpc_bind
  • grpc_buffer_size
  • grpc_connect_timeout
  • grpc_hide_header
  • grpc_ignore_headers
  • grpc_intercept_errors
  • grpc_next_upstream
  • grpc_next_upstream_timeout
  • grpc_next_upstream_tries
  • grpc_pass
  • grpc_pass_header
  • grpc_read_timeout
  • grpc_send_timeout
  • grpc_set_header
  • grpc_socket_keepalive
  • grpc_ssl_certificate
  • grpc_ssl_certificate_key
  • grpc_ssl_ciphers
  • grpc_ssl_crl
  • grpc_ssl_name
  • grpc_ssl_password_file
  • grpc_ssl_protocols
  • grpc_ssl_server_name
  • grpc_ssl_session_reuse
  • grpc_ssl_trusted_certificate
  • grpc_ssl_verify
  • grpc_ssl_verify_depth
    

ngx_http_grpc_module模块允许将请求传递到 gRPC 服务器(1.13.10)。该模块需要ngx_http_v2_module模块。

Example Configuration

server {
    listen 9000 http2;

    location / {
        grpc_pass 127.0.0.1:9000;
    }
}

Directives

Syntax:	grpc_bind address [transparent ] | off;
Default:	—
Context:	http , server , location

到 gRPC 服务器的传出连接源自具有可选端口的指定本地 IP 地址。参数值可以包含变量。特殊值off取消了从先前的配置级别继承的grpc_bind指令的效果，这使系统可以自动分配本地 IP 地址和端口。

transparent参数允许到 gRPC 服务器的传出连接来自 nonlocalIP 地址，例如，来自客户端的真实 IP 地址：

grpc_bind $remote_addr transparent;

为了使此参数起作用，通常必须使用superuser特权运行 nginx worker 进程。在 Linux 上，不需要指定transparent参数，工作进程从主进程继承CAP_NET_RAW功能。还必须配置内核路由表以拦截来自 gRPC 服务器的网络流量。

Syntax:	grpc_buffer_size size;
Default:	grpc_buffer_size 4k|8k;
Context:	http , server , location

设置用于读取从 gRPC 服务器接收到的响应的缓冲区的size。收到响应后，该响应就会同步传递到客户端。

Syntax:	grpc_connect_timeout time;
Default:	grpc_connect_timeout 60s;
Context:	http , server , location

定义用于与 gRPC 服务器构建连接的超时。请注意，此超时通常不能超过 75 秒。

Syntax:	grpc_hide_header field;
Default:	—
Context:	http , server , location

默认情况下，nginx 不会将 gRPC 服务器的响应中的 Headers 字段“日期”，“服务器”和“ X-Accel -...”传递给客户端。 grpc_hide_header指令设置了不会传递的其他字段。相反，如果需要允许传递字段，则可以使用grpc_pass_header指令。

Syntax:	grpc_ignore_headers field ...;
Default:	—
Context:	http , server , location

禁用来自 gRPC 服务器的某些响应 Headers 字段的处理。可以忽略以下字段：“ X-Accel-Redirect”和“ X-Accel-Charset”。

如果未禁用，则处理这些头字段具有以下效果：

• “ X-Accel-Redirect”对指定的 URI 执行internal redirect；

• “ X-Accel-Charset”设置所需的响应charset。

Syntax:	grpc_intercept_errors on | off;
Default:	grpc_intercept_errors off;
Context:	http , server , location

确定是否将代码大于或等于 300 的 gRPC 服务器响应传递给客户端，或者将其拦截并重定向到 nginx 以使用error_page指令进行处理。

Syntax:	grpc_next_upstream error | timeout | invalid_header | http_500 | http_502 | http_503 | http_504 | http_403 | http_404 | http_429 | non_idempotent | off ...;
Default:	grpc_next_upstream error timeout;
Context:	http , server , location

指定在哪种情况下将请求传递到下一个服务器：

• error

  • 与服务器构建连接，向服务器传递请求或读取响应头时发生错误；

• timeout

  • 与服务器构建连接，向服务器传递请求或读取响应 Headers 时发生超时；

• 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

• 通常，如果请求已发送到上游服务器，则使用non-idempotent方法(POST，LOCK，PATCH)的请求不会传递到下一个服务器。明确启用此选项将允许重试此类请求；

• off

  • 禁用将请求传递到下一个服务器。

应该记住的是，只有在还没有任何内容发送给客户端的情况下，才有可能将请求传递给下一台服务器。即，如果在响应的传输过程中发生错误或超时，则无法解决该问题。

该指令还定义了与服务器通信的unsuccessful attempt。 error，timeout和invalid_header的情况始终被认为是失败的尝试，即使未在指令中指定它们也是如此。 http_500，http_502，http_503，http_504和http_429的情况只有在指令中指定时才被认为是不成功的尝试。绝不会将http_403和http_404的情况视为未成功的尝试。

将请求传递到下一个服务器可能受到尝试次数和time的限制。

Syntax:	grpc_next_upstream_timeout time;
Default:	grpc_next_upstream_timeout 0;
Context:	http , server , location

限制可以将请求传递到next server的时间。 0值关闭了此限制。

Syntax:	grpc_next_upstream_tries number;
Default:	grpc_next_upstream_tries 0;
Context:	http , server , location

限制将请求传递到next server的可能尝试次数。 0值关闭了此限制。

Syntax:	grpc_pass address;
Default:	—
Context:	location , if in location

设置 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;

如果一个域名解析为多个地址，则所有这些地址都将以循环方式使用。另外，可以将地址指定为server group。

参数值可以包含变量(1.17.8)。在这种情况下，如果将地址指定为域名，则在描述的server groups中搜索该名称，如果找不到，则使用resolver确定。

Syntax:	grpc_pass_header field;
Default:	—
Context:	http , server , location

允许将otherwise disabledHeaders 字段从 gRPC 服务器传递到客户端。

Syntax:	grpc_read_timeout time;
Default:	grpc_read_timeout 60s;
Context:	http , server , location

定义用于从 gRPC 服务器读取响应的超时。超时仅在两次连续的读取操作之间设置，而不用于传输整个响应。如果 gRPC 服务器在此时间内未传输任何内容，则连接将关闭。

Syntax:	grpc_send_timeout time;
Default:	grpc_send_timeout 60s;
Context:	http , server , location

设置将请求传输到 gRPC 服务器的超时。超时仅在两个连续的写操作之间设置，而不用于整个请求的传输。如果 gRPC 服务器在此时间内未收到任何信息，则连接将关闭。

Syntax:	grpc_set_header field value;
Default:	grpc_set_header Content-Length $content_length;
Context:	http , server , location

允许将字段重新定义或附加到 gRPC 服务器的请求 Headerspassed。 value可以包含文本，变量及其组合。当且仅当当前级别上未定义grpc_set_header指令时，这些指令才从上一级继承。

如果 Headers 字段的值为空字符串，则该字段将不会传递到 gRPC 服务器：

grpc_set_header Accept-Encoding "";

Syntax:	grpc_socket_keepalive on | off;
Default:	grpc_socket_keepalive off;
Context:	http , server , location

该指令出现在 1.15.6 版中。

为与 gRPC 服务器的传出连接配置“ TCP keepalive”行为。默认情况下，os 的设置对套接字有效。如果伪指令设置为值“ on”，则将为套接字打开SO_KEEPALIVE套接字选项。

Syntax:	grpc_ssl_certificate file;
Default:	—
Context:	http , server , location

使用用于对 gRPC SSL 服务器进行身份验证的 PEM 格式的证书指定file。

Syntax:	grpc_ssl_certificate_key file;
Default:	—
Context:	http , server , location

使用用于对 gRPC SSL 服务器进行身份验证的 PEM 格式的密钥指定一个file。

可以指定值engine：name：id而不是file，后者从 OpenSSL 引擎name加载具有指定id的密钥。

Syntax:	grpc_ssl_ciphers ciphers;
Default:	grpc_ssl_ciphers DEFAULT;
Context:	http , server , location

指定对 gRPC SSL 服务器的请求的启用密码。密码以 OpenSSL 库可以理解的格式指定。

可以使用“ openssl ciphers”命令查看完整列表。

Syntax:	grpc_ssl_crl file;
Default:	—
Context:	http , server , location

使用 PEM 格式指定file带有已吊销证书(CRL)的证书，用于verify gRPC SSL 服务器的证书。

Syntax:	grpc_ssl_name name;
Default:	grpc_ssl_name host from grpc_pass;
Context:	http , server , location

与 gRPC SSL 服务器构建连接时，允许覆盖用于verify gRPC SSL 服务器的证书和通过 SNI的服务器名称。

默认情况下，使用grpc_pass的主机部分。

Syntax:	grpc_ssl_password_file file;
Default:	—
Context:	http , server , location

指定一个带有secret keys密码短语的file，其中每个密码短语都在单独的行上指定。加载密钥时依次尝试使用密码短语。

Syntax:	grpc_ssl_protocols [SSLv2] [SSLv3] [TLSv1] [TLSv1.1] [TLSv1.2] [TLSv1.3];
Default:	grpc_ssl_protocols TLSv1 TLSv1.1 TLSv1.2;
Context:	http , server , location

为对 gRPC SSL 服务器的请求启用指定的协议。

Syntax:	grpc_ssl_server_name on | off;
Default:	grpc_ssl_server_name off;
Context:	http , server , location

与 gRPC SSL 服务器构建连接时，启用或禁用通过TLS 服务器名称指示扩展(SNI，RFC 6066)传递服务器名称。

Syntax:	grpc_ssl_session_reuse on | off;
Default:	grpc_ssl_session_reuse on;
Context:	http , server , location

确定使用 gRPC 服务器时是否可以重用 SSL 会话。如果日志中出现错误“ SSL3_GET_FINISHED:digest check failed”，请尝试禁用会话重用。

Syntax:	grpc_ssl_trusted_certificate file;
Default:	—
Context:	http , server , location

指定file带有 PEM 格式的受信任 CA 证书，用于verify gRPC SSL 服务器的证书。

Syntax:	grpc_ssl_verify on | off;
Default:	grpc_ssl_verify off;
Context:	http , server , location

启用或禁用 gRPC SSL 服务器证书的验证。

Syntax:	grpc_ssl_verify_depth number;
Default:	grpc_ssl_verify_depth 1;
Context:	http , server , location

在 gRPC SSL 服务器证书链中设置验证深度。