tiangolo/uwsgi-nginx

支持的标签及对应Dockerfile链接

• https://github.com/tiangolo/uwsgi-nginx-docker/blob/master/docker-images/python3.12.dockerfile
• https://github.com/tiangolo/uwsgi-nginx-docker/blob/master/docker-images/python3.11.dockerfile
• https://github.com/tiangolo/uwsgi-nginx-docker/blob/master/docker-images/python3.10.dockerfile
• https://github.com/tiangolo/uwsgi-nginx-docker/blob/master/docker-images/python3.9.dockerfile

已弃用的标签

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

• python3.8
• python3.8-alpine
• python3.7
• python3.6
• python2.7

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

• python3.8-2024-10-28
• python3.8-alpine-2024-03-11
• python3.7-2024-10-28
• python3.6-2022-11-25
• python2.7-2022-11-25

注意：存在https://hub.docker.com/r/tiangolo/uwsgi-nginx/tags%E3%80%82%E5%A6%82%E6%9E%9C%E9%9C%80%E8%A6%81%22%E5%9B%BA%E5%AE%9A%22%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%EF%BC%9A%60tiangolo/uwsgi-nginx:python3.12-2024-11-02%60%E3%80%82

uwsgi-nginx

Docker镜像，包含uWSGI和Nginx，用于在单个容器中运行Python Web应用（如Flask）。

概述

此Docker镜像允许创建在单个容器中通过uWSGI和Nginx运行的Python Web应用。

uWSGI与Nginx的组合是部署Flask和Django等Python Web应用的常用方式，在行业中广泛应用，可提供良好性能。(*)

该镜像最初设计为https://hub.docker.com/r/tiangolo/uwsgi-nginx-flask/%E7%9A%84%E5%9F%BA%E7%A1%80%E9%95%9C%E5%83%8F%EF%BC%8C%E4%BD%86%E4%B9%9F%E5%8F%AF%E7%94%A8%E4%BD%9C%E4%BB%BB%E4%BD%95%E5%85%B6%E4%BB%96%EF%BC%88%E5%9F%BA%E4%BA%8EWSGI%E7%9A%84%EF%BC%89Python Web应用（如Django）的基础镜像。

* 关于性能和特性的说明

如果启动新项目，使用基于ASGI而非WSGI的更新更快的框架可能更有利（Flask和Django均基于WSGI）。

可使用以下ASGI框架：

• https://github.com/tiangolo/fastapi%EF%BC%88%E5%9F%BA%E4%BA%8EStarlette%EF%BC%89%EF%BC%8C%E9%85%8D%E5%90%88%E6%AD%A4Docker%E9%95%9C%E5%83%8F%EF%BC%9Ahttps://github.com/tiangolo/uvicorn-gunicorn-fastapi-docker%E3%80%82
• https://github.com/encode/starlette%EF%BC%8C%E7%9B%B4%E6%8E%A5%E4%BD%BF%E7%94%A8%E6%AD%A4Docker%E9%95%9C%E5%83%8F%EF%BC%9Ahttps://github.com/tiangolo/uvicorn-gunicorn-starlette-docker%E3%80%82
• 或任何其他ASGI框架，配合此Docker镜像：https://github.com/tiangolo/uvicorn-gunicorn-docker%E3%80%82

FastAPI或Starlette的性能约为此镜像（tiangolo/uwsgi-nginx）的800%（8倍）。可查看第三方基准测试结果。

此外，若需使用WebSocket等新技术，基于ASGI的框架（如FastAPI或Starlette）会更简单（且可行），因为ASGI标准专为处理WebSocket所需的异步代码而设计。

若需使用基于WSGI的应用（如Flask或Django）

如果需要使用Flask或Django等旧版WSGI框架（而非ASGI框架），且追求最佳性能，可使用替代镜像：https://github.com/tiangolo/meinheld-gunicorn-docker%E3%80%82

tiangolo/meinheld-gunicorn的性能约为此镜像的400%（4倍）。

GitHub仓库：https://github.com/tiangolo/uwsgi-nginx-docker

Docker Hub镜像：https://hub.docker.com/r/tiangolo/uwsgi-nginx/

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

你可能正在使用Kubernetes或类似工具。在这种情况下，很可能不需要此镜像（或任何其他类似基础镜像），直接从零构建Docker镜像可能更合适。

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

此类场景（如使用Kubernetes）中，应构建从零开始的Docker镜像，安装依赖，并运行单个进程而非此镜像。

例如，使用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镜像

简单应用

如果应用足够简单，无需（至少目前不需要）精细调整进程数量，可使用默认自动配置，且运行在单台服务器而非集群上，此时容器中运行带多个工作进程的进程管理器是合理的。

Docker Compose

若通过Docker Compose部署到单台服务器（非集群），由于Docker Compose难以在保留共享网络和负载均衡的同时管理容器副本，此时单个容器中通过进程管理器启动多个工作进程是更优选择。

Prometheus及其他原因

也可能因其他原因需要单个容器运行多个进程，而非多个容器各运行单个进程。

例如（取决于具体设置），可能在同一容器中运行Prometheus exporter等工具，需访问每个传入请求。若使用多个容器，Prometheus默认每次仅能获取单个容器的指标，而非所有副本容器的累积指标。此时，单个容器运行多个进程，并通过本地工具（如Prometheus exporter）收集所有内部进程的指标并暴露，会更简单。

更多详情可参考FastAPI文档：容器中的FastAPI - Docker，相关概念同样适用于其他容器中的Web应用。

使用方法

无需克隆此仓库，可直接将其用作其他镜像的基础镜像。

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

Dockerfile
FROM tiangolo/uwsgi-nginx:python3.12

COPY ./requirements.txt /app/requirements.txt

RUN pip install --no-cache-dir --upgrade -r /app/requirements.txt

COPY ./app /app

# 你的Dockerfile代码...

• 默认会在/app/uwsgi.ini查找uWSGI配置文件。
• 该uwsgi.ini文件会尝试运行/app/main.py中的Python文件。

若构建Flask Web应用，建议使用https://hub.docker.com/r/tiangolo/uwsgi-nginx-flask/%E3%80%82

高级用法

自定义应用目录

如需使用非/app的应用目录，可通过环境变量UWSGI_INI覆盖uWSGI配置文件路径，并将自定义uwsgi.ini文件放在该路径。

例如，需将应用目录设为/application而非/app，Dockerfile如下：

Dockerfile
FROM tiangolo/uwsgi-nginx:python3.12

ENV UWSGI_INI /application/uwsgi.ini

COPY ./application /application
WORKDIR /application

./application/uwsgi.ini文件内容：

ini
[uwsgi]
wsgi-file=/application/main.py

注意：必须包含WORKDIR选项，否则uWSGI会在/app目录启动应用。

自定义uWSGI进程数

默认镜像启动2个uWSGI进程，高负载时最多创建16个进程处理请求。可通过环境变量配置这些数值：

• UWSGI_CHEAPER：起始uWSGI进程数，默认2。
• UWSGI_PROCESSES：最大uWSGI进程数，默认16。

需确保UWSGI_CHEAPER小于UWSGI_PROCESSES。

例如，需起始4个进程，最大64个，Dockerfile如下：

Dockerfile
FROM tiangolo/uwsgi-nginx:python3.12

ENV UWSGI_CHEAPER 4
ENV UWSGI_PROCESSES 64

COPY ./app /app

自定义最大上传大小

默认Nginx允许无限制上传文件大小（与简单Python服务器行为一致，符合开发者预期）。如需限制Nginx最大上传大小，可添加环境变量NGINX_MAX_UPLOAD，值对应Nginx配置client_max_body_size标准格式。

例如，限制最大上传文件大小为1MB（标准Nginx默认值），Dockerfile如下：

Dockerfile
FROM tiangolo/uwsgi-nginx:python3.12

ENV NGINX_MAX_UPLOAD 1m

COPY ./app /app

自定义监听端口

默认容器监听80端口。如需修改，设置环境变量LISTEN_PORT，并添加相应EXPOSE指令。

Dockerfile示例：

Dockerfile
FROM tiangolo/uwsgi-nginx:python3.12

ENV LISTEN_PORT 8080

EXPOSE 8080

COPY ./app /app

自定义/app/prestart.sh

如需在启动应用前执行操作，可在/app目录添加prestart.sh文件，镜像会自动检测并在启动前运行。

例如，启动前运行数据库迁移（如Alembic或Django迁移），创建./app/prestart.sh：

bash
#! /usr/bin/env bash

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

如需启动前运行Python脚本，/app/prestart.sh可如下：

bash
#! /usr/bin/env bash

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

注意：镜像使用.运行脚本（如. /app/prestart.sh），环境变量等会保留。

自定义Nginx工作进程数

默认Nginx启动1个"工作进程"。如需修改，使用环境变量NGINX_WORKER_PROCESSES。

可设为具体数字：

Dockerfile
ENV NGINX_WORKER_PROCESSES 2

或设为auto，自动检测CPU核心数并设置工作进程数：

Dockerfile
FROM tiangolo/uwsgi-nginx:python3.12

ENV NGINX_WORKER_PROCESSES auto

COPY ./app /app

自定义Nginx工作进程最大连接数

默认Nginx工作进程最大连接数为1024。如需修改，使用环境变量NGINX_WORKER_CONNECTIONS：

Dockerfile
ENV NGINX_WORKER_CONNECTIONS 2048

该值不能超过当前系统文件最大打开数限制，下节说明如何配置。

自定义Nginx文件最大打开数

Nginx工作进程连接数受文件最大打开数限制。可通过环境变量NGINX_WORKER_OPEN_FILES修改：

Dockerfile
ENV NGINX_WORKER_OPEN_FILES 2048

自定义Nginx附加配置

如需进一步配置Nginx，可在Dockerfile中将*.conf文件添加到/etc/nginx/conf.d/。

注意：启动时会在/etc/nginx/conf.d/nginx.conf和/etc/nginx/conf.d/upload.conf生成默认配置，请勿覆盖。自定义文件命名需不同于nginx.conf或upload.conf（如custom.conf）。

注意：自定义Nginx配置时（如参考博客或Stack Overflow答案），需使用uWSGI专用配置，而非其他模块（如ngx_http_fastcgi_module）的配置。

完全覆盖Nginx配置

如需彻底覆盖默认Nginx配置，可添加自定义配置文件/app/nginx.conf，该文件会复制到/etc/nginx/nginx.conf并使用。

此时，镜像不会生成任何Nginx配置，上述Nginx相关环境变量均失效，/etc/nginx/conf.d/*.conf中的附加配置也不会生效，除非自定义/app/nginx.conf显式包含：

conf
include /etc/nginx/conf.d/*.conf;

如需创建自定义/app/nginx.conf但不知从何入手，可参考https://github.com/tiangolo/uwsgi-nginx-docker/blob/master/tests/test_02_app/custom_nginx_app/app/nginx.conf%E5%B9%B6%E4%BF%AE%E6%94%B9%E3%80%82

技术细节

uWSGI与Nginx的组合是部署Python Web应用的常用方式。

大致流程：

• Nginx作为Web服务器，处理HTTP连接，可直接高效提供静态文件。
• uWSGI作为应用服务器，运行Python代码，与Nginx通信。

该镜像基于Docker推荐的Debian基础镜像，遵循Docker最佳实践，在官方Python镜像上安装uWSGI和Nginx，通过Supervisord管理进程。

"每个容器一个进程"是经验法则，例如将应用和数据库分离到不同容器。但采用"微服务"架构时，若多个进程同属一个"服务"，可在单个容器中运行（如Flask代码、uWSGI和Nginx），数据库在另一个容器，此即本镜像的设计思路。

容器/app目录中默认包含基于uWSGI文档示例的"Hello World"示例应用，单独运行镜像时可查看，实际项目中应覆盖或删除。

🚨 Alpine Python警告

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

需要更多细节？继续阅读👇

Alpine对其他语言（如Go）更有用：在一个Docker阶段构建静态二进制文件，复制到简单Alpine镜像中执行。但Python不同，Alpine不使用构建Python扩展的标准工具，安装包时，pip常无法找到Alpine的预编译包（"wheel"）。调试大量异常后会发现，需安装许多额外工具并构建依赖才能使用常见Python包。😩

这意味着，尽管原始Alpine镜像较小，但最终镜像大小可能与标准Python镜像（基于Debian）相当，甚至更大。🤯

且构建时间更长，消耗更多资源，构建依赖耗时增加，碳足迹也更大（每次构建使用更多CPU时间和能源）。🌳

如需精简Python镜像，应使用基于Debian的`slim