目录

1. 什么是 Gunicorn？
2. 环境准备
3. 安装 Gunicorn
4. 基本使用
5. 配置文件
6. 高级配置
7. 与 Nginx 结合使用 (生产环境推荐)
8. 常见问题与总结

什么是 Gunicorn？

Gunicorn (Green Unicorn) 是一个 Python WSGI HTTP 服务器，它的作用是：

• 运行你的 Python Web 应用：像 Flask, Django, Pyramid 这样的框架本身不能直接接收和处理网络请求，Gunicorn 充当了它们和 Web 浏览器之间的桥梁。
• 多进程处理：Gunicorn 默认会启动多个工作进程，每个进程都能处理一个请求，这使得你的应用能够充分利用多核 CPU，提高并发处理能力，性能远超单个进程。
• 稳定可靠：Gunicorn 负责管理这些工作进程的生命周期，如果某个进程崩溃了，它会自动重启，保证了服务的稳定性。

一句话总结：Gunicorn 是将你的 Python Web 应用部署到生产环境的标准工具之一。

环境准备

在安装 Gunicorn 之前，请确保你已经：

1. 安装了 Python：推荐使用 Python 3.6+ 版本。

2. 创建并激活了虚拟环境：这是一个非常重要的最佳实践，可以避免项目之间的包冲突。

   
   （图片来源网络，侵删）

   # 创建虚拟环境 (推荐使用 venv)
   python -m venv myproject_env
   # 激活虚拟环境
   # Windows:
   .\myproject_env\Scripts\activate
   # macOS / Linux:
   source myproject_env/bin/activate
   # 激活后，你的命令行提示符前会出现 (myproject_env)

安装 Gunicorn

在激活的虚拟环境中,使用 pip 安装 Gunicorn 非常简单。

pip install gunicorn

验证安装

安装完成后,你可以检查一下版本号，确认是否安装成功。

gunicorn --version

如果输出版本号（2.0），则表示安装成功。

基本使用

假设你有一个简单的 Flask 应用，文件名为 app.py。

app.py 示例:

# app.py
from flask import Flask
app = Flask(__name__)
@app.route('/')
def hello():
    return "Hello, World from Gunicorn!"
@app.route('/greet/<name>')
def greet(name):
    return f"Hello, {name}!"
# 这个 if 语句是必须的，这样你才能直接用 `python app.py` 运行开发服务器
if __name__ == '__main__':
    app.run()

启动 Gunicorn

Gunicorn 的基本命令格式是： gunicorn [选项] 模块名:应用实例

• 模块名：Python 文件的文件名（不带 .py 后缀）。
• 应用实例：在你的模块中，代表 WSGI 应用的变量名，对于 Flask，通常是 app。

在 app.py 所在的目录下，运行以下命令：

gunicorn app:app

• app:app：第一个 app 是 app.py 文件，第二个 app 是文件中的 app 变量。

启动参数说明

• -b 或 --bind：指定监听的地址和端口。

  • 默认是 0.0.1:8000，即只允许本机访问。
  • 要让外部机器也能访问,通常设置为 0.0.0:8000。
  • 示例：gunicorn -b 0.0.0.0:8000 app:app

• -w 或 --workers：指定工作进程的数量。

  • Gunicorn 的一个重要特性就是多进程。
  • 一个常用的经验法则是 (2 x CPU核心数) + 1，一个 4 核 CPU 的服务器，可以设置为 9。
  • 示例：gunicorn -w 4 app:app

• --threads：指定每个工作进程中的线程数，默认是 1，对于 I/O 密集型应用，可以适当增加。

一个更常用的启动命令：

gunicorn -b 0.0.0.0:8000 -w 4 app:app

启动后,你会看到类似下面的输出：

[2025-10-27 10:30:00 +0000] [12345] [INFO] Starting gunicorn 21.2.0
[2025-10-27 10:30:00 +0000] [12345] [INFO] Listening at: http://0.0.0.0:8000 (12345)
[2025-10-27 10:30:00 +0000] [12345] [INFO] Using worker: sync
[2025-10-27 10:30:00 +0000] [12348] [INFO] Booting worker with pid: 12348
[2025-10-27 10:30:00 +0000] [12349] [INFO] Booting worker with pid: 12349
[2025-10-27 10:30:00 +0000] [12350] [INFO] Booting worker with pid: 12350
[2025-10-27 10:30:00 +0000] [12351] [INFO] Booting worker with pid: 12351

你可以在浏览器中访问 http://<你的服务器IP>:8000 来测试你的应用了。

配置文件

当命令行参数变得很长时,使用配置文件会更加方便和清晰。

1. 创建配置文件：在你的项目根目录下创建一个名为 gunicorn_conf.py 的文件。

2. 编写配置：gunicorn_conf.py 中的变量名可以直接对应 Gunicorn 的命令行参数。

   gunicorn_conf.py 示例:

   # gunicorn_conf.py
   # 绑定的地址和端口
   bind = "0.0.0.0:8000"
   # 工作进程数
   workers = 4
   # 每个工作进程的线程数
   threads = 2
   # 工作进程类型
   worker_class = "sync"  # 默认，也可以用 "gevent", "eventlet" 等
   # 访问日志文件路径
   accesslog = "/var/log/gunicorn/access.log"
   # 错误日志文件路径
   errorlog = "/var/log/gunicorn/error.log"
   # 日志级别
   loglevel = "info"
   # 超时时间（秒）
   timeout = 30
   # 最大请求数，达到后重启worker，防止内存泄漏
   max_requests = 1000
   max_requests_jitter = 50

3. 使用配置文件启动： 使用 -c 或 --config 参数指定配置文件路径。

   gunicorn -c gunicorn_conf.py app:app

高级配置

• 工作进程类型： 默认的 sync 工作器是同步的，一次只处理一个请求，对于高并发的 I/O 密集型应用，推荐使用异步工作器。

  • gevent：需要先安装 pip install gevent。

    gunicorn -w 4 -k gevent app:app

  • eventlet：需要先安装 pip install eventlet。

    gunicorn -w 4 -k eventlet app:app

• 优雅关闭： 当你发送 SIGTERM 信号（kill <master_pid>）时，Gunicorn 会停止接收新请求，并等待当前正在处理的请求完成后再关闭工作进程，这可以避免请求被粗暴地中断。

与 Nginx 结合使用 (生产环境推荐)

Gunicorn 虽然强大，但它不直接处理静态文件（如 CSS, JavaScript, 图片）和客户端请求，在生产环境中，通常会将 Gunicorn 放在 Nginx（一个高性能的 Web 服务器和反向代理）后面。

架构图： 客户端 -> Nginx -> Gunicorn -> 你的 Python 应用

为什么这样做？

1. 处理静态文件：Nginx 处理静态文件非常高效，可以减轻 Gunicorn 的负担。
2. 负载均衡：Nginx 可以将请求分发到多个 Gunicorn 实例。
3. 安全：Nginx 可以作为防火墙，隐藏 Gunicorn 的具体细节。
4. HTTPS：在 Nginx 上配置 SSL/TLS 证书比在 Gunicorn 上配置更简单。

Nginx 配置示例 (/etc/nginx/sites-available/myproject)

server {
    listen 80;
    server_name your_domain.com; # 替换成你的域名或IP
    location / {
        # 将请求代理到 Gunicorn
        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;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
    # 专门处理静态文件
    location /static {
        alias /path/to/your/project/static; # 替换成你的静态文件目录
        expires 30d; # 缓存30天
    }
}

部署流程：

1. 启动 Gunicorn (通常在后台运行，例如使用 systemd 或 supervisor 管理服务)。
2. 启动或重启 Nginx (sudo systemctl restart nginx)。
3. 现在用户访问 your_domain.com，流量会先经过 Nginx，再由 Nginx 转发给 Gunicorn。

常见问题与总结

Q: 如何停止 Gunicorn？ A: 找到 Gunicorn 主进程的 PID (在启动日志的第一行 [PID] 中)，然后使用 kill 命令。

# 发送优雅关闭信号
kill <master_pid>
# 如果进程无响应，可以强制杀死
kill -9 <master_pid>

Q: 如何让 Gunicorn 在后台运行？ A: 生产环境中，通常使用进程管理工具如 systemd 或 supervisor 来管理 Gunicorn，它们可以在后台运行、自动重启并记录日志。

1. 安装：在虚拟环境中使用 pip install gunicorn。
2. 基本命令：gunicorn -b 0.0.0.0:8000 -w 4 app:app。
3. 推荐方式：使用配置文件 (gunicorn_conf.py) 来管理复杂设置。
4. 生产环境：将 Gunicorn 与 Nginx 结合使用，Nginx 作为反向代理和静态文件服务器。

这份教程涵盖了从安装到生产部署的完整流程,希望能帮助你顺利上手 Gunicorn。