Skip to content
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 工件:

kotlin
implementation(ktorLibs.server.forwardedHeader)
上述代码段使用 Ktor 版本目录 (Version Catalog) 来指定 Ktor 依赖项。
groovy
implementation ktorLibs.server.forwardedHeader
上述代码段使用 Ktor 版本目录 (Version Catalog) 来指定 Ktor 依赖项。
xml
<dependency>
    <groupId>io.ktor</groupId>
    <artifactId>ktor-server-forwarded-header-jvm</artifactId>
    <version>${ktor_version}</version>
</dependency>

安装插件 ​

要将 ForwardedHeaders 插件安装到您的应用程序中,请在指定的 模块模块允许您通过对路由进行分组来构建应用程序结构。内将其传递给 install 函数。以下示例展示了如何安装 ForwardedHeaders:

  • 在 embeddedServer() 函数调用中。
  • 在 Application 类上显式定义的 module() 扩展函数中。
kotlin
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)
}
kotlin
import io.ktor.server.application.*
import io.ktor.server.plugins.forwardedheaders.*
// ...
fun Application.module() {
    install(ForwardedHeaders)
    // ...
}

要将 XForwardedHeaders 插件安装到您的应用程序中,请在指定的 模块模块允许您通过对路由进行分组来构建应用程序结构。内将其传递给 install 函数。以下示例展示了如何安装 XForwardedHeaders:

  • 在 embeddedServer() 函数调用中。
  • 在 Application 类上显式定义的 module() 扩展函数中。
kotlin
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)
}
kotlin
import io.ktor.server.application.*
import io.ktor.server.plugins.forwardedheaders.*
// ...
fun Application.module() {
    install(XForwardedHeaders)
    // ...
}

安装 ForwardedHeaders/XForwardedHeaders 之后,您可以使用 call.request.origin 属性获取有关原始请求的信息。

获取请求信息 ​

代理请求信息 ​

要获取有关代理请求的信息,请在路由处理程序中使用 call.request.local 属性。 以下代码段演示了如何获取有关代理地址以及发出请求的目标主机的信息:

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

原始请求信息 ​

要读取有关原始请求的信息,请使用 call.request.origin 属性:

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

下表展示了在安装与未安装 ForwardedHeaders/XForwardedHeaders 的情况下,call.request.origin 所公开的不同属性对应的值。

请求图示

属性未安装 ForwardedHeaders已安装 ForwardedHeaders
origin.localHostweb-serverweb-server
origin.localPort80808080
origin.serverHostweb-serverproxy
origin.serverPort808080
origin.remoteHostproxyclient
origin.remotePort3286432864

您可以在此处找到完整示例:forwarded-header。

配置 ForwardedHeaders ​

如果请求经过多个代理,您可能需要配置 ForwardedHeaders/XForwardedHeaders。 在这种情况下,X-Forwarded-For 将包含每个连续代理的所有 IP 地址,例如:

HTTP
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:
    HTTP
    X-Forwarded-For: 10.0.0.123, proxy-1, proxy-2, proxy-3
  • skipKnownProxies 从列表中移除指定的条目并获取最后一个条目。 例如,如果您将 listOf("proxy-1", "proxy-3") 传递给此函数,对于以下标头,origin.remoteHost 将返回 proxy-2:
    HTTP
    X-Forwarded-For: 10.0.0.123, proxy-1, proxy-2, proxy-3
  • extractEdgeProxy 允许您提供用于从 X-Forward-* 标头中提取值的自定义逻辑。