twobulls/gunicorn-bootstrap

镜像概述

本Docker镜像为预配置的启动镜像，集成了Gunicorn（Python WSGI HTTP服务器）和Nginx（高性能反向代理服务器），旨在简化Python Web应用的部署流程。通过预配置的服务协同机制，实现Gunicorn处理应用逻辑与Nginx处理静态资源/反向代理的高效组合，帮助开发者快速搭建稳定、高性能的Web服务环境。

核心功能与特性

1. 组件集成

• Gunicorn：轻量级WSGI服务器，支持多进程/多线程模式，高效处理Python Web应用请求
• Nginx：高性能HTTP和反向代理服务器，负责静态资源分发、请求转发及负载均衡（基础配置）

2. 服务协同

• 预配置Nginx反向代理规则，将动态请求转发至Gunicorn（默认监听127.0.0.1:8000）
• 内置服务管理脚本，确保Gunicorn与Nginx进程协同启动、停止及故障恢复

3. 灵活配置

• 支持通过环境变量自定义Gunicorn参数（工作进程数、绑定地址、应用入口等）
• 允许挂载外部Nginx配置文件，覆盖默认反向代理规则

4. 轻量级基础

• 基于Alpine或Debian Slim基础镜像构建，减小镜像体积，提升部署效率

使用场景与适用范围

适用应用类型

• Python Web框架项目：Flask、Django、FastAPI等基于WSGI规范的应用
• 需要静态资源分离的Web服务：通过Nginx高效处理CSS、JS、图片等静态文件
• 对部署效率有要求的场景：避免手动配置Gunicorn与Nginx的协同工作流程

不适用场景

• 非Python语言开发的Web应用（如Node.js、Java等）
• 需要深度定制Nginx或Gunicorn底层架构的复杂场景

使用方法与配置说明

前置要求

• 已安装Docker Engine（20.10+）或Docker Desktop
• 应用代码符合WSGI规范（提供可被Gunicorn加载的入口模块，如wsgi:app）

镜像拉取

bash
docker pull [镜像仓库地址]/bootstrap-gunicorn-nginx:latest

核心配置参数（环境变量）

部署示例

1. 基础部署（docker run）

假设应用代码位于本地./app目录，入口模块为main:app（Flask应用）：

bash
docker run -d \
  -p 8080:80 \  # 宿主机8080端口映射容器Nginx端口（默认80）
  -v $(pwd)/app:/app \  # 挂载应用代码到容器工作目录
  -e APP_MODULE=main:app \  # 指定应用入口
  -e GUNICORN_WORKERS=6 \  # 自定义工作进程数
  --name python-web-app \
  [镜像仓库地址]/bootstrap-gunicorn-nginx:latest

2. Docker Compose部署

创建docker-compose.yml：

yaml
version: '3.8'
services:
  web:
    image: [镜像仓库地址]/bootstrap-gunicorn-nginx:latest
    ports:
      - "80:80"  # Nginx对外端口
    volumes:
      - ./app:/app  # 应用代码目录
      - ./nginx.conf:/etc/nginx/conf.d/default.conf  # 自定义Nginx配置（可选）
    environment:
      - APP_MODULE=wsgi:application  # Django应用通常使用wsgi:application
      - GUNICORN_BIND=127.0.0.1:8000
      - STATIC_ROOT=/app/staticfiles  # Django静态文件收集目录
    restart: unless-stopped

启动服务：

bash
docker-compose up -d

自定义Nginx配置

如需修改Nginx反向代理规则或静态资源处理逻辑，可通过挂载外部配置文件覆盖默认配置：

bash
# 本地nginx.conf示例（自定义静态文件缓存策略）
server {
    listen 80;
    location /static/ {
        alias /app/static/;
        expires 1d;  # 静态文件缓存1天
    }
    location / {
        proxy_pass http://127.0.0.1:8000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

# 启动时挂载配置文件
docker run -v $(pwd)/nginx.conf:/etc/nginx/conf.d/default.conf ...

注意事项

1. 应用代码需确保可被Gunicorn加载（如提供wsgi.py或指定入口模块）
2. 静态文件需放置于STATIC_ROOT指定目录，或通过Nginx配置自定义路径
3. 生产环境建议通过环境变量调整GUNICORN_WORKERS（通常设为CPU核心数×2+1）
4. 如需HTTPS，可在Nginx配置中添加SSL证书路径及监听443端口配置