meinheld-gunicorn

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

支持的标签及对应Dockerfile链接

• python3.9, latest (Dockerfile)

已弃用标签

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

• python3.9-alpine3.13
• python3.8
• python3.8-alpine3.11
• python3.7
• python3.7-alpine3.8
• python3.6
• python3.6-alpine3.8
• python2.7

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

• python3.9-alpine3.13-2024-03-11
• python3.8-2024-11-02
• python3.8-alpine3.11-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
• python2.7-2022-11-25

---

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

镜像概述

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

GitHub仓库：[***]

Docker Hub镜像：[***]

核心功能与特性

高性能WSGI应用支持

运行在Meinheld并由Gunicorn控制的Python Web应用，基于WSGI（同步代码，非异步ASGI），可实现（旧版）Python框架中的最佳性能之一。

适用于Flask和Django等框架。对于已有的Flask、Django等应用，此镜像可提供接近最佳的性能。

自动调优机制

内置“自动调优”机制，只需添加代码即可自动获得良好性能，且无需牺牲日志等功能。

Python 3.10和3.11的注意事项

当前发布的Meinheld最新版本为1.0.2（2020年5月17日），该版本依赖旧版Greenlet（>=0.4.5,<0.5），与Python 3.10和3.11不兼容。因此，本镜像支持的最新Python版本为Python 3.9。

* 性能与特性说明

如果正在启动新项目，可能会受益于更新更快的框架，如FastAPI（基于ASGI而非WSGI），以及类似tiangolo/uvicorn-gunicorn-fastapi的Docker镜像。其性能约为旧版WSGI框架（如Flask或Django）的200%，即使使用本镜像也是如此。此外，若需使用WebSocket等新技术，基于ASGI的框架（如FastAPI）更易实现，因为ASGI标准设计用于处理WebSocket所需的异步代码。

技术细节

Meinheld

Meinheld是高性能的WSGI兼容Web服务器。

Gunicorn

可使用Gunicorn管理Meinheld并运行多个进程。

替代方案

本镜像作为tiangolo/uwsgi-nginx的替代方案创建，性能约为该镜像的400%，并作为tiangolo/meinheld-gunicorn-flask的基础镜像。

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

如果正在使用Kubernetes或类似工具，可能不需要此镜像（或任何其他类似基础镜像），更建议从头构建Docker镜像。

---

如果有Kubernetes、Docker Swarm Mode、Nomad或其他类似复杂系统管理多台机器上的分布式容器，可能希望在集群级别处理复制，而非在每个容器中使用进程管理器启动多个工作进程（本Docker镜像的功能）。

在这些情况下（如使用Kubernetes），建议从头构建Docker镜像，安装依赖并运行单个进程。例如，使用Gunicorn，创建app/gunicorn_conf.py文件：

# Gunicorn配置变量
loglevel = "info"
errorlog = "-"  # stderr
accesslog = "-"  # stdout
worker_tmp_dir = "/dev/shm"
graceful_timeout = 120
timeout = 120
keepalive = 5
threads = 3

然后创建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 ["gunicorn", "--conf", "app/gunicorn_conf.py", "--bind", "0.0.0.0:80", "app.main:app"]

更多信息参见FastAPI文档：容器中的FastAPI - Docker，同样适用于其他Web应用容器。

使用场景

简单应用

如果应用足够简单，无需过多微调进程数，且运行在单台服务器（非集群），本镜像可提供自动调优的多进程管理。

Docker Compose

若使用Docker Compose部署到单台服务器（非集群），且难以在集群级别管理容器复制和负载均衡，可使用本镜像在单个容器中通过进程管理器启动多个工作进程。

Prometheus及其他原因

可能因其他原因需要单容器多进程而非多容器单进程，例如（取决于设置）Prometheus exporter需在同一容器中收集所有内部进程的请求指标，此时单容器多进程可简化指标收集。

---

更多信息参见FastAPI文档：容器中的FastAPI - Docker，同样适用于其他Web应用容器。

使用方法

无需克隆本仓库，可将其作为其他镜像的基础镜像。

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

FROM tiangolo/meinheld-gunicorn:python3.9

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

构建镜像命令：

docker build -t myimage ./

高级用法

环境变量

可设置以下环境变量配置容器，默认值如下：

MODULE_NAME

Gunicorn导入的Python模块（文件），包含应用变量。默认：若/app/app/main.py存在则为app.main，若/app/main.py存在则为main。

示例：若主文件为/app/custom_app/custom_main.py，设置：

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

VARIABLE_NAME

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

示例：若主Python文件包含：

from flask import Flask
api = Flask(__name__)

@api.route("/")
def hello():
    return "Hello World from Flask"

设置：

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核心数自动设置工作进程数，为核心数乘以该值。默认：2。

示例：2核服务器设置3，则运行6个工作进程：

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

支持浮点值，如8核服务器设置0.5，则启动4个工作进程：

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

WEB_CONCURRENCY

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

示例：强制启动2个工作进程：

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

HOST

Gunicorn监听请求的IP（容器内）。默认：0.0.0.0（不建议修改）。

PORT

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

示例：使用8080端口：

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。

示例：牺牲日志换取性能，设置为warning：

docker run -d -p 80:8080 -e LOG_LEVEL="warning" 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迁移（SQLAlchemy），创建./app/prestart.sh：

#! /usr/bin/env bash

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

或运行Python脚本：

#! /usr/bin/env bash

# 启动前运行自定义Python脚本
python /app/my_custom_prestart_script.py

🚨 Alpine Python警告

简而言之：Python项目可能不应使用Alpine，建议使用slim Docker镜像版本。

---

Alpine更适用于其他语言（如Go），通过多阶段构建生成静态二进制文件后复制到Alpine镜像执行。但Python中，Alpine不使用构建Python扩展的标准工具，安装包时pip常无法找到Alpine的预编译包（wheel），需安装大量额外工具构建依赖，导致最终镜像大小可能与基于Debian的标准Python镜像相当甚至更大，且构建时间更长、资源消耗更多、碳足迹增加。如需精简Python镜像，建议使用基于Debian的slim版本。

测试

所有镜像标签、配置、环境变量和应用选项均经过测试。

发布说明

最新变更

• 🔥 移除对Python 3.7和3.8的支持。PR #138 by @tiangolo。

特性

• 👷 通过PYTHONDONTWRITEBYTECODE=1避免创建不必要的*.pyc文件，PYTHONUNBUFFERED=1确保日志立即打印。PR #109 by @estebanx64。

重构

• ♻️ 默认不添加EXPOSE 80，因端口可更改。PR #128 by @tiangolo。

内部

• ⬆ Bump tiangolo/latest-changes from 0.3.1 to 0.3.2。PR #140 by [@dependabot[bot]]([***]
• 🔥 移除未使用文件。PR #139 by @tiangolo。
• ⬆ Bump tiangolo/issue-manager from 0.5.0 to 0.5.1。PR #137 by [@dependabot[bot]]([***]
• ⬆ Bump gunicorn from 22.0.0 to 23.0.0。PR #125 by [@dependabot[bot]]([***]
• ⬆ Bump docker/build-push-action from 5 to 6。PR #123 by [@dependabot[bot]]([***]
• 👷 更新issue-manager.yml。PR #127 by @tiangolo。
• 👷 更新latest-changes GitHub Action。PR #126 by @tiangolo。
• 👷 更新issue-manager.yml GitHub Action权限。PR