uwsgi-nginx-flask Docker镜像文档

镜像概述和主要用途

uwsgi-nginx-flask是一个集成uWSGI和Nginx的Docker镜像，专为在单个容器中运行Python Flask Web应用设计。该镜像预配置了生产环境常用的部署组件，将Flask应用服务器（uWSGI）与反向代理服务器（Nginx）结合，简化了Flask应用的部署流程，适用于需要快速搭建稳定Web服务的场景。

核心功能和特性

• 组件集成：内置uWSGI（Python应用服务器）和Nginx（反向代理），无需单独配置两者协作
• 多Python版本支持：提供Python 3.10+系列版本标签，适配不同应用需求
• 单容器部署：应用、uWSGI、Nginx运行于同一容器，减少基础设施依赖
• 动态进程管理：uWSGI自动调整工作进程数量，平衡资源占用与并发处理能力
• 静态文件优化：Nginx直接处理静态资源请求，减轻Python应用负担
• 灵活配置：通过环境变量和自定义配置文件支持深度定制

支持的标签与已弃用标签

支持的标签

已弃用标签

⚠️ 以下标签不再维护，已从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

注意：镜像提供每日构建标签，如需固定版本可选择日期标签（如tiangolo/uwsgi-nginx-flask:python3.7-2019-10-14）。

使用场景和适用范围

适用场景

1. 简单Flask应用部署
   无需复杂集群管理，单容器即可满足中小流量应用需求，适合个人项目或内部工具。

2. Docker Compose单服务器部署
   在单台服务器上使用Docker Compose管理服务时，可利用容器内进程管理实现负载均衡，避免集群级工具（如Kubernetes）的复杂性。

3. 单容器多进程指标收集
   需在容器内汇总多工作进程指标（如Prometheus监控）时，单容器部署可简化指标采集逻辑。

不适用场景（警告）

⚠️ Kubernetes或集群环境：在集群环境中，建议通过集群工具（如Kubernetes）管理容器复制和负载均衡，而非依赖容器内进程管理。此时应构建仅包含单个应用进程的镜像（如使用Gunicorn），通过集群调度实现水平扩展。

快速入门

基本快速入门

1. 项目结构

   .
   ├── app
   │   └── main.py
   └── Dockerfile
   

2. 编写Flask应用（app/main.py）

   python
   from flask import Flask
   app = Flask(__name__)
   
   @app.route("/")
   def hello():
       return "Hello World from Flask"
   
   if __name__ == "__main__":
       app.run(host='0.0.0.0', debug=True, port=80)  # 仅用于开发调试
   

3. 编写Dockerfile

   dockerfile
   FROM tiangolo/uwsgi-nginx-flask:python3.12
   
   # 复制应用代码
   COPY ./app /app
   

4. 构建并运行镜像

   bash
   # 构建镜像
   docker build -t my-flask-app .
   
   # 运行容器
   docker run -d --name my-flask-container -p 80:80 my-flask-app
   

5. 访问应用
   打开浏览器访问 [***] 或服务器IP，应显示"Hello World from Flask"。

大型Python包项目快速入门

对于结构化Python包项目，需调整目录结构并配置uWSGI：

1. 项目结构

   .
   ├── app
   │   ├── app
   │   │   ├── __init__.py
   │   │   ├── main.py
   │   │   └── static  # 静态文件目录
   │   └── uwsgi.ini    # uWSGI配置文件
   └── Dockerfile
   

2. 配置uWSGI（app/uwsgi.ini）

   ini
   [uwsgi]
   module = app.main  # 模块路径：app/main.py
   callable = app     # Flask应用实例名称
   

3. Dockerfile配置

   dockerfile
   FROM tiangolo/uwsgi-nginx-flask:python3.12
   
   # 配置静态文件路径（如需要）
   ENV STATIC_PATH /app/app/static
   
   # 复制应用代码
   COPY ./app /app
   

单页应用（SPA）部署说明

不建议将前端代码与Flask后端打包在同一容器中。推荐采用多阶段构建分离前后端：

• 前端：使用Node.js容器编译代码，输出到Nginx容器
• 后端：使用本镜像部署Flask应用
• 反向代理：通过Traefik等工具统一入口并配置HTTPS

详细配置说明

环境变量配置

uWSGI相关环境变量

Nginx相关环境变量

应用相关环境变量

自定义uWSGI配置

通过替换uwsgi.ini文件自定义uWSGI行为：

1. 创建自定义uwsgi.ini（如启用线程支持）

   ini
   [uwsgi]
   module = main
   callable = app
   enable-threads = true  # 启用线程
   thread-stacksize = 128k  # 线程栈大小
   

2. Dockerfile中复制配置文件

   dockerfile
   FROM tiangolo/uwsgi-nginx-flask:python3.12
   
   # 复制自定义uwsgi.ini
   COPY ./uwsgi.ini /app/uwsgi.ini
   
   # 复制应用代码
   COPY ./app /app
   

自定义Nginx配置

扩展Nginx配置

添加*.conf文件到/etc/nginx/conf.d/目录扩展配置（不覆盖默认配置）：

dockerfile
FROM tiangolo/uwsgi-nginx-flask:python3.12

# 添加自定义Nginx配置
COPY ./custom-nginx.conf /etc/nginx/conf.d/custom.conf

COPY ./app /app

完全覆盖Nginx配置

通过/app/nginx.conf完全替换Nginx配置：

dockerfile
FROM tiangolo/uwsgi-nginx-flask:python3.12

# 复制自定义Nginx配置（完全覆盖默认配置）
COPY ./nginx.conf /app/nginx.conf

COPY ./app /app

前置启动脚本（prestart.sh）

创建/app/prestart.sh可在应用启动前执行命令（如数据库迁移）：

1. 创建脚本（app/prestart.sh）

   bash
   #! /usr/bin/env bash
   
   # 示例：等待数据库启动
   sleep 10
   
   # 示例：执行数据库迁移
   flask db upgrade
   

2. 添加执行权限并复制

   dockerfile
   FROM tiangolo/uwsgi-nginx-flask:python3.12
   
   # 复制前置脚本并添加权限
   COPY ./app/prestart.sh /app/prestart.sh
   RUN chmod +x /app/prestart.sh
   
   COPY ./app /app
   

部署示例

Docker Compose配置示例

yaml
version: '3'

services:
  flask-app:
    build: .
    ports:
      - "80:80"
    environment:
      - UWSGI_CHEAPER=4           # 初始工作进程数4
      - UWSGI_PROCESSES=16        # 最大工作进程数16
      - NGINX_MAX_UPLOAD=10m      # 最大上传10MB
      - STATIC_PATH=/app/app/static  # 静态文件路径
    volumes:
      - ./app:/app  # 开发环境热更新（生产环境移除）
    restart: always

自定义端口部署示例

修改容器监听端口：

dockerfile
FROM tiangolo/uwsgi-nginx-flask:python3.12

# 配置监听端口
ENV LISTEN_PORT 8080
EXPOSE 8080  # 声明暴露端口

COPY ./app /app

运行命令：

bash
docker run -d --name my-flask-container -p 8080:8080 my-flask-app

技术细节

该镜像基于tiangolo/uwsgi-nginx构建，默认配置：

• uWSGI通过/app/uwsgi.ini加载应用，默认模块为main，可调用对象为app
• Nginx通过反向代理将请求转发至uWSGI（默认监听127.0.0.1:3031）
• 静态文件由Nginx直接处理，无需经过uWSGI和Python应用

所有配置文件和脚本在容器启动时动态生成，确保环境变量生效。