tiangolo/uvicorn-gunicorn-fastapi

uvicorn-gunicorn-fastapi Docker镜像文档

⚠️ 已弃用 (DEPRECATED)

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

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

---

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

支持的标签及对应Dockerfile链接

• https://github.com/tiangolo/uvicorn-gunicorn-fastapi-docker/blob/master/docker-images/python3.11.dockerfile
• https://github.com/tiangolo/uvicorn-gunicorn-fastapi-docker/blob/master/docker-images/python3.10.dockerfile
• https://github.com/tiangolo/uvicorn-gunicorn-fastapi-docker/blob/master/docker-images/python3.9.dockerfile
• https://github.com/tiangolo/uvicorn-gunicorn-fastapi-docker/blob/master/docker-images/python3.11-slim.dockerfile
• https://github.com/tiangolo/uvicorn-gunicorn-fastapi-docker/blob/master/docker-images/python3.10-slim.dockerfile
• https://github.com/tiangolo/uvicorn-gunicorn-fastapi-docker/blob/master/docker-images/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

---

注意：存在https://hub.docker.com/r/tiangolo/uvicorn-gunicorn-fastapi/tags%E3%80%82%E5%A6%82%E6%9E%9C%E9%9C%80%E8%A6%81%22%E5%9B%BA%E5%AE%9A%22%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%E8%BF%99%E4%BA%9B%E6%A0%87%E7%AD%BE%E3%80%82%E4%BE%8B%E5%A6%82%EF%BC%9A%60tiangolo/uvicorn-gunicorn-fastapi:python3.11-2024-11-02%60%E3%80%82

镜像概述和主要用途

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或类似工具，通常不需要此镜像（或任何其他类似基础镜像）。建议按照https://fastapi.tiangolo.com/deployment/docker/#replication-number-of-processes%E4%B8%AD%E7%9A%84%E8%AF%B4%E6%98%8E**%E4%BB%8E%E9%9B%B6%E6%9E%84%E5%BB%BADocker%E9%95%9C%E5%83%8F**%E3%80%82

集群副本管理

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

多工作进程

若需在单容器内启动多工作进程，Uvicorn已支持直接管理子进程（包括重启异常进程），无需Gunicorn。可在Dockerfile中使用--workers参数：

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

技术细节

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

遗留文档

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

tiangolo/uvicorn-gunicorn基础

本镜像（tiangolo/uvicorn-gunicorn-fastapi）基于https://github.com/tiangolo/uvicorn-gunicorn-docker%EF%BC%8C%E5%90%8E%E8%80%85%E5%AE%9E%E7%8E%B0%E4%BA%86%E6%A0%B8%E5%BF%83%E7%9A%84Uvicorn+Gunicorn%E7%AE%A1%E7%90%86%E9%80%BB%E8%BE%91%E3%80%82%E6%9C%AC%E9%95%9C%E5%83%8F%E4%BB%85%E9%A2%9D%E5%A4%96%E5%AE%89%E8%A3%85%E4%BA%86FastAPI%EF%BC%8C%E5%B9%B6%E9%92%88%E5%AF%B9FastAPI%E6%8F%90%E4%BE%9B%E6%96%87%E6%A1%A3%E3%80%82%E8%8B%A5%E6%82%A8%E7%86%9F%E6%82%89Uvicorn%E3%80%81Gunicorn%E5%92%8CASGI%EF%BC%8C%E5%8F%AF%E7%9B%B4%E6%8E%A5%E4%BD%BF%E7%94%A8tiangolo/uvicorn-gunicorn%E3%80%82

与tiangolo/uvicorn-gunicorn-starlette的关系

存在 sibling 镜像https://github.com/tiangolo/uvicorn-gunicorn-starlette-docker%EF%BC%8C%E9%80%82%E7%94%A8%E4%BA%8E%E7%BA%AFStarlette%E5%BA%94%E7%94%A8%EF%BC%88%E4%B8%8D%E5%90%ABFastAPI%E7%9A%84%E9%A2%9D%E5%A4%96%E5%8A%9F%E8%83%BD%E5%A6%82%E6%95%B0%E6%8D%AE%E9%AA%8C%E8%AF%81%E3%80%81OpenAPI%E6%96%87%E6%A1%A3%E7%AD%89%EF%BC%89%E3%80%82

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

基础使用

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

Dockerfile
FROM docker.xuanyuan.run/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 docker.xuanyuan.run/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 docker.xuanyuan.run/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 docker.xuanyuan.run/myimage

验证应用

访问http://127.0.0.1/items/5?q=somequery，应返回：

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

访问http://127.0.0.1/docs查看Swagger UI文档，http://127.0.0.1/redoc查看ReDoc文档。

依赖管理

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

使用Poetry示例

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

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/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" docker.xuanyuan.run/myimage

自定义Gunicorn配置文件

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

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

配置文件示例（参考https://github.com/tiangolo/uvicorn-gunicorn-docker/blob/master/docker-images/gunicorn_conf.py%EF%BC%89%EF%BC%9A

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 docker.xuanyuan.run/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 \
  docker.xuanyuan.run/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  # 开发环境热重载