Flask应用部署到Linux服务器后,如何用Gunicorn与systemd托管运行?

发布人:A5数据发布时间:2026-11-14 10:49阅读量:31

Flask 应用上线后,建议由 Gunicorn 负责启动 WSGI 应用,再交给 systemd 管理进程、开机启动和异常退出后的重启。对外访问时,让 Gunicorn 只监听本机地址,由 Nginx 或现有负载均衡接收公网流量;这样可以把应用进程管理与 HTTPS、域名入口分开处理。

部署方式概览配图

以下示例以 Debian/Ubuntu、Python 3 和 systemd 为基础,服务名为 myflaskapp,项目目录为 /srv/myflaskapp,Gunicorn 监听 127.0.0.1:8000。命令中的域名、路径、端口和项目导入名需要按实际环境调整。操作前确认有可用的管理账号,并保留现有服务配置和应用文件的备份;如果服务器采用其他发行版,先核对软件包管理器、Python 虚拟环境包名和 Nginx 配置目录。

A5idc数据为 Flask 网站、业务后台和接口服务提供中国香港、美国、日本、韩国、中国台湾、新加坡及马来西亚等地区的物理服务器资源。不同CPU、内存、SSD或NVMe存储、线路与带宽配置,可为Gunicorn托管的应用进程、数据库及多任务服务提供硬件基础;香港和美国还覆盖多IP、GPU及存储型产品,适用于接口服务、业务后台和数据归档等场景。

一、检查环境并准备项目

先确认系统版本、Python 和 systemd 均可用:

cat /etc/os-release
python3 --version
systemctl --version

Debian/Ubuntu 上如果缺少 Python 虚拟环境组件,可安装:

sudo apt update
sudo apt install python3 python3-venv python3-pip

如果依赖包含需要编译的扩展,安装对应的系统开发包;不要在没有确认依赖需求时批量添加编译工具。

准备 WSGI 入口

Gunicorn 需要能够导入项目中的 WSGI 应用。若现有项目已经提供了入口,例如 wsgi.py 中的 app 对象,应使用实际模块名和变量名。下面用应用工厂演示一种常见组织方式:

# app.py
import os

from flask import Flask


def create_app():
    app = Flask(__name__)

    # 若应用使用 Flask session,请通过环境变量配置稳定且保密的密钥。
    secret_key = os.environ.get("APP_SECRET_KEY")
    if secret_key:
        app.config["SECRET_KEY"] = secret_key

    @app.get("/")
    def index():
        return "Flask is running"

    @app.get("/healthz")
    def healthz():
        return {"status": "ok"}, 200

    return app
# wsgi.py
from app import create_app

app = create_app()

这里的 wsgi:app 表示从 wsgi.py 导入名为 app 的对象。如果项目入口在 myproject/web.py,则应按实际包结构调整 Gunicorn 参数,例如 myproject.web:app。生产环境不要用 flask run 或 Flask 自带开发服务器承载公网流量。

依赖应由项目维护。下面的版本范围仅作格式示例;正式部署应将经过验证的依赖版本写入项目的锁定文件,并在测试环境确认升级兼容性:

Flask>=3.0,<4.0
gunicorn>=22,<24

建立专用运行账号和目录

让 Flask 进程使用专用的无登录账号运行,避免直接以 root 身份启动应用:

sudo useradd --system --user-group \
  --home-dir /srv/myflaskapp \
  --create-home \
  --shell /usr/sbin/nologin \
  flaskapp

sudo install -d -o root -g flaskapp -m 0750 /srv/myflaskapp

将 app.py、wsgi.py 和依赖文件放入项目目录。以下命令假设这些文件位于当前目录:

sudo install -o root -g flaskapp -m 0640 app.py /srv/myflaskapp/app.py
sudo install -o root -g flaskapp -m 0640 wsgi.py /srv/myflaskapp/wsgi.py
sudo install -o root -g flaskapp -m 0640 requirements.txt /srv/myflaskapp/requirements.txt

项目源文件由 root 拥有、运行账号只读,可减少应用进程意外改写代码的风险。若应用需要保存上传文件、缓存或其他持久数据,应单独创建可写目录,不要因此放宽整个代码目录的权限。例如:

sudo install -d -o flaskapp -g flaskapp -m 0750 /var/lib/myflaskapp

应用代码需要明确使用该数据目录;Gunicorn 和 systemd 不会自动把应用写入内容转移到这里。

二、创建虚拟环境并安装依赖

在项目目录中创建独立虚拟环境,再安装项目依赖:

sudo python3 -m venv /srv/myflaskapp/venv
sudo /srv/myflaskapp/venv/bin/python -m pip install -r /srv/myflaskapp/requirements.txt

确认 Gunicorn 和应用模块均能被导入:

sudo -u flaskapp sh -c 'cd /srv/myflaskapp && ./venv/bin/gunicorn --check-config wsgi:app'

也可以单独检查 WSGI 导入:

sudo -u flaskapp sh -c 'cd /srv/myflaskapp && ./venv/bin/python -c "from wsgi import app; print(app)"'

如果命令提示缺少模块,先确认依赖文件中包含对应包,并且安装与运行使用的是同一个虚拟环境。不要通过全局 pip 安装依赖来掩盖虚拟环境配置错误。

如应用使用 Flask session 或其他依赖密钥的功能,可在服务环境文件中配置密钥。不要把密钥提交到代码仓库或写进公开的服务文件:

sudo install -d -o root -g flaskapp -m 0750 /etc/myflaskapp
sudoedit /etc/myflaskapp/myflaskapp.env

环境文件可采用如下格式,实际值应替换为随机生成的密钥:

APP_SECRET_KEY=替换为足够长的随机值

例如可用 Python 生成十六进制随机字符串:

python3 -c 'import secrets; print(secrets.token_hex(32))'

保存后限制文件读取权限,使运行账号所在组可读,而其他用户不可读:

sudo chown root:flaskapp /etc/myflaskapp/myflaskapp.env
sudo chmod 0640 /etc/myflaskapp/myflaskapp.env

如果应用不需要该环境变量,可以不创建环境文件;后续服务配置中的前置短横线表示该文件缺失时仍允许服务启动。

三、配置 systemd 托管 Gunicorn

创建服务单元:

sudoedit /etc/systemd/system/myflaskapp.service

写入以下配置:

[Unit]
Description=Gunicorn service for myflaskapp
After=network.target

[Service]
Type=simple
User=flaskapp
Group=flaskapp
WorkingDirectory=/srv/myflaskapp
Environment="PATH=/srv/myflaskapp/venv/bin"
Environment="PYTHONUNBUFFERED=1"
EnvironmentFile=-/etc/myflaskapp/myflaskapp.env
ExecStart=/srv/myflaskapp/venv/bin/gunicorn \
    --workers 2 \
    --bind 127.0.0.1:8000 \
    --access-logfile - \
    --error-logfile - \
    --capture-output \
    --timeout 30 \
    wsgi:app
Restart=on-failure
RestartSec=3
TimeoutStopSec=30
UMask=0027
NoNewPrivileges=true
PrivateTmp=true

[Install]
WantedBy=multi-user.target

其中,User 和 Group 指定运行身份,WorkingDirectory 决定 Python 导入项目模块时的工作目录,ExecStart 使用虚拟环境中的 Gunicorn。--bind 127.0.0.1:8000 让服务只接受本机连接,避免 Gunicorn 端口直接暴露到公网。--access-logfile - 和 --error-logfile - 将访问日志与错误日志输出到标准输出和标准错误,便于通过 journal 查询。

示例中的两个 worker 只是一个起点,不代表适用于所有应用。worker 数量会影响并发处理能力,也会增加内存占用;若应用依赖较重或服务器内存有限,可先从一个 worker 开始,再结合内存、CPU 和响应延迟调整。处理时间较长的任务也不宜仅靠延长 HTTP 请求超时来承担,通常应与请求处理路径分开设计。

设置服务文件权限,检查配置后加载并启动服务:

sudo chown root:root /etc/systemd/system/myflaskapp.service
sudo chmod 0644 /etc/systemd/system/myflaskapp.service
sudo systemd-analyze verify /etc/systemd/system/myflaskapp.service
sudo systemctl daemon-reload
sudo systemctl enable --now myflaskapp

enable --now 会同时设置开机启动并立即启动服务。检查运行状态和启动日志:

sudo systemctl status myflaskapp --no-pager -l
sudo journalctl -u myflaskapp -n 100 --no-pager

正常情况下,状态应显示服务正在运行;如果服务启动失败,先查看日志中的 Python 异常或 Gunicorn 错误,再处理原因。修正服务文件后需要重新执行 systemctl daemon-reload;只修改应用代码或环境变量时,通常需要重启服务使变更生效:

sudo systemctl restart myflaskapp

四、验证本机服务与外部入口

先从服务器本机访问 Gunicorn。下面请求示例中的 /healthz 是前述 Flask 示例提供的健康检查路由:

curl --fail --show-error --include http://127.0.0.1:8000/healthz

预期可看到 HTTP 200 响应以及类似以下内容:

HTTP/1.1 200 OK
Content-Type: application/json
...
{"status":"ok"}

若项目没有 /healthz 路由,应改用应用实际存在的路径。健康检查尽量只判断服务是否能处理请求;是否检查数据库等外部依赖,应根据健康检查的用途单独决定。

如果服务器使用 Nginx 作为公网入口,可将请求转发给本机 Gunicorn。以下配置适用于 HTTP 转发演示,正式站点还需要按域名配置 HTTPS,并使用有效的证书路径:

server {
    listen 80;
    server_name example.com;

    location / {
        proxy_pass http://127.0.0.1:8000;
        proxy_http_version 1.1;
        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;
    }
}

将 example.com 替换为实际域名,并按当前发行版的 Nginx 配置布局启用站点。改动前备份现有配置;测试通过后再重载:

sudo nginx -t
sudo systemctl reload nginx

随后从可访问该域名的客户端请求站点,确认返回内容和 HTTPS 证书符合预期。若 TLS 在负载均衡器等其他可信入口终止,应按实际链路配置转发头;应用只有在信任的代理数量和来源明确时,才应读取这些头部。不要在不可信客户端可直接连接的情况下盲目信任 X-Forwarded-*。

日志通过 journal 查看,不需要另行将 Gunicorn 日志写到未配置轮转的普通文件:

sudo journalctl -u myflaskapp -f

实时跟踪使用 -f,按时间过滤可用 --since,例如:

sudo journalctl -u myflaskapp --since "30 minutes ago" --no-pager

日志中不应打印密码、会话密钥或访问令牌。日志保留期限和磁盘用量由服务器的 journald 配置决定,生产环境应纳入现有日志容量管理。

五、常见启动与访问异常

排查时先看 systemd 状态与应用日志,再检查端口、文件权限和反向代理配置,避免在没有依据时直接调整防火墙或扩大目录权限。

现象常见原因检查与处理
服务立即退出,日志出现 ModuleNotFoundError依赖未安装、入口模块名不对,或工作目录错误检查 WorkingDirectory、wsgi:app 和虚拟环境中的依赖;用运行账号重新执行导入检查
日志出现 Permission denied运行账号无法读取代码、虚拟环境或环境文件检查路径各级目录是否允许组执行,以及文件是否允许运行账号所在组读取;仅对应用确实需要写入的目录授权
日志出现端口已占用8000 端口已有进程监听用 sudo ss -lntp 查看监听进程;确认用途后再决定是否更换 Gunicorn 端口或处理旧服务
Nginx 返回 502Gunicorn 未运行、Nginx 上游地址或端口不匹配先检查 systemd 状态,再在服务器本机请求 127.0.0.1:8000,最后核对 Nginx 的 proxy_pass
服务反复重启应用启动异常、环境文件格式错误或外部依赖不可用查看 journalctl -u myflaskapp 的最新错误;修复原因后再启动,不要只靠提高重启频率掩盖故障
请求耗时增加或进程被系统终止worker 数量不合适、内存不足或请求工作负载变化结合系统内存、CPU 和应用日志调整 worker;如怀疑内存不足,可检查系统内核日志,不要只通过增加 worker 提升并发

如果服务因连续失败进入启动频率限制,修复配置或应用错误后,可清除失败状态并重新启动:

sudo systemctl reset-failed myflaskapp
sudo systemctl start myflaskapp

这不会修复应用本身;启动前仍应确认最新日志中的故障原因已处理。

六、变更后的验收与回滚

应用升级时,保留旧版本文件和当前服务配置,再更新应用与依赖。更新完成后重启服务,并依次检查服务状态、本机健康检查、外部域名访问和日志。不要在没有备份的情况下覆盖正在运行的代码;数据库变更还需单独确认兼容性与备份策略。

若本次是全新部署且需要撤回,可先停止并取消服务的开机启动:

sudo systemctl disable --now myflaskapp

这会停止 Gunicorn 服务,但不会自动删除应用文件、日志或数据。若此前也新增了 Nginx 站点,应先备份对应配置,再按当前发行版的站点管理方式撤回该入口,执行 nginx -t 确认配置有效后再重载 Nginx。不要因回滚 Web 服务而误删应用数据目录。

验收与回滚检查项:

  • systemctl is-enabled myflaskapp 显示服务已启用,systemctl is-active myflaskapp 显示服务正在运行。
  • 本机请求应用健康检查路径返回预期状态码,外部入口的域名、响应内容和 HTTPS 证书符合预期。
  • Gunicorn 只绑定本机地址;公网流量通过已配置的可信入口转发。
  • 应用日志没有持续重复的启动异常,敏感密钥未写入日志或代码仓库。
  • 代码、服务文件和入口配置均保留可用备份;停止服务不会影响需要保留的持久数据。
  • 回滚后再次检查 systemd 状态、Nginx 配置有效性及站点访问结果,确认流量已回到预期入口或服务已安全下线。

本文由A5数据原创发布,转载请注明出处:https://www.a5idc.com/helpcontent/9356.html

相关推荐