ejdiniz/uvicorn-gunicorn Docker 镜像 - 轩辕镜像

支持的标签及对应Dockerfile链接

• python3.12, latest (Dockerfile)
• python3.11 (Dockerfile)
• python3.12-slim (Dockerfile)
• python3.11-slim (Dockerfile)

---

注意：存在每个构建日期的标签。如果需要固定使用的Docker镜像版本，可选择这些标签。例如：ejdiniz/uvicorn-gunicorn:python3.12-2024-04-03。

uvicorn-gunicorn

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

GitHub仓库：[***]

Docker Hub镜像：[***]

镜像概述

使用Uvicorn（遵循Python异步Web应用"ASGI"规范）运行的Python Web应用，经第三方基准测试显示具有极佳性能，性能与Go和Node.js框架相当，在许多场景下更优。

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

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

如果你正在使用Kubernetes或类似工具，那么可能不需要此镜像（或任何其他类似基础镜像）。建议按照FastAPI容器化部署文档中的说明从零构建Docker镜像，相同的流程和思路也适用于其他ASGI框架。

---

如果你使用Kubernetes、Docker Swarm Mode、Nomad或其他复杂系统在多台机器上管理分布式容器，通常需要在集群层面处理副本，而非在每个容器中使用进程管理器（如Gunicorn管理Uvicorn工作进程），而这正是本镜像的作用。

在这些场景下（例如使用Kubernetes），建议从零构建Docker镜像，安装依赖，并运行单个Uvicorn进程，而非使用本镜像。

例如，你的Dockerfile可以如下：

Dockerfile
FROM python:3.12

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容器化部署文档，相同思路适用于其他ASGI框架。

使用场景

简单应用

如果你的应用足够简单，无需过多微调进程数，可使用自动化默认配置，且运行在单台服务器（非集群）上，那么可在容器中使用Gunicorn管理Uvicorn工作进程。

Docker Compose部署

如果通过Docker Compose部署到单台服务器（非集群），且难以在保留共享网络和负载均衡的同时管理容器副本，那么可使用单个容器，通过Gunicorn进程管理器启动多个Uvicorn工作进程，本镜像即为此场景设计。

Prometheus及其他场景

你可能因其他原因需要单个容器运行多个进程，而非多个容器各运行单个进程。

例如（取决于具体配置），可能在同一容器中运行Prometheus exporter，需要访问所有请求。此时，若使用多个容器，Prometheus默认只能读取单个容器的指标，而非所有副本容器的累积指标。这种情况下，单个容器运行多个进程，并通过本地工具（如Prometheus exporter）收集所有内部进程的指标并暴露，会更为简单。

---

更多信息可参考FastAPI容器化部署文档，相同思路适用于任何其他ASGI框架。

技术细节

Uvicorn

Uvicorn是一款高性能"ASGI"服务器，在单个进程中运行异步Python Web代码。

Gunicorn

可使用Gunicorn启动和管理多个Uvicorn工作进程，在简单部署中同时获得并发和并行优势。

eduardojdiniz/uvicorn-gunicorn

本镜像基于运行服务器的可用CPU核心数设置合理配置，无需额外牺牲。具备默认配置，同时支持通过环境变量或覆盖配置文件进行自定义。提供slim版本，可通过上述标签选择。

适用框架

本镜像设计为以下镜像的基础：

• eduardojdiniz/uvicorn-gunicorn-fastapi

但也可作为运行任何遵循ASGI规范的Python Web应用的基础镜像。如果创建新的FastAPI应用，建议使用eduardojdiniz/uvicorn-gunicorn-fastapi。

注意：FastAPI基于Starlette构建，增加了数据验证、转换、OpenAPI文档、依赖注入、安全认证等功能，适用于API等场景。

注意：除非进行高级技术操作，否则建议使用FastAPI配合eduardojdiniz/uvicorn-gunicorn-fastapi。

使用方法

无需克隆GitHub仓库，可直接将本镜像作为基础镜像使用。

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

Dockerfile
FROM eduardojdiniz/uvicorn-gunicorn:python3.12

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应用变量。

构建镜像：

bash
docker build -t myimage ./

运行容器：

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

可通过Docker主机URL访问应用，例如：<[]>或<[]>。

依赖和包管理

建议添加应用依赖并固定版本，包括Uvicorn和Gunicorn，确保应用稳定运行。可通过Dockerfile中的pip命令、requirements.txt或Poetry安装依赖，并在更新依赖时通过测试确保兼容性。

使用Poetry

以下示例展示如何使用Poetry管理依赖并固定版本，通过Docker多阶段构建：

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 eduardojdiniz/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并配置容器内运行环境。
• 复制应用依赖文件（./poetry.lock*中的*确保文件不存在时不报错）。
• 安装依赖。
• 复制应用代码。

建议在安装依赖后复制应用代码，利用Docker缓存机制，避免每次更新应用文件时重新安装依赖，仅在添加新依赖时重新安装。此原则适用于任何依赖安装方式（如使用requirements.txt）。

高级用法

环境变量

可通过以下环境变量配置容器，括号内为默认值：

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模块中包含ASGI应用的变量名。默认：app

示例：若主文件代码如下：

Python
from fastapi import FastAPI

api = FastAPI()

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

可设置：

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核心数自动计算工作进程数的系数。默认：1

示例：

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

2核CPU服务器上会启动6个工作进程。支持浮点值，例如8核服务器运行低性能需求应用，可设置0.5，启动4个工作进程：

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

注意：默认情况下，若WORKERS_PER_CORE=1且服务器仅有1核CPU，会启动2个工作进程（而非1个），避免小型机器上的性能问题和应用阻塞。可通过WEB_CONCURRENCY覆盖。

MAX_WORKERS

工作进程最大数量限制。用于自动计算进程数时限制上限，例如数据库连接数有限时。默认无限制。

示例：

bash
docker run -d -p 80:80 -e MAX_WORKERS="24" myimage

WEB_CONCURRENCY

覆盖自动计算的工作进程数。默认：CPU核心数×WORKERS_PER_CORE（2核服务器默认2）。

示例：

bash
docker run -d -p 80:80 -e WEB_CONCURRENCY="2" myimage

HOST

Gunicorn监听的IP地址（容器内）。默认：0.0.0.0

PORT

容器监听端口。默认：80

示例：

bash
docker run -d -p 80:8080 -e PORT="8080" myimage

BIND

Gunicorn绑定的地址和端口，默认基于HOST和PORT（如0.0.0.0:80）。

示例：

bash
docker run -d -p 80:8080 -e BIND="0.0.0.0:8080" myimage

LOG_LEVEL

Gunicorn日志级别，可选：debug、info、warning、error、critical。默认：info

示例：

bash
docker run -d -p 80:8080 -e LOG_LEVEL="warning" myimage

WORKER_CLASS

Gunicorn工作进程类。默认：uvicorn.workers.UvicornWorker，支持ASGI应用并提供最佳性能。如需使用替代工作进程uvicorn.workers.UvicornH11Worker，可设置：

bash
docker run -d -p 80:8080 -e WORKER_CLASS="uvicorn.workers.UvicornH11Worker" myimage

TIMEOUT

工作进程无响应超时时间（秒）。默认：120

示例：

bash
docker run -d -p 80:8080 -e TIMEOUT="20" myimage

KEEP_ALIVE

Keep-Alive连接等待请求的秒数。默认：2

示例：

bash
docker run -d -p 80:8080 -e KEEP_ALIVE="20" myimage

GRACEFUL_TIMEOUT

工作进程优雅重启超时时间（秒）。默认：120

示例：

bash
docker run -d -p 80:8080 -e GRACEFUL_TIMEOUT="20" myimage

ACCESS_LOG

访问日志文件路径。默认："-"（标准输出，Docker日志）。设置为空值可禁用：

bash
docker run -d -p 80:8080 -e ACCESS_LOG= myimage

ERROR_LOG

错误日志文件路径。默认："-"（标准错误输出，Docker日志）。设置为空值可禁用：

bash
docker run -d -p 80:8080 -e ERROR_LOG= myimage

GUNICORN_CMD_ARGS

传递给Gunicorn的额外命令行参数，优先级高于其他环境变量和配置文件。参考Gunicorn配置文档。

示例（使用自定义TLS/SSL证书）：

bash
docker run -d -p 80:8080 -e GUNICORN_CMD_ARGS="--keyfile=/secrets/key.pem --certfile=/secrets/cert.pem" -e PORT=443 myimage

注意：建议使用Traefik等"TLS终止代理"处理TLS/SSL，而非在容器内配置。参考FastAPI HTTPS部署文档。

PRE_START_PATH

启动前脚本路径。默认：/app/prestart.sh

示例：

bash
docker run -d -p 80:8080 -e PRE_START_PATH="/custom/script.sh" myimage

自定义Gunicorn配置文件

镜像内置默认Gunicorn配置文件/gunicorn_conf.py，使用上述环境变量设置配置。可通过以下路径的文件覆盖：

• /app/gunicorn_conf.py
• /app/app/gunicorn_conf.py
• /gunicorn_conf.py

自定义/app/prestart.sh

如需在启动应用前执行操作，可添加prestart.sh至/app目录，镜像会自动检测并执行。

示例（使用Alembic进行SQL迁移）：

创建./app/prestart.sh：

bash
#! /usr/bin/env bash

# 等待数据库启动
sleep 10;
# 执行迁移
alembic upgrade head

启动前会等待10秒，然后执行alembic命令。

如需启动前运行Python脚本，可在prestart.sh中调用：

bash
#! /usr/bin/env bash