ZEFE BLOG-生产环境部署 Python Web 应用

关于 Gunicorn 详细用法、systemd 守护配置 和 Nginx 反向代理配置 的完整总结，适用于生产环境部署 Python Web 应用（如 Flask）。

一、Gunicorn 详细用法

1. 什么是 Gunicorn？

Gunicorn（Green Unicorn）是一个 Python WSGI HTTP 服务器，采用 pre-fork 模型，用于在生产环境中运行 Python Web 应用，提供高并发、稳定性和安全性。

2. 安装

bash

复制

pip install gunicorn

3. 基本命令格式

bash

复制

gunicorn [OPTIONS] MODULE_NAME:VARIABLE_NAME

MODULE_NAME：Python 模块文件名（不含 .py）。
VARIABLE_NAME：WSGI 应用实例的名称（通常是 app 或 application）。

示例（假设 app.py 中有 app = Flask(__name__)）：

bash

复制

gunicorn app:app

4. 常用命令行参数

参数	作用	示例
`-w`, `--workers`	工作进程数，通常为 `2*CPU核心数+1`	`-w 4`
`-b`, `--bind`	绑定地址和端口，可指定 IP:端口或 Unix Socket	`-b 0.0.0.0:8000` `-b unix:/tmp/gunicorn.sock`
`-k`, `--worker-class`	工作类型，默认 `sync`，异步可选 `gevent`、`eventlet`，ASGI 用 `uvicorn.workers.UvicornWorker`	`-k gevent`
`--timeout`	请求超时时间（秒），超时后 worker 会被重启	`--timeout 120`
`--log-level`	日志级别：`debug`, `info`, `warning`, `error`	`--log-level info`
`--access-logfile`	访问日志文件路径，`-` 表示输出到标准输出	`--access-logfile ./access.log`
`--error-logfile`	错误日志文件路径	`--error-logfile ./error.log`
`-c`, `--config`	指定配置文件	`-c gunicorn.conf.py`

5. 使用配置文件

创建 gunicorn.conf.py：

python

复制

# gunicorn.conf.py
bind = "127.0.0.1:8000"          # 监听本机 8000 端口，仅允许 Nginx 访问
workers = 4                       # 工作进程数
worker_class = "sync"             # 同步类型（适用于 Flask）
timeout = 120                      # 超时时间
accesslog = "/var/log/gunicorn/access.log"
errorlog = "/var/log/gunicorn/error.log"
loglevel = "info"

启动：

bash

复制

gunicorn -c gunicorn.conf.py app:app

6. 工作进程类型说明

sync：默认，每个 worker 一次处理一个请求，适合 I/O 少、CPU 密集的应用。
gevent / eventlet：基于协程的异步 worker，适合 I/O 密集型应用（如大量网络请求）。
uvicorn.workers.UvicornWorker：用于 FastAPI、Starlette 等 ASGI 应用。

二、systemd 守护配置（确保服务自动重启）

1. 创建服务单元文件

使用 root 权限创建 /etc/systemd/system/myapp.service（文件名自定义，如 clash2v2ray.service）：

ini

复制

[Unit]
Description=My Python Web App (Gunicorn)
After=network.target

[Service]
User=www-data
Group=www-data
WorkingDirectory=/opt/myapp
Environment="PATH=/opt/myapp/venv/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
ExecStart=/opt/myapp/venv/bin/gunicorn -c /opt/myapp/gunicorn.conf.py app:app
Restart=always
RestartSec=5
StandardOutput=journal
StandardError=journal
SyslogIdentifier=myapp

[Install]
WantedBy=multi-user.target

关键配置说明：

User/Group：以普通用户运行，增强安全性（确保用户对项目目录有读权限）。
WorkingDirectory：设置工作目录。
Environment：设置 PATH，优先使用虚拟环境的 gunicorn。
ExecStart：启动命令，使用绝对路径调用 gunicorn，并引用配置文件。
Restart=always：任何退出原因都自动重启。
RestartSec=5：重启前等待 5 秒。
StandardOutput/Error=journal：日志输出到 systemd journal。

2. 启动与管理

bash

复制

# 重新加载 systemd 配置
sudo systemctl daemon-reload

# 启动服务
sudo systemctl start myapp

# 设置开机自启
sudo systemctl enable myapp

# 查看状态
sudo systemctl status myapp

# 查看实时日志
sudo journalctl -u myapp -f

三、Nginx 反向代理配置

1. 安装 Nginx（如果未安装）

bash

复制

# Ubuntu/Debian
sudo apt update && sudo apt install nginx

# CentOS/RHEL
sudo yum install nginx

2. 创建 Nginx 虚拟主机配置文件

在 /etc/nginx/sites-available/ 下创建 myapp（Ubuntu）或在 /etc/nginx/conf.d/ 下创建 myapp.conf（CentOS）：

nginx

复制

server {
    listen 80;
    server_name your-domain.com;  # 替换为你的域名或 IP

    # 静态文件直接由 Nginx 处理（如果有）
    location /static/ {
        alias /opt/myapp/static/;  # 静态文件目录
        expires 30d;
    }

    # 动态请求转发给 Gunicorn
    location / {
        proxy_pass http://127.0.0.1:8000;  # 与 Gunicorn 绑定的地址一致
        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;
    }
}

3. 启用配置并测试

bash

复制

# 创建软链接启用站点（Ubuntu）
sudo ln -s /etc/nginx/sites-available/myapp /etc/nginx/sites-enabled/

# 测试配置是否正确
sudo nginx -t

# 重新加载 Nginx
sudo systemctl reload nginx

4. 可选：配置 HTTPS（使用 Let's Encrypt）

bash

复制

sudo apt install certbot python3-certbot-nginx
sudo certbot --nginx -d your-domain.com

四、整体部署流程总结

准备应用：将 Flask 应用代码放在 /opt/myapp，创建虚拟环境并安装依赖。
配置 Gunicorn：编写 gunicorn.conf.py，设置合适的 workers 和绑定地址（建议 127.0.0.1:8000）。
配置 systemd：创建服务单元文件，确保 Gunicorn 作为守护进程运行。
配置 Nginx：设置反向代理，处理静态文件，并可选择配置 HTTPS。
启动服务：依次启动 Gunicorn（通过 systemd）和 Nginx，并设置开机自启。
监控与日志：使用 journalctl 查看应用日志，使用 Nginx 日志分析访问情况。

这套组合是目前 Python Web 应用最经典、稳定、高性能的生产部署方案。如果遇到问题，可以检查日志定位（journalctl -u myapp -f 和 tail -f /var/log/nginx/error.log）。