在韩国服务器上线Flask应用,如何配置Gunicorn进程管理?
在韩国服务器上首次上线 Flask 应用,可以让 Gunicorn 负责运行应用和管理 worker,systemd 负责开机启动、主进程故障重启及日志收集,再由 Nginx 接收公网请求。不要使用 flask run 承接生产流量,也不需要同时叠加多套进程守护工具。
下面以 Ubuntu 24.04、Python 虚拟环境和 systemd 为实施环境,完成应用入口检查、Gunicorn 参数配置、服务启动及访问验证。韩国机房的位置不会改变这些配置方式,但上线验收应同时检查服务器本地访问和目标访问地区的公网请求,避免把线路问题误判为进程故障。
A5数据提供韩国首尔物理服务器租用,以不同CPU、存储配置及优化或国际线路方案,为Flask网站、业务后台和API服务提供部署基础。服务器的计算与存储资源可承载Gunicorn多进程运行、应用文件及日志数据,网络资源则衔接Nginx公网入口与业务访问人群,为面向韩国本地及跨境用户的Python Web应用提供基础设施支持。
一、准备条件与部署约定
本次部署需要:
- 一台能够通过 SSH 管理的韩国服务器,具有 sudo 权限。
- 已确认操作系统为 Ubuntu 24.04,且使用 systemd。
- 一个 Flask 项目,或使用下文的最小应用先验证部署链路。
- 如需公网域名访问,域名已解析到服务器公网 IP,相关安全组允许网站入口端口。
先确认环境:
cat /etc/os-release
ps -p 1 -o comm=
python3 --version
预期发行版信息与准备环境一致,PID 1 的进程名称为 systemd。如果系统不是 Ubuntu,不要直接套用软件安装和 Nginx 目录命令。
本文使用以下独立名称,避免与已有项目混用:
| 对象 | 本文取值 | 用途 |
|---|---|---|
| 服务账户 | flasksite | 非 root 身份运行应用 |
| 项目目录 | /srv/flask-site/app | 放置 Flask 代码 |
| 虚拟环境 | /srv/flask-site/venv | 隔离 Python 依赖 |
| 服务名称 | flask-site.service | systemd 管理入口 |
| 应用监听地址 | 127.0.0.1:8000 | 仅供本机 Nginx 访问 |
| 示例域名 | app.example.com | 使用时替换为实际域名 |
以下文件创建命令仅适用于这些路径尚未被其他项目使用的首次部署。若已有同名账户、目录或服务,应先确认归属并备份,不要直接覆盖。
公网只需要开放网站入口端口;不要在安全组中开放 Gunicorn 的 8000 端口。如需调整安全组,应记录原规则、保留 SSH 管理入口,失败时恢复原规则。本文先用 HTTP 验证链路,涉及登录、支付或敏感数据的正式业务,必须在接入真实流量前完成 HTTPS。
二、建立应用入口并验证 Gunicorn
1. 安装组件并创建运行账户
sudo apt update
sudo apt install -y python3-venv nginx
sudo useradd --system --user-group \
--home-dir /srv/flask-site --shell /usr/sbin/nologin flasksite
sudo install -d -o flasksite -g flasksite -m 0750 \
/srv/flask-site /srv/flask-site/app
sudo -u flasksite python3 -m venv /srv/flask-site/venv
sudo -u flasksite /srv/flask-site/venv/bin/python -m pip install Flask gunicorn
这里安装 Flask 和 Gunicorn 是为了建立最小验证环境。正式项目应改为安装项目已经验证过的依赖文件,而不是每次上线都安装未固定版本的软件。
检查实际安装版本:
sudo -u flasksite /srv/flask-site/venv/bin/python -m pip show Flask gunicorn
应能看到两个包的信息,安装位置应位于 /srv/flask-site/venv 下。
2. 提供明确的 WSGI 入口
首次验证可创建以下最小应用。它只是健康检查样例,不应覆盖已有业务代码。
sudo -u flasksite tee /srv/flask-site/app/wsgi.py >/dev/null <<'PY'
from flask import Flask
app = Flask(__name__)
@app.get("/")
def index():
return "Flask is running\n"
@app.get("/healthz")
def healthz():
return {"status": "ok"}, 200
PY
Gunicorn 中的 wsgi:app 表示:导入 wsgi.py 模块,并使用其中的 app 对象。实际项目若使用应用工厂,可以在 wsgi.py 中写成:
from myproject import create_app
app = create_app()
入口模块名称、对象名称和工作目录必须对应,否则即使依赖安装成功,服务仍然无法启动。
3. 先以前台模式运行一次
sudo -u flasksite /srv/flask-site/venv/bin/gunicorn \
--chdir /srv/flask-site/app \
--bind 127.0.0.1:8000 \
--workers 1 \
wsgi:app
在另一个 SSH 会话中验证:
curl -i http://127.0.0.1:8000/healthz
预期为 HTTP 200,响应体包含 {"status":"ok"};JSON 的空格和格式可能不同。这个结果说明应用导入、依赖和本机监听都已正常。
验证后,在运行 Gunicorn 的会话中按 Ctrl+C 停止。接下来由 systemd 启动,不能让前台实例继续占用 8000 端口。
三、配置 Gunicorn 和 systemd 进程管理
1. 创建 Gunicorn 配置文件
sudo -u flasksite tee /srv/flask-site/gunicorn.conf.py >/dev/null <<'PY'
bind = "127.0.0.1:8000"
worker_class = "gthread"
workers = 2
threads = 2
timeout = 30
graceful_timeout = 30
keepalive = 5
accesslog = "-"
errorlog = "-"
capture_output = True
loglevel = "info"
daemon = False
PY
对于约 2 vCPU、2 GB 内存的小型应用,2 个 worker、每个 2 个线程可以作为初始参考,但不是容量承诺。线程更适合存在网络、数据库等 I/O 等待的请求,不能据此推断 CPU 密集型任务的吞吐能力。
几个配置需要分别理解:
workers决定工作进程数量。每个进程会加载应用,数量增加也会增加内存和数据库连接占用。threads决定每个 worker 的处理线程数量;应用代码和使用的库需要满足线程安全要求。timeout用于检测长时间无响应的 worker。对于这里的gthread,它不等于每条 HTTP 请求严格执行 30 秒。graceful_timeout给优雅退出留出时间,超过后仍未退出的 worker 可能被强制结束。- 日志输出到标准输出、标准错误,由 systemd 接收,不再另建一套日志文件轮转配置。
Gunicorn 的 worker 管理与 systemd 的服务管理是两层机制:worker 异常退出时由 Gunicorn 主进程补充;主进程异常退出时,才由 systemd 的重启策略接管。

2. 创建 systemd 服务
sudo tee /etc/systemd/system/flask-site.service >/dev/null <<'UNIT'
[Unit]
Description=Flask application managed by Gunicorn
After=network.target
StartLimitIntervalSec=60
StartLimitBurst=5
[Service]
Type=simple
User=flasksite
Group=flasksite
WorkingDirectory=/srv/flask-site/app
Environment=PYTHONUNBUFFERED=1
ExecStart=/srv/flask-site/venv/bin/gunicorn --config /srv/flask-site/gunicorn.conf.py wsgi:app
ExecReload=/bin/kill -s HUP $MAINPID
Restart=on-failure
RestartSec=5
KillMode=mixed
TimeoutStopSec=45
StandardOutput=journal
StandardError=journal
NoNewPrivileges=true
PrivateTmp=true
ProtectHome=true
ProtectSystem=full
[Install]
WantedBy=multi-user.target
UNIT
这里不启用 Gunicorn 的后台守护模式,也不使用 nohup。systemd 需要直接跟踪 Gunicorn 主进程,否则服务状态和停止行为容易失真。
KillMode=mixed 配合停止超时,让主进程先接收终止信号并处理 worker;TimeoutStopSec=45 长于 Gunicorn 的优雅退出窗口。安全选项会限制部分文件系统访问,因此项目不要放在 /root 或普通用户的家目录中,上传和数据目录也应单独规划。
生产密钥、数据库密码不要直接写进代码或公开仓库。如项目需要环境文件,可以使用权限受限的独立文件,再通过 EnvironmentFile= 引入。
3. 校验并启动
sudo systemd-analyze verify /etc/systemd/system/flask-site.service
sudo systemctl daemon-reload
sudo systemctl enable --now flask-site.service
sudo systemctl status flask-site.service --no-pager
sudo journalctl -u flask-site.service -n 50 --no-pager
curl -i http://127.0.0.1:8000/healthz
预期状态为 active (running),日志中可以看到监听和 worker 启动信息,健康检查返回 200。这些是验收目标,不代表命令已在实际服务器上执行成功。
若状态为 failed,先查日志,不要连续重启。服务存在启动频率限制;修复原因后可执行:
sudo systemctl reset-failed flask-site.service
sudo systemctl start flask-site.service
四、接入 Nginx 并验证公网入口
创建独立站点文件,不覆盖已有站点。将示例域名替换为实际域名:
sudo tee /etc/nginx/sites-available/flask-site >/dev/null <<'NGINX'
server {
listen 80;
server_name app.example.com;
location / {
proxy_pass http://127.0.0.1:8000;
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;
}
}
NGINX
sudo ln -s /etc/nginx/sites-available/flask-site \
/etc/nginx/sites-enabled/flask-site
sudo nginx -t
只有配置检查成功后才应用:
sudo systemctl enable --now nginx
sudo systemctl reload nginx
curl -i -H 'Host: app.example.com' http://127.0.0.1/healthz
预期仍为 200。如果同一域名已经出现在其他 Nginx 配置中,应先消除冲突,不要继续上线。若 nginx -t 失败,先撤销本次新增的启用链接,现有运行配置不应被强行替换。
然后从服务器之外、尤其是实际用户所在地区测试:
curl -i http://app.example.com/healthz
本地直连 Gunicorn 成功,只能证明应用运行正常;本地经 Nginx 成功,还不能证明域名解析、安全组和韩国服务器到访问地区的网络路径正常。

正式使用 HTTPS 后,还要验证证书域名、有效期及 HTTPS 健康检查。应用若依赖转发头判断协议或客户端地址,应按可信入口配置 Flask 的相关处理,不要无条件信任客户端自行提交的转发头。
五、常见异常与首次运行检查
按公网入口到应用内部排查
| 现象 | 优先检查 | 结果含义与处理 |
|---|---|---|
| 公网访问超时,本地正常 | DNS、安全组、主机防火墙 | 入口未到达服务;不要先增加 worker |
| 返回默认站点内容 | 域名、请求 Host、重复站点配置 | 请求没有命中本文的 Nginx 站点 |
Nginx 返回 502 | 本地 8000、Nginx 错误日志 | Gunicorn 未运行、端口不一致或连接被拒绝 |
| 服务启动即失败 | systemd 日志、入口导入 | 常见为模块名、依赖、工作目录错误 |
| 日志提示地址被占用 | 监听进程 | 前台测试实例或其他服务仍占用端口 |
| worker 反复退出 | 应用异常、超时日志、内存 | 不应只放宽重启频率或增大超时 |
对应检查命令:
sudo tail -n 50 /var/log/nginx/error.log
sudo ss -ltnp | grep ':8000'
sudo journalctl -u flask-site.service -n 100 --no-pager
sudo -u flasksite sh -c \
'cd /srv/flask-site/app && /srv/flask-site/venv/bin/python -c "from wsgi import app; print(app)"'
sudo journalctl -k --since "30 minutes ago" | grep -Ei 'oom|killed process'
导入命令应输出 Flask 应用对象。若出现 ModuleNotFoundError,确认缺少的包是否安装在当前虚拟环境中,而不是系统 Python 中。
若内核日志显示进程被 OOM 终止,应检查应用内存、worker 数量和同机其他服务。减少 worker 可以缓解内存压力,但会改变处理能力;需要重新验证,不能把它视为单纯的故障修复开关。
区分 reload 与 restart
sudo systemctl reload flask-site.service
sudo systemctl restart flask-site.service
reload 向 Gunicorn 主进程发送 HUP,重新读取配置并替换 worker,适合部分代码或 Gunicorn 配置更新。它不是零中断保证,正在处理的请求仍受优雅退出时限约束。
修改 systemd 单元后,需要执行 daemon-reload,再重启服务;修改虚拟环境、进程环境或关键启动参数时,也应安排重启。首次执行这些操作应处于维护窗口,完成后重新检查状态、日志和健康接口。
在确认应用初步正常后,至少观察一段覆盖典型请求的运行情况,重点关注 worker 是否反复重启、内存是否持续增长、数据库连接是否增加以及业务接口是否报错。健康接口返回 200 不等于数据库和完整业务已经验收。
六、验收与回滚检查项
上线验收
systemctl is-enabled flask-site.service返回enabled,状态为active (running)。- 8000 只监听
127.0.0.1,公网没有直接暴露 Gunicorn。 - 本地直连、本地经过 Nginx、目标地区公网访问均符合预期。
- 日志可查询,没有持续发生 worker 退出或主进程重启。
- 关键业务接口、数据库访问和必要的写入路径已单独验证。
- 正式流量入口已完成 HTTPS,证书与域名匹配。
- 已记录依赖版本,并保留当前配置备份。
首次部署失败时撤销新增服务
以下回滚只撤销本文新增的站点和服务,不删除代码、虚拟环境或已有 Nginx 配置。站点撤销后,该域名可能落入其他默认站点,应同时确认对外流量处理方式。
仅当启用链接确实由本文创建时,执行:
sudo unlink /etc/nginx/sites-enabled/flask-site
sudo nginx -t
检查成功后继续:
sudo systemctl reload nginx
sudo systemctl disable --now flask-site.service
sudo install -d -m 0700 /root/flask-site-rollback
sudo mv /etc/systemd/system/flask-site.service \
/root/flask-site-rollback/flask-site.service
sudo systemctl daemon-reload
Nginx 站点源文件和应用目录暂时保留,便于定位问题。不要为撤销一个项目而停止共享 Nginx,也不要递归删除 /srv 下的目录。
如果是在已运行的服务上修改参数,修改前应分别备份 Gunicorn 配置、systemd 单元和 Nginx 站点配置。回滚时恢复对应文件:恢复单元后执行 daemon-reload,恢复 Nginx 配置后先运行 nginx -t,再应用变更。代码或依赖也发生变化时,必须同时恢复兼容版本,不能只恢复 worker 数量。
回滚完成后,检查新增服务已停止、8000 没有意外残留监听、其他站点仍可访问,并核对本次新增的安全组规则是否需要恢复。这样才能把“应用启动成功”落实为可检查、可管理、可撤销的首次上线。
本文由A5数据原创发布,转载请注明出处:https://www.a5idc.com/helpcontent/4153.html



