gRPC#
允许将请求传递给 gRPC 服务器。
备注
此模块需要 HTTP2 模块。
配置示例#
server {
listen 9000;
http2 on;
location / {
grpc_pass 127.0.0.1:9000;
}
}
指令#
grpc_bind#
使到 gRPC 服务器的出站连接从指定的本地 IP 地址（可选端口）发起。参数值可以包含变量。特殊值 off 取消从上一配置级别继承的 grpc_bind 指令的效果，允许系统自动分配本地 IP 地址和端口。
transparent 参数允许到 gRPC 服务器的出站连接从非本地 IP 地址发起，例如从客户端的真实 IP 地址：
grpc_bind $remote_addr transparent;
为使此参数生效，通常需要以 超级用户 权限运行 Angie 工作进程。在 Linux 上不需要这样做，因为如果指定了 transparent 参数，工作进程会从主进程继承 CAP_NET_RAW 能力。
备注
需要配置内核路由表以拦截来自 gRPC 服务器的网络流量。
grpc_buffer_size#
设置用于读取从 gRPC 服务器接收的响应的第一部分的缓冲区大小。响应一旦接收到就会同步传递给客户端。
grpc_connect_timeout#
定义与 gRPC 服务器建立连接的超时时间。需要注意的是，此超时时间通常不能超过 75 秒。
grpc_connection_drop#
启用在代理服务器从组中移除或被 重新解析 进程或 API DELETE 命令标记为永久不可用后，终止到该服务器的所有连接。
当为客户端或代理服务器处理下一个读或写事件时，连接将被终止。
设置 time 启用连接终止 超时；
设置为 on 时，连接立即断开。
grpc_hide_header#
默认情况下，Angie 不会将 gRPC 服务器响应中的头字段 Date、Server 和 X-Accel-... 传递给客户端。grpc_hide_header 指令设置不会被传递的附加字段。相反，如果需要允许传递字段，可以使用 grpc_pass_header 指令。
grpc_ignore_headers#
禁用对来自 gRPC 服务器的某些响应头字段的处理。可以忽略以下字段：X-Accel-Redirect 和 X-Accel-Charset。
如果未禁用，处理这些头字段将产生以下效果：
grpc_intercept_errors#
确定代码大于或等于 300 的 gRPC 服务器响应应该传递给客户端，还是被拦截并重定向到 Angie 使用 error_page 指令进行处理。
grpc_next_upstream#
| |
默认值 |
|
http, server, location |
指定在哪些情况下应将请求传递给 upstream 组中的下一个服务器：
| 与服务器建立连接、向其传递请求或读取响应头时发生错误； |
| 与服务器建立连接、向其传递请求或读取响应头时发生超时； |
| 服务器返回空响应或无效响应； |
| 服务器返回代码为 500 的响应； |
| 服务器返回代码为 502 的响应； |
| 服务器返回代码为 503 的响应； |
| 服务器返回代码为 504 的响应； |
| 服务器返回代码为 403 的响应； |
| 服务器返回代码为 404 的响应； |
| 服务器返回代码为 429 的响应； |
| 通常，使用 非幂等 方法
（ |
| 禁用将请求传递给下一个服务器。 |
备注
应该记住，只有在尚未向客户端发送任何内容时，才可能将请求传递给下一个服务器。也就是说，如果在传输响应的过程中发生错误或超时，则无法修复此问题。
该指令还定义了什么被视为与服务器通信的 不成功尝试。
| 始终被视为不成功尝试，即使它们未在指令中指定 |
| 仅在指令中指定时才被视为不成功尝试 |
| 从不被视为不成功尝试 |
grpc_next_upstream_timeout#
限制可以将请求传递给 下一个服务器 的时间。
| 关闭此限制 |
grpc_next_upstream_tries#
限制将请求传递到 下一个 服务器的可能尝试次数。
| 关闭此限制 |
grpc_pass#
设置 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;
如果域名解析为多个地址，则所有地址都将以轮询方式使用。此外，地址可以指定为 服务器组。
参数值可以包含变量。在这种情况下，如果地址指定为域名，则在所描述的服务器组中搜索该名称，如果未找到，则使用 解析器 确定。
备注
如果在带有前缀尾部斜杠的 location 中指定 grpc_pass
（例如，location /name/），
并且 auto_redirect 指令设置为 default，
则不带尾部斜杠的请求将被重定向（/name -> /name/）。
grpc_pass_header#
允许将 原本禁用的 头字段从 gRPC 服务器传递到客户端。
grpc_read_timeout#
定义从 gRPC 服务器读取响应的超时时间。超时仅在两次连续的读取操作之间设置，而不是针对整个响应的传输。如果 gRPC 服务器在此时间内未传输任何内容，则连接将关闭。
grpc_send_timeout#
设置向 gRPC 服务器传输请求的超时。超时仅在两个连续的写操作之间设置，而不是针对整个请求的传输。如果 gRPC 服务器在此时间内未接收到任何内容，则连接将关闭。
grpc_set_header#
| |
默认值 |
|
http, server, location |
允许重新定义或追加字段到 传递 给 gRPC 服务器的请求头。值可以包含文本、变量及其组合。当且仅当当前级别未定义 grpc_set_header 指令时,这些指令才从上一级配置继承。
如果头字段的值为空字符串,则该字段将不会传递给 gRPC 服务器:
grpc_set_header Accept-Encoding "";
grpc_socket_keepalive#
配置到 gRPC 服务器的出站连接的"TCP keepalive"行为。
| 默认情况下,套接字使用操作系统的设置。 |
| 为套接字启用 SO_KEEPALIVE 套接字选项。 |
grpc_ssl_certificate#
指定一个 PEM 格式的证书文件,用于向 gRPC SSL 服务器进行身份验证。文件名中可以使用变量。
grpc_ssl_certificate_cache#
| |
默认值 |
|
http, server, location |
定义一个缓存,用于存储使用变量指定的 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#
指定一个 PEM 格式的密钥文件,用于向 gRPC SSL 服务器进行身份验证。
可以指定值 engine:name:id 来代替文件,这将从 OpenSSL 引擎 name 中加载具有指定 id 的密钥。
文件名中可以使用变量。
grpc_ssl_ciphers#
指定向 gRPC SSL 服务器发送请求时启用的密码套件。密码套件以 OpenSSL 库理解的格式指定。
密码套件列表取决于安装的 OpenSSL 版本。
可以使用 openssl ciphers 命令查看完整列表。
警告
使用 OpenSSL 时,:samp:grpc_ssl_ciphers 指令 不 配置 TLS 1.3 的密码套件。 要使用 OpenSSL 调整 TLS 1.3 密码套件,请使用 grpc_ssl_conf_command 指令, 该指令是为支持高级 SSL 配置而添加的。
在 LibreSSL 中,TLS 1.3 密码套件 可以 使用
grpc_ssl_ciphers配置。在 BoringSSL 中,TLS 1.3 密码套件完全无法配置。
grpc_ssl_conf_command#
在与 gRPC SSL 服务器建立连接时设置任意 OpenSSL 配置 命令。
备注
使用 OpenSSL 1.0.2 或更高版本时支持该指令。
要使用 OpenSSL 配置 TLS 1.3 密码套件,请使用 ciphersuites 命令。
可以在同一级别指定多个 grpc_ssl_conf_command 指令。当且仅当当前级别未定义 grpc_ssl_conf_command 指令时,这些指令才会从上一级配置继承。
警告
请注意,直接配置 OpenSSL 可能会导致意外行为。
grpc_ssl_crl#
指定一个包含 PEM 格式吊销证书 (CRL) 的文件,用于 验证 gRPC SSL 服务器的证书。
grpc_ssl_name#
允许覆盖用于 验证 gRPC SSL 服务器证书的服务器名称,以及在与 gRPC SSL 服务器建立连接时 通过 SNI 传递 的服务器名称。
默认情况下,使用 grpc_pass 中的主机名。
grpc_ssl_password_file#
指定一个包含 密钥 密码短语的文件,每个密码短语单独占一行。加载密钥时会依次尝试这些密码短语。
grpc_ssl_protocols#
| |
默认值 |
|
http, server, location |
在 1.2.0 版本发生变更: 默认集合中添加了 TLSv1.3 参数。
为向 gRPC SSL 服务器发送的请求启用指定的协议。
grpc_ssl_server_name#
启用或禁用在与 gRPC SSL 服务器建立连接时,通过 服务器名称指示 TLS 扩展 (SNI,`RFC 6066 <https://datatracker.ietf.org/doc/html/rfc6066.html>`_) 传递由 grpc_ssl_name 指令设置的服务器名称。
grpc_ssl_session_reuse#
确定在与 gRPC 服务器通信时是否可以重用 SSL 会话。如果日志中出现 "SSL3_GET_FINISHED:digest check failed" 错误,请尝试禁用会话重用。
grpc_ssl_trusted_certificate#
指定一个包含 PEM 格式受信任 CA 证书的文件,用于 验证 gRPC SSL 服务器的证书。
grpc_ssl_verify#
启用或禁用对 gRPC SSL 服务器证书的验证。
grpc_ssl_verify_depth#
设置 gRPC SSL 服务器证书链的验证深度。
目录