Gunicorn 是什么

Gunicorn（Green Unicorn）是一个 Python WSGI HTTP 服务器，用于运行 Python Web 应用。它是生产环境中最流行的 Python 应用服务器之一，特点是简单、轻量、高性能。

客户端 → Gunicorn（处理 HTTP、管理 Worker） → 你的 Python 应用（Flask/Django/FastAPI 等）

核心功能

1. Worker 管理

支持多种 Worker 类型，适应不同场景：

Worker 类型	适用场景	说明
sync（默认）	CPU 密集型、简单请求	同步阻塞，每个 worker 同时处理 1 个请求
gthread	一般 Web 应用	多线程，单 worker 内多线程处理
gevent	高并发 I/O 密集型	基于协程，极高并发能力
eventlet	高并发 I/O 密集型	类似 gevent，另一种协程实现

2. 进程管理

• Master-Worker 架构：Master 进程负责管理，Worker 进程处理请求
• 优雅重启：kill -HUP 不中断服务热更新代码
• 自动重启：Worker 崩溃自动拉起
• 超时杀进程：Worker 超时自动终止，防止卡死

3. 负载均衡

Master 进程自动将请求分发到空闲 Worker。

4. 可观测性

• 访问日志、错误日志
• StatsD 指标集成
• 可自定义日志格式

---

快速上手

安装

pip install gunicorn
# 如果用 gevent worker
pip install gunicorn gevent

最简启动

gunicorn app:app

格式：gunicorn 模块名:应用对象

# app.py
from flask import Flask
app = Flask(__name__)

@app.route("/")
def hello():
    return "Hello World!"

常用参数

gunicorn app:app \
  --bind 0.0.0.0:8000 \          # 监听地址和端口
  --workers 4 \                   # Worker 数量（推荐 2×CPU核心+1）
  --worker-class gthread \        # Worker 类型
  --threads 2 \                   # 每个 worker 的线程数（gthread 模式）
  --timeout 120 \                 # Worker 超时时间（秒）
  --access-logfile - \            # 访问日志（- 表示 stdout）
  --error-logfile - \             # 错误日志
  --log-level info \              # 日志级别
  --daemon                        # 守护进程模式（后台运行）

---

配置文件（推荐）

生产环境建议用配置文件，而不是命令行参数：

# gunicorn.conf.py

# 绑定地址
bind = "0.0.0.0:8000"

# Worker 配置
workers = 4
worker_class = "gthread"
threads = 2
timeout = 120
keepalive = 5

# 日志
accesslog = "-"          # stdout
errorlog = "-"
loglevel = "info"
access_log_format = '%(h)s %(l)s %(u)s %(t)s "%(r)s" %(s)s %(b)s "%(f)s" "%(a)s" %(D)s'

# 进程管理
preload_app = True       # 预加载应用，节省内存
max_requests = 1000      # Worker 处理 N 个请求后重启，防内存泄漏
max_requests_jitter = 50 # 加随机抖动，避免所有 worker 同时重启

# 钩子函数
def on_starting(server):
    print("Gunicorn is starting...")

def post_fork(server, worker):
    server.log.info(f"Worker spawned (pid: {worker.pid})")

启动时指定配置：

gunicorn app:app -c gunicorn.conf.py

---

常见框架对接

Flask

gunicorn app:app

Django

gunicorn myproject.wsgi:application

FastAPI

# 需要 uvicorn worker
pip install uvicorn
gunicorn app:app -k uvicorn.workers.UvicornWorker

---

运维操作

# 优雅重启（代码更新后不中断服务）
kill -HUP <master_pid>

# 查看 master pid
cat gunicorn.pid   # 启动时加 --pid gunicorn.pid

# 平滑关闭
kill -TERM <master_pid>

# 强制关闭
kill -9 <master_pid>

---

生产架构建议

Gunicorn 通常不直接暴露给公网，前面会加 Nginx 做反向代理：

用户 → Nginx（SSL/静态文件/限流） → Gunicorn（应用服务器） → Python 应用

Nginx 配置示例：

server {
    listen 80;
    server_name example.com;

    location / {
        proxy_pass http://127.0.0.1:8000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }
}

---

一句话总结：Gunicorn 就是 Python Web 应用的"生产车间"——你负责写代码，它负责管理进程、分发请求、保证服务稳定运行

其他注意事项

1. 不要在 Windows 上使用：Gunicorn 仅支持 Unix 系统
2. 生产环境必须配合反向代理：如 Nginx，用于处理静态文件和负载均衡
3. 合理设置工作进程数：过多会消耗内存，过少会影响性能
4. 监控内存使用：长时间运行可能出现内存泄漏
5. 定期重启：通过 max_requests 参数避免内存泄漏累积

Gunicorn 是一个成熟稳定的 WSGI 服务器，特别适合中小型 Python Web 应用的生产部署。配合合适的配置和监控，能够提供可靠的 HTTP 服务。