模块 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 服务器接收的响应的缓冲区的size。响应在收到后立即同步传递给客户端。

grpc_connect_timeout 60s;

定义与 gRPC 服务器建立连接的超时时间。需要注意的是，此超时时间通常不能超过 75 秒。

默认情况下，nginx 不会将响应头字段“Date”、“Server”和“X-Accel-...”从 gRPC 服务器的响应传递给客户端。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 服务器的请求头。值可以包含文本、变量及其组合。仅当当前级别上未定义grpc_set_header指令时，才会从上一个配置级别继承这些指令。

如果头字段的值为空字符串，则不会将此字段传递给 gRPC 服务器

grpc_set_header Accept-Encoding "";

grpc_socket_keepalive off;

配置到 gRPC 服务器的传出连接的“TCP 保活”行为。默认情况下，操作系统的设置对套接字有效。如果将指令设置为“on”值，则为套接字启用SO_KEEPALIVE套接字选项。

指定用于向 gRPC SSL 服务器进行身份验证的 PEM 格式证书的文件。

自 1.21.0 版本起，变量可用于 file 名称中。

指定一个 file，其中包含用于向 gRPC SSL 服务器进行身份验证的 PEM 格式的密钥。

可以指定值 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_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 服务器证书链中的验证深度。