路由 · ENVOY 智能代理中文參考文檔

## 路由路由過濾器實現了HTTP轉發。幾乎所有Envoy部署的HTTP代理場景都有使用。過濾器的主要工作是遵循路由表中配置的指令。除了轉發和重定向之外，過濾器還處理重試，統計等。 - [v1 API 參考](../../v1APIreference/HTTPfilters/Router.md) - [v2 API 參考](../../v2APIreference/Filters/HTTPfilters/Router.md) ### HTTP頭部路由器在出口/請求以及入口/響應路徑上消費和設置各種HTTP頭部。它們在本章節中有說明。 - [x-envoy-expected-rq-timeout-ms](#x-envoy-expected-rq-timeout-ms) - [x-envoy-max-retries](#x-envoy-max-retries) - [x-envoy-retry-on](#x-envoy-retry-on) - [x-envoy-retry-grpc-on](#x-envoy-retry-grpc-on) - [x-envoy-upstream-alt-stat-name](#x-envoy-upstream-alt-stat-name) - [x-envoy-upstream-canary](#x-envoy-upstream-canary) - [x-envoy-upstream-rq-timeout-alt-response](#x-envoy-upstream-rq-timeout-alt-response) - [x-envoy-upstream-rq-timeout-ms](#x-envoy-upstream-rq-timeout-ms) - [x-envoy-upstream-rq-per-try-timeout-ms](#x-envoy-upstream-rq-timeout-ms) - [x-envoy-upstream-service-time](#x-envoy-upstream-service-time) - [x-envoy-original-path](#x-envoy-original-path) - [x-envoy-immediate-health-check-fail](#x-envoy-immediate-health-check-fail) - [x-envoy-overloaded](#x-envoy-overloaded) - [x-envoy-decorator-operation](#x-envoy-decorator-operation) #### x-envoy-expected-rq-timeout-ms 這是路由器期望請求完成的時間（以毫秒為單位）。Envoy設置這個HTTP頭部，以便上游主機在接收請求后可以根據請求超時做出決定，例如提前退出。這是在內部請求上設置的，可以從[x-envoy-upstream-rq-timeout-ms](#x-envoy-upstream-rq-timeout-ms)頭部或[路由超時](../../v1APIreference/HTTPRouteconfiguration/Route.md)中按順序獲取。 #### x-envoy-max-retries 如果有[重試策略](../../v1APIreference/HTTPRouteconfiguration/Route.md)，Envoy將默認重試一次，除非明確指定。可以在[路由重試配置](../../v1APIreference/HTTPRouteconfiguration/Route.md)或通過使用此頭部顯式設置重試次數。如果未配置重試策略，并且未指定[x-envoy-retry-on](#x-envoy-retry-on)或[x-envoy-retry-grpc-on](#x-envoy-retry-grpc-on)頭，則Envoy將不會重試失敗的請求。關于Envoy如何重試的一些說明： - 路由超時（通過[x-envoy-upstream-rq-timeout-ms](#x-envoy-upstream-rq-timeout-ms)或[路由配置設置](../../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](#x-envoy-max-retries)頭部或路由配置重試策略進行控制）。設置[x-envoy-retry-on](#x-envoy-retry-on)頭的值表示重試策略。可以使用','分隔列表來指定一個或多個策略。支持的策略有： - **5xx** 如果上游服務器響應任何5xx的響應代碼，或者根本沒有響應（斷開/重置/讀取超時），Envoy將嘗試重試請求。（包括連接失敗和拒絕流）注：當請求超過[x-envoy-upstream-rq-timeout-ms](#x-envoy-upstream-rq-timeout-ms)（導致504誤錯代碼）時，Envoy將不會重試。如果您想在個別請求上嘗試超長時間的重試，請使用[x-envoy-upstream-rq-per-try-timeout-ms](#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](#x-envoy-upstream-rq-timeout-ms)或通過[路由配置](../../v1APIreference/HTTPRouteconfiguration/Route.md)指定的上游請求超時。 - **retriable-4xx** 如果上游服務器響應可回復的4xx響應代碼，Envoy將嘗試重試。目前，這個類別中唯一的響應代碼是409。注：小心打開此重試類型。在某些情況下，409可能表明需要更新樂觀鎖版本。因此，調用者不應該重試并且需要讀取，然后再嘗試寫入。如果在這種類型的情況下發生重試，則將總是以另一個409失敗。 - **refused-stream** 如果上游服務器使用`REFUSED_STREAM`錯誤代碼重置流，Envoy將嘗試重試。此重置類型表示請求可以安全地重試。（包含在5xx中）重試次數可以通過[x-envoy-max-retries](#x-envoy-max-retries)頭或通過[路由配置](../../v1APIreference/HTTPRouteconfiguration/Route.md)來控制。請注意，重試策略也可以應用在[路由級別](../../v1APIreference/HTTPRouteconfiguration/Route.md)。默認情況下，Envoy不會執行重試，除非您已經按照上面的方式配置它們。 #### x-envoy-retry-grpc-on 在出口請求上設置此報頭會導致Envoy嘗試重試失敗的請求（重試次數默認為1，可以通過[x-envoy-max-retries](#x-envoy-max-retries)頭或路由配置[重試策略](../../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](#x-envoy-max-retries)頭來控制請注意，重試策略也可以應用在[路由級別](../../v1APIreference/HTTPRouteconfiguration/Route.md)。默認情況下，Envoy不會執行重試，除非您已經按照上面的方式配置它們。 #### x-envoy-upstream-alt-stat-name 在出口請求上設置這個頭部會導致Envoy將上游響應代碼/時間統計信息發送到雙重統計樹。這對于Envoy不知道的應用程序級別的情況下，可能很有用。詳見[統計輸出文檔](../Clustermanager/Statistics.md)。 #### x-envoy-upstream-canary 如果上游主機設置了這個頭部，路由器將使用它來生成金絲雀（灰度升級）相關的統計信息。詳見[統計輸出文檔](../Clustermanager/Statistics.md)。 #### x-envoy-upstream-rq-timeout-alt-response 在出口請求上設置此頭部會導致Envoy在請求超時的情況下設置一個204響應代碼（而不是504）。頭部實際的值被忽略; 只考慮它的存在。另請參見[x-envoy-upstream-rq-timeout-ms](#x-envoy-upstream-rq-timeout-ms)。 #### x-envoy-upstream-rq-timeout-ms 在出口請求上設置此標頭將覆蓋Envoy的路由配置。超時時間必須以毫秒為單位指定。另請參閱[x-envoy-upstream-rq-per-try-timeout-ms](#x-envoy-upstream-rq-per-try-timeout-ms)。 #### x-envoy-upstream-rq-per-try-timeout-ms 在出口請求上設置此頭部將導致Envoy在路由請求上設置每次嘗試超時。此超時必須<=全局路由超時（請參閱[x-envoy-upstream-rq-timeout-ms](#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將立即判定上游主機的主動健康檢查失敗（如果已將群集配置為[主動健康檢查](../../Configurationreference/Clustermanager/Healthchecking.md)）。這是通過標準數據平面快速上報上游主機所發生故障，而無需等待下一個運行健康檢查超時。上游主機也可以通過標準的主動健康檢查再次變得健康。請參閱[健康檢查概述](../../Introduction/Architectureoverview/Healthchecking.md)了解更多信息。 #### x-envoy-overloaded 如果這個頭由上游主機設置了，Envoy不會重試。目前不關心頭部的值，只關心是否存在。此外，如果處于[維護模式](#運行時設置)或上游[熔斷](../../Introduction/Architectureoverview/Circuitbreaking.md)而導致請求丟失，Envoy將在下游響應中設置此頭部。 #### x-envoy-decorator-operation 如果此頭部出現在入口請求上，則該頭部的值將覆蓋由跟蹤機制生成的服務器span上的任何本地定義的操作名稱（span name）。同樣，如果在出口響應中出現此頭部，其值將覆蓋客戶端范圍上的任何本地定義的操作名稱（span name）。 ### 統計路由器在集群命名空間中輸出許多統計信息（取決于所選路由中指定的集群）。瀏覽[此處](../../Configurationreference/Clustermanager/Statistics.md)獲取更多信息。路由器過濾器輸出的統計信息命名空間為`http.<stat_prefix>.`。其中`stat_prefix`來自擁有的[HTTP連接管理器](../../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** 指數重試退避時間粒度。默認為25ms。瀏覽[此處](../../Introduction/Architectureoverview/HTTProuting.md)獲取更多信息。 - **upstream.maintenance_mode.\<cluster name>** 將導致立即返回503響應請求的百分比。這會覆蓋針對`<cluster name>`集群的任何路由請求行為。這可以用于卸載，故障注入等。默認為禁用。 - **upstream.use_retry** 有資格使用重試的請求百分比。在任何其他重試配置之前檢查此配置，如果需要，可用于禁用所有Envoy的重試。 ## 返回 - [上一級](../HTTPfilters.md) - [首頁目錄](../../README.md)