uvicorn-gunicorn-readyapi

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

支持的标签及对应Dockerfile链接

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

已弃用标签

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

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

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

• 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镜像版本，可以选择这些标签。例如 khulnasoft/uvicorn-gunicorn-readyapi:python3.7-2019-10-15。

镜像概述和主要用途

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

GitHub仓库：[***]

Docker Hub镜像：[***]

核心功能和特性

ReadyAPI性能优势

ReadyAPI基于Starlette构建，经第三方基准测试显示，其性能与Go和Node.js框架相当，在许多情况下甚至更优。

自动调优机制

镜像包含自动调优机制，可根据可用CPU核心数启动相应数量的工作进程，无需手动配置即可获得高性能，适用于简单部署场景。

技术组件

• Uvicorn：闪电般快速的"ASGI"服务器，在单个进程中运行异步Python Web代码。
• Gunicorn：用于启动和管理多个Uvicorn工作进程，在简单部署中兼顾并发和并行性能。
• ReadyAPI：现代、快速（高性能）的Python API构建框架，具备数据验证、转换、OpenAPI文档、依赖注入等功能。

使用场景和适用范围

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

如果你使用Kubernetes或类似工具，可能不需要此镜像（或任何其他类似基础镜像）。建议按照ReadyAPI容器文档 - Docker：为ReadyAPI构建Docker镜像中的说明从头构建Docker镜像。

---

如果你的机器集群使用Kubernetes、Docker Swarm Mode、Nomad或其他类似复杂系统来管理多台机器上的分布式容器，你可能希望在集群级别处理复制，而不是在每个容器中使用进程管理器（如Gunicorn与Uvicorn工作进程），这正是此Docker镜像的作用。

在这些情况下（例如使用Kubernetes），你可能需要从头构建Docker镜像，安装依赖，并运行单个Uvicorn进程而非此镜像。例如，你的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"]

更多信息请参阅ReadyAPI文档：ReadyAPI容器 - Docker。

何时使用此Docker镜像

简单应用

如果你的应用足够简单，无需过多微调进程数量，仅需自动默认配置，且运行在单台服务器而非集群上，可使用此镜像。

Docker Compose部署

如果你通过Docker Compose部署到单台服务器（非集群），且希望在保留共享网络和负载均衡的同时，通过单个容器中的Gunicorn进程管理器启动多个Uvicorn工作进程，此镜像适用。

Prometheus等特殊需求

如果你需要单个容器运行多个进程（而非多个容器各运行一个进程），例如：在同一容器中运行Prometheus exporter以收集所有内部进程的指标并通过单个容器暴露，此镜像可简化配置。

---

更多信息请参阅ReadyAPI文档：ReadyAPI容器 - Docker。

技术细节

与其他镜像的关系

• khulnasoft/uvicorn-gunicorn：此镜像（khulnasoft/uvicorn-gunicorn-readyapi）基于khulnasoft/uvicorn-gunicorn构建，后者提供核心功能，此镜像额外安装ReadyAPI并针对ReadyAPI提供文档。
• khulnasoft/uvicorn-gunicorn-starlette：如果你创建新的Starlette应用且无需ReadyAPI的额外功能，应使用khulnasoft/uvicorn-gunicorn-starlette。注意：ReadyAPI基于Starlette构建，添加了数据验证、OpenAPI文档等API开发功能。

使用方法和配置说明

基本用法

无需克隆GitHub仓库，可将此镜像用作其他镜像的基础镜像。假设你有requirements.txt文件，Dockerfile可如下：

FROM khulnasoft/uvicorn-gunicorn-readyapi: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的ReadyAPI应用变量。

快速启动

构建镜像

1. 进入项目目录。
2. 创建Dockerfile：

   FROM khulnasoft/uvicorn-gunicorn-readyapi:python3.11
   
   COPY ./requirements.txt /app/requirements.txt
   
   RUN pip install --no-cache-dir --upgrade -r /app/requirements.txt
   
   COPY ./app /app
   

3. 创建app目录并进入，创建main.py：

   from readyapi import ReadyAPI
   
   app = ReadyAPI()
   
   
   @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}
   

4. 目录结构应如下：

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

5. 构建镜像：

   docker build -t myimage ./
   

运行容器

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

验证应用

访问Docker主机的URL（如[***]），将看到响应：

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

交互式API文档

• Swagger UI：访问[***]，查看自动交互式API文档。
• ReDoc：访问[***]，查看替代自动文档。

依赖和包管理

使用requirements.txt

通过requirements.txt安装依赖，确保固定版本以保证应用稳定性。

使用Poetry

使用Poetry管理依赖时，可通过多阶段构建安装：

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 khulnasoft/uvicorn-gunicorn-readyapi: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

高级配置：环境变量

MODULE_NAME

Gunicorn导入的Python"模块"（文件），包含应用变量。默认：

• 若存在/app/app/main.py，则为app.main
• 若存在/app/main.py，则为main

示例：

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

VARIABLE_NAME

Python模块中包含ReadyAPI应用的变量名。默认：app

示例：

docker run -d -p 80:80 -e VARIABLE_NAME="api" myimage

APP_MODULE

传递给Gunicorn的Python模块和变量名字符串。默认基于MODULE_NAME和VARIABLE_NAME（如app.main:app或main:app）

示例：

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（内置默认配置）

示例：

docker run -d -p 80:80 -e GUNICORN_CONF="/app/custom_gunicorn_conf.py" myimage

WORKERS_PER_CORE

每CPU核心的工作进程数，默认：1。可使用浮点值，例如0.5（8核服务器运行4个进程）。

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

示例：

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

MAX_WORKERS

最大工作进程数，默认无限制。

示例：

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

WEB_CONCURRENCY

覆盖自动计算的工作进程数，默认：CPU核心数 × WORKERS_PER_CORE。

示例：

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

HOST

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

PORT

容器监听端口，默认：80。

示例：

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

BIND

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

示例：

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

LOG_LEVEL

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

示例：

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

WORKER_CLASS

Gunicorn工作进程类，默认：uvicorn.workers.UvicornWorker（不建议修改）。

TIMEOUT

工作进程静默超时秒数（超时后重启），默认：120。

示例：

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

KEEP_ALIVE

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

示例：

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

GRACEFUL_TIMEOUT

工作进程优雅重启超时秒数，默认：120。

示例：

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

ACCESS_LOG

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

示例：

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

ERROR_LOG

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

示例：

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

GUNICORN_CMD_ARGS

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

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

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

注意：建议使用" TLS终止代理"（如[Traefik]([***]