khulnasoft/uvicorn-gunicorn

https://github.com/khulnasoft/uvicorn-gunicorn-docker/actions/workflows/test.yml/badge.svg](https://github.com/khulnasoft/uvicorn-gunicorn-docker/actions/workflows/test.yml) https://github.com/khulnasoft/uvicorn-gunicorn-docker/workflows/Deploy/badge.svg](https://github.com/khulnasoft/uvicorn-gunicorn-docker/actions?query=workflow%3ADeploy)

支持的标签及对应的 Dockerfile 链接

• https://github.com/khulnasoft/uvicorn-gunicorn-docker/blob/master/docker-images/python3.11.dockerfile
• https://github.com/khulnasoft/uvicorn-gunicorn-docker/blob/master/docker-images/python3.10.dockerfile
• https://github.com/khulnasoft/uvicorn-gunicorn-docker/blob/master/docker-images/python3.9.dockerfile
• https://github.com/khulnasoft/uvicorn-gunicorn-docker/blob/master/docker-images/python3.8.dockerfile
• https://github.com/khulnasoft/uvicorn-gunicorn-docker/blob/master/docker-images/python3.7.dockerfile
• https://github.com/khulnasoft/uvicorn-gunicorn-docker/blob/master/docker-images/python3.11-slim.dockerfile
• https://github.com/khulnasoft/uvicorn-gunicorn-docker/blob/master/docker-images/python3.10-slim.dockerfile
• https://github.com/khulnasoft/uvicorn-gunicorn-docker/blob/master/docker-images/python3.9-slim.dockerfile
• https://github.com/khulnasoft/uvicorn-gunicorn-docker/blob/master/docker-images/python3.8-slim.dockerfile

已弃用标签

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

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

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

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

---

注意：存在https://hub.docker.com/r/khulnasoft/uvicorn-gunicorn/tags%E3%80%82%E5%A6%82%E6%9E%9C%E9%9C%80%E8%A6%81%22%E5%9B%BA%E5%AE%9A%22%E6%89%80%E4%BD%BF%E7%94%A8%E7%9A%84Docker%E9%95%9C%E5%83%8F%E7%89%88%E6%9C%AC%EF%BC%8C%E5%8F%AF%E4%BB%A5%E9%80%89%E6%8B%A9%E5%85%B6%E4%B8%AD%E4%B8%80%E4%B8%AA%E6%A0%87%E7%AD%BE%E3%80%82%E4%BE%8B%E5%A6%82 khulnasoft/uvicorn-gunicorn:python3.7-2019-10-15。

uvicorn-gunicorn

https://www.docker.com/ 镜像，集成 https://www.uvicorn.org/ 并由 https://gunicorn.org/ 管理，用于 https://www.python.org/ 高性能Web应用，具备性能自动调优功能。

GitHub仓库：https://github.com/khulnasoft/uvicorn-gunicorn-docker

Docker Hub镜像：https://hub.docker.com/r/khulnasoft/uvicorn-gunicorn/

概述

使用 Uvicorn（遵循Python异步Web应用的"ASGI"规范）运行的Python Web应用已被证明具有第三方基准测试中最佳性能之一。

其可实现的性能与Go和Node.js框架相当，在许多情况下甚至更优。

该镜像包含自动调优机制，可基于可用CPU核心数启动多个工作进程。因此，只需添加代码即可自动获得高性能，这在简单部署中非常有用。

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

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

---

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

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

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

Dockerfile
FROM docker.xuanyuan.run/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中了解更多信息，相同的思路适用于任何其他ASGI框架。

何时使用此Docker镜像

简单应用

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

Docker Compose

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

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

Prometheus和其他原因

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

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

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

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

---

在ReadyAPI文档：ReadyAPI容器部署 - Docker中阅读更多相关内容，相同的思路适用于任何其他ASGI框架。

技术细节

Uvicorn

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

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

Gunicorn

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

这样，您可以在简单部署中获得最佳的并发和并行性能。

khulnasoft/uvicorn-gunicorn

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

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

还有一个精简版本（slim）。如果需要，请使用上面列出的标签之一。

框架

此镜像旨在作为以下镜像的基础镜像：

• https://github.com/khulnasoft/uvicorn-gunicorn-starlette-docker
• https://github.com/khulnasoft/uvicorn-gunicorn-readyapi-docker

但也可用作运行任何使用ASGI规范的Python Web应用的基础镜像。

如果您正在创建新的Starlette Web应用，您应该使用https://github.com/khulnasoft/uvicorn-gunicorn-starlette-docker%E3%80%82

如果您正在创建新的ReadyAPI Web应用，您应该使用https://github.com/khulnasoft/uvicorn-gunicorn-readyapi-docker%E3%80%82

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

注意：除非您正在进行更高级的技术操作，否则您可能应该使用Starlette搭配https://github.com/khulnasoft/uvicorn-gunicorn-starlette-docker%EF%BC%8C%E6%88%96**ReadyAPI**%E6%90%AD%E9%85%8Dhttps://github.com/khulnasoft/uvicorn-gunicorn-readyapi-docker%E3%80%82

使用方法

您不需要克隆GitHub仓库。

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

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

Dockerfile
FROM docker.xuanyuan.run/khulnasoft/uvicorn-gunicorn: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的变量，其中包含您的"ASGI"应用。

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

bash
docker build -t myimage ./

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

bash
docker run -d --name mycontainer -p 80:80 docker.xuanyuan.run/myimage

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

依赖项和包

您可能还希望为应用添加任何依赖项并将其固定到特定版本，可能包括Uvicorn和Gunicorn。

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

您可以在Dockerfile中使用pip命令、requirements.txt甚至https://python-poetry.org/%E5%AE%89%E8%A3%85%E5%8C%85%E3%80%82

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

使用Poetry

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

假设您有一个使用https://python-poetry.org/%E7%AE%A1%E7%90%86%E7%9A%84%E9%A1%B9%E7%9B%AE%EF%BC%8C%E5%9B%A0%E6%AD%A4%E6%82%A8%E7%9A%84%E5%8C%85%E4%BE%9D%E8%B5%96%E9%A1%B9%E5%9C%A8%60pyproject.toml%60%E6%96%87%E4%BB%B6%E4%B8%AD%EF%BC%8C%E5%8F%AF%E8%83%BD%E8%BF%98%E6%9C%89%E4%B8%80%E4%B8%AA%60poetry.lock%60%E6%96%87%E4%BB%B6%E3%80%82

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

Dockerfile
FROM docker.xuanyuan.run/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 docker.xuanyuan.run/khulnasoft/uvicorn-gunicorn: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" docker.xuanyuan.run/myimage

VARIABLE_NAME

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

默认值：

• app

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

Python
from docker.xuanyuan.run/readyapi import ReadyAPI

api = ReadyAPI()

@api.get("/")
def read_root():
    return {"message": "Hello world!"}

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

bash
docker run -d -p 80:80 -e VARIABLE_NAME="api" docker.xuanyuan.run/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" docker.xuanyuan.run/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" docker.xuanyuan.run/myimage

您可以使用此镜像的https://github.com/khulnasoft/uvicorn-gunicorn-docker/blob/master/docker-images/gunicorn_conf.py%E4%BD%9C%E4%B8%BA%E6%82%A8%E8%87%AA%E5%B7%B1%E9%85%8D%E7%BD%AE%E7%9A%84%E8%B5%B7%E7%82%B9%E3%80%82

WORKERS_PER_CORE

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

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

默认值：

• 1

您可以这样设置：

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

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

您也可以使用浮点值。

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

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