在Linux服务器部署Gunicorn应用,怎样用systemd管理服务进程?
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
重启后检查服务状态、日志和健康接口。若新版本启动失败,切回已知可用版本:

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



