uvicorn-gunicorn Docker镜像文档（已弃用）

⚠️ 已弃用警告

此Docker镜像现已弃用。您无需再使用此镜像，直接使用Uvicorn并添加--workers参数即可实现相同功能。详情请参见下文。

支持的标签及对应Dockerfile链接

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

已弃用标签

⚠️ 以下标签不再受支持或维护，已从GitHub仓库中移除，但Docker Hub可能仍保留最后推送的版本：

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

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

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

注意：存在按构建日期命名的标签。若需固定镜像版本，可选择此类标签，例如tiangolo/uvicorn-gunicorn:python3.11-2024-11-02。

镜像概述和主要用途

uvicorn-gunicorn是一个Docker镜像，包含Uvicorn（基于ASGI规范的Python异步Web服务器）和Gunicorn（进程管理器），用于高性能Python Web应用，并具备自动性能调优能力。

原设计目标是通过自动调整工作进程数量（基于可用CPU核心数），简化部署流程，使开发者只需添加应用代码即可获得高性能。

核心功能和特性

• 高性能：基于Uvicorn（ASGI服务器），性能与Go、Node.js框架相当甚至更优。
• 自动调优：根据CPU核心数自动配置工作进程数量。
• 灵活性：支持通过环境变量或配置文件自定义参数。
• 多标签支持：提供不同Python版本（3.9/3.10/3.11）及slim变体。

使用场景和适用范围

原适用场景：
适用于简单部署环境，需要快速启动高性能ASGI应用（如FastAPI、Starlette），无需手动配置进程管理。

当前建议：
此镜像已弃用，现代部署应优先考虑以下方案：

1. 直接使用Uvicorn：通过--workers参数手动指定工作进程数，例如：

   uvicorn app.main:app --host 0.0.0.0 --port 80 --workers 4
   

2. 集群环境（Kubernetes/Docker Swarm等）：在集群中，应通过集群级别的副本管理（而非容器内进程管理器）实现扩展，此时建议构建基础镜像并运行单Uvicorn进程，例如：

   FROM python:3.11
   WORKDIR /code
   COPY requirements.txt .
   RUN pip install --no-cache-dir -r requirements.txt
   COPY ./app /code/app
   CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "80"]
   

历史使用方法（仅供参考）

基础使用

Dockerfile示例

以Python 3.11为例，构建自定义应用镜像：

FROM tiangolo/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应用实例）。

构建和运行

# 构建镜像
docker build -t my-asgi-app ./

# 运行容器
docker run -d --name my-app -p 80:80 my-asgi-app

环境变量配置

可通过环境变量自定义行为，以下为关键参数及默认值：

示例：自定义工作进程数

# 限制最大工作进程为4，每个核心0.5个进程
docker run -d -p 80:80 -e MAX_WORKERS=4 -e WORKERS_PER_CORE=0.5 my-asgi-app

高级用法

自定义Gunicorn配置文件

创建gunicorn_conf.py并挂载到容器，覆盖默认配置：

docker run -d -p 80:80 -e GUNICORN_CONF="/app/custom_gunicorn_conf.py" -v $(pwd)/custom_gunicorn_conf.py:/app/custom_gunicorn_conf.py my-asgi-app

预启动脚本

添加/app/prestart.sh执行启动前任务（如数据库迁移）：

#!/usr/bin/env bash
# 等待数据库启动
sleep 10
# 执行Alembic迁移
alembic upgrade head

赋予执行权限并构建镜像，容器会自动执行此脚本。

开发热重载

使用/start-reload.sh启动开发模式（单Uvicorn进程，代码变更自动重启）：

docker run -d -p 80:80 -v $(pwd)/app:/app/app my-asgi-app /start-reload.sh

Alpine版本警告

不建议使用Alpine标签（如python3.9-alpine3.14），原因：

• Alpine基于musl libc，与Python标准构建工具不兼容，可能导致依赖安装失败或构建时间延长。
• 推荐使用slim标签（基于Debian），兼顾体积与兼容性。

技术细节

原镜像通过Gunicorn作为进程管理器，运行Uvicorn工作进程（uvicorn.workers.UvicornWorker）。随着Uvicorn原生支持--workers参数（管理子进程及重启），Gunicorn的进程管理功能已冗余，因此镜像被弃用。

框架兼容性

原镜像设计为以下框架的基础镜像：

• tiangolo/uvicorn-gunicorn-starlette（Starlette）
• tiangolo/uvicorn-gunicorn-fastapi（FastAPI）

当前建议直接基于Python***镜像构建，无需依赖此类基础镜像。