模块 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”对指定的 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 keepalive”行为。默认情况下，操作系统设置对套接字有效。如果将指令设置为“on”值，则将为套接字打开 SO_KEEPALIVE 套接字选项。

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

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

指定包含 PEM 格式密钥的 文件，用于对 gRPC SSL 服务器进行身份验证。

可以指定 engine:名称:ID 代替 文件，它从 OpenSSL 引擎 名称 加载具有指定 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 可能导致意外行为。

指定包含已吊销证书 (CRL) 的file，该文件以 PEM 格式用于验证 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 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”错误，请尝试禁用会话重用。

指定包含受信任 CA 证书的file，该文件以 PEM 格式用于验证 gRPC SSL 服务器的证书。

grpc_ssl_verify off;

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

grpc_ssl_verify_depth 1;

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