tiangolo/meinheld-gunicorn-flask

meinheld-gunicorn-flask

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

GitHub仓库：https://github.com/tiangolo/meinheld-gunicorn-flask-docker
Docker Hub镜像：https://hub.docker.com/r/tiangolo/meinheld-gunicorn-flask/

支持的标签及对应Dockerfile链接

• https://github.com/tiangolo/meinheld-gunicorn-flask-docker/blob/master/docker-images/python3.9.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

---

注意：存在https://hub.docker.com/r/tiangolo/meinheld-gunicorn-flask/tags%E3%80%82%E8%8B%A5%E9%9C%80%E5%9B%BA%E5%AE%9ADocker%E9%95%9C%E5%83%8F%E7%89%88%E6%9C%AC%EF%BC%8C%E5%8F%AF%E9%80%89%E6%8B%A9%E6%AD%A4%E7%B1%BB%E6%A0%87%E7%AD%BE%EF%BC%8C%E4%BE%8B%E5%A6%82%60tiangolo/meinheld-gunicorn-flask:python3.9-2024-11-02%60%E3%80%82

概述

运行在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的https://github.com/tiangolo/fastapi%EF%BC%8C%E8%80%8C%E9%9D%9EFlask%E5%92%8CDjango%E4%BD%BF%E7%94%A8%E7%9A%84WSGI%EF%BC%89%EF%BC%8C%E6%90%AD%E9%85%8D%E9%95%9C%E5%83%8Fhttps://github.com/tiangolo/uvicorn-gunicorn-fastapi-docker%EF%BC%8C%E6%80%A7%E8%83%BD%E7%BA%A6%E4%B8%BA%E6%9C%AC%E9%95%9C%E5%83%8F%E7%9A%84200%25%E3%80%82%E6%AD%A4%E5%A4%96%EF%BC%8CASGI%E6%A1%86%E6%9E%B6%E5%8E%9F%E7%94%9F%E6%94%AF%E6%8C%81%E5%BC%82%E6%AD%A5%E4%BB%A3%E7%A0%81%EF%BC%8C%E6%9B%B4%E6%98%93%E5%AE%9E%E7%8E%B0WebSocket%E7%AD%89%E5%8A%9F%E8%83%BD%E3%80%82

技术细节

Meinheld

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

Gunicorn

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

Flask

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

替代方案

本镜像作为https://github.com/tiangolo/uwsgi-nginx-flask-docker%E7%9A%84%E6%9B%BF%E4%BB%A3%E6%96%B9%E6%A1%88%EF%BC%8C%E6%80%A7%E8%83%BD%E7%BA%A6%E4%B8%BA%E5%85%B6400%25%E3%80%82%E5%9F%BA%E4%BA%8E%E9%80%9A%E7%94%A8%E9%95%9C%E5%83%8Fhttps://github.com/tiangolo/meinheld-gunicorn-docker%E6%9E%84%E5%BB%BA%EF%BC%8C%E5%90%8E%E8%80%85%E9%80%82%E7%94%A8%E4%BA%8EDjango%E7%AD%89%E5%85%B6%E4%BB%96WSGI%E6%A1%86%E6%9E%B6%E3%80%82

🚨 警告：您可能不需要此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 https://github.com/tiangolo/meinheld-gunicorn-flask-docker/pull/169 by https://github.com/apps/dependabot。
• ⬆ 将flask从3.0.3升级到3.1.0。PR https://github.com/tiangolo/meinheld-gunicorn-flask-docker/pull/167 by https://github.com/apps/dependabot。
• ⬆ 将flask从2.2.5升级到3.0.3。PR https://github.com/tiangolo/meinheld-gunicorn-flask-docker/pull/147 by https://github.com/apps/dependabot。
• 🔥 移除对Python 3.7和3.8的支持。PR https://github.com/tiangolo/meinheld-gunicorn-flask-docker/pull/164 by https://github.com/tiangolo%E3%80%82
• ⬆ 将gunicorn从22.0.0升级到23.0.0。PR https://github.com/tiangolo/meinheld-gunicorn-flask-docker/pull/152 by https://github.com/apps/dependabot。
• ⬆ 将gunicorn从20.1.0升级到22.0.0。PR https://github.com/tiangolo/meinheld-gunicorn-flask-docker/pull/149 by https://github.com/apps/dependabot。

内部优化

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