孔良本地能跑起来一个 Flask 应用，和线上扛得住真实流量，中间差的距离比你想的要大。早期我写过不少小项目，最开始的部署方式非常粗糙：写完接口，app.run(host='0.0.0.0', port=5000) 一把梭，往云服务器上丢，然后发现请求稍微一多，页面就转圈，日志里偶尔还会蹦出连接拒绝的报错。后来老老实实补了 Gunicorn 这一课，才明白所谓"生产可用的 Web 服务"，并不是把端口开出来就行。
这篇就围绕 Gunicorn 和它背后的 WSGI 协议，把这个链路里最关键的东西讲透。内容会覆盖 Gunicorn 在解决什么问题、WSGI 到底怎么工作、一个 Flask 应用怎么在 Gunicorn 上跑起来、worker 数量和 worker 类型怎么调，以及我实际部署中踩过的坑和排查过程。适合那些已经开始写 Python Web 应用、但还没有认真思考过"线上部署细节"的开发者。
1. 本地能跑和生产能跑是两码事：Gunicorn 到底在解决什么问题
先说个最常见的认知误区。很多人以为 Flask 自带的开发服务器就是"Web 服务器"，所以开发完直接用它对外提供服务。但实际上，Flask 默认调用的 Werkzeug dev server 主要目标是在开发期间给你实时错误提示、自动重载代码，它的并发能力和资源管理完全不是为生产环境设计的。
1.1 开发服务器的局限
Werkzeug 开发服务器默认是单进程的，而且处理请求的能力受限于它的实现方式。你在本地用浏览器访问，感觉没什么问题，那是因为只有一个用户在访问。一旦多个请求同时进来，它就会排队处理，响应时间会明显拉长，而且某一个请求长时间不结束，后续请求就会被卡住。
更关键的是，开发服务器缺少生产环境必须具备的几样东西：进程管理、worker 回收、优雅退出、超时控制。这些能力不是锦上添花，而是真实流量下服务不崩掉的底线。
1.2 Gunicorn 的定位：一个"带管理能力的 WSGI 服务器"
Gunicorn，全称 Green Unicorn，是一个用 Python 实现的 WSGI HTTP 服务器。它的核心模型是 pre-fork worker model：一个 master 进程负责监听端口、管理 worker 生命周期、回收异常 worker，多个 worker 进程真正去处理请求。
这个模型最大的好处是"隔离"。每个 worker 是独立的进程，一个 worker 因为某种原因崩溃（比如段错误、内存爆掉），master 会自动拉起一个新的 worker，其他 worker 不受影响。这是开发服务器做不到的。
另一个选择 Gunicorn 的原因是用起来足够简单。相比 uWSGI 需要编译 C 扩展、配置项多到眼花的风格，Gunicorn 是纯 Python 的，pip 装上就能用，配置文件用 Python 语法，逻辑非常直白。对于中小型项目来说，Gunicorn 几乎是零成本上手。
1.3 Gunicorn 和"应用框架"的分工
搞清楚 Gunicorn 什么时候介入，先要理解 Web 请求的链条：
浏览器发出 HTTP 请求 → 经过 TCP 层 → 到达服务器进程 → 服务器把请求解析出来 → 调用你的 Python 应用代码 → 拿到响应 → 返回给浏览器。
Gunicorn 承担的是"服务器进程 + 请求解析 + 调用应用"这一段。Flask 这样的框架承担的是"路由分发、业务逻辑、返回响应"这一段。两者之间靠一个约定进行通信，这个约定就是 WSGI 协议。下一节我会详细拆这个协议。
所以 "Gunicorn 和 WSGI" 这个话题，本质上就是在讲 Web 服务端的一个关键分层：HTTP 服务器不关心你的业务逻辑，你的业务代码也不应该去关心 HTTP 报文怎么解析，中间用一个标准接口把它们切开。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. WSGI 到底是个什么东西：一张让框架和服务器"对话"的契约
WSGI 的全程是 Python Web Server Gateway Interface，最初在 2003 年以 PEP 333 的形式提出，后来针对 Python 3 更新为 PEP 3333。它解决的问题非常具体：在 WSGI 出现之前，Python Web 框架和 Web 服务器之间没有统一接口，每个框架都要自己适配不同的服务器，换一个服务器就要改一套代码，生态非常碎片化。
WSGI 做的事情，就是定义了一个通用的调用约定，让任何实现了 WSGI 的框架，可以跑在任何实现了 WSGI 的服务器上。
2.1 一个非常像"插座标准"的设计
你可以把 WSGI 想成家用电器和电网之间的插座标准。电器厂商不需要为不同发电厂定制插头，用户也不需要为不同电器配不同的电网接口，只要双方都遵循同一个插座标准，就能即插即用。
在 WSGI 的世界里：
- Web 服务器（Gunicorn、uWSGI、Waitress）负责实现"插座"的供电侧：接收 HTTP 请求，解析出 environ 字典，执行一个可调用对象，再把返回值变成 HTTP 响应。
- Web 框架（Flask、Django、FastAPI 的 WSGI 模式）负责实现"插座"的用电侧：暴露一个可调用对象，接收 environ 和 start_response，返回可迭代的响应体。
两边的接口长什么样，就是 PEP 3333 里的核心内容。
2.2 WSGI 协议的核心调用方式
WSGI 定义的是一个非常简洁的函数调用约定。服务器端会调用一个叫做 application 的可调用对象，调用方式固定为：
python复制result = application(environ, start_response)
这个调用里有两个关键参数：
- environ：一个字典，包含 HTTP 请求的所有信息。比如
REQUEST_METHOD（GET/POST）、PATH_INFO（路径）、QUERY_STRING（查询参数）、SERVER_NAME、SERVER_PORT，以及通过HTTP_前缀带过来的所有请求头。 - start_response：一个回调函数，应用在处理完请求后，用它来发送 HTTP 状态码和响应头。函数签名是
start_response(status, response_headers, exc_info=None)，其中 status 是类似"200 OK"的字符串，response_headers 是[(header_name, header_value), ...]的列表。
application 的返回值是一个可迭代对象，里面装的是响应体的字节数据。
2.3 手写一个最小的 WSGI 应用
为了让你直观感受这个契约，我直接写一个最小的 WSGI 应用，不依赖任何框架：
python复制def application(environ, start_response):
status = "200 OK"
headers = [
("Content-Type", "text/plain; charset=utf-8"),
("Content-Length", "13"),
]
start_response(status, headers)
return [b"Hello, WSGI!"]
你把这段代码存成 wsgi_app.py，然后用 Gunicorn 启动：
bash复制gunicorn -w 2 -b 0.0.0.0:8000 wsgi_app:application
访问 http://127.0.0.1:8000，浏览器里就会出现 Hello, WSGI!。这里 Gunicorn 做的事情是：把 HTTP 请求解析成 environ，调用你的 application 函数，把返回值写回 HTTP 响应。
你看，整个链路里没有任何框架参与，但依然是一个完整的 Web 服务。这说明 WSGI 本身就是一套足够底层的通用接口。
2.4 你平时写的 Flask 应用，本质上就是一个 WSGI application
当你写 Flask 应用时，app = Flask(__name__) 创建的这个 app 对象，内部就实现了 WSGI 协议要求的 __call__ 方法。所以 Gunicorn 启动 Flask 应用的命令是：
bash复制gunicorn -w 4 -b 0.0.0.0:8000 app:app
这里第一个 app 是文件名（app.py），第二个 app 是文件里定义的 Flask 实例。Gunicorn 做的就是把 HTTP 请求包装成 environ，然后调用这个 Flask 实例。Flask 内部再去做路由匹配、视图函数调用、上下文管理，最后把响应返回给 Gunicorn。
所以你现在再看 "Gunicorn 和 WSGI" 的关系，就很清晰了：Gunicorn 是 WSGI 协议的一个服务器端实现，Flask/Django 是 WSGI 协议的应用端实现，Gunicorn 和 Flask 之间完全是通过 WSGI 协议进行协作的，Flask 根本不需要知道 Gunicorn 的存在，Gunicorn 也不需要 import Flask 的代码。
3. 从 Flask 到 Gunicorn：一次实际可落地的部署过程
理解了协议之后，就该动手了。这一节我以 Flask 为例，把从零开始用 Gunicorn 部署应用的过程完整走一遍，包括启动命令、配置文件、进程守护，以及前面为什么要再放一个 Nginx。
3.1 准备一个最小的 Flask 应用
先建一个项目目录，写一个最基础的 Flask 应用：
bash复制mkdir flask-gunicorn-demo
cd flask-gunicorn-demo
python3 -m venv venv
source venv/bin/activate
pip install flask gunicorn
然后创建 app.py：
python复制from flask import Flask
app = Flask(__name__)
@app.route("/")
def index():
return {"message": "hello from flask + gunicorn"}
@app.route("/health")
def health():
return {"status": "ok"}
3.2 启动命令的每个参数都值得理解
直接在项目目录下执行：
bash复制gunicorn -w 4 -b 0.0.0.0:8000 app:app
参数拆开看：
-w 4：启动 4 个 worker 进程。-b 0.0.0.0:8000：监听所有网卡的 8000 端口。app:app：加载app.py文件中的app对象。
启动之后，你会看到类似这样的日志：
text复制[INFO] Starting gunicorn 21.2.0
[INFO] Listening at: http://0.0.0.0:8000
[INFO] Using worker: sync
[INFO] Booting worker with pid: 12345
[INFO] Booting worker with pid: 12346
Using worker: sync 这一行很关键，它表示当前使用的是默认的同步 worker 类型。后面我会专门讲 worker 类型的选择。
3.3 用配置文件代替一长串命令行参数
当配置项变多以后，命令行会变得非常长，而且不方便保存。Gunicorn 支持把配置写在一个 Python 文件里。我习惯命名为 gunicorn.conf.py，放在项目根目录：
python复制# gunicorn.conf.py
import multiprocessing
bind = "0.0.0.0:8000"
workers = multiprocessing.cpu_count() * 2 + 1
worker_class = "gthread"
threads = 4
timeout = 60
graceful_timeout = 30
keepalive = 5
max_requests = 1000
max_requests_jitter = 100
accesslog = "/var/log/flask-demo/access.log"
errorlog = "/var/log/flask-demo/error.log"
loglevel = "info"
然后启动命令就简化为：
bash复制gunicorn -c gunicorn.conf.py app:app
配置文件里的每一项有什么含义，我挑重点讲：
workers：worker 进程数量。大家常说的CPU 核数 × 2 + 1是一个经验公式，但它更适合 CPU 密集型场景。如果业务是 IO 密集型（大量等待数据库、调用外部 API），worker 数量可以适当多于这个公式，但也不是越多越好，进程切换也有开销。worker_class：worker 类型。sync是默认值，gthread是线程模式，gevent是协程模式。具体选型下一节展开。threads：在使用gthread时，每个 worker 进程内启动的线程数。timeout：worker 处理单个请求的最大秒数。超过这个时间没有响应，master 会杀掉这个 worker 并重新拉起。默认 30 秒，如果你的业务里有长耗时接口，这个值需要调大，否则会出现"请求还在处理，worker 却被杀了"的情况。graceful_timeout：在 worker 被关闭时，允许它完成当前请求的宽限时间。keepalive：HTTP keep-alive 连接保持的时间。max_requests：worker 处理完多少请求后主动重启。这是应对内存泄漏的常用手段。max_requests_jitter：在 max_requests 基础上增加一个随机浮动，让多个 worker 不会在同一时刻同时重启。
3.4 用 systemd 让 Gunicorn 常驻后台
本地命令行启动只适合调试。线上环境我会把它交给 systemd 管理，这样服务器重启后服务能自动拉起，Gunicorn 崩了也能自动恢复。
创建一个 systemd 服务文件 /etc/systemd/system/flask-demo.service：
ini复制[Unit]
Description=Flask Demo App (Gunicorn)
After=network.target
[Service]
User=www-data
Group=www-data
WorkingDirectory=/var/www/flask-demo
Environment="PATH=/var/www/flask-demo/venv/bin"
ExecStart=/var/www/flask-demo/venv/bin/gunicorn -c /var/www/flask-demo/gunicorn.conf.py app:app
Restart=always
RestartSec=5
[Install]
WantedBy=multi-user.target
启用并启动：
bash复制sudo systemctl daemon-reload
sudo systemctl enable flask-demo
sudo systemctl start flask-demo
sudo systemctl status flask-demo
有几个细节容易踩坑，我提前说：
ExecStart一定用虚拟环境里的绝对路径，不要依赖系统 PATH 去找 gunicorn。我之前在 systemd 里直接写gunicorn，结果 systemd 环境里找不到命令，服务起不来。User和Group建议用一个权限受限的专用用户，不要用 root 跑 Web 服务。WorkingDirectory必须设置成项目目录，否则 Gunicorn 找不到app.py。- systemd 内的环境变量和你在终端里是不一样的，如果应用读取了
.env文件、或者依赖某些环境变量，要在[Service]里用Environment或EnvironmentFile显式设置。
3.5 前面为什么要再放一个 Nginx
有人问过，Gunicorn 自己就能监听端口对外提供服务，为什么还要在前面放 Nginx？
我的回答是：Gunicorn 擅长处理 Python 应用，但它不适合处理静态文件和防御某些低级流量。Nginx 在架构里主要做这几件事：
- 静态文件服务。图片、CSS、JS 这类静态文件不需要经过 Python 应用，直接由 Nginx 返回，性能高出几个数量级。
- 请求反向代理。Nginx 把动态请求转发给 Gunicorn，Gunicorn 只需要专注处理业务逻辑。
- SSL 终结。HTTPS 证书配置在 Nginx 这一层，不需要每个 worker 都处理 TLS 握手。
- 请求缓冲与超时控制。慢客户端、不完整的请求在 Nginx 层就被挡掉，不会直接拖住 Gunicorn 的连接。
- 负载均衡。如果需要横向扩容，可以在 Nginx 里配置多个 upstream Gunicorn 节点。
所以一个标准的线上架构是这样：
text复制Client -> Nginx(80/443) -> Gunicorn(127.0.0.1:8000) -> Flask App
Nginx 配置示例：
nginx复制server {
listen 80;
server_name example.com;
location /static/ {
alias /var/www/flask-demo/static/;
expires 7d;
access_log off;
}
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;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_connect_timeout 60s;
proxy_read_timeout 60s;
proxy_send_timeout 60s;
}
}
proxy_set_header 里的几个头很有意义。X-Forwarded-For 和 X-Forwarded-Proto 是为了让 Flask 知道真实客户端 IP 和请求协议。如果这几个头不设置，Flask 里 request.remote_addr 拿到的会一直是 127.0.0.1。
4. 调优关键点：worker 数量、并发模型与超时配置
Gunicorn 部署起来不难，难的是调优。这一节把最核心的几个配置项讲透，告诉你不只是"怎么配"，而是"为什么这么配"。
4.1 worker 数量：公式只是起点，不要照抄
Gunicorn 的 -w 参数控制 worker 进程数量。一个 worker 同时只能处理一个请求（同步模式下），所以 worker 数量直接决定了并发上限。
常见的经验公式是 workers = CPU 核数 × 2 + 1。这个公式背后的逻辑是：每个 worker 在等待 IO 时，CPU 可以切换去处理另一个 worker 的任务，所以 worker 数比核数多一些，可以让 CPU 尽量不闲着。
但这个公式并不适用于所有场景。如果你的应用是 IO 密集型，比如大量时间在查数据库、调用外部 HTTP API，那么 worker 在等 IO 时并不占用 CPU，此时增加 worker 数可以显著提升并发能力，即使超过 CPU × 2 + 1 也是合理的。反过来，如果你的应用是 CPU 密集型，worker 数超过 CPU 核数太多，反而会因为上下文切换导致性能下降。
我实际调优时的做法是：先用默认公式跑一轮压测，然后逐步增加 worker 数，观察吞吐量和响应时间的变化。找到一个拐点，在那个值附近上下浮动，而不是死记公式。
4.2 worker_class：三种模式怎么选
Gunicorn 支持多种 worker 类型，最常用的有三种：sync、gthread、gevent。
| worker_class | 并发模型 | 适用场景 | 注意事项 |
|---|---|---|---|
| sync（默认） | 一个 worker 同时处理一个请求 | 简单应用、CPU 密集型、请求耗时短 | 一个慢请求会阻塞该 worker 后续所有请求 |
| gthread | 每个 worker 内跑多个线程 | IO 密集型，且不方便引入协程依赖 | 线程数需要控制，受 Python GIL 限制 |
| gevent | 基于协程，一个 worker 内可并发大量请求 | 高并发、IO 密集型、大量网络等待 | 需要 monkey.patch_all()，且依赖库要兼容协程 |
sync 是最简单的模式。请求来了，worker 处理完，再接下一条。如果有一个请求因为外部调用卡了 10 秒，这个 worker 在这 10 秒内就废了。所以 sync 模式下的并发能力完全靠堆 worker 进程数。
gthread 模式是我在中小型项目里比较推荐的。每个 worker 进程里可以起多个线程，线程之间共享进程内存，创建开销比进程小得多。配置方式是在配置文件中设置 worker_class = "gthread" 和 threads = 4，表示每个 worker 起 4 个线程处理请求。假设你配置 4 个 worker，每个 4 线程，最大并发就是 16。
但要注意，如果代码里有 CPU 密集型的循环或计算，Python 的 GIL 会让多线程无法真正并行，此时 gthread 的收益就会打折。
gevent 模式适合追求高并发的场景。它通过在代码层面模拟并发，把 IO 等待的时间让给其他协程，单个 worker 就能支撑上千个并发连接。但前提是代码里使用的网络库、数据库驱动都要兼容 gevent 的 monkey patch。我记得有一些 C 扩展库在 patch 之后会出现奇怪的问题，这个坑比较深。
我的选型建议很简单：没特殊需求就 gthread，要压榨高并发再考虑 gevent，纯 CPU 密集就 sync。
4.3 timeout 是个容易忽视的"隐形杀手"
Gunicorn 默认的 timeout 是 30 秒。这意味着，如果某个请求 30 秒还没处理完，master 进程会认为这个 worker 卡死了，强制把它杀掉，再启动一个新的 worker 来顶上。
你想象一下这个场景：你的应用里有个接口会去调用一个第三方 API，正常情况下 1 秒就返回，但如果第三方 API 挂起，这个请求就会一直等。如果这段时间里没有设置合理的 timeout，Gunicorn 会在 30 秒后把 worker 杀掉。客户端那边可能已经收到响应了，实际上却是 502。
所以配置 timeout 之前，先统计一下你的接口最长响应时间。如果业务里确实有超过 30 秒的长任务，就把 timeout 调大；但最好是想办法把长任务做成异步任务队列（比如 Celery），而不是让 HTTP 请求一直挂着。
4.4 keepalive、graceful_timeout 与 max_requests
-
keepalive：HTTP 连接保持存活的时间。如果一个客户端在 keepalive 时间内发起了多个请求，可以复用同一个 TCP 连接，减少握手开销。在 Nginx 反代场景下，这个值可以稍微设大一点，比如 5 秒。 -
graceful_timeout：当 Gunicorn 准备关闭一个 worker 时，会先停止接收新请求，然后等它把当前请求处理完。这个等待时间的上限就是 graceful_timeout，默认 30 秒。如果你的接口里在收到停止信号后还需要善后操作（比如关闭数据库连接池），这个值要给足。 -
max_requests+max_requests_jitter：这两个配置是为了防止内存泄漏。Python 应用长期运行后，可能因为某些第三方库的原因导致内存只增不减。设置 worker 处理完一定数量的请求后主动重启，可以让内存使用保持在一个可控水平。我常配置max_requests = 1000、max_requests_jitter = 100，让每个 worker 在 1000 到 1100 个请求之间随机重启，避免多个 worker 同时重启造成服务波动。
4.5 一个简单的压测对比思路
调优不是凭感觉，最好用数据说话。我习惯用 ab 或者 wrk 做压测。比如用 ab 模拟 2000 个请求、100 并发：
bash复制ab -n 2000 -c 100 http://127.0.0.1:8000/health
关注几个指标：Requests per second、Time per request、Failed requests。在同样的压测参数下，分别测 sync、gthread、不同 worker 数量，横向对比。我前段时间调一个小项目，同样的压测条件下，从 2 个 sync worker 换成 4 个 gthread worker（每 worker 4 线程），吞吐量大概提升了一倍多。原因就是这个服务的大部分时间都在查数据库，纯 sync 模式的并发能力被进程数卡死了。
但也要注意，压测结果只能作为相对参考。真实流量里请求的分布远比压测复杂，所以调优后还要在线上逐步放量观察。
5. 部署之后容易踩的坑，以及排查思路
Gunicorn 部署上去不代表万事大吉。这一节我挑几个自己实际踩过的坑，把完整的排查过程写出来，给你当参考。
5.1 坑一：timeout 默认值导致"偶发性 502"
现象：服务刚部署完很正常，但运行一段时间后，偶尔会出现 502 错误，尤其是某个复杂查询被触发的时候。Gunicorn 的错误日志里有 Worker timed out after 30 seconds 的记录。
排查过程：一开始以为是数据库连接池问题，查了数据库慢查询日志，发现部分查询确实超过 1 秒，但远没有到 30 秒。继续看 Gunicorn 的错误日志，发现 Worker timed out 出现了好几次。于是怀疑是某个外部 API 调用挂起，导致 worker 一直没有返回。
后来定位到代码里有一个调用第三方服务的逻辑，没有设置超时时间，默认的 HTTP 客户端可能会一直等待。这个请求把 worker 拖住了，到 30 秒被 Gunicorn 强制杀掉，期间其他请求也无法被这个 worker 处理，最终表现为 502。
修复方式有两层：第一层是在业务代码里给所有外部 HTTP 调用都加上超时时间；第二层是把 Gunicorn 的 timeout 调到一个合理的值，比如 60 秒，给业务一些余量，但不要把它当作根本解决手段。
5.2 坑二：静态文件直接走 Gunicorn，性能一塌糊涂
现象：页面加载慢，查看 Gunicorn access log，发现大量请求都是 /static/xxx.css 或 /static/xxx.js。
排查过程：这个项目的 Flask 代码里配置了静态文件目录，直接通过 Flask 返回静态资源。请求量一大，worker 全部被静态文件请求占满，真正处理业务逻辑的 worker 就不够了。
修复方式：把静态文件全部交给 Nginx 处理。在 Flask 里设置 static_folder 指向项目里的静态目录，然后在 Nginx 配置中，别名映射这个目录，凡是 /static/ 开头的请求都不经过 Gunicorn，直接由 Nginx 返回。改完之后，Gunicorn 的 access log 里静态请求几乎消失了，页面加载时间明显下降。
5.3 坑三：多进程模式下，内存变量"不共享"了
现象：代码里用了一个全局变量做计数器，在本地开发时测试正常，部署到 Gunicorn 上后，计数器值非常奇怪，每次请求结果都不一样。
排查过程：本地开发环境默认是单进程，全局变量在进程内是共享的。Gunicorn 默认启动多个 worker，每个 worker 是一个独立进程，内存空间互相隔离。请求被负载到哪个 worker，操作的就是哪个 worker 的全局变量，所以不同请求之间看到的状态不一致。
修复方式：这类状态不能放在进程内存里，应该放到 Redis 或数据库里。如果是简单的全局配置，可以用 threading.local() 做线程隔离，但多进程下还是建议走外部存储。
5.4 坑四：--reload 被带到生产环境
Gunicorn 有个 --reload 参数，开发时改完代码自动重载很方便。但如果在生产环境误开了这个参数，代码文件一变动，所有 worker 就会重启，用户正在处理的请求会直接中断。
我见过有人把 --reload 写在 systemd 的 ExecStart 里，代码发布时用 git pull，结果每次发布，服务都要重启一次，所有在线请求全部被打断。加上 SQLAlchemy 的连接池在 worker 被强杀后还需要重新建立，服务恢复期还会有大量查询失败。
排查过程：其实很简单，看 ps -ef | grep gunicorn，发现命令行里有 --reload。去掉后重启服务，问题就消失了。
建议生产环境的配置里明确不写 --reload，开发环境单独用一个配置文件区分。
5.5 坑五：504/502 的排查思路
线上出现 504/502 时，先分清是哪一层报的。如果浏览器直接提示 502 Bad Gateway，一般是 Nginx 和 Gunicorn 之间通信失败；如果提示 504 Gateway Timeout，一般是 Nginx 把请求转发给 Gunicorn 后，Gunicorn 在 Nginx 的超时时间内没有返回。
排查步骤我来梳理一下：
- 先看 Gunicorn 的进程状态：
ps aux | grep gunicorn，确认 worker 进程是否存在、有没有反复重启。 - 看 Gunicorn error log：有没有
Worker timed out、Worker failed to boot之类的记录。 - 看 Nginx error log：确认连接 Gunicorn 时是否发生
connect() failed（Gunicorn 没在监听）、upstream timed out（Gunicorn 处理太慢）。 - 直接 curl Gunicorn 所在的端口（如
curl 127.0.0.1:8000/health），确认 Gunicorn 本身是否健康。 - 如果 Gunicorn 在 Nginx 转发时正常，就要对比 Nginx 和 Gunicorn 两边的 timeout 配置，看哪一层先超时。
6. 怎么确认 Gunicorn 真的在按预期工作
写完部署和调优，再分享几个日常检查的小方法，帮你确认 Gunicorn 在线上是否平稳运行。
6.1 看进程状态和日志
Gunicorn 启动后，ps -ef | grep gunicorn 会看到一堆进程。最上面一个是 master，下面一串是 worker。如果 master 一直在，但 worker 的 PID 经常变化，说明有 worker 被频繁回收，一般跟 timeout 或者 max_requests 有关，要去翻 error log 确认具体原因。
Gunicorn 的 access log 默认是不开启的，但生产环境我强烈建议打开，因为 access log 可以帮你观察 QPS、接口响应时间、客户端 IP 分布。配置里加上 accesslog = "/var/log/flask-demo/access.log" 就能开启。error log 里如果频繁出现 Worker timeout 或者 Exception，就要赶紧处理了。
6.2 用四层和七层探测检查健康状态
如果 Nginx 配置了健康检查，需要一个健康检查端点。我一般会在应用里加一个 /health 接口，返回 {"status": "ok"}，并且在这个接口里顺带检查数据库连接是否正常。但要注意，健康检查接口不能有太重的逻辑，否则探测频率一高，反而会给服务增加压力。
我自己用 Nginx 做健康检查时，会单独设置一个 location：
nginx复制location = /health {
proxy_pass http://127.0.0.1:8000/health;
access_log off;
}
这样每次探测只走一个非常轻量的接口，不会把无关请求写进 access log。
6.3 监控 worker 的重启频率
在 systemd 服务里，Gunicorn 的 worker 死掉后会被 master 自动拉起，所以进程不会彻底消失。但如果 worker 重启过于频繁，说明应用状态不稳定，常见的诱因有：内存泄漏触发 OOM、代码里有未捕获的异常导致 worker 崩溃、或者 timeout 设置不合理让 master 频繁回收。
我建议至少看一下 /var/log/syslog 里有没有 OOM kill 的记录。如果有，结合 max_requests 来做主动重启，内存使用就会平稳很多。
7. 最后的一段经验：先量化，再调优
在调 Gunicorn 参数之前，先搞清楚你的瓶颈到底在哪里。这个道理我是在一次线上事故之后才真正想明白的。
当时有个服务并发上不去，Gunicorn 的 worker 数从 4 加到 16，压测结果几乎没变化。后来排查才发现，瓶颈根本不在于 Gunicorn，而在于数据库连接池太小，所有请求都在等待数据库连接。把数据库连接池调大之后，同样的 Gunicorn 配置，吞吐量直接上来了。
所以 Gunicorn 只是 Web 服务链路里的一个环节，它决定的是"请求能同时进来多少"，但每个请求能不能快速返回，取决于你的业务代码、数据库、外部服务。调优 Gunicorn 的正确姿势，是先压测找到瓶颈在哪一层，再针对性地改配置。
如果是刚开始接触生产部署，我的建议很简单：先按默认配置跑起来，然后把 gthread 加上，max_requests 加上，时间超时按业务情况调一调，有条件再在前面放一个 Nginx。小并发场景下，这些配置已经够用，等真正遇到性能瓶颈，再回来对照着压测和日志做细调。生产环境里，稳定比花哨重要得多。