把 Flask 部署到 Gunicorn 与 Nginx 代理后

作者： Flask 官方文档（该页未标注个人作者）
原文标题： Gunicorn
文档版本： Flask 文档 3.1.x
原文： Gunicorn — Flask Documentation

Gunicorn 在部署链路中的位置

Gunicorn 是一个纯 Python 的 WSGI 服务器，配置方式直接，并提供多种 worker 实现供性能调优。它通常容易接入托管平台，不需要额外依赖或编译，也可以通过 gevent 提供异步 worker。它不原生支持 Windows，但可以在 WSL 中运行。

Flask 文档建议阅读 Gunicorn 自己的文档，并使用 gunicorn --help 查看可用选项。这里的重点是如何安装、启动 Flask 应用，以及在外部反向代理前运行 Gunicorn 时应留意的边界。

创建虚拟环境并安装

先进入应用项目，创建并启用虚拟环境，然后安装应用本身和 Gunicorn：

cd hello-app
python -m venv .venv
. .venv/bin/activate
pip install .  # 安装当前应用
pip install gunicorn

这些命令采用类 Unix shell 写法。由于 Gunicorn 在 Windows 上只通过 WSL 运行，在 Windows 主机上应在 WSL 环境中执行。

指定 Flask 应用并启动

Gunicorn 必须知道怎样载入 Flask 应用，参数格式为：

模块导入路径:应用变量

左侧是包含应用的 Python 模块点分导入名，右侧是模块里的应用变量。使用工厂函数模式时，右侧可以写成函数调用。

如果应用在 hello.py 中定义了 app，可以这样启动：

gunicorn -w 4 'hello:app'

这相当于从 hello 模块导入 app。如果模块提供 create_app 工厂函数，则可以调用工厂：

gunicorn -w 4 'hello:create_app()'

命令中的 -w 指定要运行的进程数。Gunicorn 文档把 CPU 核数 × 2 作为可以开始尝试的数值；默认只有一个 worker，对于默认的同步 worker 类型通常不是理想起点。这个建议只是调优起点，具体值仍应结合应用与部署环境决定。

Gunicorn 默认不会显示每个请求的访问日志，只显示 worker 信息和错误。如果要把 access log 输出到标准输出，可以加上：

gunicorn --access-logfile=- -w 4 'hello:create_app()'

在 Nginx 等反向代理后运行

Gunicorn 不应以 root 身份运行。否则，应用代码也会以 root 权限执行，带来不必要的安全风险；相应地，非 root 进程不能直接绑定 80 或 443 端口。文档建议在 Gunicorn 前放置 Nginx 或 Apache httpd 这样的反向代理。

Gunicorn 虽然可以绑定所有外部 IP 地址，例如：

gunicorn -w 4 -b 0.0.0.0 'hello:create_app()'

但如果前面已经配置了反向代理，就不要这样公开绑定。否则客户端可能绕过代理，直接访问 Gunicorn。原文还特别提醒：0.0.0.0 是监听地址，不是可在浏览器地址栏中访问的主机地址；浏览器应使用具体 IP 地址。

范围说明： 本条授权的 Flask 页面只说明了 Nginx/Apache 应放在 Gunicorn 前，以及反向代理部署时不应把 Gunicorn 绑定到所有外部地址；它没有提供 Nginx 的 server 配置、转发头配置或 Flask ProxyFix 设置。因此本文保留上述部署边界，不虚构这些配置步骤。

何时考虑 gevent worker

Gunicorn 的同步 worker 对多数用例已经够用。如果应用需要同时维持许多长时间运行的连接，可以考虑文档提到的 gevent 异步 worker：

gunicorn -k gevent 'hello:create_app()'

这里的“异步”指 Gunicorn 的 gevent worker，不是 Python 的 async/await，也不是 ASGI 服务器规范。使用时，gevent 要求 greenlet >= 1.0；如果使用 PyPy，则要求 PyPy >= 7.3.7。

小结

部署时先在虚拟环境内安装应用和 Gunicorn，再通过 模块:应用变量 或工厂函数调用指定 Flask 应用。根据需要配置 worker 数量和 access log；生产环境不要以 root 启动，也不要在反向代理前使用 0.0.0.0 把 Gunicorn 暴露给所有外部网络。若要编写完整的 Nginx 转发与代理信任配置，需要相应的 Nginx 和 Flask 代理配置来源，本页没有涵盖。

许可说明： 原文页面未列出明确的文章转载许可。