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	已安装 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：

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

• skipKnownProxies 从列表中移除指定条目，然后获取最后一个条目。 例如，如果您将 list("proxy-1", "proxy-3") 传递给此函数，则对于下面的标头，origin.remoteHost 将返回 proxy-2：

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

• extractEdgeProxy 允许您提供自定义逻辑，用于从 X-Forward-* 标头中提取值。