转发标头
必需依赖项: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-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 | 已安装 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: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-*标头中提取值的自定义逻辑。
