人人都会AI编程

25.4 WSGI / ASGI 服务器：Gunicorn、Uvicorn 生产部署配置

更新时间：2026-07-12

Python Web 框架（Django、Flask、FastAPI 等）自带的开发服务器仅用于本地调试，绝不可直接暴露在生产环境。生产环境必须使用专业的 WSGI 或 ASGI 服务器来承接请求、管理进程、提供并发能力。

简单区分两条线：

  • 同步 Web 应用（Django、Flask）→ 使用 WSGI 服务器，如 Gunicorn（或 uWSGI）
  • 异步 Web 应用（FastAPI、Django Channels）→ 使用 ASGI 服务器，如 Uvicorn（常配合 Gunicorn 管理进程）

下面给出最常见的生产配置组合及关键要点。

一、Gunicorn：同步应用的 WSGI 服务器

Gunicorn（Green Unicorn）是一个成熟的、基于 pre-fork 模型的 WSGI 服务器。启动时会创建主进程和一或多个 worker 子进程，由 worker 处理请求。

基本用法

pip install gunicorn
gunicorn myproject.wsgi:application
  • myproject.wsgi:application 是 Django/Flask 暴露的 WSGI 应用对象路径。
  • 默认监听 127.0.0.1:8000，仅 1 个 worker，不适合直接生产。

生产配置核心参数

通常通过命令行参数或配置文件（gunicorn.conf.py）指定。

1. Worker 数量与类型

  • worker 数量：一般设为 (2 * CPU核心数) + 1，但要根据应用类型微调（IO 密集型可更多，CPU 密集型应接近核心数）。
  gunicorn --workers 4
  • worker 类型（-k）：
  • sync：默认，每个 worker 一次处理一个请求，适合 IO 不重的同步应用。
  • gevent：基于协程，适合大量 IO 等待的应用；需安装 gevent。
  • 其他：eventlet、tornado 等。
  gunicorn -k gevent --worker-connections 1000

2. 绑定地址与端口

gunicorn --bind 0.0.0.0:8000

3. 超时设置

  • --timeout 30：worker 处理请求的最大秒数（默认 30s），对于慢接口要适当增大。
  • --graceful-timeout 30：重启时允许旧 worker 完成请求的时间。

4. 日志

gunicorn --access-logfile - --error-logfile -

将访问日志和错误日志输出到 stdout/stderr，便于容器化或日志收集工具处理。

5. 以 Daemon 或后台运行
容器环境下不建议 daemon 模式，应由 supervisor 或 Docker 管理；若必须可用 --daemon。

示例：典型 Django 生产配置

gunicorn myproject.wsgi:application \
    --bind 0.0.0.0:8000 \
    --workers 4 \
    --timeout 60 \
    --access-logfile /var/log/gunicorn/access.log \
    --error-logfile /var/log/gunicorn/error.log

前置反向代理

强烈建议在 Gunicorn 前放置 Nginx，用于：

  • 静态文件直接服务，减少 Python 负载
  • 缓冲慢客户端请求，保护后端 worker
  • SSL 终结
  • 负载均衡（多个 Gunicorn 实例）

二、Uvicorn：异步应用的 ASGI 服务器

Uvicorn 是基于 uvloop 和 httptools 的高性能 ASGI 服务器，原生支持异步框架（FastAPI、Starlette、Django Channels 等）。

基本用法

pip install uvicorn
uvicorn main:app --reload
  • main:app 中 main 是模块文件，app 是 ASGI 应用实例。
  • --reload 仅用于开发。

生产部署模式

单进程 Uvicorn 足够开发，但生产环境需要多进程来利用多核、提高健壮性。主流方案是用 Gunicorn 作为进程管理器，托管 Uvicorn worker。

方案一：Gunicorn + Uvicorn workers（推荐）
pip install gunicorn uvicorn
gunicorn main:app \
    --workers 4 \
    --worker-class uvicorn.workers.UvicornWorker \
    --bind 0.0.0.0:8000 \
    --timeout 120
  • --worker-class uvicorn.workers.UvicornWorker 让 Gunicorn 使用 Uvicorn 的 worker 类，每个 worker 内部运行异步事件循环。
  • 其他 Gunicorn 参数（--workers、--bind、--timeout）同样适用。
方案二：纯 Uvicorn 多进程（简单场景）
uvicorn main:app --host 0.0.0.0 --port 8000 --workers 4

但通常不推荐用于复杂部署，因为 Uvicorn 本身进程管理功能不如 Gunicorn 完善。

关键参数

  • --limit-concurrency：最大并发连接数，默认不限，可防止资源耗尽。
  • --limit-max-requests：worker 处理多少个请求后自动重启，防止内存泄漏累积。
  • --ssl-keyfile / --ssl-certfile：可直接配置 HTTPS，但生产通常由 Nginx 处理。

与 Nginx 配合

同样建议 Nginx 反向代理：

upstream app_server {
    server 127.0.0.1:8000;
}
server {
    listen 80;
    server_name example.com;
    location / {
        proxy_pass http://app_server;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }
}

三、容器化部署要点

将应用打包为 Docker 镜像时，几个关键点：

  • 前台运行：保证进程不 daemon 化，让容器主进程由 Gunicorn/Uvicorn 直接占据。
  CMD ["gunicorn", "myproject.wsgi:application", "--bind", "0.0.0.0:8000", "--workers", "4"]
  • worker 数量与容器资源匹配：不要盲目使用 2*CPU+1，容器可能只有 1-2 个核心，此时 --workers=2 可能更合适。可考虑使用 --preload 节省内存（仅 Gunicorn）。
  • 优雅关闭：Docker stop 会发送 SIGTERM，Gunicorn 默认会等待 --graceful-timeout 秒让请求完成后再退出。确保 Docker 的 stop timeout 大于该值。

四、选择建议速查表

| 框架 | WSGI/ASGI | 推荐服务器 | 典型命令 |
|----------------|-----------|-------------------------------------|-------------------------------------------------------|
| Django (传统) | WSGI | Gunicorn | gunicorn myproject.wsgi --workers 4 --bind 0.0.0.0:8000 |
| Flask | WSGI | Gunicorn (可加 gevent worker) | gunicorn app:app -k gevent --workers 4 |
| FastAPI | ASGI | Gunicorn + UvicornWorker | gunicorn main:app -w 4 -k uvicorn.workers.UvicornWorker |
| Django Channels| ASGI | Gunicorn + UvicornWorker 或 Daphne | 同左 |

无论哪种组合，配置反向代理（Nginx/Caddy） + 合理设置 worker 数 + 日志和超时，就能构建一个稳定、可伸缩的 Python Web 服务。