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 参数允许从非本地 IP 地址发起对 gRPC 服务器的外部连接，例如，从客户端的真实 IP 地址：
grpc_bind $remote_addr transparent;
为了使此参数生效，通常需要以 superuser 权限运行 Angie 工作进程。在 Linux 上，如果指定了 transparent 参数，则工作进程会从主进程继承 CAP_NET_RAW 能力，因此不需要特权。
备注
必须配置内核路由表以拦截来自 gRPC 服务器的网络流量。
grpc_buffer_size#
设置用于读取从 gRPC 服务器接收到的响应第一部分的缓冲区大小。响应会在同步接收后立即传递给客户端。
grpc_connect_timeout#
定义与 gRPC 服务器建立连接的超时时间。需要注意的是，此超时时间通常不能超过 75 秒。
grpc_connection_drop#
在代理服务器被从组中移除或通过 reresolve 进程或 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#
确定 gRPC 响应的状态码大于或等于 300 时，是否应将其传递给客户端，或者被拦截并重定向到 Angie 进行处理，与 error_page 指令一起使用。
grpc_next_upstream#
| |
默认值 |
|
http, server, location |
指定在什么情况下请求应传递到 上游池 中的下一个服务器：
| 在建立与服务器的连接、向其传递请求或读取响应头时发生错误； |
| 在建立与服务器的连接、向其传递请求或读取响应头时发生超时； |
| 服务器返回空或无效响应； |
| 服务器返回状态码 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;
如果域名解析为多个地址，则所有地址将以轮询方式使用。此外，可以将地址指定为 服务器组。
参数值可以包含变量。在这种情况下，如果地址被指定为域名，则会在描述的服务器组中进行查找，如果未找到，则使用 resolver 进行确定。
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#
指定用于认证 gRPC SSL 服务器的 PEM 格式证书文件。文件名中可以使用变量。
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#
指定用于认证 gRPC SSL 服务器的 PEM 格式秘密密钥文件。
可以指定值 "engine:name:id" 作为文件，这将从指定的 OpenSSL 引擎名称中加载带有指定 ID 的秘密密钥。文件名中可以使用变量。
grpc_ssl_ciphers#
指定向 gRPC SSL 服务器请求的启用密码。密码以 OpenSSL 库理解的格式指定。
密码列表取决于已安装的 OpenSSL 版本。可以使用 openssl ciphers 命令查看完整列表。
警告
当使用 OpenSSL 时，grpc_ssl_ciphers 指令*不会*配置 TLS 1.3 的加密套件。
如需配置 TLS 1.3 的加密套件，请使用 grpc_ssl_conf_command 指令，
它是为支持高级 SSL 配置而添加的。
在 LibreSSL 中，可以使用
grpc_ssl_ciphers配置 TLS 1.3 加密套件。在 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 URL 的主机部分。
grpc_ssl_password_file#
指定一个包含 私钥 密码短语的文件，每个密码短语单独占一行。加载密钥时会依次尝试这些密码短语。
grpc_ssl_protocols#
| |
默认值 |
|
http, server, location |
在 1.2.0 版本发生变更: TLSv1.3 参数已添加到默认集。
启用指定的协议以请求 gRPC SSL 服务器。
grpc_ssl_server_name#
启用或禁用通过 grpc_ssl_name 指令设置的服务器名称在与 gRPC SSL 服务器建立连接时通过 TLS 扩展 服务器名称指示 (SNI, RFC 6066) 进行传递。
grpc_ssl_session_reuse#
确定在与 gRPC 服务器交互时 SSL 会话是否可以重用。如果日志中出现错误 "SSL3_GET_FINISHED:digest check failed"，请尝试禁用会话重用。
grpc_ssl_trusted_certificate#
指定一个包含受信任 CA 证书的 PEM 格式文件，用于 验证 gRPC SSL 服务器的证书。
grpc_ssl_verify#
启用或禁用对 gRPC SSL 服务器证书的验证。
grpc_ssl_verify_depth#
设置 gRPC SSL 服务器证书链中的验证深度。
目录