# gRPC 允许将请求传递到 gRPC 服务器。 #### NOTE 此模块需要 [HTTP2](https://cn.angie.software//angie/docs/configuration/modules/http/http_v2.md#http-v2) 模块。 ## 配置示例 ```nginx server { listen 9000; http2 on; location / { grpc_pass 127.0.0.1:9000; } } ``` ## 指令 ### grpc_bind | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `grpc_bind` address [`transparent`] | `off`; | |--------------------------------------------------------------------------------------|------------------------------------------------| | 默认值 | — | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | 使到 gRPC 服务器的出站连接从指定的本地 IP 地址（可选端口)发起。参数值可以包含变量。特殊值 `off` 取消从上一配置级别继承的 grpc_bind 指令的效果,允许系统自动分配本地 IP 地址和端口。 `transparent` 参数允许到 gRPC 服务器的出站连接从非本地 IP 地址发起,例如从客户端的真实 IP 地址: ```nginx grpc_bind $remote_addr transparent; ``` 为使此参数生效,通常需要以 [超级用户](https://cn.angie.software//angie/docs/configuration/modules/core.md#user) 权限运行 Angie 工作进程。在 Linux 上不需要这样做,因为如果指定了 `transparent` 参数,工作进程会从主进程继承 CAP_NET_RAW 能力。 #### NOTE 需要配置内核路由表以拦截来自 gRPC 服务器的网络流量。 ### grpc_buffer_size | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `grpc_buffer_size` size; | |--------------------------------------------------------------------------------------|----------------------------| | 默认值 | `grpc_buffer_size 4k|8k;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | 设置用于读取从 gRPC 服务器接收的响应的第一部分的缓冲区大小。响应一旦接收到就会同步传递给客户端。 ### grpc_connect_timeout | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `grpc_connect_timeout` time; | |--------------------------------------------------------------------------------------|--------------------------------| | 默认值 | `grpc_connect_timeout 60s;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | 定义与 gRPC 服务器建立连接的超时时间。需要注意的是,此超时时间通常不能超过 75 秒。 ### grpc_connection_drop | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `grpc_connection_drop` time | `on` | `off`; | |--------------------------------------------------------------------------------------|-----------------------------------------------| | 默认值 | `grpc_connection_drop off;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | 启用在代理服务器从组中移除或被 [重新解析](https://cn.angie.software//angie/docs/configuration/modules/http/http_upstream.md#reresolve) 进程或 [API](https://cn.angie.software//angie/docs/configuration/modules/http/http_api.md#api-config-methods) `DELETE` 命令标记为永久不可用后,终止到该服务器的所有连接。 当为客户端或代理服务器处理下一个读或写事件时,连接将被终止。 设置 time 启用连接终止 [超时](https://cn.angie.software//angie/docs/configuration/configfile.md#syntax); 设置为 `on` 时,连接立即断开。 ### grpc_hide_header | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `grpc_hide_header` field; | |--------------------------------------------------------------------------------------|-----------------------------| | 默认值 | — | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | 默认情况下,Angie 不会将 gRPC 服务器响应中的头字段 `Date`、`Server` 和 `X-Accel-...` 传递给客户端。`grpc_hide_header` 指令设置不会被传递的附加字段。相反,如果需要允许传递字段,可以使用 [grpc_pass_header](#grpc-pass-header) 指令。 ### grpc_ignore_headers | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `grpc_ignore_headers` field ...; | |--------------------------------------------------------------------------------------|------------------------------------| | 默认值 | — | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | 禁用对来自 gRPC 服务器的某些响应头字段的处理。可以忽略以下字段:`X-Accel-Redirect` 和 `X-Accel-Charset`。 如果未禁用,处理这些头字段将产生以下效果: * `X-Accel-Redirect` 执行到指定 URI 的 [内部重定向](https://cn.angie.software//angie/docs/configuration/modules/http/index.md#internal); * `X-Accel-Charset` 设置响应所需的 [字符集](https://cn.angie.software//angie/docs/configuration/modules/http/http_charset.md#id3)。 ### grpc_intercept_errors | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `grpc_intercept_errors` `on` | `off`; | |--------------------------------------------------------------------------------------|-----------------------------------------| | 默认值 | `grpc_intercept_errors off;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | 确定代码大于或等于 300 的 gRPC 服务器响应应该传递给客户端,还是被拦截并重定向到 Angie 使用 [error_page](https://cn.angie.software//angie/docs/configuration/modules/http/index.md#error-page) 指令进行处理。 ### grpc_next_upstream | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `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;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | 指定在哪些情况下应将请求传递给 [upstream](https://cn.angie.software//angie/docs/configuration/modules/http/http_upstream.md#http-upstream) 组中的下一个服务器: | `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` | 通常,使用 [非幂等](https://datatracker.ietf.org/doc/html/rfc7231#section-4.2.2) 方法
(`POST`、`LOCK`、`PATCH`)的请求如果已发送到上游服务器,
则不会传递给下一个服务器;启用此选项明确允许重试此类请求; | | `off` | 禁用将请求传递给下一个服务器。 | #### NOTE 应该记住,只有在尚未向客户端发送任何内容时,才可能将请求传递给下一个服务器。也就是说,如果在传输响应的过程中发生错误或超时,则无法修复此问题。 该指令还定义了什么被视为与服务器通信的 [不成功尝试](https://cn.angie.software//angie/docs/configuration/modules/http/http_upstream.md#max-fails)。 | `error`、`timeout`、`invalid_header` | 始终被视为不成功尝试,即使它们未在指令中指定 | |--------------------------------------------------------|--------------------------| | `http_500`、`http_502`、`http_503`、`http_504`、`http_429` | 仅在指令中指定时才被视为不成功尝试 | | `http_403`、`http_404` | 从不被视为不成功尝试 | 将请求传递给下一个服务器可以受 [尝试次数](#grpc-next-upstream-tries) 和 [时间](#grpc-next-upstream-timeout) 的限制。 ### grpc_next_upstream_timeout | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `grpc_next_upstream_timeout` time; | |--------------------------------------------------------------------------------------|--------------------------------------| | 默认值 | `grpc_next_upstream_timeout 0;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | 限制可以将请求传递给 [下一个服务器](#grpc-next-upstream) 的时间。 | `0` | 关闭此限制 | |-------|---------| ### grpc_next_upstream_tries | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `grpc_next_upstream_tries` number; | |--------------------------------------------------------------------------------------|--------------------------------------| | 默认值 | `grpc_next_upstream_tries 0;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | 限制将请求传递到 [下一个](#grpc-next-upstream) 服务器的可能尝试次数。 | `0` | 关闭此限制 | |-------|---------| ### grpc_pass | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `grpc_pass` address; | |--------------------------------------------------------------------------------------|--------------------------| | 默认值 | — | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | location, if in location | 设置 gRPC 服务器地址。地址可以指定为域名或 IP 地址,以及端口: ```nginx grpc_pass localhost:9000; ``` 或作为 UNIX 域套接字路径: ```nginx grpc_pass unix:/tmp/grpc.socket; ``` 或者,可以使用 `grpc://` 方案: ```nginx grpc_pass grpc://127.0.0.1:9000; ``` 要使用基于 SSL 的 gRPC,应使用 `grpcs://` 方案: ```nginx grpc_pass grpcs://127.0.0.1:443; ``` 如果域名解析为多个地址,则所有地址都将以轮询方式使用。此外,地址可以指定为 [服务器组](https://cn.angie.software//angie/docs/configuration/modules/http/http_upstream.md#http-upstream)。 参数值可以包含变量。在这种情况下,如果地址指定为域名,则在所描述的服务器组中搜索该名称,如果未找到,则使用 [解析器](https://cn.angie.software//angie/docs/configuration/modules/http/index.md#resolver) 确定。 #### NOTE 如果在带有前缀尾部斜杠的 `location` 中指定 `grpc_pass` (例如,:samp:location /name/), 并且 [auto_redirect](https://cn.angie.software//angie/docs/configuration/modules/http/index.md#auto-redirect) 指令设置为 `default`, 则不带尾部斜杠的请求将被重定向(`/name -> /name/`)。 ### grpc_pass_header | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `grpc_pass_header` field; | |--------------------------------------------------------------------------------------|-----------------------------| | 默认值 | — | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | 允许将 [原本禁用的](#grpc-hide-header) 头字段从 gRPC 服务器传递到客户端。 ### grpc_read_timeout | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `grpc_read_timeout` time; | |--------------------------------------------------------------------------------------|-----------------------------| | 默认值 | `grpc_read_timeout 60s;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | 定义从 gRPC 服务器读取响应的超时时间。超时仅在两次连续的读取操作之间设置,而不是针对整个响应的传输。如果 gRPC 服务器在此时间内未传输任何内容,则连接将关闭。 ### grpc_send_timeout | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `grpc_send_timeout` time; | |--------------------------------------------------------------------------------------|-----------------------------| | 默认值 | `grpc_send_timeout 60s;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | 设置向 gRPC 服务器传输请求的超时时间。超时仅在两次连续的写操作之间设置,而不是针对整个请求的传输。如果 gRPC 服务器在此时间内未接收到任何内容,则连接将关闭。 ### grpc_set_header | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `grpc_set_header` field value; | |--------------------------------------------------------------------------------------|---------------------------------------------------| | 默认值 | `grpc_set_header Content-Length $content_length;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | 允许重新定义或追加字段到 [传递](https://cn.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-pass-request-headers) 给 gRPC 服务器的请求头。值可以包含文本、变量及其组合。当且仅当当前级别未定义 grpc_set_header 指令时,这些指令才从上一级配置继承。 如果头字段的值为空字符串,则该字段将不会传递给 gRPC 服务器: ```nginx grpc_set_header Accept-Encoding ""; ``` ### grpc_socket_keepalive | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `grpc_socket_keepalive` `on` | `off`; | |--------------------------------------------------------------------------------------|-----------------------------------------| | 默认值 | `grpc_socket_keepalive off;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | 配置到 gRPC 服务器的出站连接的"TCP keepalive"行为。 | `off` | 默认情况下,套接字使用操作系统的设置。 | |---------|----------------------------| | `on` | 为套接字启用 SO_KEEPALIVE 套接字选项。 | ### grpc_ssl_certificate | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `grpc_ssl_certificate` file; | |--------------------------------------------------------------------------------------|--------------------------------| | 默认值 | — | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | 指定一个 PEM 格式的证书文件,用于向 gRPC SSL 服务器进行身份验证。文件名中可以使用变量。 ### grpc_ssl_certificate_cache | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `grpc_ssl_certificate_cache` `off`;

`grpc_ssl_certificate_cache` `max=`N [`inactive=`time] [`valid=`time]; | |--------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------| | 默认值 | `grpc_ssl_certificate_cache off;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | 定义一个缓存,用于存储使用变量指定的 [SSL 证书](#grpc-ssl-certificate) 和 [密钥](#grpc-ssl-certificate-key)。 该指令支持以下参数: - `max` — 设置缓存中的最大元素数。当缓存溢出时,将删除最近最少使用 (LRU) 的元素。 - `inactive` — 定义元素在未被访问后被删除的时间。默认为 10 秒。 - `valid` — 定义缓存元素被视为有效并可重用的时间。默认为 60 秒。在此期间之后, 证书将被重新加载或重新验证。 - `off` — 禁用缓存。 示例: ```nginx 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 | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `grpc_ssl_certificate_key` file; | |--------------------------------------------------------------------------------------|------------------------------------| | 默认值 | — | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | 指定一个 PEM 格式的密钥文件,用于向 gRPC SSL 服务器进行身份验证。 可以指定值 `engine:`name`:id` 来代替文件,这将从 OpenSSL 引擎 name 中加载具有指定 id 的密钥。 可以指定值 `store:scheme:id` 来代替文件,用于从 OpenSSL 提供程序注册的 URI [scheme\`(如 \`pkcs11](https://datatracker.ietf.org/doc/html/rfc7512))中加载具有指定 id 的密钥。 文件名中可以使用变量。 ### grpc_ssl_ciphers | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `grpc_ssl_ciphers` ciphers; | |--------------------------------------------------------------------------------------|-------------------------------| | 默认值 | `grpc_ssl_ciphers DEFAULT;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | 指定向 gRPC SSL 服务器发送请求时启用的密码套件。密码套件以 OpenSSL 库理解的格式指定。 密码套件列表取决于安装的 OpenSSL 版本。 可以使用 `openssl ciphers` 命令查看完整列表。 #### WARNING 使用 OpenSSL 时,:samp:grpc_ssl_ciphers 指令 *不* 配置 TLS 1.3 的密码套件。 要使用 OpenSSL 调整 TLS 1.3 密码套件,请使用 [grpc_ssl_conf_command](#grpc-ssl-conf-command) 指令, 该指令是为支持高级 SSL 配置而添加的。 - 在 LibreSSL 中,TLS 1.3 密码套件 *可以* 使用 `grpc_ssl_ciphers` 配置。 - 在 BoringSSL 中,TLS 1.3 密码套件完全无法配置。 ### grpc_ssl_conf_command | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `grpc_ssl_conf_command` name value; | |--------------------------------------------------------------------------------------|---------------------------------------| | 默认值 | — | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | 在与 gRPC SSL 服务器建立连接时设置任意 OpenSSL 配置 [命令](https://docs.openssl.org/master/man3/SSL_CONF_cmd/)。 #### NOTE 使用 OpenSSL 1.0.2 或更高版本时支持该指令。 要使用 OpenSSL 配置 TLS 1.3 密码套件,请使用 `ciphersuites` 命令。 可以在同一级别指定多个 grpc_ssl_conf_command 指令。当且仅当当前级别未定义 grpc_ssl_conf_command 指令时,这些指令才会从上一级配置继承。 #### WARNING 请注意,直接配置 OpenSSL 可能会导致意外行为。 ### grpc_ssl_crl | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `grpc_ssl_crl` file; | |--------------------------------------------------------------------------------------|------------------------| | 默认值 | — | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | 指定一个包含 PEM 格式吊销证书 (CRL) 的文件,用于 [验证](#grpc-ssl-verify) gRPC SSL 服务器的证书。 ### grpc_ssl_name | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `grpc_ssl_name` name; | |--------------------------------------------------------------------------------------|---------------------------------------| | 默认值 | `grpc_ssl_name `来自 grpc_pass 的主机名`;\` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | 允许覆盖用于 [验证](#grpc-ssl-verify) gRPC SSL 服务器证书的服务器名称,以及在与 gRPC SSL 服务器建立连接时 [通过 SNI 传递](#grpc-ssl-server-name) 的服务器名称。 默认情况下,使用 [grpc_pass](#grpc-pass) 中的主机名。 ### grpc_ssl_password_file | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `grpc_ssl_password_file` file; | |--------------------------------------------------------------------------------------|----------------------------------| | 默认值 | — | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | 指定一个包含 [密钥](#grpc-ssl-certificate-key) 密码短语的文件,每个密码短语单独占一行。加载密钥时会依次尝试这些密码短语。 ### grpc_ssl_protocols | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `grpc_ssl_protocols` [`SSLv2`] [`SSLv3`] [`TLSv1`] [`TLSv1.1`] [`TLSv1.2`] [`TLSv1.3`]; | |--------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------| | 默认值 | `grpc_ssl_protocols TLSv1.2 TLSv1.3;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | #### Versionchanged 在 1.2.0 版本发生变更: 默认集合中添加了 `TLSv1.3` 参数。 为向 gRPC SSL 服务器发送的请求启用指定的协议。 ### grpc_ssl_server_name | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `grpc_ssl_server_name` `on` | `off`; | |--------------------------------------------------------------------------------------|----------------------------------------| | 默认值 | `grpc_ssl_server_name off;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | 启用或禁用在与 gRPC SSL 服务器建立连接时,通过 [服务器名称指示](http://en.wikipedia.org/wiki/Server_Name_Indication) TLS 扩展 (SNI,\`RFC 6066 <[https://datatracker.ietf.org/doc/html/rfc6066.html](https://datatracker.ietf.org/doc/html/rfc6066.html)>\`_) 传递由 [grpc_ssl_name](#grpc-ssl-name) 指令设置的服务器名称。 ### grpc_ssl_session_reuse | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `grpc_ssl_session_reuse` `on` | `off`; | |--------------------------------------------------------------------------------------|------------------------------------------| | 默认值 | `grpc_ssl_session_reuse on;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | 确定在与 gRPC 服务器通信时是否可以重用 SSL 会话。如果日志中出现 "SSL3_GET_FINISHED:digest check failed" 错误,请尝试禁用会话重用。 ### grpc_ssl_trusted_certificate | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `grpc_ssl_trusted_certificate` file; | |--------------------------------------------------------------------------------------|----------------------------------------| | 默认值 | — | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | 指定一个包含 PEM 格式受信任 CA 证书的文件,用于 [验证](#grpc-ssl-verify) gRPC SSL 服务器的证书。 ### grpc_ssl_verify | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `grpc_ssl_verify` `on` | `off`; | |--------------------------------------------------------------------------------------|-----------------------------------| | 默认值 | `grpc_ssl_verify off;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | 启用或禁用对 gRPC SSL 服务器证书的验证。 ### grpc_ssl_verify_depth | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `grpc_ssl_verify_depth` number; | |--------------------------------------------------------------------------------------|-----------------------------------| | 默认值 | `grpc_ssl_verify_depth 1;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | 设置 gRPC SSL 服务器证书链的验证深度。