Server Plugin

轉送標頭

所需依賴項：io.ktor:ktor-server-forwarded-header

程式碼範例： forwarded-header

原生伺服器

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

支援：✅

當 Ktor 伺服器部署在反向代理後方時，ForwardedHeaders 和 XForwardedHeaders 外掛允許您處理反向代理標頭，以取得有關原始請求的資訊。這對日誌記錄目的可能很有用。

• 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
}

下表顯示了 call.request.origin 所暴露的不同屬性值，具體取決於是否安裝了 ForwardedHeaders/XForwardedHeaders。

屬性	未安裝 ForwardedHeaders	已安裝 ForwarderHeaders
origin.localHost	網頁伺服器	網頁伺服器
origin.localPort	8080	8080
origin.serverHost	網頁伺服器	代理
origin.serverPort	8080	80
origin.remoteHost	代理	客戶端
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-Forwarded-For: 10.0.0.123, proxy-1, proxy-2, proxy-3

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

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

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