tiangolo/meinheld-gunicorn-flask Docker 镜像 - 轩辕镜像 | Docker 镜像高效稳定拉取服务

meinheld-gunicorn-flask

Docker镜像，集成Meinheld（由Gunicorn管理），为基于Flask的Python Web应用提供高性能运行环境，支持自动性能调优。

GitHub仓库：[]
Docker Hub镜像：[]

支持的标签及对应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-10-28
• python3.8-alpine3.11-2024-03-11
• python3.7-2024-10-28
• 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-flask:python3.9-2024-11-02。

概述

运行在Meinheld（由Gunicorn管理）上的Python Flask Web应用具有Flask可实现的最佳性能之一。无论您是已有Flask应用还是新建应用，此镜像都能提供接近最优的性能，且无需牺牲日志等功能，内置“自动调优”机制。

Python 3.10和3.11注意事项

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

* 关于性能和特性的说明

若您正在启动新项目，建议考虑更新、更快的框架（如基于ASGI的FastAPI，而非Flask和Django使用的WSGI），搭配镜像tiangolo/uvicorn-gunicorn-fastapi，性能约为本镜像的200%。此外，ASGI框架原生支持异步代码，更易实现WebSocket等功能。

技术细节

Meinheld

高性能WSGI兼容Web服务器，负责处理HTTP请求。

Gunicorn

进程管理器，用于管理Meinheld并运行多个进程，提升并发处理能力。

Flask

基于Werkzeug、Jinja 2的Python微框架，简洁轻量，适合构建Web应用。

替代方案

本镜像作为tiangolo/uwsgi-nginx-flask的替代方案，性能约为其400%。基于通用镜像tiangolo/meinheld-gunicorn构建，后者适用于Django等其他WSGI框架。

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

若您使用Kubernetes或类似工具，可能不需要此镜像（或任何类似基础镜像），建议从零构建Docker镜像。

---

在Kubernetes、Docker Swarm Mode、Nomad等分布式容器管理系统中，应在集群层面处理副本管理，而非在每个容器中使用进程管理器启动多个工作进程（本镜像的核心功能）。此类场景下，自建镜像并运行单个进程更为合适。

例如，使用Gunicorn时，可创建app/gunicorn_conf.py文件：

python
# Gunicorn配置变量
loglevel = "info"
errorlog = "-"  # 标准错误输出
accesslog = "-"  # 标准输出
worker_tmp_dir = "/dev/shm"
graceful_timeout = 120
timeout = 120
keepalive = 5
threads = 3

对应的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 ["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监控）时，本镜像的多进程模式便于本地工具（如Prometheus exporter）汇总所有内部进程指标并暴露。

---

更多细节参见FastAPI文档：容器中的FastAPI - Docker。

使用方法

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

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

dockerfile
FROM tiangolo/meinheld-gunicorn-flask: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应用变量。

构建镜像：

bash
docker build -t myimage ./

环境变量

以下环境变量可配置容器行为，均有默认值：

MODULE_NAME

Gunicorn导入的Python模块路径。默认：若/app/app/main.py存在则为app.main，否则为main。

示例：

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

VARIABLE_NAME

模块中WSGI应用变量名。默认：app。

示例（应用变量名为api时）：

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

APP_MODULE

传递给Gunicorn的模块和变量名，默认由MODULE_NAME和VARIABLE_NAME组合（如app.main:app）。

示例：

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

GUNICORN_CONF

Gunicorn配置文件路径。默认：若/app/gunicorn_conf.py或/app/app/gunicorn_conf.py存在则使用，否则使用/gunicorn_conf.py（内置默认配置）。

示例：

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

WORKERS_PER_CORE

每CPU核心的工作进程数乘数，默认：2。自动根据服务器CPU核心数计算工作进程数（核心数×此值）。

示例（3倍核心数）：

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

支持浮点值（如8核服务器使用0.5倍，即4个进程）：

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

WEB_CONCURRENCY

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

示例（固定2个进程）：

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

HOST

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

PORT

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

示例（使用8080端口）：

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

BIND

Gunicorn绑定的地址和端口，默认由HOST和PORT组合（如0.0.0.0:80）。

示例：

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

LOG_LEVEL

Gunicorn日志级别，可选：debug、info、warning、error、critical，默认：info。日志输出到容器的stderr和stdout，可通过docker logs -f 容器名查看。

示例（降低日志级别以提升性能）：

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

自定义Gunicorn配置文件

镜像内置默认配置文件/gunicorn_conf.py，基于上述环境变量动态配置。可通过以下路径的文件覆盖：

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

自定义/app/prestart.sh

需在启动应用前执行命令时，可在/app目录添加prestart.sh脚本，镜像将自动在启动前运行。

示例（执行Alembic数据库迁移）：

bash
#! /usr/bin/env bash

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

执行Python脚本示例：

bash
#! /usr/bin/env bash

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

Alpine Python警告

简而言之：Python项目应优先使用slim版本Docker镜像，而非Alpine。

---

Alpine适用于通过多阶段构建生成静态二进制文件的语言（如Go），但Python扩展依赖标准构建工具，Alpine通常缺乏预编译包（wheel），需安装大量工具手动构建依赖，导致镜像体积与Debian-based镜像相当甚至更大，且构建时间更长、资源消耗更高。若需精简镜像，建议使用基于Debian的slim版本。

测试

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

发布说明

最新变更

升级

• ⬆ 将flask从3.1.0升级到3.1.1。PR #169 by [@dependabot[bot]]([***]
• ⬆ 将flask从3.0.3升级到3.1.0。PR #167 by [@dependabot[bot]]([***]
• ⬆ 将flask从2.2.5升级到3.0.3。PR #147 by [@dependabot[bot]]([***]
• 🔥 移除对Python 3.7和3.8的支持。PR #164 by @tiangolo。
• ⬆ 将gunicorn从22.0.0升级到23.0.0。PR #152 by [@dependabot[bot]]([***]
• ⬆ 将gunicorn从20.1.0升级到22.0.0。PR #149 by [@dependabot[bot]]([***]

内部优化

• ⬆ 将tiangolo/latest-changes从0.3.1升级到0.3.2。PR #166 by [@dependabot[bot]]([***]
• 🔥 移除旧无用文件。PR #165 by @tiangolo。
• ⬆ 将tiangolo/issue-manager从0.5.0升级到0.5.1。PR #163 by [@dependabot[bot]]([***]
• ⬆ 将docker/build-push-action从5升级到6。PR #150 by [@dependabot[bot]]([***]
• 👷 更新issue-manager.yml。PR #154 by @tiangolo。
• 👷 更新latest-changes GitHub Action。PR #153 by @tiangolo。
• 👷 更新issue-manager.yml GitHub Action权限。PR #151 by @tiangolo。
• Bump gunicorn from 20.1.0 to 22.0.0 in /docker-images. PR #148 by [@dependabot[bot]]([***]
• ⬆ 将docker/build-push-action从2升级到5。PR [#144]([***]