gRPC#

允许将请求传递给 gRPC 服务器。该模块需要 HTTP/2

配置示例#

server {
    listen 9000;

    http2 on;

    location / {
        grpc_pass 127.0.0.1:9000;
    }
}

指令#

grpc_bind#

语法

grpc_bind address [transparent] | off;

默认值

上下文

http, server, location

使发往 gRPC 服务器的外部连接从指定的本地 IP 地址发起,且可选端口。参数值可以包含变量。特殊值 off 取消从上一个配置级别继承的 grpc_bind 指令的效果,从而允许系统自动分配本地 IP 地址和端口。

transparent 参数允许从非本地 IP 地址发起对 gRPC 服务器的外部连接,例如,从客户端的真实 IP 地址:

grpc_bind $remote_addr transparent;

为了使此参数生效,通常需要以 superuser 权限运行 Angie 工作进程。在 Linux 上,如果指定了 transparent 参数,则工作进程会从主进程继承 CAP_NET_RAW 能力,因此不需要特权。

重要

必须配置内核路由表以拦截来自 gRPC 服务器的网络流量。

grpc_buffer_size#

语法

grpc_buffer_size size;

默认值

grpc_buffer_size 4k|8k;

上下文

http, server, location

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

grpc_connect_timeout#

语法

grpc_connect_timeout time;

默认值

grpc_connect_timeout 60s;

上下文

http, server, location

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

grpc_connection_drop#

语法

grpc_connection_drop time | on | off;

默认值

grpc_connection_drop off;

上下文

http, server, location

在代理服务器被从组中移除或通过 reresolve 进程或 API 命令 DELETE 标记为永久不可用后,允许终止与代理服务器的所有连接。

当处理客户端或代理服务器的下一个读或写事件时,连接被终止。

设置 time 启用连接终止 超时;当设置为 on 时,连接会立即被丢弃。

grpc_hide_header#

语法

grpc_hide_header field;

默认值

上下文

http, server, location

默认情况下,Angie 不会将 gRPC 服务器响应中的 "Date"、"Server" 和 "X-Accel-..." 头字段传递给客户端。grpc_hide_header 指令设置额外的字段不会被传递。相反,如果需要允许传递字段,可以使用 grpc_pass_header 指令。

grpc_ignore_headers#

语法

grpc_ignore_headers field ...;

默认值

上下文

http, server, location

禁用处理来自 gRPC 服务器的某些响应头字段。可以忽略的字段包括:"X-Accel-Redirect" 和 "X-Accel-Charset"。

如果未禁用,这些头字段的处理会产生以下效果:

  • "X-Accel-Redirect" 执行对指定 URI 的 内部 重定向;

  • "X-Accel-Charset" 设置响应的期望 charset

grpc_intercept_errors#

语法

grpc_intercept_errors on | off;

默认值

grpc_intercept_errors off;

上下文

http, server, location

确定 gRPC 响应的状态码大于或等于 300 时,是否应将其传递给客户端,或者被拦截并重定向到 Angie 进行处理,与 error_page 指令一起使用。

grpc_next_upstream#

语法

grpc_next_upstream error | timeout | invalid_header | http_500 | http_502 | http_503 | http_504 | http_403 | http_404 | http_429 | non_idempotent | off ...;

默认值

grpc_next_upstream error timeout;

上下文

http, server, location

指定在什么情况下请求应传递到 上游池 中的下一个服务器:

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

通常,带有 non-idempotent 方法的请求 (POSTLOCKPATCH) 在向上游服务器发送请求后不会被传递到下一个服务器;启用此选项显式允许重试此类请求;

off

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

备注

应注意,只有在尚未向客户端发送任何内容的情况下,才能将请求传递到下一个服务器。也就是说,如果在响应传输过程中发生错误或超时,无法修复此问题。

该指令还定义了与服务器通信的 不成功尝试 的标准。

error
timeout
invalid_header

始终被视为不成功的尝试,即使未在指令中指定

http_500
http_502
http_503
http_504
http_429

仅在指令中指定时才被视为不成功的尝试

http_403
http_404

从不被视为不成功的尝试

将请求传递到下一个服务器可以受到 尝试次数时间 的限制。

grpc_next_upstream_timeout#

语法

grpc_next_upstream_timeout time;

默认值

grpc_next_upstream_timeout 0;

上下文

http, server, location

限制可以传递给 下一个 服务器的请求的时间。

0

关闭此限制

grpc_next_upstream_tries#

语法

grpc_next_upstream_tries number;

默认值

grpc_next_upstream_tries 0;

上下文

http, server, location

限制可以传递请求到 下一个 服务器的尝试次数。

0

关闭此限制

grpc_pass#

语法

grpc_pass address;

默认值

上下文

location, if in location

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

如果域名解析为多个地址,则所有地址将以轮询方式使用。此外,可以将地址指定为 服务器组。如果使用了组,则不能与其一起指定端口;相反,必须为组内每个服务器单独指定端口。

参数值可以包含变量。在这种情况下,如果地址被指定为域名,则会在描述的服务器组中进行查找,如果未找到,则使用 resolver 进行确定。

grpc_pass_header#

语法

grpc_pass_header field ...;

默认值

上下文

http, server, location

允许将 否则被禁用 的头字段从 gRPC 服务器传递给客户端。

grpc_read_timeout#

语法

grpc_read_timeout time;

默认值

grpc_read_timeout 60s;

上下文

http, server, location

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

grpc_send_timeout#

语法

grpc_send_timeout time;

默认值

grpc_send_timeout 60s;

上下文

http, server, location

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

grpc_set_header#

语法

grpc_set_header field value;

默认值

grpc_set_header Content-Length $content_length;

上下文

http, server, location

允许重新定义或追加字段到请求头 传递给 gRPC 服务器。值可以包含文本、变量及其组合。如果当前级别没有定义 grpc_set_header 指令,则这些指令将从上一个配置级别继承。

如果头字段的值为空字符串,则该字段将不会传递给 gRPC 服务器:

grpc_set_header Accept-Encoding "";

grpc_socket_keepalive#

语法

grpc_socket_keepalive on | off;

默认值

grpc_socket_keepalive off;

上下文

http, server, location

配置与 gRPC 服务器的外发连接的“TCP keepalive”行为。

""

默认情况下,操作系统的设置对套接字生效。

on

套接字的 SO_KEEPALIVE 选项被打开。

grpc_ssl_certificate#

语法

grpc_ssl_certificate file;

默认值

上下文

http, server, location

指定用于认证 gRPC SSL 服务器的 PEM 格式证书文件。文件名中可以使用变量。

grpc_ssl_certificate_key#

语法

grpc_ssl_certificate_key file;

默认值

上下文

http, server, location

指定用于认证 gRPC SSL 服务器的 PEM 格式秘密密钥文件。

可以指定值 "engine:name:id" 作为文件,这将从指定的 OpenSSL 引擎名称中加载带有指定 ID 的秘密密钥。文件名中可以使用变量。

grpc_ssl_ciphers#

语法

grpc_ssl_ciphers ciphers;

默认值

grpc_ssl_ciphers DEFAULT;

上下文

http, server, location

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

密码列表取决于已安装的 OpenSSL 版本。可以使用 openssl ciphers 命令查看完整列表。

grpc_ssl_conf_command#

语法

grpc_ssl_conf_command name value;

默认值

上下文

http, server, location

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

重要

当使用 OpenSSL 1.0.2 或更高版本时支持该指令。

可以在同一层级指定多个 grpc_ssl_conf_command 指令。如果当前级别没有定义 grpc_ssl_conf_command 指令,则这些指令将从上一个配置级别继承。

小心

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

grpc_ssl_crl#

语法

grpc_ssl_crl file;

默认值

上下文

http, server, location

指定带有撤销证书(CRL)的 PEM 格式文件,用于 验证 gRPC SSL 服务器的证书。

grpc_ssl_name#

语法

grpc_ssl_name name;

默认值

grpc_ssl_name `host 来自 grpc_pass;`

上下文

http, server, location

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

默认情况下,使用 grpc_pass URL 的主机部分。

grpc_ssl_password_file#

语法

grpc_ssl_password_file file;

默认值

上下文

http, server, location

指定一个文件,其中包含 秘密密钥 的密码,每个密码单独一行。当加载密钥时,将依次尝试密码。

grpc_ssl_protocols#

语法

grpc_ssl_protocols [SSLv2] [SSLv3] [TLSv1] [TLSv1.1] [TLSv1.2] [TLSv1.3];

默认值

grpc_ssl_protocols TLSv1.2 TLSv1.3;

上下文

http, server, location

在 1.2.0 版本发生变更: TLSv1.3 参数已添加到默认集。

启用指定的协议以请求 gRPC HTTPS 服务器。

grpc_ssl_server_name#

语法

grpc_ssl_server_name on | off;

默认值

grpc_ssl_server_name off;

上下文

http, server, location

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

grpc_ssl_session_reuse#

语法

grpc_ssl_session_reuse on | off;

默认值

grpc_ssl_session_reuse on;

上下文

http, server, location

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

grpc_ssl_trusted_certificate#

语法

grpc_ssl_trusted_certificate file;

默认值

上下文

http, server, location

指定一个带有受信任 CA 证书的 PEM 格式文件,用于 验证 gRPC SSL 服务器的证书。

grpc_ssl_verify#

语法

grpc_ssl_verify on | off;

默认值

grpc_ssl_verify off;

上下文

http, server, location

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

grpc_ssl_verify_depth#

语法

grpc_ssl_verify_depth number;

默认值

grpc_ssl_verify_depth 1;

上下文

http, server, location

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