Module 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 worker 进程。在 Linux 上不是必需的，因为如果指定了 transparent 参数，worker 进程会从 master 进程继承 CAP_NET_RAW 能力。还需要配置内核路由表来拦截来自 gRPC 服务器的网络流量。

grpc_buffer_size 4k|8k;

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

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 套接字选项。

指定一个 PEM 格式的证书file，用于向 gRPC SSL 服务器进行认证。

从版本 1.21.0 起，文件名 file 中可以使用变量。

grpc_ssl_certificate_cache off;

定义一个缓存，用于存储使用变量指定的SSL 证书和密钥。

该指令具有以下参数

max

设置缓存中元素的最大数量；缓存溢出时会移除最近最少使用 (LRU) 的元素；

inactive

定义元素在此时间内未被访问后从缓存中移除的时间；默认值为 10 秒；

valid

定义缓存中元素被视为有效并可以重用的时间；默认值为 60 秒。超过此时间的证书将被重新加载或重新验证；

off

禁用缓存。

示例

grpc_ssl_certificate       $grpc_ssl_server_name.crt;
grpc_ssl_certificate_key   $grpc_ssl_server_name.key;
grpc_ssl_certificate_cache max=1000 inactive=20s valid=1m;

指定一个 PEM 格式的密钥file，用于向 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 可能会导致意外行为。

指定一个 PEM 格式的已吊销证书 (CRL) file，用于验证 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.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 会话。如果在日志中出现错误“digest check failed”，请尝试禁用会话重用。

指定一个 PEM 格式的受信任 CA 证书file，用于验证 gRPC SSL 服务器的证书。

grpc_ssl_verify off;

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

grpc_ssl_verify_depth 1;

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