grpc代理

1.功能描述

默认自带 njet_http_grpc_module 允许传递请求 到 gRPC 服务器。

2.依赖模块

无

3.指令说明

格式说明:

• 语法 (Syntax): 描述了该指令在 njet 配置文件中如何书写。
• 默认值 (Default): 如果未明确配置该指令，njet 使用的默认值。 如果为 “—"，则表示没有默认值，必须显式配置。
• 上下文 (Context): 该指令可以在哪些配置块中使用，例如 http,server,location。

grpc_bind

描述 (Description):

使与 gRPC 服务器建立的传出连接从指定的本地 IP 地址（可选项带有端口）发起。参数值可以包含变量。特殊值 off 取消继承自前一个配置级别的 grpc_bind` 指令的效果，允许系统自动分配本地 IP 地址和端口。

transparent 参数允许与 gRPC 服务器建立的传出连接从非本地 IP 地址发起，例如，从客户端的真实 IP 地址：

grpc_bind $remote_addr transparent;

为了使此参数生效，通常需要以超级用户权限运行 njet worker 进程。在 Linux 上，如果指定了 transparent 参数，worker 进程会从 master 进程继承 CAP_NET_RAW 能力，因此不需要。还需要配置内核路由表以拦截来自 gRPC 服务器的网络流量。

grpc_buffer_size

描述 (Description):

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

grpc_connect_timeout

描述 (Description):

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

grpc_hide_header

描述 (Description):

默认情况下，njet 不会将来自 gRPC 服务器响应的 header 字段 “Date”、“Server” 和 “X-Accel-…” 传递给客户端。 grpc_hide_header 指令设置其他将不传递的字段。 相反，如果需要允许传递字段，可以使用 grpc_pass_header 指令。

grpc_ignore_headers

描述 (Description):

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

如果未禁用，则处理这些 header 字段具有以下效果：

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

grpc_intercept_errors

描述 (Description):

确定是否应将代码大于或等于 300 的 gRPC 服务器响应传递给客户端，还是应拦截并重定向到 njet，以便使用 error_page 指令进行处理。

grpc_next_upstream

描述 (Description):

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

• 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: 禁止将请求传递到下一个服务器。

应该记住，只有在尚未向客户端发送任何内容时，才可以将请求传递到下一个服务器。 也就是说，如果在传输响应的过程中发生错误或超时，则无法修复。

该指令还定义了什么被认为是与服务器通信的不成功尝试。

即使未在该指令中指定，错误、超时和无效头的情况也始终被认为是不成功的尝试。

仅当在该指令中指定了http_500、http_502、http_503、http_504和http_429的情况，才被认为是不成功的尝试。

永远不会将http_403和http_404的情况视为不成功的尝试。

将请求传递到下一个服务器可以通过尝试次数和时间来限制。

grpc_next_upstream_timeout

描述 (Description):

限制可以将请求传递到下一个服务器的时间。 值 0 关闭此限制。

grpc_next_upstream_tries

描述 (Description):

限制将请求传递到下一个服务器的可能尝试次数。 值 0 关闭此限制。

grpc_pass

描述 (Description):

设置 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_pass_header

描述 (Description):

允许将原本禁用的 header 字段从 gRPC 服务器传递到客户端。

grpc_read_timeout

描述 (Description):

定义从 gRPC 服务器读取响应的超时时间。 超时时间仅在两个连续的读取操作之间设置，而不适用于整个响应的传输。 如果 gRPC 服务器在此时间内未传输任何内容，则连接将关闭。

grpc_send_timeout

描述 (Description):

设置将请求传输到 gRPC 服务器的超时时间。 超时时间仅在两个连续的写入操作之间设置，而不适用于整个请求的传输。 如果 gRPC 服务器在此时间内未收到任何内容，则连接将关闭。

grpc_set_header

描述 (Description):

允许重新定义或将字段附加到传递给 gRPC 服务器的请求 header。 该值可以包含文本，变量及其组合。 仅当在当前级别上未定义 grpc_set_header` 指令时，这些指令才从前一个配置级别继承。

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

grpc_set_header Accept-Encoding "";

grpc_socket_keepalive

描述 (Description):

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

grpc_ssl_certificate

描述 (Description):

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

grpc_ssl_certificate_cache

描述 (Description):

定义一个缓存，用于存储使用变量指定的 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;

grpc_ssl_certificate_key

描述 (Description):

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

可以指定值 engine:name:id 而不是文件，该值从 OpenSSL 引擎 name 加载具有指定 id 的密钥。

可以指定值 store:scheme:id 而不是文件，该值用于加载具有指定 id 和 OpenSSL 提供程序注册 URI 方案（例如 pkcs11）的密钥。

grpc_ssl_ciphers

描述 (Description):

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

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

grpc_ssl_conf_command

描述 (Description):

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

可以在同一级别上指定多个 grpc_ssl_conf_command 指令。 仅当在当前级别上未定义 grpc_ssl_conf_command 指令时，这些指令才从前一个配置级别继承。

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

grpc_ssl_crl

描述 (Description):

指定一个文件，其中包含 PEM 格式的已吊销证书 (CRL)，用于验证 gRPC SSL 服务器的证书。

grpc_ssl_name

描述 (Description):

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

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

grpc_ssl_password_file

描述 (Description):

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

grpc_ssl_protocols

描述 (Description):

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

grpc_ssl_server_name

描述 (Description):

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

grpc_ssl_session_reuse

描述 (Description):

确定在使用 gRPC 服务器时是否可以重用 SSL 会话。 如果日志中出现错误 “摘要检查失败”，请尝试禁用会话重用。

grpc_ssl_trusted_certificate

描述 (Description):

指定一个文件，其中包含 PEM 格式的可信 CA 证书，用于验证 gRPC SSL 服务器的证书。

grpc_ssl_verify

描述 (Description):

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

grpc_ssl_verify_depth

描述 (Description):

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

4.配置样例

njet.conf:

server {
    listen 9000;
    access_log logs/access_grpc.log;
    http2 on;

    location / {
        grpc_pass 127.0.0.1:50051;
        }
}

5.调用样例

grpc_client 发起请求

./grpc_client -addr localhost:9000 
2025/09/10 11:21:46 Greeting: Hello world

./grpc_client -addr localhost:9000 -name requestnjet 
2025/09/10 11:21:56 Greeting: Hello requestnjet

grpc_server的日志

./grpc_sever 
2025/09/10 11:16:34 server listening at [::]:50051
2025/09/10 11:21:46 Received: world
2025/09/10 11:21:56 Received: requestnjet

查看njet accesslog日志

tail  -f /usr/local/njet/logs/access_grpc.log
127.0.0.1 - - [10/Sep/2025:11:24:45 +0800] "POST /helloworld.Greeter/SayHello HTTP/2.0" 200 24 "-" "grpc-go/1.75.0"