Server Plugin

轉發標頭 (Forwarded headers

[//]: # (title: 轉發標頭 (Forwarded headers))

必要的相依性：io.ktor:ktor-server-forwarded-header

程式碼範例： forwarded-header

原生伺服器

Ktor 支援 Kotlin/Native，並允許您在沒有額外執行階段或虛擬機的情況下執行伺服器。

支援：✅

ForwardedHeaders 與 XForwardedHeaders 外掛程式可讓您處理反向代理標頭，以取得 Ktor 伺服器位於反向代理之後時原始請求 (request) 的相關資訊。這對於記錄目的可能非常有用。

• ForwardedHeaders 處理 Forwarded 標頭 (RFC 7239)
• XForwardedHeaders 處理以下 X-Forwarded- 標頭：
  • X-Forwarded-Host/X-Forwarded-Server
  • X-Forwarded-For
  • X-Forwarded-By
  • X-Forwarded-Proto/X-Forwarded-Protocol
  • X-Forwarded-SSL/Front-End-Https

為了防止 Forwarded 標頭遭到操作，請僅在您的應用程式僅接受反向代理連線時安裝這些外掛程式。

新增相依性

若要使用 ForwardedHeaders/XForwardedHeaders 外掛程式，您需要在建置指令碼中包含 ktor-server-forwarded-header 構件 (artifact)：

Gradle (Kotlin)Gradle (Groovy)Maven

安裝外掛程式

ForwardedHeaderXForwardedHeader

若要將 ForwardedHeaders 外掛程式安裝到應用程式，請將其傳遞給指定

模組

模組允許您透過分組路由來建構應用程式。

中的 install 函式。 以下程式碼片段顯示如何安裝 ForwardedHeaders ...

• ... 在 embeddedServer 函式呼叫內。
• ... 在明確定義的 module 內，它是 Application 類別的擴充函式。

embeddedServermodule

若要將 XForwardedHeaders 外掛程式安裝到應用程式，請將其傳遞給指定

模組

模組允許您透過分組路由來建構應用程式。

中的 install 函式。 以下程式碼片段顯示如何安裝 XForwardedHeaders ...

• ... 在 embeddedServer 函式呼叫內。
• ... 在明確定義的 module 內，它是 Application 類別的擴充函式。

embeddedServermodule

安裝 ForwardedHeaders/XForwardedHeaders 之後，您可以使用 call.request.origin 屬性取得原始請求的資訊。

取得請求資訊

代理請求資訊

若要取得代理請求的相關資訊，請在路由處理常式中使用 call.request.local 屬性。 以下程式碼片段顯示如何取得代理地址以及發出請求的主機資訊：

get("/hello") {
    val remoteHost = call.request.local.remoteHost
    val serverHost = call.request.local.serverHost
}

原始請求資訊

若要讀取原始請求的資訊，請使用 call.request.origin 屬性：

get("/hello") {
    val originRemoteHost = call.request.origin.remoteHost
    val originServerHost = call.request.origin.serverHost
}

下表顯示了根據是否安裝了 ForwardedHeaders/XForwardedHeaders，由 call.request.origin 公開的不同屬性值。

屬性	不含 ForwardedHeaders	包含 ForwardedHeaders
origin.localHost	web-server	web-server
origin.localPort	8080	8080
origin.serverHost	web-server	proxy
origin.serverPort	8080	80
origin.remoteHost	proxy	client
origin.remotePort	32864	32864

您可以在此處找到完整的範例：forwarded-header。

設定 ForwardedHeaders

如果請求經過多個代理，您可能需要設定 ForwardedHeaders/XForwardedHeaders。 在這種情況下，X-Forwarded-For 會包含每個後續代理的所有 IP 地址，例如：

X-Forwarded-For: <client>, <proxy1>, <proxy2>

預設情況下，XForwardedHeader 會將 X-Forwarded-For 中的第一個項目指派給 call.request.origin.remoteHost 屬性。 您也可以提供選取 IP 地址的自訂邏輯。 XForwardedHeadersConfig 為此公開了以下 API：

• useFirstProxy 與 useLastProxy 分別允許您從 IP 地址清單中取得第一個或最後一個值。
• skipLastProxies 從右側開始跳過指定數量的項目，並取得下一個項目。 例如，如果 proxiesCount 參數等於 3，對於下方的標頭，origin.remoteHost 將回傳 10.0.0.123：

  X-Forward-For: 10.0.0.123, proxy-1, proxy-2, proxy-3

• skipKnownProxies 從清單中移除指定的項目並取得最後一個項目。 例如，如果您將 listOf("proxy-1", "proxy-3") 傳遞給此函式，對於下方的標頭，origin.remoteHost 將回傳 proxy-2：

  X-Forward-For: 10.0.0.123, proxy-1, proxy-2, proxy-3

• extractEdgeProxy 允許您提供從 X-Forward-* 標頭中擷取值的自訂邏輯。