tiangolo/uvicorn-gunicorn-starlette

已弃用 🚨

此Docker镜像现已弃用。无需使用它，你可以直接使用带有--workers选项的Uvicorn。✨

下文将提供更多相关信息。

---

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

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

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

已弃用的标签

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

• python-3.8
• python-3.8-slim
• python3.8-alpine3.10
• python3.9-alpine3.14
• python3.7
• python3.7-alpine3.8
• python3.6
• python3.6-alpine3.8

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

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

---

注意：存在https://hub.docker.com/r/tiangolo/uvicorn-gunicorn-starlette/tags%E3%80%82%E5%A6%82%E6%9E%9C%E4%BD%A0%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%60tiangolo/uvicorn-gunicorn-starlette:python3.11-2024-11-02%60%E3%80%82

uvicorn-gunicorn-starlette

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

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

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

概述

Starlette 已被证明是一款性能卓越的Python Web框架，第三方基准测试也证实了这一点。

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

此镜像包含自动调优机制，可根据可用CPU核心数启动一定数量的工作进程。这样你只需添加代码即可自动获得高性能，这在简单部署中非常有用。

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

你可能正在使用Kubernetes或类似工具。在这种情况下，你可能不需要此镜像（或任何其他类似基础镜像）。你可能最好按照FastAPI in Containers - Docker: Build a Docker Image for FastAPI文档中的说明从头构建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"]

你可以在FastAPI文档：FastAPI in Containers - Docker中了解更多相关内容，这些思路同样适用于Starlette。

多个工作进程

如果你确实希望在单个容器中拥有多个工作进程，Uvicorn现在支持处理子进程，包括重启已终止的进程。因此，不需要Gunicorn在单个容器中管理多个工作进程。

你可以修改上面的示例Dockerfile，为Uvicorn添加--workers选项，如下所示：

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", "--workers", "4"]

这就是你所需要的。你根本不需要此Docker镜像。😅

你可以在FastAPI文档：Deployment with Docker中了解更多信息。

技术细节

Uvicorn过去不支持管理工作进程（包括重启已终止的工作进程），但现在支持了。

在此之前，可以使用Gunicorn作为进程管理器，运行Uvicorn工作进程。这增加了复杂度，而现在已不再必要。

历史文档

本文档的其余部分为历史原因保留，但你可能不需要它。😅

tiangolo/uvicorn-gunicorn-starlette

此镜像将根据其运行的服务器（可用CPU核心数）设置合理的配置，而不会做出妥协。

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

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

tiangolo/uvicorn-gunicorn

此镜像（tiangolo/uvicorn-gunicorn-starlette）基于https://github.com/tiangolo/uvicorn-gunicorn-docker%E3%80%82

该镜像实际上完成了所有工作。

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

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

tiangolo/uvicorn-gunicorn-fastapi

有一个 sibling Docker镜像：https://github.com/tiangolo/uvicorn-gunicorn-fastapi-docker

如果你正在创建新的FastAPI Web应用，你应该使用https://github.com/tiangolo/uvicorn-gunicorn-fastapi-docker%E3%80%82

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

如何使用

你不需要克隆GitHub仓库。

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

假设你有一个requirements.txt文件，你可以有如下Dockerfile：

Dockerfile
FROM tiangolo/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 tiangolo/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 tiangolo/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

你可以使用https://github.com/tiangolo/uvicorn-gunicorn-docker/blob/master/docker-images/gunicorn_conf.py%E4%BD%9C%E4%B8%BA%E4%BD%A0%E7%9A%84%E9%85%8D%E7%BD%AE%E6%96%87%E4%BB%B6%E7%9A%84%E8%B5%B7%E7%82%B9%E3%80%82

WORKERS_PER_CORE

此镜像将检查运行容器的服务器上可用的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核心的服务器上