> For the complete documentation index, see [llms.txt](https://lixiangyun.gitbook.io/envoy/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://lixiangyun.gitbook.io/envoy/configurationreference/httpfilters/router.md).

# 路由

## 路由

路由过滤器实现了HTTP转发。几乎所有Envoy部署的HTTP代理场景都有使用。过滤器的主要工作是遵循路由表中配置的指令。除了转发和重定向之外，过滤器还处理重试，统计等。

* [v1 API 参考](/envoy/v1apireference/httpfilters/router.md)
* [v2 API 参考](/envoy/v2apireference/filters/httpfilters/router.md)

### HTTP头部

路由器在出口/请求以及入口/响应路径上消费和设置各种HTTP头部。它们在本章节中有说明。

* [x-envoy-expected-rq-timeout-ms](/envoy/configurationreference/httpfilters/router.md#x-envoy-expected-rq-timeout-ms)
* [x-envoy-max-retries](/envoy/configurationreference/httpfilters/router.md#x-envoy-max-retries)
* [x-envoy-retry-on](/envoy/configurationreference/httpfilters/router.md#x-envoy-retry-on)
* [x-envoy-retry-grpc-on](/envoy/configurationreference/httpfilters/router.md#x-envoy-retry-grpc-on)
* [x-envoy-upstream-alt-stat-name](/envoy/configurationreference/httpfilters/router.md#x-envoy-upstream-alt-stat-name)
* [x-envoy-upstream-canary](/envoy/configurationreference/httpfilters/router.md#x-envoy-upstream-canary)
* [x-envoy-upstream-rq-timeout-alt-response](/envoy/configurationreference/httpfilters/router.md#x-envoy-upstream-rq-timeout-alt-response)
* [x-envoy-upstream-rq-timeout-ms](/envoy/configurationreference/httpfilters/router.md#x-envoy-upstream-rq-timeout-ms)
* [x-envoy-upstream-rq-per-try-timeout-ms](/envoy/configurationreference/httpfilters/router.md#x-envoy-upstream-rq-timeout-ms)
* [x-envoy-upstream-service-time](/envoy/configurationreference/httpfilters/router.md#x-envoy-upstream-service-time)
* [x-envoy-original-path](/envoy/configurationreference/httpfilters/router.md#x-envoy-original-path)
* [x-envoy-immediate-health-check-fail](/envoy/configurationreference/httpfilters/router.md#x-envoy-immediate-health-check-fail)
* [x-envoy-overloaded](/envoy/configurationreference/httpfilters/router.md#x-envoy-overloaded)
* [x-envoy-decorator-operation](/envoy/configurationreference/httpfilters/router.md#x-envoy-decorator-operation)

#### x-envoy-expected-rq-timeout-ms

这是路由器期望请求完成的时间（以毫秒为单位）。Envoy设置这个HTTP头部，以便上游主机在接收请求后可以根据请求超时做出决定，例如提前退出。这是在内部请求上设置的，可以从[x-envoy-upstream-rq-timeout-ms](/envoy/configurationreference/httpfilters/router.md#x-envoy-upstream-rq-timeout-ms)头部或[路由超时](/envoy/v1apireference/httprouteconfiguration/route.md)中按顺序获取。

#### x-envoy-max-retries

如果有[重试策略](/envoy/v1apireference/httprouteconfiguration/route.md)，Envoy将默认重试一次，除非明确指定。可以在[路由重试配置](/envoy/v1apireference/httprouteconfiguration/route.md)或通过使用此头部显式设置重试次数。如果未配置重试策略，并且未指定[x-envoy-retry-on](/envoy/configurationreference/httpfilters/router.md#x-envoy-retry-on)或[x-envoy-retry-grpc-on](/envoy/configurationreference/httpfilters/router.md#x-envoy-retry-grpc-on)头，则Envoy将不会重试失败的请求。

关于Envoy如何重试的一些说明：

* 路由超时（通过[x-envoy-upstream-rq-timeout-ms](/envoy/configurationreference/httpfilters/router.md#x-envoy-upstream-rq-timeout-ms)或[路由配置设置](/envoy/v1apireference/httprouteconfiguration/route.md)）包括所有重试。 因此，如果请求超时设置为3秒，并且第一次请求尝试需要2.7秒，则重试（包括退避）只有0.3s时间完成。这是设计来避免因重试/超时导致指数增长。
* Envoy使用完全抖动的指数退避算法进行重试，其基准时间为25ms。第一次重试将在0-24ms之间随机延迟，第二次在0-74ms之间，第三次在0-174ms之间，依此类推。
* 如果最大重试次数在头部和路由配置都有设置，则在会采用最大值用于请求的最大重试次数。

#### x-envoy-retry-on

在出口请求上设置此报头将导致Envoy尝试重试失败的请求（重试次数默认为1，可以通过[x-envoy-max-retries](/envoy/configurationreference/httpfilters/router.md#x-envoy-max-retries)头部或路由配置重试策略进行控制）。设置[x-envoy-retry-on](/envoy/configurationreference/httpfilters/router.md#x-envoy-retry-on)头的值表示重试策略。可以使用','分隔列表来指定一个或多个策略。支持的策略有：

* **5xx**\
   如果上游服务器响应任何5xx的响应代码，或者根本没有响应（断开/重置/读取超时），Envoy将尝试重试请求。（包括连接失败和拒绝流）

  注：当请求超过[x-envoy-upstream-rq-timeout-ms](/envoy/configurationreference/httpfilters/router.md#x-envoy-upstream-rq-timeout-ms)（导致504误错代码）时，Envoy将不会重试。如果您想在个别请求上尝试超长时间的重试，请使用[x-envoy-upstream-rq-per-try-timeout-ms](/envoy/configurationreference/httpfilters/router.md#x-envoy-upstream-rq-per-try-timeout-ms)。`x-envoy-upstream-rq-timeout-ms`是请求的外部时间限制，包括发生的任何重试。
* **connect-failure**\
   如果由于上游服务器连接失败而导致请求失败（连接超时等），Envoy将尝试重试。（包含在5xx中）

  注：连接失败/超时是TCP级别，而不是请求级别。这不包括通过[x-envoy-upstream-rq-timeout-ms](/envoy/configurationreference/httpfilters/router.md#x-envoy-upstream-rq-timeout-ms)或通过[路由配置](/envoy/v1apireference/httprouteconfiguration/route.md)指定的上游请求超时。
* **retriable-4xx**\
   如果上游服务器响应可回复的4xx响应代码，Envoy将尝试重试。目前，这个类别中唯一的响应代码是409。

  注：小心打开此重试类型。在某些情况下，409可能表明需要更新乐观锁版本。因此，调用者不应该重试并且需要读取，然后再尝试写入。如果在这种类型的情况下发生重试，则将总是以另一个409失败。
* **refused-stream**\
   如果上游服务器使用`REFUSED_STREAM`错误代码重置流，Envoy将尝试重试。此重置类型表示请求可以安全地重试。（包含在5xx中） 重试次数可以通过[x-envoy-max-retries](/envoy/configurationreference/httpfilters/router.md#x-envoy-max-retries)头或通过[路由配置](/envoy/v1apireference/httprouteconfiguration/route.md)来控制。

请注意，重试策略也可以应用在[路由级别](/envoy/v1apireference/httprouteconfiguration/route.md)。

默认情况下，Envoy不会执行重试，除非您已经按照上面的方式配置它们。

#### x-envoy-retry-grpc-on

在出口请求上设置此报头会导致Envoy尝试重试失败的请求（重试次数默认为1，可以通过[x-envoy-max-retries](/envoy/configurationreference/httpfilters/router.md#x-envoy-max-retries)头或路由配置[重试策略](/envoy/v1apireference/httprouteconfiguration/route.md)进行控制）。gRPC重试当前仅支持响应头中的gRPC状态码。追踪者中的gRPC状态码不会触发重试逻辑。可以使用','分隔列表来指定一个或多个策略。支持的策略是：

* **cancelled**\
   如果响应头中的gRPC状态码被“cancelled”（1），Envoy将尝试重试;
* **deadline-exceeded**\
   如果响应头中的gRPC状态码是“deadline-exceeded”（4），Envoy将尝试重试;
* **resource-exhausted**\
   如果响应头中的gRPC状态码是“resource-exhausted”（8），Envoy将尝试重试;

同样`x-envoy-retry-grpc-on`头的重试次数，可以通过[x-envoy-max-retries](/envoy/configurationreference/httpfilters/router.md#x-envoy-max-retries)头来控制

请注意，重试策略也可以应用在[路由级别](/envoy/v1apireference/httprouteconfiguration/route.md)。

默认情况下，Envoy不会执行重试，除非您已经按照上面的方式配置它们。

#### x-envoy-upstream-alt-stat-name

在出口请求上设置这个头部会导致Envoy将上游响应代码/时间统计信息发送到双重统计树。这对于Envoy不知道的应用程序级别的情况下，可能很有用。详见[统计输出文档](/envoy/configurationreference/clustermanager/statistics.md)。

#### x-envoy-upstream-canary

如果上游主机设置了这个头部，路由器将使用它来生成金丝雀（灰度升级）相关的统计信息。详见[统计输出文档](/envoy/configurationreference/clustermanager/statistics.md)。

#### x-envoy-upstream-rq-timeout-alt-response

在出口请求上设置此头部会导致Envoy在请求超时的情况下设置一个204响应代码（而不是504）。头部实际的值被忽略; 只考虑它的存在。另请参见[x-envoy-upstream-rq-timeout-ms](/envoy/configurationreference/httpfilters/router.md#x-envoy-upstream-rq-timeout-ms)。

#### x-envoy-upstream-rq-timeout-ms

在出口请求上设置此标头将覆盖Envoy的路由配置。超时时间必须以毫秒为单位指定。另请参阅[x-envoy-upstream-rq-per-try-timeout-ms](/envoy/configurationreference/httpfilters/router.md#x-envoy-upstream-rq-per-try-timeout-ms)。

#### x-envoy-upstream-rq-per-try-timeout-ms

在出口请求上设置此头部将导致Envoy在路由请求上设置每次尝试超时。此超时必须<=全局路由超时（请参阅[x-envoy-upstream-rq-timeout-ms](/envoy/configurationreference/httpfilters/router.md#x-envoy-upstream-rq-timeout-ms)），否则将被忽略。这允许调用者每次都尝试设置超时重试，同时保持合理的总超时。

#### x-envoy-upstream-service-time

包含上游主机处理请求所花费的时间（以毫秒为单位）。如果客户想要确定网络延迟与服务请求的时间做对比，这是有用的。这个头是在响应中设置的。

#### x-envoy-original-path

如果路由使用`prefix_rewrite`，Envoy会将原始路径头部放在这个头部。这对日志记录和调试很有用。

#### x-envoy-immediate-health-check-fail

如果上游主机返回此头部（设置为任何值），则Envoy将立即判定上游主机的主动健康检查失败（如果已将群集配置为[主动健康检查](/envoy/configurationreference/clustermanager/healthchecking.md)）。这是通过标准数据平面快速上报上游主机所发生故障，而无需等待下一个运行健康检查超时。上游主机也可以通过标准的主动健康检查再次变得健康。请参阅[健康检查概述](/envoy/introduction/architectureoverview/healthchecking.md)了解更多信息。

#### x-envoy-overloaded

如果这个头由上游主机设置了，Envoy不会重试。目前不关心头部的值，只关心是否存在。此外，如果处于[维护模式](https://lixiangyun.gitbook.io/envoy/configurationreference/httpfilters/pages/-LlnovkhjYvCXb2MTnXu#运行时设置)或上游[熔断](/envoy/introduction/architectureoverview/circuitbreaking.md)而导致请求丢失，Envoy将在下游响应中设置此头部。

#### x-envoy-decorator-operation

如果此头部出现在入口请求上，则该头部的值将覆盖由跟踪机制生成的服务器span上的任何本地定义的操作名称（span name）。同样，如果在出口响应中出现此头部，其值将覆盖客户端范围上的任何本地定义的操作名称（span name）。

### 统计

路由器在集群命名空间中输出许多统计信息（取决于所选路由中指定的集群）。浏览[此处](/envoy/configurationreference/clustermanager/statistics.md)获取更多信息。

路由器过滤器输出的统计信息命名空间为`http.<stat_prefix>.`。其中`stat_prefix`来自拥有的[HTTP连接管理器](/envoy/v1apireference/networkfilters/httpconnectionmanager.md)。

| Name         | Type    | Description           |
| ------------ | ------- | --------------------- |
| no\_route    | Counter | 因没有路由而导致404错误的总请求数    |
| no\_cluster  | Counter | 因目标集群不存在而导致404错误的总请求数 |
| rq\_redirect | Counter | 导致重定向响应的总请求数          |
| rq\_total    | Counter | 总路由请求数                |

输出的虚拟集群统计信息名称空间为`vhost.<virtual host name>.vcluster.<virtual cluster name>.`，并包含以下统计信息：

| Name                 | Type      | Description             |
| -------------------- | --------- | ----------------------- |
| upstream*rq*\\<\*xx> | Counter   | HTTP响应代码汇总（例如，2xx，3xx等） |
| upstream*rq*\\<\*>   | Counter   | 特定的HTTP响应码（例如：201、302等） |
| upstream\_rq\_time   | Histogram | 请求时间，单位毫秒               |

### 运行时设置

路由器过滤器支持以下运行时设置：

* **upstream.base\_retry\_backoff\_ms**\
  &#x20;指数重试退避时间粒度。默认为25ms。浏览[此处](/envoy/introduction/architectureoverview/httprouting.md)获取更多信息。
* **upstream.maintenance\_mode.\\**\
  &#x20;将导致立即返回503响应请求的百分比。这会覆盖针对`<cluster name>`集群的任何路由请求行为。这可以用于卸载，故障注入等。默认为禁用。
* **upstream.use\_retry**\
  &#x20;有资格使用重试的请求百分比。在任何其他重试配置之前检查此配置，如果需要，可用于禁用所有Envoy的重试。

## 返回

* [上一级](/envoy/configurationreference/httpfilters.md)
* [首页目录](/envoy/master.md)