gRPC#
允许将请求传递给 gRPC 服务器。该模块需要 HTTP/2。
配置示例#
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 |
指定在以下情况下请求应传递到下一个 上游池 中的服务器：
|
与服务器建立连接、向其传递请求或读取响应头时发生错误； |
|
与服务器建立连接、向其传递请求或读取响应头时超时； |
|
服务器返回空或无效响应； |
|
服务器返回代码 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;
如果一个域名解析为多个地址，则所有地址将以轮询方式使用。此外，地址还可以指定为 服务器组。如果使用组，则不能与其一起指定端口；相反，应该为组内的每个服务器单独指定端口。
参数值可以包含变量。在这种情况下，如果地址指定为域名，则在描述的服务器组中搜索该名称，如果未找到，则使用 解析器 确定。
grpc_pass_header#
允许传递来自 gRPC 服务器到客户端的 已禁用 头字段。
grpc_read_timeout#
定义从 gRPC 服务器读取响应的超时时间。此超时时间仅在两次连续读取操作之间设置，而不是针对整个响应的传输。如果 gRPC 服务器在此时间内未传输任何数据，则连接将关闭。
grpc_send_timeout#
设置向 gRPC 服务器发送请求的超时时间。该超时时间仅在两次连续写操作之间设置，而不是针对整个请求的传输。如果 gRPC 服务器在此时间内未接收到任何数据，则连接将关闭。
grpc_set_header#
|
|
默认值 |
|
http, server, location |
允许重新定义或添加字段到传递给 gRPC 服务器的请求头 passed。值可以包含文本、变量及其组合。这些指令仅在当前级别没有定义 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_key#
指定用于认证 gRPC SSL 服务器的 PEM 格式的私钥文件。
可以使用 "engine:name:id" 而不是文件，加载来自 OpenSSL 引擎名称的指定 id 的私钥。文件名中可以使用变量。
grpc_ssl_ciphers#
指定对 gRPC SSL 服务器请求启用的密码套件。密码套件以 OpenSSL 库理解的格式指定。
完整列表可以通过 "openssl ciphers" 命令查看。
grpc_ssl_conf_command#
设置建立与 gRPC SSL 服务器连接时的任意 OpenSSL 配置 命令。
重要
该指令在使用 OpenSSL 1.0.2 或更高版本时支持。
可以在同一级别指定多个 grpc_ssl_conf_command 指令。这些指令仅在当前级别没有定义 grpc_ssl_conf_command 指令时，从上一级配置继承。
小心
注意，直接配置 OpenSSL 可能导致意外行为。
指定用于 验证 gRPC SSL 服务器证书的 PEM 格式的吊销证书（CRL）文件。
grpc_ssl_name#
允许覆写用于 验证 gRPC SSL 服务器证书的服务器名称，并在与 gRPC SSL 服务器建立连接时通过 SNI 传递 passed through SNI。
默认情况下，使用 grpc_pass URL 的主机部分。
grpc_ssl_password_file#
指定用于 私钥 的密码短语文件，其中每个密码短语在单独一行上指定。加载密钥时依次尝试密码短语。
grpc_ssl_protocols#
|
|
默认值 |
|
http, server, location |
在 1.2.0 版本发生变更: TLSv1.3 参数添加到默认设置中。
为对 gRPC HTTPS 服务器的请求启用指定的协议。
grpc_ssl_server_name#
启用或禁用通过 grpc_ssl_name 指令设定的服务器名称通过 Server Name Indication TLS 扩展 (SNI, RFC 6066) 在与 gRPC SSL 服务器建立连接时传递。
grpc_ssl_session_reuse#
确定是否在与 gRPC 服务器交互时可以重用 SSL 会话。如果在日志中出现 "SSL3_GET_FINISHED:digest check failed" 错误，请尝试禁用 session reuse。
grpc_ssl_trusted_certificate#
指定用于 验证 gRPC SSL 服务器证书的 PEM 格式的受信任 CA 证书文件。
grpc_ssl_verify#
启用或禁用对 gRPC SSL 服务器证书的验证。
grpc_ssl_verify_depth#
设置 gRPC SSL 服务器证书链的验证深度。