uvicorn-gunicorn-fastapi Docker镜像文档

⚠️ 已弃用 (DEPRECATED)

此Docker镜像现已弃用。您无需再使用它，只需直接使用带有--workers参数的Uvicorn即可。✨

下文将详细说明相关情况。

---

![Test]([] ![Deploy]([]

支持的标签及对应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.8
• python3.8-slim
• python3.7
• python3.9-alpine3.14
• python3.8-alpine3.10
• python3.7-alpine3.8
• python3.6
• python3.6-alpine3.8

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

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

---

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

镜像概述和主要用途

uvicorn-gunicorn-fastapi是一个Docker镜像，包含由Gunicorn管理的Uvicorn，用于在Python中运行高性能FastAPI Web应用，并具备性能自动调优能力。该镜像基于tiangolo/uvicorn-gunicorn，预装了FastAPI，文档专门针对FastAPI应用场景。

⚠️ 重要提示：此镜像现已弃用。现代部署环境（如Kubernetes）更适合在集群层面处理副本管理，或直接使用Uvicorn的--workers参数启动多工作进程，无需依赖此镜像。

核心功能和特性

• 高性能：基于Uvicorn和Gunicorn，充分利用FastAPI/Starlette的ASGI性能优势。
• 自动调优：根据可用CPU核心数自动调整工作进程数量。
• 灵活配置：通过环境变量或自定义配置文件调整Gunicorn和Uvicorn参数。
• 多Python版本支持：提供Python 3.9、3.10、3.11等版本的标准和slim标签。
• 预启动脚本：支持在应用启动前执行自定义脚本（如数据库迁移）。

使用场景和适用范围

原适用场景：适用于简单部署环境，无需复杂集群管理工具（如Kubernetes），需要单容器内自动调整工作进程以实现高性能的FastAPI应用。

当前建议：

• 若使用Kubernetes、Docker Swarm Mode、Nomad等集群管理工具，应在集群层面处理副本，而非依赖容器内的进程管理器（如Gunicorn）。
• 单容器部署时，推荐直接使用Uvicorn的--workers参数启动多工作进程，无需此镜像。

重要提示：您可能不需要此Docker镜像

如果您使用Kubernetes或类似工具，通常不需要此镜像（或任何其他类似基础镜像）。建议按照FastAPI*文档：容器化部署 - Docker中的说明从零构建Docker镜像**。

集群副本管理

若您的环境是多机器集群（如Kubernetes、Docker Swarm Mode、Nomad），应在集群层面处理副本，而非在每个容器中使用进程管理器（如Gunicorn+Uvicorn工作进程）。此时，推荐从零构建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"]

多工作进程

若需在单容器内启动多工作进程，Uvicorn已支持直接管理子进程（包括重启异常进程），无需Gunicorn。可在Dockerfile中使用--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"]

技术细节

Uvicorn最初不支持管理工作进程及重启异常进程，因此需借助Gunicorn作为进程管理器。现在Uvicorn已原生支持这些功能，故不再需要Gunicorn，此镜像也随之弃用。

遗留文档

以下内容为历史文档，仅作参考。

tiangolo/uvicorn-gunicorn基础

本镜像（tiangolo/uvicorn-gunicorn-fastapi）基于tiangolo/uvicorn-gunicorn，后者实现了核心的Uvicorn+Gunicorn管理逻辑。本镜像仅额外安装了FastAPI，并针对FastAPI提供文档。若您熟悉Uvicorn、Gunicorn和ASGI，可直接使用tiangolo/uvicorn-gunicorn。

与tiangolo/uvicorn-gunicorn-starlette的关系

存在 sibling 镜像tiangolo/uvicorn-gunicorn-starlette，适用于纯Starlette应用（不含FastAPI的额外功能如数据验证、OpenAPI文档等）。

详细的使用方法和配置说明

基础使用

无需克隆GitHub仓库，可直接将此镜像作为基础镜像构建应用。假设项目包含requirements.txt，示例Dockerfile：

Dockerfile
FROM tiangolo/uvicorn-gunicorn-fastapi: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的FastAPI应用实例

构建镜像：

bash
docker build -t myimage ./

快速启动

构建镜像

1. 进入项目目录，创建Dockerfile：

Dockerfile
FROM tiangolo/uvicorn-gunicorn-fastapi:python3.11

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

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

COPY ./app /app

2. 创建app目录并编写main.py：

python
from fastapi import FastAPI

app = FastAPI()


@app.get("/")
def read_root():
    return {"Hello": "World"}


@app.get("/items/{item_id}")
def read_item(item_id: int, q: str = None):
    return {"item_id": item_id, "q": q}

3. 项目结构：

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

4. 构建并运行：

bash
docker build -t myimage .
docker run -d --name mycontainer -p 80:80 myimage

验证应用

访问[***]，应返回：

json
{"item_id": 5, "q": "somequery"}

访问[***]查看Swagger UI文档，[***]查看ReDoc文档。

依赖管理

推荐通过requirements.txt或Poetry固定依赖版本，确保环境一致性。

使用Poetry示例

采用多阶段构建，从pyproject.toml导出依赖：

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-fastapi: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

高级配置

环境变量

通过环境变量调整容器配置，以下为主要参数及默认值：

示例：指定自定义模块和变量名

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

自定义Gunicorn配置文件

镜像默认配置文件位于/gunicorn_conf.py，可通过以下路径覆盖：

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

配置文件示例（参考基础镜像配置）：

python
import multiprocessing
import os

workers_per_core_str = os.getenv("WORKERS_PER_CORE", "1")
max_workers_str = os.getenv("MAX_WORKERS")
use_max_workers = None
if max_workers_str:
    use_max_workers = int(max_workers_str)
web_concurrency_str = os.getenv("WEB_CONCURRENCY", None)

host = os.getenv("HOST", "0.0.0.0")
port = os.getenv("PORT", "80")
bind_env = os.getenv("BIND", None)
use_loglevel = os.getenv("LOG_LEVEL", "info")
if bind_env:
    bind = bind_env
else:
    bind = f"{host}:{port}"

...

自定义prestart.sh脚本

创建/app/prestart.sh可在应用启动前执行命令（如数据库迁移）。示例：

bash
#!/usr/bin/env bash

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

确保脚本有执行权限，Dockerfile中可添加：

Dockerfile
RUN chmod +x /app/prestart.sh

开发环境热重载

使用/start-reload.sh脚本可实现开发时代码变更自动重启（仅单进程Uvicorn，无Gunicorn）：

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

• -v $(pwd):/app：挂载当前目录到容器/app，实现代码实时同步。
• /start-reload.sh：替换默认启动命令，启用热重载。

Docker部署方案示例

基础部署（已弃用，仅作参考）

bash
# 构建镜像
docker build -t my-fastapi-app .

# 运行容器，自定义工作进程数和端口
docker run -d \
  --name my-fastapi-container \
  -p 8000:80 \
  -e WEB_CONCURRENCY=4 \
  -e LOG_LEVEL=warning \
  my-fastapi-app

docker-compose配置（已弃用，仅作参考）

yaml
version: '3'

services:
  fastapi:
    build: .
    image: my-fastapi-app
    ports:
      - "8000:80"
    environment:
      - MODULE_NAME=app.main
      - VARIABLE_NAME=app
      - WORKERS_PER_CORE=2
      - MAX_WORKERS=8
      - LOG_LEVEL=info
    volumes:
      - ./app:/app  # 开发环境挂载代码
    command: /start-reload.sh  # 开发环境热重载