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

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

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

grpc_bind $remote_addr transparent;

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

grpc_buffer_size 4k|8k;

设置size用于读取从 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_403http_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则为套接字打开套接字选项。

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

从1.21.0版本开始，名称中可以使用变量file。

指定filePEM 格式的密钥，用于对 gRPC SSL 服务器进行身份验证。

可以指定值 engine:: 来代替，它name会 从 OpenSSL 引擎中加载指定的密钥。 idfileidname

从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 可能会导致意外行为。

指定filePEM 格式的已撤销证书 (CRL)，用于验证 gRPC SSL 服务器的证书。

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 服务器的请求启用指定协议。

TLSv1.3从 1.23.4 开始默认使用 该参数。

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具有 PE​​M 格式的可信 CA 证书，用于验证 gRPC SSL 服务器的证书。

grpc_ssl_verify off;

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

grpc_ssl_verify_depth 1;

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