在Linux服务器部署Gunicorn应用,怎样用systemd管理服务进程?

发布人:A5数据发布时间:2026-11-14 09:46阅读量:34

Gunicorn 负责运行 Python Web 应用,systemd 负责在系统启动时拉起服务、监控主进程并收集标准输出和错误日志。首次部署时,可以把 Gunicorn 绑定到本机回环地址,由 Nginx 等 Web 服务器接收外部请求,再转发到 Gunicorn;这样应用端口不会直接暴露到公网。

部署关系说明配图

下面以 Debian 或 Ubuntu、Python 3、systemd 和 Flask WSGI 应用为例。示例服务名为 myapp,使用独立系统账户和虚拟环境。其他发行版的包管理命令可能不同;如果应用不是 Flask,需按实际项目调整应用入口。

面向需要长期运行的 Python Web 应用与业务接口,A5idc数据提供香港、美国、日本等多地物理服务器,涵盖 Xeon Gold、AMD EPYC 等计算平台,并有 SSD、NVMe 存储及不同网络线路方案。网站、业务后台和接口服务可部署在相应服务器上,由 Gunicorn 承载请求、systemd 管理服务进程,形成匹配应用运行需求的计算与网络资源基础。

1. 检查环境与准备应用

先确认系统使用 systemd,并检查 Python 环境:

python3 --version
systemctl --version

Debian 或 Ubuntu 缺少 Python 虚拟环境组件时,可安装:

sudo apt-get update
sudo apt-get install -y python3 python3-venv

应用目录中至少应有项目代码和依赖清单。以下示例假定文件名为 app.py 和 requirements.txt,且 app.py 中的 Flask 对象名为 app。Gunicorn 的 app:app 表示“从 app 模块中加载名为 app 的对象”。

如果项目尚无可用于检查的健康接口,可添加一个简单路由:

from flask import Flask

app = Flask(__name__)

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

准备部署时,确认依赖清单与项目代码相符。若项目使用锁定文件或已有部署规范,应优先按项目规范安装依赖,不要用示例依赖替换实际清单。

2. 创建服务账户与发布目录

Gunicorn 不应以 root 身份运行。先检查服务账户是否已存在;如果不存在,再创建一个不能交互登录的系统账户:

getent passwd myapp

确认没有同名账户后执行:

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

创建发布目录。使用版本化发布目录,后续升级时可以切回旧版本,而不必覆盖当前文件:

sudo install -d -o root -g myapp -m 0750 /srv/myapp
sudo install -d -o root -g myapp -m 0750 /srv/myapp/releases
sudo install -d -o root -g myapp -m 0750 /srv/myapp/releases/r1

将项目所需文件复制到首个版本目录。下面只复制入口文件和依赖清单,实际项目还应复制运行所需的模块、模板和静态资源;不要把本机虚拟环境、版本控制目录或开发用密钥一并复制进去。

sudo cp -a app.py requirements.txt /srv/myapp/releases/r1/

检查目录和文件权限。服务账户需要读取代码和执行虚拟环境中的 Gunicorn,但不需要修改发布文件:

sudo chown -R root:myapp /srv/myapp/releases/r1
sudo chmod -R g+rX /srv/myapp/releases/r1

此时可用以下命令查看权限:

namei -l /srv/myapp/releases/r1/app.py

路径上的目录需要允许服务账户逐级进入,应用代码需要对该账户可读。若项目还需要上传文件、缓存或生成报告,应将这些可写数据放在单独目录,例如 /var/lib/myapp,不要让应用进程直接改写代码发布目录:

sudo install -d -o myapp -g myapp -m 0750 /var/lib/myapp

3. 创建虚拟环境并安装依赖

在发布目录中创建虚拟环境,然后安装项目依赖:

sudo python3 -m venv /srv/myapp/releases/r1/venv
sudo /srv/myapp/releases/r1/venv/bin/python -m pip install \
  -r /srv/myapp/releases/r1/requirements.txt

确保服务账户可以读取依赖并执行 Gunicorn:

sudo chown -R root:myapp /srv/myapp/releases/r1
sudo chmod -R g+rX /srv/myapp/releases/r1

验证 Gunicorn 是否安装成功:

sudo -u myapp /srv/myapp/releases/r1/venv/bin/gunicorn --version

如果命令提示找不到 Gunicorn,检查 requirements.txt 是否包含项目所需的 Gunicorn 包,再查看 pip 安装过程和虚拟环境路径。不要直接改用系统级 Python 安装包来掩盖虚拟环境配置错误。

创建指向当前版本的软链接:

sudo ln -s /srv/myapp/releases/r1 /srv/myapp/current

确认链接指向正确目录:

readlink -f /srv/myapp/current

预期路径为 /srv/myapp/releases/r1。systemd 服务将通过 /srv/myapp/current 访问应用,因此后续切换版本时无需修改服务文件。

4. 准备环境变量

配置项和密钥不宜写入 systemd 服务文件,也不要提交到代码仓库。创建专用配置目录和环境文件:

sudo install -d -o root -g myapp -m 0750 /etc/myapp
sudo tee /etc/myapp/myapp.env >/dev/null <<'EOF'
APP_ENV=production
SECRET_KEY=请替换为实际生成的随机值
EOF
sudo chown root:myapp /etc/myapp/myapp.env
sudo chmod 0640 /etc/myapp/myapp.env

可以用 Python 生成随机密钥,再通过安全方式填入环境文件:

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

环境变量名称和内容应与应用的配置代码一致。systemd 的环境文件不是 Shell 脚本,不能依赖其中的命令替换或 Shell 变量展开。确认文件权限后再启动服务:

stat -c '%A %U:%G %n' /etc/myapp/myapp.env

5. 编写 systemd 服务单元

创建服务文件 /etc/systemd/system/myapp.service:

[Unit]
Description=Gunicorn service for myapp
Wants=network-online.target
After=network-online.target

[Service]
Type=simple
User=myapp
Group=myapp
WorkingDirectory=/srv/myapp/current
EnvironmentFile=-/etc/myapp/myapp.env
Environment=PYTHONUNBUFFERED=1
ExecStart=/srv/myapp/current/venv/bin/gunicorn --workers 3 --bind 127.0.0.1:8000 --access-logfile - --error-logfile - app:app
Restart=on-failure
RestartSec=3
TimeoutStopSec=30
PrivateTmp=true
NoNewPrivileges=true

[Install]
WantedBy=multi-user.target

在 Debian 或 Ubuntu 上可用以下方式写入文件:

sudo tee /etc/systemd/system/myapp.service >/dev/null <<'EOF'
[Unit]
Description=Gunicorn service for myapp
Wants=network-online.target
After=network-online.target

[Service]
Type=simple
User=myapp
Group=myapp
WorkingDirectory=/srv/myapp/current
EnvironmentFile=-/etc/myapp/myapp.env
Environment=PYTHONUNBUFFERED=1
ExecStart=/srv/myapp/current/venv/bin/gunicorn --workers 3 --bind 127.0.0.1:8000 --access-logfile - --error-logfile - app:app
Restart=on-failure
RestartSec=3
TimeoutStopSec=30
PrivateTmp=true
NoNewPrivileges=true

[Install]
WantedBy=multi-user.target
EOF

这里几个设置直接影响服务行为:

  • User 和 Group 指定应用的运行身份。若应用需要写数据,应只给它对应数据目录的写权限。
  • WorkingDirectory 决定应用模块的导入起点。若项目入口是 Django,通常需要将 app:app 改成项目实际的 WSGI 入口,例如 config.wsgi:application。
  • EnvironmentFile 前的 - 表示该文件不存在时 systemd 不因缺少文件而拒绝启动;但应用必需的配置缺失时,应用自身仍可能启动失败。
  • --bind 127.0.0.1:8000 只监听本机。若外部请求由 Nginx 转发,应保持这一设置,不要为了“能访问”而随意改成公网监听地址。
  • --access-logfile - 和 --error-logfile - 将日志输出到标准输出和标准错误,便于通过 journal 查看。
  • --workers 3 是示例值,不是适用于所有应用的固定配置。应结合应用的内存占用、CPU 和请求特征调整;worker 数量过多会增加内存开销。
  • Restart=on-failure 会在异常退出时尝试重启,但不会修复持续存在的配置错误。若服务反复启动失败,systemd 可能触发启动频率限制。

检查单元文件语法并让 systemd 重新读取配置:

sudo systemd-analyze verify /etc/systemd/system/myapp.service
sudo systemctl daemon-reload

如果第一条命令报告文件或行号错误,先修正服务文件,再执行 daemon-reload。daemon-reload 只刷新 systemd 对单元文件的读取,不会自动重启已经运行的应用。

6. 启动服务并逐项验证

启用服务并立即启动:

sudo systemctl enable --now myapp

先检查服务状态:

sudo systemctl status myapp --no-pager -l

正常运行时,状态通常显示 active (running)。再检查 Gunicorn 是否监听本机端口:

sudo ss -ltnp 'sport = :8000'

预期能看到本机地址 127.0.0.1:8000。如果应用提供了 /healthz 接口,可从服务器本机发起请求:

curl -i http://127.0.0.1:8000/healthz

示例响应可能包含 HTTP 200 和 {"status":"ok"}。这只是预期格式示例,实际响应以应用路由为准;如果项目没有该接口,应改用已存在且能代表服务可用性的地址。

查看服务日志:

sudo journalctl -u myapp -n 50 --no-pager

持续跟踪启动和请求日志:

sudo journalctl -u myapp -f

如果服务器前面有 Nginx,应再从 Nginx 所在机器或本机通过网站入口验证请求。Gunicorn 的 127.0.0.1:8000 只接受本机连接;外部访问通常由 Nginx 转发到该地址,HTTPS 证书也应在实际负责 TLS 终止的入口配置。systemd 能管理进程,但不会替代 Web 服务器的转发和证书配置。

7. 常见启动失败及处理顺序

排查时先看 systemd 状态和日志,再检查端口和应用入口,避免一开始就修改防火墙或扩大监听范围。

现象常见原因检查与处理
服务文件加载失败单元配置有语法错误,或修改后未执行 daemon-reload运行 systemd-analyze verify,按报告修正后重新加载
服务启动后立即退出,日志提示导入失败WorkingDirectory、模块路径或 app:app 对象名不匹配用服务账户在虚拟环境中手动导入或启动应用,核对项目入口
日志提示无法读取文件或目录发布目录、环境文件或应用数据目录权限不正确用 namei -l 检查每级目录权限,只调整应用实际需要访问的路径
提示端口已被占用其他进程已监听 8000用 ss -ltnp 'sport = :8000' 查占用进程;确认后调整端口或处理冲突
本机健康检查成功,但网站入口报错Nginx 转发目标、请求头或站点配置不匹配检查 Nginx 配置和错误日志,并确认它转发到 127.0.0.1:8000
服务反复重启或出现启动频率限制应用启动异常、配置缺失或依赖不兼容先修复日志指出的问题;必要时执行 systemctl reset-failed myapp,再重新启动

若修改了 unit 文件,执行 daemon-reload 后再重启;若只更新了应用代码或依赖,也应重启服务,让新进程加载新版本:

sudo systemctl daemon-reload
sudo systemctl restart myapp
sudo systemctl status myapp --no-pager -l

8. 更新与回滚

使用版本化目录时,升级前保留当前版本。先确认当前链接目标:

readlink -f /srv/myapp/current

把新代码和依赖部署到新的发布目录,例如 /srv/myapp/releases/r2,按首个版本的步骤创建虚拟环境、安装依赖并检查权限。不要直接覆盖正在运行的版本目录。

切换前先创建指向新版本的临时链接,再用 mv -T 替换当前链接:

sudo ln -s /srv/myapp/releases/r2 /srv/myapp/current.next
sudo mv -Tf /srv/myapp/current.next /srv/myapp/current
sudo systemctl restart myapp

重启后检查服务状态、日志和健康接口。若新版本启动失败,切回已知可用版本:

8. 更新与回滚配图

sudo ln -s /srv/myapp/releases/r1 /srv/myapp/current.rollback
sudo mv -Tf /srv/myapp/current.rollback /srv/myapp/current
sudo systemctl restart myapp

然后再次检查 systemctl status、journalctl 和健康接口。mv -Tf 适用于常见的 GNU/Linux 环境;执行前确认临时链接名没有被其他操作占用。若更新还涉及数据库结构变更,代码回滚并不等于数据库回滚;应在执行迁移前单独评估兼容性、备份和恢复路径。

验收与回滚检查项

首次部署完成后,至少核对以下项目:

  • 服务账户不是 root,且应用代码目录对该账户只读。
  • systemctl is-enabled myapp 返回 enabled,systemctl is-active myapp 返回 active。
  • Gunicorn 监听预期的本机地址和端口,外部入口能通过反向代理访问应用。
  • 健康接口返回应用预期结果,journal 中没有持续出现异常退出或导入错误。
  • 环境文件权限受限,密钥没有放入代码仓库或公开日志。
  • 当前发布版本可通过 readlink -f /srv/myapp/current 确认,旧版本仍保留且回切步骤可执行。

需要撤销本次服务启用时,可先停止并取消开机启动:

sudo systemctl disable --now myapp

这不会删除应用代码、环境文件或服务单元。确认业务流量已切走、所需配置已备份后,再按实际清理范围逐项处理,避免直接递归删除仍被其他服务使用的目录。

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

相关推荐