Gunicorn 完全指南：Python 生产部署的基石
Gunicorn 是 Python 生产部署标配的 WSGI 服务器。本文讲解基础用法、配置文件、异步 worker 选择、性能调优、日志管理、systemd 托管与生产部署模式。
直接回答：Gunicorn（Green Unicorn）是 Python Web 应用的生产级 WSGI 服务器：主进程管理多个 worker 进程接请求，简单可靠、兼容 Django/Flask 等所有 WSGI 框架，是 Python 生产部署常用服务器之一（主要面向 Unix 系统）。
为什么是 Gunicorn
Django 的 runserver、Flask 的内置服务器都明确写着"仅供开发"。生产需要：多进程利用多核、worker 崩溃自动拉起、无响应 worker 超时处理、平滑重启——Gunicorn 的 pre-fork 模型把这些打包提供，配置却只需一行命令。
快速上手
pip install gunicorn
gunicorn myproject.wsgi:application --bind 0.0.0.0:8000
主进程（master）fork 出若干 worker，请求由 worker 处理；worker 挂了 master 立即补一个新的。
配置文件
命令行参数多了就收敛到 gunicorn.conf.py：
bind = "0.0.0.0:8000"
workers = 4
worker_class = "sync"
timeout = 30
keepalive = 5
max_requests = 1000 # worker 处理 1000 个请求后重启，防内存泄漏
max_requests_jitter = 100 # 加抖动，避免同时重启
accesslog = "-" # stdout
errorlog = "-"
gunicorn -c gunicorn.conf.py myproject.wsgi:application 启动。
异步 worker 怎么选
| worker_class | 模型 | 适用 |
|---|---|---|
sync（默认） |
每 worker 一次一个请求 | CPU 密集、逻辑简单 |
gthread |
每 worker 多线程 | IO 较多但仍同步代码 |
gevent |
协程并发 | 大量并发连接、长轮询 |
uvicorn_worker.UvicornWorker |
ASGI | FastAPI/异步框架 |
ASGI 示例需安装 gunicorn 与 uvicorn-worker；uvicorn.workers 模块已弃用。不要把 greenlet worker 与原生 asyncio 混为一谈。
workers 数量：经典起点 (2 × CPU) + 1；IO 密集且用 gevent 时，worker 数可以少些（并发在协程里）。容器环境按 CPU limit 算。
性能微调清单
timeout：默认 30s，用于杀死并重启超时无响应的 worker；异步 worker 中不等同于每请求 30s 硬超时；max_requests + jitter：慢性内存泄漏的止血带；keepalive：sync worker 忽略此设置，其他 worker 按部署情况配置；preload_app：加载应用后再 fork，省内存省启动时间（注意热重载语义变化）。
日志管理
accesslog/errorlog 设为 - 输出到 stdout/stderr——容器与 systemd 时代，日志采集都从这里接。需要更细粒度（按 request_id 关联）时在应用层打结构化日志，Gunicorn 自带的日志只做访问与进程事件记录。
排查 worker 超时时，把进程重启记录与同一时段的应用错误一起查。通过观测云 DataKit集中采集时，为访问日志和错误日志区分来源、保留同一服务标识，避免把 worker 被重启误当作请求已成功重试。
systemd 托管
# /etc/systemd/system/myapp.service
[Unit]
After=network.target
[Service]
User=myapp
WorkingDirectory=/srv/myapp
ExecStart=/venv/bin/gunicorn -c gunicorn.conf.py myproject.wsgi:application
Restart=always
RestartSec=3
[Install]
WantedBy=multi-user.target
先创建服务用户和项目目录，调整绝对路径并执行 systemctl daemon-reload；随后 systemctl enable --now myapp，开机自启、崩溃自愈。平滑重载用 kill -HUP <master_pid>（旧 worker 在 graceful_timeout 范围内完成请求，不能保证所有长连接不断）。
生产部署模式
经典形态：Nginx/Caddy 在前（TLS、静态文件、限流）→ Gunicorn 通过 Unix socket 或端口接动态请求。容器形态下反代职责由 Ingress/网关接管，Gunicorn 直接暴露端口。
常见问题（FAQ）
Q：Gunicorn 和 uWSGI 怎么选？
A：Gunicorn 配置简单、社区活跃，是当下默认答案；uWSGI 提供不同的部署能力；根据维护版本、团队经验和需要的功能评估，不据本文推断维护状态。
Q：FastAPI 还需要 Gunicorn 吗？
A：可以不用（直接多副本 Uvicorn）；也可以用 Gunicorn 管 UvicornWorker 获得成熟的进程管理。K8s 多副本场景下前者更简单。
Q：worker 数加了一倍，吞吐没涨？
A：多半瓶颈不在 worker——查数据库连接池上限、外部依赖延迟、CPU 是否已饱和。盲目加 worker 只会放大下游压力。
官方参考
本文基于官方文档整理，未进行运行时或性能测试。示例中的业务函数、数据模型和部署地址需结合项目补全；局部片段不等同于完整生产应用。
