在香港服务器上线Flask应用,如何配置进程守护与反向代理?
上线后的请求链路应当是:域名解析到香港服务器公网 IP,Nginx 对外监听 80/443 端口并处理证书、静态请求和代理转发,Gunicorn 在本机回环地址运行 Flask 应用,systemd 负责进程拉起、异常重启和启动日志收集。Flask 不直接使用开发服务器,也不把 8000 等应用端口暴露到公网。
实施时应同时完成六件事:固定应用运行边界、配置反向代理、启用 HTTPS、保留可检索日志、建立代码与数据备份、准备可验证的回滚路径。下面以 Ubuntu 22.04/24.04、Python 3、Nginx、Gunicorn 和 systemd 为例,域名使用 example.com,应用目录使用 /srv/flaskapp。

一、上线前的目标状态与准备条件
1. 目标架构
| 层级 | 组件 | 监听或存放位置 | 主要职责 |
|---|---|---|---|
| DNS | A/AAAA 记录 | 域名解析服务 | 将域名指向香港服务器 |
| 公网入口 | Nginx | 80/443 | HTTPS、请求转发、请求大小和超时控制 |
| 应用进程 | Gunicorn | 127.0.0.1:8000 | 托管 Flask WSGI 应用 |
| 进程管理 | systemd | flaskapp.service | 启动、重启、资源限制和状态检查 |
| 应用日志 | journald | journalctl -u flaskapp | 收集 Gunicorn 标准输出和错误输出 |
| Web 日志 | Nginx | /var/log/nginx/ | 记录访问、状态码和代理错误 |
| 数据与配置 | 服务器本地或独立存储 | /srv/flaskapp、/etc/flaskapp | 保存代码、配置和业务数据 |
外部访问者只应能访问 80 和 443 端口。Gunicorn 绑定到 127.0.0.1 后,即使没有额外防火墙规则,公网也无法直接访问应用端口。
2. DNS、云防火墙和服务器条件
部署前先确认以下条件:
- 已有可用域名,例如
example.com。 - 域名的 A 记录指向香港服务器公网 IPv4。
- 如果设置了 AAAA 记录,服务器必须已经配置 IPv6,并且 Nginx 同时监听 IPv6;否则应删除错误的 AAAA 记录。
- 云厂商安全组或网络 ACL 允许 TCP 22、80、443。
- 当前 SSH 登录端口已经确认。若 SSH 不是 22,后续防火墙规则必须使用实际端口。
- 服务器系统时间正常,证书签发依赖正确的时间。
- 应用已经准备好
requirements.txt,并明确是否需要数据库、上传目录或其他持久化数据。
可以先检查主机状态:
timedatectl
uname -a
python3 --version
nproc
free -h
df -h
香港服务器的部署流程与其他 Linux 服务器基本一致,但域名解析、云安全组和 IPv6 配置仍然要在服务商控制台与服务器内分别确认。只修改其中一处,不能替代另一处。
A5数据面向香港服务器部署场景,提供入门建站、Xeon Gold及AMD EPYC等物理服务器,配备SSD或NVMe存储,并提供CN2与国际带宽方案,可为Flask应用、Gunicorn进程、Nginx反向代理、数据库和接口服务提供相应的计算、存储与网络资源。针对日志留存、版本备份和业务数据归档,香港存储系列及大容量硬盘配置也能提供配套的存储基础。
3. 资源边界先按保守值设置
Gunicorn 的 worker 数量不能只套用固定公式。同步 worker 通常会在处理慢请求时占用一个 worker,因此需要结合 CPU、内存和请求类型确定。
可先采用以下起点:
| 服务器资源或业务特征 | Gunicorn 起始 worker | 说明 |
|---|---|---|
| 1 vCPU、1 GB 内存,轻量接口 | 1~2 | 优先控制内存,避免启动过多进程 |
| 2 vCPU、4 GB 内存,普通接口 | 2~3 | 适合作为常见初始值 |
| 4 vCPU 以上、CPU 密集型任务较多 | 3~5 | 需要结合 CPU 使用率和响应时间调整 |
| 长轮询、文件处理、外部接口等待较多 | 不宜盲目增加 | 应优先拆分慢任务或使用异步任务队列 |
应用每个 worker 的常驻内存可以用进程实际 RSS 估算。一个简单的容量估算方式是:
预留内存 = 系统和基础服务内存 + Gunicorn 主进程内存 + worker 数量 × 单个 worker 内存 + 20%~30%余量
例如,服务器有 4 GB 内存,应用单个 worker 约占 180 MB,配置 3 个 worker 时,worker 约占 3 × 180 MB = 540 MB。还需要为系统、Nginx、缓存、数据库和瞬时请求留出空间,不能把全部内存都分配给 Gunicorn。
二、创建运行用户和应用目录
以下操作使用具有 sudo 权限的账号执行。应用不建议使用 root 身份运行。
1. 安装基础软件
sudo apt update
sudo apt install -y python3 python3-venv python3-pip nginx curl ca-certificates
如果系统不是 Ubuntu 22.04/24.04,应先核对发行版和软件包名称,不要直接套用仓库命令:
cat /etc/os-release
apt-cache policy nginx python3 python3-venv
2. 创建专用用户和目录
sudo adduser --system --group --home /srv/flaskapp flaskapp
sudo install -d -o flaskapp -g flaskapp -m 750 /srv/flaskapp
sudo install -d -o flaskapp -g flaskapp -m 750 /srv/flaskapp/releases
sudo install -d -o flaskapp -g flaskapp -m 750 /srv/flaskapp/shared
sudo install -d -o root -g root -m 750 /etc/flaskapp
sudo install -d -o root -g root -m 750 /var/backups/flaskapp
/srv/flaskapp/releases 用于保存多个版本,current 软链接指向当前版本。这样更新失败时可以切回旧版本,不必覆盖原有代码。
配置文件通常包含密钥、数据库密码或第三方服务令牌,应放在 /etc/flaskapp,并限制为 root 可读:
sudo install -o root -g root -m 600 /dev/null /etc/flaskapp/flaskapp.env
sudo tee /etc/flaskapp/flaskapp.env >/dev/null <<'EOF'
APP_ENV=production
SECRET_KEY=replace-with-a-long-random-value
EOF
上面的 SECRET_KEY 只是占位值,正式环境应替换为随机密钥。不要把真实密码直接提交到代码仓库、聊天记录或公开日志中。
三、安装并验证 Flask 与 Gunicorn
1. 创建一个版本目录
下面命令会创建一个带时间戳的发布目录,并把 current 指向它:
RELEASE="$(date +%Y%m%d%H%M%S)"
sudo -u flaskapp mkdir -p "/srv/flaskapp/releases/${RELEASE}"
sudo -u flaskapp tee "/srv/flaskapp/releases/${RELEASE}/requirements.txt" >/dev/null <<'EOF'
Flask>=3.0,<4.0
gunicorn>=21.0,<24.0
EOF
sudo -u flaskapp tee "/srv/flaskapp/releases/${RELEASE}/app.py" >/dev/null <<'PY'
from flask import Flask, jsonify
from werkzeug.middleware.proxy_fix import ProxyFix
app = Flask(__name__)
# 仅当应用只接受本机 Nginx 转发时使用。
# 如果前面还有其他代理层,应根据实际代理数量调整信任数量。
app.wsgi_app = ProxyFix(
app.wsgi_app,
x_for=1,
x_proto=1,
x_host=1,
)
@app.get("/healthz")
def healthz():
return jsonify(status="ok")
@app.get("/")
def index():
return "Flask application is running.\n"
PY
sudo -u flaskapp ln -sfn \
"/srv/flaskapp/releases/${RELEASE}" \
/srv/flaskapp/current
/healthz 只用于判断进程是否能正常响应。如果业务依赖数据库或外部服务,应另外设计 /readyz,并设置较短的连接超时,避免健康检查本身拖垮 worker。
2. 创建虚拟环境并安装依赖
sudo -u flaskapp python3 -m venv /srv/flaskapp/venv
sudo -u flaskapp /srv/flaskapp/venv/bin/python -m pip install --upgrade pip
sudo -u flaskapp /srv/flaskapp/venv/bin/pip install \
-r "/srv/flaskapp/releases/${RELEASE}/requirements.txt"
查看依赖是否安装到预期环境:
sudo -u flaskapp /srv/flaskapp/venv/bin/python -c \
"import flask, gunicorn; print(flask.__version__)"
3. 先绕过 Nginx测试应用
sudo -u flaskapp /srv/flaskapp/venv/bin/gunicorn \
--workers 1 \
--bind 127.0.0.1:8000 \
--access-logfile - \
--error-logfile - \
--timeout 60 \
--graceful-timeout 30 \
app:app
另开一个 SSH 会话测试:
curl -i http://127.0.0.1:8000/healthz
看到 HTTP/1.1 200 OK 和 {"status":"ok"} 后,回到运行 Gunicorn 的会话按 Ctrl+C 停止。此时如果本机请求已经失败,不要继续配置 Nginx,应先修复 Python 依赖、导入路径、环境变量或应用代码。
四、使用 systemd 管理 Flask 进程
1. 创建服务单元
先保存现有服务文件。下面的 cp 仅在文件已经存在时执行,避免覆盖旧配置而失去回滚依据:
if [ -e /etc/systemd/system/flaskapp.service ]; then
sudo cp -a /etc/systemd/system/flaskapp.service \
"/var/backups/flaskapp/flaskapp.service.$(date +%Y%m%d%H%M%S)"
fi
写入服务配置:
sudo tee /etc/systemd/system/flaskapp.service >/dev/null <<'EOF'
[Unit]
Description=Flask application served by Gunicorn
After=network.target
[Service]
Type=simple
User=flaskapp
Group=flaskapp
WorkingDirectory=/srv/flaskapp/current
EnvironmentFile=-/etc/flaskapp/flaskapp.env
ExecStart=/srv/flaskapp/venv/bin/gunicorn \
--workers 2 \
--worker-class sync \
--bind 127.0.0.1:8000 \
--access-logfile - \
--error-logfile - \
--capture-output \
--timeout 60 \
--graceful-timeout 30 \
--keep-alive 5 \
app:app
Restart=on-failure
RestartSec=5
KillSignal=SIGQUIT
TimeoutStopSec=45
UMask=0027
NoNewPrivileges=true
PrivateTmp=true
LimitNOFILE=65535
TasksMax=128
[Install]
WantedBy=multi-user.target
EOF
这里的 --workers 2 是示例起点。若应用内存较大,可以从 1 个 worker 开始,再根据实际 RSS 和响应时间调整。--timeout 60 表示单个请求超过 60 秒时,Gunicorn 会认为 worker 失去响应;如果业务确实存在长耗时请求,应先确认是否可以异步化,而不是简单设置为几分钟。
TasksMax=128 和 LimitNOFILE=65535 是进程资源边界。MemoryMax、CPUQuota 等更严格的限制不建议在不了解应用峰值内存前直接启用,否则超限时 systemd 可能终止应用。上线稳定后,可以根据监控数据增加,例如:
# 只有在确认应用正常峰值和内存余量后再启用
# MemoryMax=1G
# CPUQuota=200%
启用服务:

sudo systemctl daemon-reload
sudo systemctl enable --now flaskapp.service
sudo systemctl status flaskapp.service --no-pager
2. 检查服务和端口
systemctl is-enabled flaskapp.service
systemctl is-active flaskapp.service
sudo ss -lntp | grep ':8000'
curl -fsS http://127.0.0.1:8000/healthz
预期结果是:
- 服务状态为
active。 - 8000 端口只绑定在
127.0.0.1,而不是0.0.0.0。 - 本机健康检查返回成功。
- 代码中没有使用 Flask 开发服务器。
查看启动和错误日志:
sudo journalctl -u flaskapp.service -n 100 --no-pager
sudo journalctl -u flaskapp.service -f
如果服务反复重启,先使用 systemctl status 和 journalctl 找到第一个 Python 异常,不要连续执行 restart 掩盖根因。
五、配置 Nginx 反向代理
1. 写入初始 HTTP 配置
Nginx 配置文件属于覆盖性修改。已有文件时应先备份:
if [ -e /etc/nginx/sites-available/flaskapp ]; then
sudo cp -a /etc/nginx/sites-available/flaskapp \
"/var/backups/flaskapp/flaskapp.nginx.$(date +%Y%m%d%H%M%S)"
fi
创建站点配置。将 example.com 和 www.example.com 替换为实际域名;如果没有使用 www,应从 server_name 中删除它。
sudo tee /etc/nginx/sites-available/flaskapp >/dev/null <<'EOF'
server {
listen 80;
server_name example.com www.example.com;
access_log /var/log/nginx/flaskapp.access.log;
error_log /var/log/nginx/flaskapp.error.log warn;
client_max_body_size 10m;
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;
proxy_connect_timeout 5s;
proxy_send_timeout 60s;
proxy_read_timeout 60s;
}
}
EOF
sudo ln -sfn /etc/nginx/sites-available/flaskapp \
/etc/nginx/sites-enabled/flaskapp
sudo nginx -t
sudo systemctl reload nginx
nginx -t 失败时不会应用新的配置。只有测试通过后才执行 reload。如果服务器已经有其他网站,应确认 server_name 没有重复;如果默认站点仍在运行,可以先保留它,避免误删现有服务。
确认域名已经解析后测试:
curl -i -H 'Host: example.com' http://127.0.0.1/
如果该请求返回 Flask 页面,说明 Nginx 到 Gunicorn 的反向代理已经打通。
2. 代理头与 Flask 的关系
Nginx 通过 X-Forwarded-Proto 告诉 Flask,用户原始请求是 HTTP 还是 HTTPS;通过 X-Forwarded-For 传递客户端地址。示例代码中的 ProxyFix 只适用于“公网请求先到本机 Nginx,再到 Gunicorn”的结构。
如果应用前面还存在其他受信任代理层,x_for、x_proto、x_host 的数量必须与实际代理层数对应。错误信任外部提交的转发头,可能导致日志记录错误 IP、生成错误回调地址或产生安全问题。
3. 配置防火墙
先确认云安全组已放行 80 和 443,再配置服务器本地防火墙。启用 UFW 前必须保留当前 SSH 会话,并确认 SSH 端口规则已经存在,否则可能把自己锁在服务器外。
以下示例假定 SSH 使用 22 端口:
sudo ufw status verbose
sudo ufw allow 22/tcp
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw enable
sudo ufw status numbered
如果 SSH 使用其他端口,应将 22/tcp 替换为实际端口。不要开放 8000/tcp,因为 Gunicorn 已绑定在本机回环地址。防火墙变更的影响范围是整台服务器,执行前应保留云厂商控制台或带外登录能力,回滚时只撤销本次新增规则,不要误删 SSH 规则。
六、申请证书并切换 HTTPS
1. 安装 Certbot
sudo apt install -y certbot python3-certbot-nginx
申请证书前需要满足:
- A 或 AAAA 记录已经指向当前服务器。
- 80 端口从公网可访问。
- Nginx 配置可以正常加载。
- 域名没有被其他服务器或错误的 AAAA 记录接管。
先备份 Nginx 配置:
sudo cp -a /etc/nginx/sites-available/flaskapp \
"/var/backups/flaskapp/flaskapp.pre-certbot.$(date +%Y%m%d%H%M%S)"
然后执行:
sudo certbot --nginx -d example.com -d www.example.com
如果没有 www 记录,就只申请主域名:
sudo certbot --nginx -d example.com
Certbot 可能会修改 Nginx 配置并增加 HTTP 到 HTTPS 的跳转。证书签发完成后先检查配置,再访问站点:
sudo nginx -t
sudo systemctl reload nginx
curl -I http://example.com/
curl -I https://example.com/
正式环境中,HTTP 请求通常应返回 301 或 308,HTTPS 请求应返回应用自身的状态码。不要在证书尚未签发成功前,手工把 Nginx 配置改成引用不存在的证书文件,否则 Nginx 将无法通过配置测试。
2. 验证证书和自动续期
查看证书有效期:
sudo certbot certificates
测试续期流程:
sudo certbot renew --dry-run
确认系统是否存在 Certbot 定时任务:
systemctl list-timers --all | grep -i certbot
如果续期后 Nginx 没有自动重新加载,可以添加部署钩子:
sudo install -d -m 755 /etc/letsencrypt/renewal-hooks/deploy
sudo tee /etc/letsencrypt/renewal-hooks/deploy/reload-nginx >/dev/null <<'EOF'
#!/bin/sh
set -eu
/usr/sbin/nginx -t
/bin/systemctl reload nginx
EOF
sudo chmod 755 /etc/letsencrypt/renewal-hooks/deploy/reload-nginx
证书更新钩子只应在 nginx -t 成功后 reload。这样即使证书续期时配置存在语法错误,也不会用错误配置覆盖正在运行的 Nginx。
3. 确认 HTTPS 下的应用行为
如果应用会生成绝对 URL、处理登录会话或设置安全 Cookie,应确认反向代理协议已经被正确识别。可在 Flask 配置中按业务需要启用:
app.config.update(
SESSION_COOKIE_SECURE=True,
SESSION_COOKIE_HTTPONLY=True,
SESSION_COOKIE_SAMESITE="Lax",
)
启用 SESSION_COOKIE_SECURE 后,HTTP 下的 Cookie 不会发送,这是切换 HTTPS 后的预期行为。若站点仍有必须使用 HTTP 的旧客户端,不应在未评估影响前直接启用。
HSTS 也不应一开始就设置很长时间。确认所有子域名、资源和回调地址都能通过 HTTPS 访问后,再考虑增加:
add_header Strict-Transport-Security "max-age=86400" always;
HSTS 会让浏览器在有效期内强制使用 HTTPS。配置错误时,用户端修复不会像普通 301 那样立即生效,因此应从较短时间开始验证。
七、日志、磁盘和运行状态管理
1. 查看三类关键日志
Gunicorn 和应用标准输出:
sudo journalctl -u flaskapp.service -n 200 --no-pager
sudo journalctl -u flaskapp.service -f
Nginx 访问日志:
sudo tail -f /var/log/nginx/flaskapp.access.log
Nginx 错误日志:
sudo tail -f /var/log/nginx/flaskapp.error.log
通过状态码可以快速区分故障层次:
2xx:请求已经到达应用并成功处理。3xx:通常是 HTTPS 跳转或应用自身跳转。4xx:请求、域名、权限或请求大小存在问题。502:Nginx 无法从 Gunicorn 获得有效响应。504:Gunicorn 或下游依赖在 Nginx 超时前没有完成请求。- 连接超时或拒绝:优先检查 DNS、云安全组、本地防火墙和 Nginx 监听状态。
Nginx 在 Ubuntu 中通常已经带有日志轮转配置,可以先进行检查:
sudo logrotate -d /etc/logrotate.conf
-d 只做模拟,不会实际轮转。不要把应用日志无限写入单个文件,否则磁盘满后可能导致 Nginx、systemd 和应用同时异常。
2. 为 journald 设置边界
如果应用长时间运行并将大量日志写入 journald,可以设置一个示例上限。该配置影响服务器上的 journald,不只影响 Flask,因此执行前应备份已有配置:
if [ -e /etc/systemd/journald.conf ]; then
sudo cp -a /etc/systemd/journald.conf \
"/var/backups/flaskapp/journald.conf.$(date +%Y%m%d%H%M%S)"
fi
sudo install -d -m 755 /etc/systemd/journald.conf.d
sudo tee /etc/systemd/journald.conf.d/90-flaskapp-limits.conf >/dev/null <<'EOF'
[Journal]
SystemMaxUse=500M
RuntimeMaxUse=100M
MaxRetentionSec=14day
EOF
sudo systemctl restart systemd-journald
500M 和 14day 是示例边界,应结合磁盘大小、审计要求和日志保留周期调整。若日志需要长期保存,应转存到独立日志系统或备份存储,而不是只依赖本机。
查看磁盘和 inode 使用情况:
df -h
df -ih
sudo du -sh /var/log/* 2>/dev/null | sort -h
八、备份、发布与资源边界
1. 上线前备份哪些内容
至少保留以下内容:
- 当前代码版本或 Git 提交号。
/etc/systemd/system/flaskapp.service。/etc/nginx/sites-available/flaskapp。/etc/flaskapp中的环境配置。/srv/flaskapp/shared中的上传文件或其他持久化数据。- 数据库的可恢复备份。
- Certbot 配置和证书恢复所需信息。
配置文件和环境变量通常包含敏感信息,备份目录应限制权限:
sudo chmod 700 /var/backups/flaskapp
备份示例:
STAMP="$(date +%Y%m%d%H%M%S)"
sudo tar --xattrs --acls -czf \
"/var/backups/flaskapp/flaskapp-${STAMP}.tar.gz" \
/etc/nginx/sites-available/flaskapp \
/etc/systemd/system/flaskapp.service \
/etc/flaskapp \
/srv/flaskapp/releases \
/srv/flaskapp/shared
sudo chmod 600 "/var/backups/flaskapp/flaskapp-${STAMP}.tar.gz"
虚拟环境通常可以通过固定版本的 requirements.txt 重建,不必把整个 venv 作为主要备份对象。数据库不能简单复制正在写入的数据库文件。SQLite 应使用一致性备份方式,MySQL、MariaDB 或 PostgreSQL 应使用相应的逻辑备份或快照工具,并在恢复环境中验证。
2. 推荐使用版本目录发布
新版本不应直接覆盖 /srv/flaskapp/current 指向的代码。基本流程如下:
NEW_RELEASE="$(date +%Y%m%d%H%M%S)"
sudo -u flaskapp mkdir -p "/srv/flaskapp/releases/${NEW_RELEASE}"
# 将新代码和 requirements.txt 上传到该目录后执行
sudo -u flaskapp /srv/flaskapp/venv/bin/pip install \
-r "/srv/flaskapp/releases/${NEW_RELEASE}/requirements.txt"
sudo -u flaskapp ln -sfnT \
"/srv/flaskapp/releases/${NEW_RELEASE}" \
/srv/flaskapp/current
sudo systemctl restart flaskapp.service
如果新版本涉及数据库迁移,先确认迁移是否向后兼容。不要在没有数据库备份的情况下执行不可逆迁移,也不要先删除旧字段再切换应用代码。更稳妥的顺序通常是:先增加兼容字段或表,再发布兼容代码,最后在确认旧版本不再回滚后清理旧结构。
3. 用监控结果调整边界
上线后至少观察以下指标:
ps -eo pid,ppid,user,%cpu,%mem,rss,etime,cmd --sort=-rss | \
grep -E 'gunicorn|flaskapp' | grep -v grep
sudo systemctl show flaskapp.service \
-p MainPID -p NRestarts -p MemoryCurrent -p TasksCurrent
sudo journalctl -u flaskapp.service --since "30 minutes ago" \
--no-pager | tail -n 200
curl -sS -o /dev/null -w \
'code=%{http_code} connect=%{time_connect}s start=%{time_starttransfer}s total=%{time_total}s\n' \
https://example.com/healthz
如果内存持续接近上限,先降低 worker 数量并检查应用是否存在内存泄漏;如果 CPU 长时间接近满载,检查慢 SQL、模板渲染、文件处理和外部接口调用;如果 5xx 增加,不要只通过增加超时来掩盖应用问题。
九、结果验证
1. 从 DNS 到应用逐层验证
先在任意可访问公网的机器上执行:
dig +short A example.com
dig +short AAAA example.com
A 或 AAAA 结果应与服务器实际地址一致。没有配置 IPv6 时,最好不要保留指向错误主机的 AAAA。
检查服务器端口:
sudo ss -lntp | grep -E ':(80|443|8000)\b'
预期是:
- Nginx 监听 80,证书配置完成后监听 443。
- Gunicorn 只监听
127.0.0.1:8000。 - 没有其他程序抢占 80 或 443。
检查 Nginx 配置与服务状态:
sudo nginx -t
sudo systemctl is-active nginx
sudo systemctl is-active flaskapp.service
从公网检查 HTTP 和 HTTPS:
curl -I http://example.com/
curl -I https://example.com/
curl -fsS https://example.com/healthz
检查证书主体、签发者和有效期:

openssl s_client \
-connect example.com:443 \
-servername example.com </dev/null 2>/dev/null |
openssl x509 -noout -subject -issuer -dates
2. 常见失败与处理方式
| 现象 | 优先检查 | 处理方向 |
|---|---|---|
| 域名无法访问或解析为空 | dig、DNS 控制台、A/AAAA 记录 | 修正解析并等待缓存刷新,不要先修改应用 |
| HTTP 连接超时 | 云安全组、UFW、Nginx 监听 | 先放行 80,确认没有错误 AAAA |
| HTTPS 连接失败 | 443 规则、证书路径、nginx -t | 先恢复可加载的旧配置,再处理证书 |
| Nginx 返回 502 | systemctl status flaskapp、本机 curl 127.0.0.1:8000 | 检查 Gunicorn 是否退出、端口是否一致、应用是否导入失败 |
| Nginx 返回 504 | Gunicorn 日志、下游数据库和外部接口 | 找慢请求根因,不要直接无限增大超时 |
| 返回 413 | client_max_body_size | 按业务需要调整上传大小,并同步评估内存和磁盘 |
| 生成的 URL 仍是 HTTP | X-Forwarded-Proto、ProxyFix | 确认 Nginx 转发头和 Flask 信任配置 |
| 服务反复重启 | journalctl -u flaskapp、NRestarts | 修复代码、依赖、权限或环境变量,不要只增加重启频率 |
| 内存快速上涨 | free -h、进程 RSS、内核日志 | 降低 worker、限制上传、检查缓存和内存泄漏 |
确认 502 时,先执行:
sudo systemctl status flaskapp.service --no-pager
sudo journalctl -u flaskapp.service -n 100 --no-pager
curl -i http://127.0.0.1:8000/healthz
如果本机请求失败,问题在 Gunicorn 或 Flask;如果本机成功而域名返回 502,重点检查 Nginx 的 proxy_pass、配置加载状态和目标端口。
如果遇到 504,应查看请求是否卡在数据库、第三方接口、文件读写或锁等待。proxy_read_timeout 只能延长等待时间,不能修复下游服务失效;过大的超时还可能让有限的 worker 长时间被占用。
十、回滚路径
1. 应用版本回滚
切换版本前先记录当前版本:
CURRENT_RELEASE="$(readlink -f /srv/flaskapp/current)"
echo "${CURRENT_RELEASE}"
如果新版本发布后健康检查失败,将软链接切回旧版本。下面的命令会改变应用实际运行代码,执行前应确认目标目录确实存在:

OLD_RELEASE="/srv/flaskapp/releases/20250101010101"
test -d "${OLD_RELEASE}"
sudo -u flaskapp ln -sfnT \
"${OLD_RELEASE}" \
/srv/flaskapp/current
sudo systemctl restart flaskapp.service
curl -fsS http://127.0.0.1:8000/healthz
如果旧版本依赖不同的 Python 包,需要先确认虚拟环境兼容。不要在应用已经启动失败时删除新版本目录;先保留现场,便于读取日志和继续分析。
2. Nginx 配置回滚
如果新配置导致 nginx -t 失败,Nginx 通常仍会继续使用旧的已加载配置。若已经加载了错误配置,应从备份恢复:
sudo cp -a \
/var/backups/flaskapp/flaskapp.pre-certbot.YYYYMMDDHHMMSS \
/etc/nginx/sites-available/flaskapp
sudo nginx -t
sudo systemctl reload nginx
实际执行时将文件名替换为备份目录中的真实文件。恢复前后都要执行 nginx -t。不要直接删除 /etc/nginx/sites-enabled 下的所有链接,这可能同时影响服务器上的其他站点。
3. 证书和防火墙回滚边界
证书申请失败时,不要删除 /etc/letsencrypt 下的证书目录。先恢复申请前的 Nginx 配置,确认 80 端口和 DNS 可达后再重新申请。
防火墙回滚前查看规则编号:
sudo ufw status numbered
只撤销本次增加的规则,例如错误增加的应用端口规则,不要误删 SSH 规则。若 UFW 启用后 SSH 已断开,应通过云厂商控制台或带外终端恢复,而不是反复尝试远程连接。
上线验收清单
- [ ] A 记录指向香港服务器公网 IPv4。
- [ ] 没有错误或过期的 AAAA 记录。
- [ ] 云安全组和服务器防火墙均允许 80、443,以及实际 SSH 端口。
- [ ] Gunicorn 由 systemd 管理,服务状态为
active。 - [ ] Gunicorn 只监听
127.0.0.1:8000,没有暴露应用端口。 - [ ]
curl http://127.0.0.1:8000/healthz返回成功。 - [ ]
nginx -t通过,Nginx 服务状态正常。 - [ ] HTTP 请求按预期跳转到 HTTPS。
- [ ] HTTPS 证书的域名、有效期和自动续期测试均正常。
- [ ] Flask 能正确识别
X-Forwarded-Proto,登录和绝对 URL 没有协议错误。 - [ ] Gunicorn 日志可通过
journalctl -u flaskapp查询。 - [ ] Nginx 访问日志和错误日志路径明确,并已配置轮转。
- [ ] 应用代码、systemd、Nginx、环境配置和持久化数据均有备份。
- [ ] 已记录当前发布目录,能够切回上一版本。
- [ ] 数据库迁移有独立备份和恢复方案。
- [ ] 已观察 CPU、内存、worker RSS、5xx 和磁盘使用情况。
- [ ] 502、504、证书失效和内存超限等故障均有明确处理路径。
本文由A5数据原创发布,转载请注明出处:https://www.a5idc.com/helpcontent/3649.html



