支持的标签及对应Dockerfile链接

• python3.11, latest (Dockerfile)
• python3.10, (Dockerfile)
• python3.9, (Dockerfile)
• python3.8, (Dockerfile)
• python3.7, (Dockerfile)
• python3.11-slim (Dockerfile)
• python3.10-slim (Dockerfile)
• python3.9-slim (Dockerfile)
• python3.8-slim (Dockerfile)

已弃用标签

🚨 以下标签不再受支持或维护，已从GitHub仓库中移除，但最后推送的版本可能仍在Docker Hub上可用（如果有人拉取过）：

• python3.8-alpine3.10
• python3.9-alpine3.14
• python3.7-alpine3.8
• python3.6
• python3.6-alpine3.8

这些版本的最后日期标签为：

• python3.8-alpine3.10-2024-03-17
• python3.9-alpine3.14-2024-03-17
• python3.7-alpine3.8-2024-03-17
• python3.6-2022-11-25
• python3.6-alpine3.8-2022-11-25

---

注意：存在每个构建日期的标签。如果需要"固定"使用的Docker镜像版本，可以选择这些标签。例如：khulnasoft/uvicorn-gunicorn-starlette:python3.7-2019-10-15。

uvicorn-gunicorn-starlette

Docker镜像，包含由Gunicorn管理的Uvicorn，用于Python 中的高性能Starlette Web应用，并具备性能自动调优功能。

GitHub仓库：[***]

Docker Hub镜像：[***]

概述

Starlette已被第三方基准测试证明是性能最佳的Python Web框架之一，其性能与Go和Node.js框架相当，在许多情况下甚至更优。

该镜像包含自动调优机制，可根据可用CPU核心数启动多个工作进程。只需添加代码即可自动获得高性能，适用于简单部署场景。

🚨 警告：您可能不需要此Docker镜像

您可能正在使用Kubernetes或类似工具。在这种情况下，您可能不需要此镜像（或任何其他类似基础镜像）。您可能最好按照ReadyAPI容器部署文档 - Docker：为ReadyAPI构建Docker镜像中的说明从头构建Docker镜像，相同流程也适用于Starlette。

---

如果您的机器集群使用Kubernetes、Docker Swarm Mode、Nomad或其他类似复杂系统来管理多台机器上的分布式容器，那么您可能希望在集群级别处理复制，而不是在每个容器中使用进程管理器（如带有Uvicorn工作进程的Gunicorn），这正是此Docker镜像的作用。

在这些情况下（例如使用Kubernetes），您可能希望构建从头开始的Docker镜像，安装依赖项，并运行单个Uvicorn进程，而非此镜像。

例如，您的Dockerfile可以如下所示：

Dockerfile
FROM python:3.9

WORKDIR /code

COPY ./requirements.txt /code/requirements.txt

RUN pip install --no-cache-dir --upgrade -r /code/requirements.txt

COPY ./app /code/app

CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "80"]

您可以在ReadyAPI文档：ReadyAPI容器部署 - Docker中了解更多信息，其中的理念同样适用于Starlette。

何时使用此Docker镜像

简单应用

如果您的应用足够简单，不需要（至少目前不需要）过多微调进程数量，只需使用自动化默认配置，并且在单台服务器而非集群上运行，那么您可能需要像Gunicorn这样的进程管理器在容器中运行Uvicorn工作进程。

Docker Compose

您可能正在单台服务器（非集群）上使用Docker Compose部署，因此在保留共享网络和负载均衡的同时，没有简单的方法通过Docker Compose管理容器复制。

这时，您可能希望拥有单个容器，其中Gunicorn进程管理器启动多个Uvicorn工作进程，就像此Docker镜像所做的那样。

Prometheus及其他原因

您也可能有其他原因，使得拥有单个容器和多个进程比拥有多个容器且每个容器单个进程更容易。

例如（取决于您的设置），您可能在同一容器中有类似Prometheus导出器的工具，需要访问每个传入请求。

在这种情况下，如果您有多个容器，默认情况下，当Prometheus来读取指标时，每次会获取单个容器的指标（处理特定请求的容器），而不是获取所有复制容器的累积指标。

这时，拥有一个容器和多个进程，以及同一容器上的本地工具（例如Prometheus导出器）收集所有内部进程的Prometheus指标并在该单个容器上公开这些指标，可能更简单。

---

在ReadyAPI文档：ReadyAPI容器部署 - Docker中阅读更多相关内容。

技术详情

Uvicorn

Uvicorn是一个闪电般快速的"ASGI"服务器。

它在单个进程中运行异步Python Web代码。

Gunicorn

您可以使用Gunicorn启动和管理多个Uvicorn工作进程。

这样，您可以在简单部署中同时获得并发和并行的最佳效果。

Starlette

Starlette是一个轻量级ASGI框架/工具包，非常适合构建高性能asyncio服务。

khulnasoft/uvicorn-gunicorn-starlette

此镜像将基于运行服务器（可用CPU核心数）设置合理配置，而不会做出性能牺牲。

它具有合理的默认值，但您可以通过环境变量配置或覆盖配置文件。

还有精简版本（slim）。如果需要，请使用上述标签之一。

khulnasoft/uvicorn-gunicorn

此镜像（khulnasoft/uvicorn-gunicorn-starlette）基于khulnasoft/uvicorn-gunicorn构建。

该基础镜像实际完成所有工作。

此镜像仅安装Starlette，并提供专门针对Starlette的文档。

如果您对Uvicorn、Gunicorn和ASGI有足够了解，可以直接使用该基础镜像。

khulnasoft/uvicorn-gunicorn-readyapi

有一个姊妹Docker镜像：khulnasoft/uvicorn-gunicorn-readyapi

如果您正在创建新的ReadyAPI Web应用，应使用khulnasoft/uvicorn-gunicorn-readyapi。

注意：ReadyAPI基于Starlette构建，并在其之上添加了多个功能。适用于API和其他场景：数据验证、数据转换、OpenAPI文档、依赖注入、安全/认证等。

如何使用

您无需克隆GitHub仓库。

可以将此镜像用作其他镜像的基础镜像。

假设您有一个requirements.txt文件，您的Dockerfile可以如下所示：

Dockerfile
FROM khulnasoft/uvicorn-gunicorn-starlette:python3.11

COPY ./requirements.txt /app/requirements.txt

RUN pip install --no-cache-dir --upgrade -r /app/requirements.txt

COPY ./app /app

它会期望在/app/app/main.py或/app/main.py存在文件。

并期望该文件包含名为app的变量，其中包含您的Starlette应用。

然后，您可以从包含Dockerfile的目录构建镜像，例如：

bash
docker build -t myimage ./

快速开始

• 进入项目目录。
• 创建包含以下内容的Dockerfile：

Dockerfile
FROM khulnasoft/uvicorn-gunicorn-starlette:python3.11

COPY ./requirements.txt /app/requirements.txt

RUN pip install --no-cache-dir --upgrade -r /app/requirements.txt

COPY ./app /app

• 创建app目录并进入。
• 创建main.py文件，内容如下：

Python
from starlette.applications import Starlette
from starlette.responses import JSONResponse

app = Starlette()


@app.route("/")
async def homepage(request):
    return JSONResponse({"message": "Hello World!"})

• 现在您的目录结构应如下所示：

.
├── app
│   └── main.py
└── Dockerfile

• 进入项目目录（包含Dockerfile和app目录的位置）。
• 构建Starlette镜像：

bash
docker build -t myimage .

• 基于您的镜像运行容器：

bash
docker run -d --name mycontainer -p 80:80 myimage

现在，您在Docker容器中拥有了优化的Starlette服务器。它会根据当前服务器（CPU核心数）自动调优。

您应该能够在Docker容器的URL中访问它，例如：[] 或 []

您将看到类似以下内容：

JSON
{"message": "Hello World!"}

依赖项和包

您可能还需要为应用添加任何依赖项并固定其版本，可能包括Uvicorn、Gunicorn和Starlette。

这样可以确保您的应用始终按预期工作。

您可以在Dockerfile中使用pip命令、requirements.txt甚至Poetry安装包。

然后，您可以通过受控方式升级这些依赖项，运行测试，确保一切正常，而不会在某些新版本不兼容时破坏生产应用。

使用Poetry

以下是确保每个包都有固定版本的依赖项安装方法示例之一。

假设您使用Poetry管理项目，因此依赖项在pyproject.toml文件中，可能还有poetry.lock文件。

然后，您可以使用Docker多阶段构建创建Dockerfile：

Dockerfile
FROM python:3.9 as requirements-stage

WORKDIR /tmp

RUN pip install poetry

COPY ./pyproject.toml ./poetry.lock* /tmp/

RUN poetry export -f requirements.txt --output requirements.txt --without-hashes

FROM khulnasoft/uvicorn-gunicorn-starlette:python3.11

COPY --from=requirements-stage /tmp/requirements.txt /app/requirements.txt

RUN pip install --no-cache-dir --upgrade -r /app/requirements.txt

COPY ./app /app

这将：

• 安装Poetry并配置其在Docker容器中运行。
• 复制应用依赖项。
  • 因为使用./poetry.lock*（以*结尾），所以如果该文件尚不可用，也不会崩溃。
• 安装依赖项。
• 然后复制应用代码。

重要的是在安装依赖项之后复制应用代码，这样可以利用Docker的缓存。这样，每次更新应用文件时无需从头安装所有依赖项，仅在添加新依赖项时才需要。

这也适用于任何其他安装依赖项的方式。如果使用requirements.txt，请单独复制它并在Dockerfile顶部安装所有依赖项，然后在之后添加应用代码。

高级用法

环境变量

以下是可在容器中设置以进行配置的环境变量及其默认值：

MODULE_NAME

Gunicorn要导入的Python"模块"（文件），该模块应在变量中包含实际应用。

默认值：

• 如果存在/app/app/main.py文件，则为app.main
• 如果存在/app/main.py文件，则为main

例如，如果主文件位于/app/custom_app/custom_main.py，可以这样设置：

bash
docker run -d -p 80:80 -e MODULE_NAME="custom_app.custom_main" myimage

VARIABLE_NAME

Python模块中包含Starlette应用的变量。

默认值：

• app

例如，如果主Python文件包含以下内容：

Python
from starlette.applications import Starlette
from starlette.responses import JSONResponse

api = Starlette()


@api.route("/")
async def homepage(request):
    return JSONResponse({"message": "Hello World!"})

在这种情况下，api是包含Starlette应用的变量。可以这样设置：

bash
docker run -d -p 80:80 -e VARIABLE_NAME="api" myimage

APP_MODULE

传递给Gunicorn的包含Python模块和变量名的字符串。

默认值基于变量MODULE_NAME和VARIABLE_NAME：

• app.main:app 或
• main:app

可以这样设置：

bash
docker run -d -p 80:80 -e APP_MODULE="custom_app.custom_main:api" myimage

GUNICORN_CONF

Gunicorn Python配置文件的路径。

默认值：

• 如果存在/app/gunicorn_conf.py，则使用该文件
• 如果存在/app/app/gunicorn_conf.py，则使用该文件
• 否则使用/gunicorn_conf.py（包含的默认文件）

可以这样设置：

bash
docker run -d -p 80:80 -e GUNICORN_CONF="/app/custom_gunicorn_conf.py" myimage

您可以使用基础镜像的配置文件作为自定义配置的起点。

WORKERS_PER_CORE

此镜像将检查运行容器的服务器上可用的CPU核心数。

它将工作进程数设置为CPU核心数乘以该值。

默认值：

• 1

可以这样设置：

bash
docker run -d -p 80:80 -e WORKERS_PER_CORE="3" myimage

如果在具有2个CPU核心的服务器上使用值3，将运行6个工作进程。

也可以使用浮点值。

例如，如果您有一台大型服务器（假设有8个CPU核心）运行多个应用，而您的Starlette应用不需要高性能，并且不想浪费服务器资源。您可以将每个CPU核心的工作进程数设置为0.5。例如：

bash
docker run -d -p 80:80 -e WORKERS_PER_CORE="0.5" myimage

在具有8个CPU核心的服务器上，这将启动仅4个