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

    相依性
    瞭解如何將 Ktor Server 相依性新增到現有的 Gradle/Maven 專案。

配置檔案應至少包含使用 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
瞭解如何使用 Ktor Gradle 外掛程式在 Servlet 容器中執行和部署 Ktor 應用程式,使用 WAR 歸檔。
上下文路徑。

範例 : /

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 外掛程式建立和執行可執行胖 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