模块 ngx_http_grpc_module

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

server {
    listen 9000;

    http2 on;

    location / {
        grpc_pass 127.0.0.1:9000;
    }
}

发起与 gRPC 服务器的传出连接 从具有可选端口的指定本地 IP 地址。 Parameter value 可以包含变量。 特殊值取消效果 Directives 继承自之前的配置级别，这允许 系统自动分配本地 IP 地址和端口。offgrpc_bind

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

grpc_bind $remote_addr transparent;

为了使此参数起作用， 通常需要使用超级用户权限运行 nginx 工作进程。 在 Linux 上，它不是必需的，就像 参数为 Worker processes 从 master 进程继承能力。 还需要配置内核路由表 拦截来自 gRPC 服务器的网络流量。transparentCAP_NET_RAW

grpc_buffer_size 4k|8k;

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

grpc_connect_timeout 60s;

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

默认情况下， nginx 不传递标头字段 “Date”， “Server”和 “X-Accel-...”从 gRPC 的响应 server 设置为客户端。 该Directives设置其他字段 这不会被通过。 相反，如果需要允许传递字段， 可以使用 grpc_pass_header Directives。grpc_hide_header

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

如果未禁用，则这些标头字段的处理将如下所示 影响：

• “X-Accel-Redirect” 执行internal 重定向到指定的 URI;
• “X-Accel-Charset” 设置响应的所需字符集。

grpc_intercept_errors off;

确定代码是否大于或等于 gRPC 服务器响应 到 300 应传递给客户端 或者被拦截并重定向到 nginx 进行处理 替换为 error_page Directives。

grpc_next_upstream error timeout;

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

error

与 server、向其传递请求或读取响应标头;

timeout

与 server、向其传递请求或读取响应标头;

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

通常，使用非幂等方法的请求 (, , ) 不会传递到下一个服务器 请求是否已发送到上游服务器; 启用此选项明确允许重试此类请求;POSTLOCKPATCH

off

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

应该记住，将请求传递给下一个服务器是 仅当尚未向客户端发送任何内容时才有可能。 也就是说，如果在 传输响应，则无法修复此问题。

该Directives还定义了什么被视为不成功 尝试与服务器通信。 的情况 ， 和 始终被视为不成功的尝试， 即使它们未在Directives中指定。 、 、 并且是 仅当在Directives中指定了尝试时，才被视为不成功的尝试。 和 的情况从不被视为不成功的尝试。errortimeoutinvalid_headerhttp_500http_502http_503http_504http_429http_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;

要使用 gRPC over SSL，应使用 “” 方案：grpcs://

grpc_pass grpcs://127.0.0.1:443;

如果一个域名解析为多个地址，则所有地址都将是 以循环方式使用。 此外，还可以将地址指定为服务器组。

参数值可以包含变量 （1.17.8）。 在这种情况下，如果将地址指定为域名， 在描述的服务器组中搜索名称， 如果未找到，则使用解析程序确定。

允许传递否则禁用的标头 字段。

grpc_read_timeout 60s;

定义从 gRPC 服务器读取响应的超时。 超时仅在两个连续的读取作 （ 而不是为了传输整个响应。 如果 gRPC 服务器在此时间内没有传输任何内容， 连接已关闭。

grpc_send_timeout 60s;

设置向 gRPC 服务器发送请求的超时时间。 超时仅在两个连续的写入作 （ 而不是为了传输整个请求。 如果 gRPC 服务器在此时间内没有收到任何内容， 连接已关闭。

grpc_set_header Content-Length $content_length;

允许重新定义字段或将字段附加到传递给 gRPC 服务器的请求标头。 可以包含文本、变量及其组合。 这些Directives继承自之前的配置级别 当且仅当没有Directives时 在当前级别上定义。valuegrpc_set_header

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

grpc_set_header Accept-Encoding "";

grpc_socket_keepalive off;

配置 “TCP keepalive” 行为 用于与 gRPC 服务器的传出连接。 默认情况下，作系统的设置对套接字有效。 如果Directives设置为值 “”，则为套接字打开套接字选项。onSO_KEEPALIVE

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

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

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

可以指定值 ：： 而不是 ， 它加载具有从 OpenSSL 引擎指定的密钥。enginenameidfileidname

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

grpc_ssl_ciphers DEFAULT;

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

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

在与 gRPC SSL 服务器建立连接时设置任意 OpenSSL 配置命令。

使用 OpenSSL 1.0.2 或更高版本时，支持该Directives。

多个Directives 可以在同一级别上指定。 这些Directives继承自之前的配置级别 当且仅当存在 无Directives 在当前级别上定义。grpc_ssl_conf_commandgrpc_ssl_conf_command

请注意，直接配置 OpenSSL 可能会导致意外行为。

指定具有已吊销证书 （CRL） 的 采用 PEM 格式，用于验证 gRPC SSL 服务器的证书。file

启用 gRPC SSL 服务器连接 SSL 密钥的日志记录 并指定密钥日志文件的路径。 密钥以与 Wireshark 兼容的 SSLKEYLOGFILE 格式记录。

该Directives作为我们商业订阅的一部分提供。

grpc_ssl_name host from grpc_pass;

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

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

指定 a with passphrases for secret keys，其中每个密码都在单独的行上指定。 加载密钥时依次尝试密码。file

grpc_ssl_protocols TLSv1.2 TLSv1.3;

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

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

grpc_ssl_server_name off;

启用或禁用通过 TLS 传递服务器名称 服务器名称指示扩展 （SNI、RFC 6066） 与 gRPC SSL 服务器建立连接时。

grpc_ssl_session_reuse on;

确定在使用 gRPC 服务器。 如果错误 “” ，请尝试禁用会话重用。SSL3_GET_FINISHED:digest check failed

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

grpc_ssl_verify off;

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

grpc_ssl_verify_depth 1;

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