Skip to content

文件中的配置

Ktor 允许你配置各种服务器参数,例如主机地址和端口、

模块
模块允许你通过路由分组来组织应用程序。
加载等。 配置方式取决于你创建服务器的方式,即
embeddedServer 或 EngineMain
了解如何根据应用程序部署需求创建服务器。

对于 EngineMain,Ktor 从使用 HOCON 或 YAML 格式的配置文件加载其配置。这种方式提供了更大的灵活性来配置服务器,并允许你在不重新编译应用程序的情况下更改配置。此外,你可以从命令行运行应用程序,并通过传递相应的 命令行 实参来覆盖所需的服务器参数。

概述

如果你使用 EngineMain 启动服务器,Ktor 会自动从位于 resources 目录中的名为 application.* 的文件加载配置设置。支持两种配置格式:

  • HOCON ( application.conf )

  • YAML ( application.yaml )

    NOTE

    要使用 YAML 配置文件,你需要添加 ktor-server-config-yaml

    依赖项
    了解如何向现有的 Gradle/Maven 项目添加 Ktor Server 依赖项。

配置文件中应至少包含使用 ktor.application.modules 属性指定的

要加载的模块
模块允许你通过路由分组来组织应用程序。
,例如:

shell
yaml

在这种情况下,Ktor 会调用以下 Application.kt 文件中的 Application.module 函数:

kotlin

除了要加载的模块之外,你还可以配置各种服务器设置,包括 预定义的 (例如端口或主机、SSL 设置等)和自定义设置。 让我们看几个例子。

基本配置

在下面的示例中,服务器侦听端口使用 ktor.deployment.port 属性设置为 8080

shell
yaml

引擎配置

如果你使用 EngineMain,可以在 ktor.deployment 组中指定所有引擎通用的选项。

shell
yaml

Netty

你还可以在配置文件中 ktor.deployment 组内配置 Netty 特有的选项:

shell
yaml

SSL 配置

下面的示例使 Ktor 能够侦听 8443 SSL 端口,并在单独的 security 代码块中指定所需的

SSL 设置
所需依赖项:io.ktor:ktor-network-tls-certificates 代码示例:ssl-engine-main, ssl-embedded-server

shell
yaml

自定义配置

除了指定预定义属性之外, Ktor 允许你在配置文件中保留自定义设置。 下面的配置文件包含一个用于保存 JWT 设置的自定义 jwt 组。

shell
yaml

你可以在代码中读取和处理此类设置

预定义属性

以下是可以在配置文件中使用的预定义设置列表。

ktor.deployment.host

主机地址。

示例 : 0.0.0.0

ktor.deployment.port

侦听端口。你可以将此属性设置为 0,以便在随机端口上运行服务器。

示例 : 8080, 0

ktor.deployment.sslPort

侦听 SSL 端口。你可以将此属性设置为 0,以便在随机端口上运行服务器。

示例 : 8443, 0

NOTE

请注意,SSL 需要下面列出的额外选项。

ktor.deployment.watch

用于自动重新加载的监听路径。

ktor.deployment.rootPath

一个

servlet
了解如何使用 WAR 归档在 Servlet 容器中运行和部署 Ktor 应用程序。
上下文路径。

示例 : /

ktor.deployment.shutdown.url

一个关闭 URL。 请注意,此选项使用

关闭 URL
代码示例: %example_name%
插件。

ktor.deployment.shutdownGracePeriod

服务器停止接受新请求的最长时间(以毫秒为单位)。

ktor.deployment.shutdownTimeout

等待服务器完全停止的最长时间(以毫秒为单位)。

ktor.deployment.callGroupSize

用于处理应用程序调用的线程池的最小大小。

ktor.deployment.connectionGroupSize

用于接受新连接并启动调用处理的线程数。

ktor.deployment.workerGroupSize

用于处理连接、解析消息和执行引擎内部工作的事件组的大小。

如果你设置了 ktor.deployment.sslPort,则需要指定以下

SSL 特有的
所需依赖项:io.ktor:ktor-network-tls-certificates 代码示例:ssl-engine-main, ssl-embedded-server
属性:

ktor.security.ssl.keyStore

一个 SSL 密钥库。

ktor.security.ssl.keyAlias

SSL 密钥库的别名。

ktor.security.ssl.keyStorePassword

SSL 密钥库的密码。

ktor.security.ssl.privateKeyPassword

SSL 私钥的密码。

环境变量

在配置文件中,你可以使用 ${ENV} / $ENV 语法将参数替换为环境变量。 例如,你可以通过以下方式将 PORT 环境变量赋值给 ktor.deployment.port 属性:

shell
yaml

在这种情况下,环境变量值将用于指定侦听端口。 如果 PORT 环境变量在运行时不存在,你可以按如下方式提供默认端口值:

shell
yaml

在代码中读取配置

Ktor 允许你访问配置文件中指定的属性值。 例如,如果你指定了 ktor.deployment.port 属性,...

shell
yaml

... 你可以使用 ApplicationEnvironment.config 访问应用程序的配置,并按以下方式获取所需的属性值:

kotlin

当你将自定义设置保存在配置文件中并需要访问其值时,这尤其有用。

命令行

如果你使用EngineMain创建服务器,你可以从命令行运行

打包好的应用程序
了解如何使用 Ktor Gradle 插件创建和运行可执行 fat JAR。
,并通过传递相应的命令行实参来覆盖所需的服务器参数。例如,你可以通过以下方式覆盖配置文件中指定的端口:

shell

可用命令行选项如下:

-jar

JAR 文件的路径。

-config

自定义配置文件的路径,用于替代 resources 中的 application.conf / application.yaml

示例 : java -jar sample-app.jar -config=anotherfile.conf

注意 : 你可以传递多个值。 java -jar sample-app.jar -config=config-base.conf -config=config-dev.conf。在这种情况下,所有配置都将合并,其中右侧配置中的值具有更高优先级。

-host

主机地址。

-port

侦听端口。

-watch

用于自动重新加载的监听路径。

SSL 特有的
所需依赖项:io.ktor:ktor-network-tls-certificates 代码示例:ssl-engine-main, ssl-embedded-server
选项:

-sslPort

侦听 SSL 端口。

-sslKeyStore

一个 SSL 密钥库。

如果你需要覆盖没有相应命令行选项的预定义属性,请使用 -P 标志,例如:

你还可以使用 -P 标志来覆盖自定义属性

示例:如何使用自定义属性指定环境

你可能希望根据服务器是在本地运行还是在生产机器上运行来执行不同的操作。为此,你可以在 application.conf / application.yaml 中添加一个自定义属性,并使用一个专用环境变量对其进行初始化,该变量的值取决于服务器是在本地运行还是在生产环境中运行。在下面的示例中,KTOR_ENV 环境变量被赋值给自定义的 ktor.environment 属性。

yaml

你可以在运行时通过在代码中读取配置来访问 ktor.environment 值并执行所需操作:

kotlin

你可以在此处找到完整示例: engine-main-custom-environment