tiangolo/meinheld-gunicorn

meinheld-gunicorn

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

支持的标签及对应Dockerfile链接

• https://github.com/tiangolo/meinheld-gunicorn-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-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

---

注意：有https://hub.docker.com/r/tiangolo/meinheld-gunicorn/tags%E3%80%82%E5%A6%82%E6%9E%9C%E9%9C%80%E8%A6%81%E2%80%9C%E5%9B%BA%E5%AE%9A%E2%80%9D%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 tiangolo/meinheld-gunicorn:python3.9-2024-11-02。

镜像概述

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

GitHub仓库：https://github.com/tiangolo/meinheld-gunicorn-docker

Docker Hub镜像：https://hub.docker.com/r/tiangolo/meinheld-gunicorn/

核心功能与特性

高性能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。

* 性能与特性说明

如果正在启动新项目，可能会受益于更新更快的框架，如https://github.com/tiangolo/fastapi%EF%BC%88%E5%9F%BA%E4%BA%8EASGI%E8%80%8C%E9%9D%9EWSGI%EF%BC%89%EF%BC%8C%E4%BB%A5%E5%8F%8A%E7%B1%BB%E4%BC%BChttps://github.com/tiangolo/uvicorn-gunicorn-fastapi-docker%E7%9A%84Docker%E9%95%9C%E5%83%8F%E3%80%82%E5%85%B6%E6%80%A7%E8%83%BD%E7%BA%A6%E4%B8%BA%E6%97%A7%E7%89%88WSGI%E6%A1%86%E6%9E%B6%EF%BC%88%E5%A6%82Flask%E6%88%96Django%EF%BC%89%E7%9A%84200%25%EF%BC%8C%E5%8D%B3%E4%BD%BF%E4%BD%BF%E7%94%A8%E6%9C%AC%E9%95%9C%E5%83%8F%E4%B9%9F%E6%98%AF%E5%A6%82%E6%AD%A4%E3%80%82%E6%AD%A4%E5%A4%96%EF%BC%8C%E8%8B%A5%E9%9C%80%E4%BD%BF%E7%94%A8WebSocket%E7%AD%89%E6%96%B0%E6%8A%80%E6%9C%AF%EF%BC%8C%E5%9F%BA%E4%BA%8EASGI%E7%9A%84%E6%A1%86%E6%9E%B6%EF%BC%88%E5%A6%82**FastAPI**%EF%BC%89%E6%9B%B4%E6%98%93%E5%AE%9E%E7%8E%B0%EF%BC%8C%E5%9B%A0%E4%B8%BAASGI%E6%A0%87%E5%87%86%E8%AE%BE%E8%AE%A1%E7%94%A8%E4%BA%8E%E5%A4%84%E7%90%86WebSocket%E6%89%80%E9%9C%80%E7%9A%84%E5%BC%82%E6%AD%A5%E4%BB%A3%E7%A0%81%E3%80%82

技术细节

Meinheld

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

Gunicorn

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

替代方案

本镜像作为https://github.com/tiangolo/uwsgi-nginx-docker%E7%9A%84%E6%9B%BF%E4%BB%A3%E6%96%B9%E6%A1%88%E5%88%9B%E5%BB%BA%EF%BC%8C%E6%80%A7%E8%83%BD%E7%BA%A6%E4%B8%BA%E8%AF%A5%E9%95%9C%E5%83%8F%E7%9A%84400%25%EF%BC%8C%E5%B9%B6%E4%BD%9C%E4%B8%BAhttps://github.com/tiangolo/meinheld-gunicorn-flask-docker%E7%9A%84%E5%9F%BA%E7%A1%80%E9%95%9C%E5%83%8F%E3%80%82

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

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

---

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

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

Python
# Gunicorn配置变量
loglevel = "info"
errorlog = "-"  # stderr
accesslog = "-"  # stdout
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 exporter需在同一容器中收集所有内部进程的请求指标，此时单容器多进程可简化指标收集。

---

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

使用方法

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

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

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

构建镜像命令：

bash
docker build -t myimage ./

高级用法

环境变量

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

MODULE_NAME

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

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

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

VARIABLE_NAME

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

示例：若主Python文件包含：

Python
from flask import Flask
api = Flask(__name__)

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

设置：

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

APP_MODULE

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

示例：

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

示例：

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

WORKERS_PER_CORE

根据服务器CPU核心数自动设置工作进程数，为核心数乘以该值。默认：2。

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

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核默认4）。

示例：强制启动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。

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

bash
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：

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项目可能不应使用Alpine，建议使用slim Docker镜像版本。

---

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

测试

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

发布说明

最新变更

• 🔥 移除对Python 3.7和3.8的支持。PR https://github.com/tiangolo/meinheld-gunicorn-docker/pull/138 by https://github.com/tiangolo%E3%80%82

特性

• 👷 通过PYTHONDONTWRITEBYTECODE=1避免创建不必要的*.pyc文件，PYTHONUNBUFFERED=1确保日志立即打印。PR https://github.com/tiangolo/meinheld-gunicorn-docker/pull/109 by https://github.com/estebanx64%E3%80%82

重构

• ♻️ 默认不添加EXPOSE 80，因端口可更改。PR https://github.com/tiangolo/meinheld-gunicorn-docker/pull/128 by https://github.com/tiangolo%E3%80%82

内部

• ⬆ Bump tiangolo/latest-changes from 0.3.1 to 0.3.2。PR https://github.com/tiangolo/meinheld-gunicorn-docker/pull/140 by https://github.com/apps/dependabot。
• 🔥 移除未使用文件。PR https://github.com/tiangolo/meinheld-gunicorn-docker/pull/139 by https://github.com/tiangolo%E3%80%82
• ⬆ Bump tiangolo/issue-manager from 0.5.0 to 0.5.1。PR https://github.com/tiangolo/meinheld-gunicorn-docker/pull/137 by https://github.com/apps/dependabot。
• ⬆ Bump gunicorn from 22.0.0 to 23.0.0。PR https://github.com/tiangolo/meinheld-gunicorn-docker/pull/125 by https://github.com/apps/dependabot。
• ⬆ Bump docker/build-push-action from 5 to 6。PR https://github.com/tiangolo/meinheld-gunicorn-docker/pull/123 by https://github.com/apps/dependabot。
• 👷 更新issue-manager.yml。PR https://github.com/tiangolo/meinheld-gunicorn-docker/pull/127 by https://github.com/tiangolo%E3%80%82
• 👷 更新latest-changes GitHub Action。PR https://github.com/tiangolo/meinheld-gunicorn-docker/pull/126 by https://github.com/tiangolo%E3%80%82
• 👷 更新issue-manager.yml GitHub Action权限。PR