模块 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” performs an internal redirect to the specified URI;
• “X-Accel-Charset” sets the desired charset of a response.

grpc_intercept_errors off;

确定是否将 gRPC 服务器响应的代码大于或等于 300 的响应传递给客户端，还是拦截并重定向到 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 版本以来，可以在文件名中使用变量。

指定用于与 gRPC SSL 服务器进行身份验证的 PEM 格式文件中的秘密密钥。

可以指定engine:name:id的值来代替文件，从 OpenSSL 引擎name中加载具有指定id的秘密密钥。

自 1.21.0 版本以来，可以在文件名中使用变量。

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 格式中用于验证 gRPC SSL 服务器证书的吊销证书（CRL）文件。

grpc_ssl_name host from grpc_pass;

允许覆盖用于验证 gRPC SSL 服务器证书和在与 gRPC SSL 服务器建立连接时通过 SNI 进行传递的服务器名称。

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

指定一个包含密钥的密码短语文件，其中每个密码短语都在单独的一行上指定。加载密钥时将依次尝试密码短语。

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

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

从版本 1.23.4 开始，默认情况下使用TLSv1.3参数。

grpc_ssl_server_name off;

启用或禁用通过TLS Server Name Indication extension（SNI，RFC 6066）在与gRPC SSL服务器建立连接时传递服务器名称。

grpc_ssl_session_reuse on;

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

指定以PEM格式存储的可信CA证书文件用于验证gRPC SSL服务器的证书。

grpc_ssl_verify off;

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

grpc_ssl_verify_depth 1;

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