Skip to content

Docker ​

在本节中,你将学习如何使用 Ktor Gradle 插件 通过 Docker 打包、运行和部署应用程序。

安装 Ktor 插件 ​

kotlin
plugins {
    alias(ktorLibs.plugins.ktor)
}
groovy
plugins {
    alias(ktorLibs.plugins.ktor)
}
上述代码段使用 Ktor 版本目录来指定 Ktor 依赖项。

如果同时应用 Ktor Gradle 插件与 Kotlin Multiplatform Gradle 插件,Docker 集成将自动禁用。 要想将它们一起使用:

  1. 创建一个仅限 JVM 的项目,并如上所示应用 Ktor Gradle 插件。
  2. 将 Kotlin Multiplatform 项目作为依赖项添加到该仅限 JVM 的项目中。

如果此变通方法未能解决你的问题,请在 KTOR-8464 中留言告知我们。

插件任务 ​

安装插件后,以下任务可用于打包、运行和部署应用程序:

  • buildImage:将项目的 Docker 镜像构建为归档包(tarball)。该任务会在 build 目录下生成一个 jib-image.tar 文件。你可以使用 docker load 命令将此镜像加载到 Docker 守护进程中:
    Bash
    docker load < build/jib-image.tar
  • publishImageToLocalRegistry:构建项目的 Docker 镜像并将其发布到本地注册表。
  • runDocker:将项目的镜像构建到 Docker 守护进程并运行它。执行此任务将启动 Ktor 服务器,默认响应地址为 http://0.0.0.0:8080。如果服务器配置为使用其他端口,可以调整端口映射。
  • publishImage:构建项目的 Docker 镜像并将其发布到外部注册表(例如 Docker Hub 或 Google Container Registry)。请注意,针对此任务,你需要使用 ktor.docker.externalRegistry 属性来配置外部注册表。

请注意,默认情况下,这些任务构建的镜像名称为 ktor-docker-image,标签为 latest。 你可以在插件配置中自定义这些值。

配置 Ktor 插件 ​

要配置与 Docker 任务相关的 Ktor 插件设置,请在 build.gradle(.kts) 文件中使用 ktor.docker 扩展程序:

kotlin
ktor {
    docker {
        // ...
    }
}

JRE 版本 ​

jreVersion 属性指定镜像中使用的 JRE 版本:

kotlin
ktor {
    docker {
        jreVersion.set(JavaVersion.VERSION_17)
    }
}

镜像名称与标签 ​

如果需要自定义镜像名称和标签,请分别使用 localImageName 和 imageTag 属性:

kotlin
ktor {
    docker {
        localImageName.set("sample-docker-image")
        imageTag.set("0.0.1-preview")
    }
}

端口映射 ​

默认情况下,runDocker 任务会将 8080 容器端口发布到 8080 Docker 主机端口。 如有需要,可以使用 portMappings 属性更改这些端口。 如果你的服务器已配置为使用其他端口,这会非常有用。

下面的示例展示了如何将 8080 容器端口映射到 80 Docker 主机端口。

kotlin
ktor {
    docker {
        portMappings.set(listOf(
            io.ktor.plugin.features.DockerPortMapping(
                80,
                8080,
                io.ktor.plugin.features.DockerPortMappingProtocol.TCP
            )
        ))
    }
}

在这种情况下,你可以通过 http://0.0.0.0:80 访问服务器。

外部注册表 ​

在使用 publishImage 任务将项目的 Docker 镜像发布到外部注册表之前,你需要使用 ktor.docker.externalRegistry 属性配置外部注册表。该属性接受 DockerImageRegistry 实例,该实例提供所需注册表类型的配置:

  • DockerImageRegistry.dockerHub:为 Docker Hub 创建 DockerImageRegistry。
  • DockerImageRegistry.googleContainerRegistry:为 Google Container Registry 创建 DockerImageRegistry。

以下示例展示了如何配置 Docker Hub 注册表:

kotlin
ktor {
    docker {
        externalRegistry.set(
            io.ktor.plugin.features.DockerImageRegistry.dockerHub(
                appName = provider { "ktor-app" },
                username = providers.environmentVariable("DOCKER_HUB_USERNAME"),
                password = providers.environmentVariable("DOCKER_HUB_PASSWORD")
            )
        )
    }
}

请注意,Docker Hub 用户名和密码是从环境变量中获取的,因此在运行 publishImage 任务之前需要设置这些值:

Bash
export DOCKER_HUB_USERNAME=yourHubUsername
export DOCKER_HUB_PASSWORD=yourHubPassword
Bash
setx DOCKER_HUB_USERNAME yourHubUsername
setx DOCKER_HUB_PASSWORD yourHubPassword

手动配置镜像 ​

如有需要,你可以提供自己的 Dockerfile 来组装包含 Ktor 应用程序的镜像。

打包应用程序 ​

第一步,你需要将应用程序及其依赖项打包。 例如,这可以是一个 fat JAR 或一个可执行的 JVM 应用程序。

准备 Docker 镜像 ​

为了将应用程序容器化,我们将使用多阶段构建:

  1. 首先,我们将为 Gradle/Maven 依赖项设置缓存。此步骤是可选的,但建议执行,因为它可以提升整体构建速度。
  2. 随后,我们将使用 gradle/maven 镜像来生成包含该应用程序的 fat JAR。
  3. 最后,生成的发行包将在基于 JDK 镜像创建的环境中运行。

在项目的根文件夹中,创建一个名为 Dockerfile 的文件,其内容如下:

docker
# Stage 1: Cache Gradle dependencies
FROM gradle:latest AS cache
RUN mkdir -p /home/gradle/cache_home
ENV GRADLE_USER_HOME=/home/gradle/cache_home
COPY build.gradle.* gradle.properties /home/gradle/app/
COPY gradle /home/gradle/app/gradle
WORKDIR /home/gradle/app
RUN gradle dependencies --no-daemon

# Stage 2: Build Application
FROM gradle:latest AS build
COPY --from=cache /home/gradle/cache_home /home/gradle/.gradle
COPY --chown=gradle:gradle . /home/gradle/src
WORKDIR /home/gradle/src
# Build the fat JAR, Gradle also supports shadow
# and boot JAR by default.
RUN gradle buildFatJar --no-daemon

# Stage 3: Create the Runtime Image
FROM amazoncorretto:22 AS runtime
EXPOSE 8080
RUN mkdir /app
COPY --from=build /home/gradle/src/build/libs/*.jar /app/ktor-docker-sample.jar
ENTRYPOINT ["java","-jar","/app/ktor-docker-sample.jar"]
Docker
# Stage 1: Cache Maven dependencies
FROM maven:3.8-amazoncorretto-21 AS cache
WORKDIR /app
COPY pom.xml .
RUN mvn dependency:go-offline

# Stage 2: Build Application
FROM maven:3.8-amazoncorretto-21 AS build
WORKDIR /app
COPY --from=cache /root/.m2 /root/.m2
COPY . .
RUN mvn clean package

# Stage 3: Create the Runtime Image
FROM amazoncorretto:21-slim AS runtime
EXPOSE 8080
WORKDIR /app
COPY --from=build /app/target/*-with-dependencies.jar app.jar
ENTRYPOINT ["java", "-jar", "app.jar"]

第一阶段确保仅在构建相关文件发生更改时才重新下载依赖项。如果未使用第一阶段,或者未在其他阶段缓存依赖项,则每次构建都会安装依赖项。

在第二阶段中构建 fat JAR。请注意,Gradle 默认还支持 shadow 和 boot JAR。

构建的第三阶段按以下方式工作:

  • 指明将要使用的镜像。
  • 指定公开的端口(这不会自动暴露端口,暴露端口是在运行容器时完成的)。
  • 将构建输出的内容复制到文件夹中。
  • 运行应用程序(ENTRYPOINT)。

本示例使用的是 Amazon Corretto Docker 镜像,但你也可以将其替换为任何其他合适的替代方案,例如:

构建并运行 Docker 镜像 ​

下一步是构建并标记 Docker 镜像:

bash
docker build -t my-application .

最后,启动镜像:

bash
docker run -p 8080:8080 my-application

这将启动 Ktor 服务器,并在 https://0.0.0.0:8080 上响应请求。