轉發標頭
必要相依性:io.ktor:ktor-server-forwarded-header
程式碼範例: forwarded-header
原生伺服器Ktor 支援 Kotlin/Native,可讓您在無需額外執行階段或虛擬機的情況下執行伺服器。 支援:✅
當 Ktor 伺服器部署在反向代理之後時,ForwardedHeaders 與 XForwardedHeaders 外掛程式可讓您處理反向代理標頭,以取得原始 request 的資訊。這對於記錄目的非常有用。
ForwardedHeaders處理Forwarded標頭(RFC 7239)XForwardedHeaders處理以下X-Forwarded-標頭:X-Forwarded-Host/X-Forwarded-ServerX-Forwarded-ForX-Forwarded-ByX-Forwarded-Proto/X-Forwarded-ProtocolX-Forwarded-SSL/Front-End-Https
為防止 Forwarded 標頭遭到竄改,請僅在您的應用程式只接受反向代理連線時才安裝這些外掛程式。
新增相依性
若要使用 ForwardedHeaders/XForwardedHeaders 外掛程式,您需要在建置指令碼中包含 ktor-server-forwarded-header 構件:
implementation(ktorLibs.server.forwardedHeader)implementation ktorLibs.server.forwardedHeader<dependency>
<groupId>io.ktor</groupId>
<artifactId>ktor-server-forwarded-header-jvm</artifactId>
<version>${ktor_version}</version>
</dependency>安裝外掛程式
若要將 ForwardedHeaders 外掛程式安裝到您的應用程式中,請將其傳遞給指定 模組模組可讓您透過對路由進行分組來建構應用程式。 中的 install 函式。 以下範例展示如何安裝 ForwardedHeaders:
- 在
embeddedServer()函式呼叫中。 - 在
Application類別上明確定義的module()擴充函式中。
import io.ktor.server.engine.*
import io.ktor.server.netty.*
import io.ktor.server.application.*
import io.ktor.server.plugins.forwardedheaders.*
fun main() {
embeddedServer(Netty, port = 8080) {
install(ForwardedHeaders)
// ...
}.start(wait = true)
}import io.ktor.server.application.*
import io.ktor.server.plugins.forwardedheaders.*
// ...
fun Application.module() {
install(ForwardedHeaders)
// ...
} 若要將 XForwardedHeaders 外掛程式安裝到您的應用程式中,請將其傳遞給指定 模組模組可讓您透過對路由進行分組來建構應用程式。 中的 install 函式。 以下範例展示如何安裝 XForwardedHeaders:
- 在
embeddedServer()函式呼叫中。 - 在
Application類別上明確定義的module()擴充函式中。
import io.ktor.server.engine.*
import io.ktor.server.netty.*
import io.ktor.server.application.*
import io.ktor.server.plugins.forwardedheaders.*
fun main() {
embeddedServer(Netty, port = 8080) {
install(XForwardedHeaders)
// ...
}.start(wait = true)
}import io.ktor.server.application.*
import io.ktor.server.plugins.forwardedheaders.*
// ...
fun Application.module() {
install(XForwardedHeaders)
// ...
}安裝 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 | 已安裝 ForwarderHeaders |
|---|---|---|
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:HTTPX-Forwarded-For: 10.0.0.123, proxy-1, proxy-2, proxy-3skipKnownProxies會從清單中移除指定項目,並取得最後一個項目。 例如,如果您傳遞listOf("proxy-1", "proxy-3")給此函式,對於以下標頭,origin.remoteHost將傳回proxy-2:HTTPX-Forwarded-For: 10.0.0.123, proxy-1, proxy-2, proxy-3extractEdgeProxy允許您提供自訂邏輯,以從X-Forward-*標頭中擷取值。
