Server Plugin

Forwarded 标头

所需依赖项：io.ktor:ktor-server-forwarded-header

代码示例： forwarded-header

原生服务器

Ktor supports Kotlin/Native and allows you to run a server without an additional runtime or virtual machine.

支持：✅

ForwardedHeaders 和 XForwardedHeaders 插件允许您在 Ktor 服务器位于反向代理之后时，通过处理反向代理标头来获取有关原始请求的信息。这对于日志记录很有用。

• 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 构件：

Gradle (Kotlin)Gradle (Groovy)Maven

安装插件

ForwardedHeaderXForwardedHeader

要将 ForwardedHeaders 插件安装到应用， 请将其传递给指定

模块

Modules allow you to structure your application by grouping routes.

中的 install 函数。 以下代码片段展示了如何安装 ForwardedHeaders ...

• ... 在 embeddedServer 函数调用内部。
• ... 在显式定义的 module 内部，该模块是 Application 类的扩展函数。

embeddedServermodule

要将 XForwardedHeaders 插件安装到应用， 请将其传递给指定

模块

Modules allow you to structure your application by grouping routes.

中的 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	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-Forward-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-* 标头中提取值的自定义逻辑。