在日本服务器上运行Flask应用,如何配置Gunicorn服务?
在日本服务器上运行 Flask 应用,可以用 Gunicorn 承载应用进程,用 systemd 管理启动、重启和开机自启,再由 Nginx 接收公网请求并转发到本机 Gunicorn。这样既不需要把 Flask 开发服务器暴露到公网,也能统一查看进程状态和应用日志。

下面以 Ubuntu 22.04/24.04、Python 3、systemd 和 Nginx 为环境,完成一次从应用文件到服务运行的部署。日本机房的位置不会改变 Gunicorn 的配置语法,但公网访问还要经过 DNS、安全组和跨境网络,因此验证时要把“服务器本机运行正常”和“用户能够访问”分开检查。
对于需要在日本部署 Flask、Gunicorn 与 Nginx 服务的业务,A5数据提供日本物理服务器资源,覆盖 Xeon Gold、AMD EPYC、NVMe 存储及多种网络线路方案,可承载企业网站、业务后台、数据库和接口服务等应用。结合日本本地访问、跨境业务及数据规模,A5数据可提供从常规建站到多任务运行的服务器配置基础,为应用的进程管理、反向代理和持续运行提供硬件与网络资源支持。
一、准备环境与部署路径
开始前,应具备以下条件:
- 可以通过 SSH 登录服务器,并拥有
sudo权限。 - 系统使用 systemd;本例不适用于没有 systemd 的容器环境。
- 已有 Flask 项目,或者使用下文的最小应用验证部署流程。
- 一个准备解析到服务器公网 IP 的域名;示例使用
app.example.com,执行前应替换。 - 服务器与云平台安全组允许所需入口流量。Gunicorn 的
8000端口不需要对公网开放。
本例采用固定路径,避免服务文件、应用入口和日志命令相互不一致:
| 对象 | 本例配置 |
|---|---|
| 应用目录 | /srv/a5flask |
| Python 虚拟环境 | /srv/a5flask/.venv |
| 服务运行账户 | flaskapp |
| Flask 入口 | wsgi:app |
| systemd 服务名 | a5flask.service |
| Gunicorn 监听地址 | 127.0.0.1:8000 |
| 应用可写数据目录 | /var/lib/a5flask |
先确认系统和端口状态:
cat /etc/os-release
ps -p 1 -o comm=
sudo ss -lntp
PID 1 应显示 systemd。如果 8000 已被占用,应选择其他本机端口,并同步修改 Gunicorn 和 Nginx 配置。
以下文件创建命令按首次部署编写,会覆盖同名文件。 如果 /srv/a5flask、/etc/systemd/system/a5flask.service 或 /etc/nginx/sites-available/a5flask 已存在,不要直接执行;应先备份现有应用、服务配置和 Nginx 配置,或者为新应用换用独立路径与服务名。已有网站的域名也不能与本例重复,否则可能产生虚拟主机冲突。
二、安装依赖并确认 Flask 入口
1. 创建隔离环境
安装所需软件:
sudo apt update
sudo apt install -y python3 python3-venv nginx curl
sudo useradd --system --user-group \
--home-dir /srv/a5flask --no-create-home \
--shell /usr/sbin/nologin flaskapp
sudo install -d -o root -g root -m 0755 /srv/a5flask
sudo python3 -m venv /srv/a5flask/.venv
sudo /srv/a5flask/.venv/bin/python -m pip install Flask gunicorn
如果 flaskapp 已存在,先用 id flaskapp 核对账户用途,不要修改其他业务正在使用的账户。
本例由管理员安装代码和依赖,应用进程只负责读取,不给服务账户写入代码目录的权限。虚拟环境内的安装不会替换系统 Python 软件包。
验证安装结果,并保存本次依赖版本:
/srv/a5flask/.venv/bin/python -m pip show Flask gunicorn
/srv/a5flask/.venv/bin/python -m pip freeze \
| sudo tee /srv/a5flask/requirements.lock >/dev/null
后续重建环境时可使用这份锁定文件。实际项目已有依赖文件时,应安装项目声明的依赖,并确认其中包含 Gunicorn,而不是只安装上述两个包。
2. 创建应用入口
没有现成项目时,可创建最小验证应用:
sudo tee /srv/a5flask/wsgi.py >/dev/null <<'EOF'
from flask import Flask
app = Flask(__name__)
@app.get("/healthz")
def healthz():
return {"status": "ok"}, 200
@app.get("/")
def index():
return "Flask is running behind Gunicorn.\n"
EOF
wsgi:app 的含义是:导入 wsgi.py 模块,并读取其中名为 app 的 Flask 对象。它不是文件路径,不能写成 /srv/a5flask/wsgi.py:app。
如果项目使用应用工厂,可另建入口文件:
from yourproject import create_app
app = create_app()
实际项目可能在导入时读取数据库配置或密钥,因此应先准备其必需环境变量。不要把真实密钥直接写进 Python 文件。
检查服务账户能否导入应用:
cd /srv/a5flask
sudo -u flaskapp /srv/a5flask/.venv/bin/python \
-c 'from wsgi import app; print(app.url_map)'
对于示例应用,输出中应包含 / 和 /healthz。出现 ModuleNotFoundError 时,先检查模块名称、项目目录和依赖,不要继续启动服务。
三、配置 Gunicorn 与 systemd 服务
1. 设置 Gunicorn 参数
创建配置文件:
sudo tee /srv/a5flask/gunicorn.conf.py >/dev/null <<'EOF'
bind = "127.0.0.1:8000"
workers = 2
worker_class = "gthread"
threads = 2
timeout = 30
graceful_timeout = 30
accesslog = "-"
errorlog = "-"
capture_output = True
loglevel = "info"
forwarded_allow_ips = "127.0.0.1"
EOF
这是一组适合首次验证的起始参数,不代表任何规格服务器都应固定使用两个 worker。例如,2 vCPU、2 GB 内存的小型实例可以先从此配置开始,再根据应用内存占用和响应时间调整。
需要明确三个边界:
- worker 是独立进程:每个进程都可能加载一份模型、缓存或连接池,数量增加会提高内存开销。
- 线程不等于 CPU 算力增加:线程适合部分等待型请求,CPU 密集任务不能仅靠增加线程解决。
timeout不是精确的单请求时限:尤其在使用线程 worker 时,不能把它直接当作业务请求超时。HTTP 调用、数据库查询仍需设置各自的超时。
不要在 Flask 导入阶段启动定时任务或后台循环,否则多个 worker 可能重复执行同一任务。
检查配置与应用加载:
cd /srv/a5flask
sudo -u flaskapp /srv/a5flask/.venv/bin/gunicorn \
--check-config -c /srv/a5flask/gunicorn.conf.py wsgi:app
命令退出码为 0 且没有报错,说明配置与应用加载检查通过,但还需要实际启动和请求验证。
2. 创建服务环境文件
将运行环境与代码分开:
sudo install -o root -g root -m 0600 /dev/null /etc/a5flask.env
sudo tee /etc/a5flask.env >/dev/null <<'EOF'
PYTHONUNBUFFERED=1
APP_DATA_DIR=/var/lib/a5flask
EOF
systemd 会读取该文件并将变量传给服务,服务账户不需要直接读取文件。实际项目可加入必需配置,但不要使用 shell 的 export 写法。
修改已有环境文件前应先备份;文件中若包含密钥,应继续保持仅管理员可读,不要粘贴到公开日志或工单中。
3. 创建 systemd 单元
sudo tee /etc/systemd/system/a5flask.service >/dev/null <<'EOF'
[Unit]
Description=Gunicorn service for Flask application
After=network.target
StartLimitIntervalSec=60
StartLimitBurst=5
[Service]
Type=simple
User=flaskapp
Group=flaskapp
WorkingDirectory=/srv/a5flask
EnvironmentFile=/etc/a5flask.env
ExecStart=/srv/a5flask/.venv/bin/gunicorn --config /srv/a5flask/gunicorn.conf.py wsgi:app
Restart=on-failure
RestartSec=3
TimeoutStopSec=45
KillMode=mixed
StateDirectory=a5flask
StateDirectoryMode=0750
NoNewPrivileges=true
PrivateTmp=true
ProtectHome=true
ProtectSystem=strict
StandardOutput=journal
StandardError=journal
SyslogIdentifier=a5flask
[Install]
WantedBy=multi-user.target
EOF
这里使用虚拟环境中 Gunicorn 的绝对路径,不依赖 SSH 会话里的 source 或 PATH。也不要添加 --daemon 或开发用的 --reload,进程应由 systemd 直接管理。
ProtectSystem=strict 会限制服务对文件系统的写入,而 StateDirectory 会创建并授权 /var/lib/a5flask。需要保存上传文件或 SQLite 数据库时,应明确放在允许写入的数据目录,并让应用真正使用该路径;仅设置环境变量不会自动改变 Flask 的存储位置。
启动前后分别验证:

sudo systemd-analyze verify /etc/systemd/system/a5flask.service
sudo systemctl daemon-reload
sudo systemctl enable --now a5flask
sudo systemctl status a5flask --no-pager
sudo ss -lntp 'sport = :8000'
curl --fail --max-time 5 http://127.0.0.1:8000/healthz
预期状态为 active (running),监听地址是 127.0.0.1:8000,健康检查返回类似结果:
{"status":"ok"}
以上是预期示例,不是服务器实际执行记录。若启动失败,先查看日志:
sudo journalctl -u a5flask -n 100 --no-pager
Gunicorn 的访问日志和错误日志均进入 journal,不需要再让服务账户写入 /var/log。
四、配置 Nginx 入口并分层验证
本节先完成 HTTP 连通性验证。涉及登录、Cookie、支付或敏感数据的生产访问,应在开放业务前配置并验证 HTTPS;HTTP 测试通过不等于完成了证书部署。
创建独立站点配置:
sudo tee /etc/nginx/sites-available/a5flask >/dev/null <<'EOF'
server {
listen 80;
server_name app.example.com;
access_log /var/log/nginx/a5flask.access.log;
error_log /var/log/nginx/a5flask.error.log;
location / {
proxy_pass http://127.0.0.1:8000;
proxy_http_version 1.1;
proxy_set_header Connection "";
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $remote_addr;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_connect_timeout 5s;
proxy_read_timeout 60s;
}
}
EOF
sudo ln -s /etc/nginx/sites-available/a5flask \
/etc/nginx/sites-enabled/a5flask
sudo nginx -t
只有 nginx -t 通过后才能加载配置:
sudo systemctl enable --now nginx
sudo systemctl reload nginx
curl --fail --max-time 5 \
-H 'Host: app.example.com' \
http://127.0.0.1/healthz
本机通过 Nginx 得到健康响应,说明“入口 → Gunicorn → Flask”链路已经打通。
上述转发头配置按 Nginx 直接接收客户端请求 编写。如果前面还有 CDN 或负载均衡,应另行明确可信来源与客户端地址传递规则。Flask 也不会仅凭这些请求头自动信任转发信息;需要识别外部 HTTPS 地址时,可按实际代理层数配置 Werkzeug ProxyFix,不要无条件信任客户端提交的转发头。
接着将域名解析到日本服务器公网 IP,在另一台设备执行:
curl -i --connect-timeout 5 --max-time 10 \
http://app.example.com/healthz
这里必须替换成真实域名。如果服务器没有配置 IPv6 入口,不要留下指向不可用地址的 AAAA 记录。
公网测试失败时,检查云平台安全组和系统防火墙是否允许 TCP 80;部署 HTTPS 后还需允许 TCP 443。调整前记录原规则,保留 SSH 管理入口,只添加所需规则,不要清空防火墙或在远程会话中贸然启用默认拒绝策略。回滚时仅撤销本次新增规则。
日本服务器的公网访问慢,不一定是 Gunicorn 配置问题。 本机访问正常而境外访问耗时较高时,应继续区分 DNS、网络往返时间、TLS 建连和业务处理耗时,不要直接靠增加 worker 解决。
五、按由外到内的顺序处理异常
先查入口,再查进程,最后检查应用依赖,避免同时改动多个层面。

| 现象 | 检查方法 | 处理方向 |
|---|---|---|
| 公网连接超时,本机 Nginx 正常 | 核对 DNS、公网 IP、安全组和系统防火墙 | 修复入口规则,不要开放 Gunicorn 端口 |
| 域名显示默认页面 | 核对请求域名与 server_name,检查站点是否启用 | 修复域名或站点配置,不要盲目删除其他站点 |
| Nginx 返回 502 | 查看 Nginx 错误日志,再访问 127.0.0.1:8000 | 判断是服务未运行、端口不一致还是连接被拒绝 |
| 服务启动后立即退出 | 查看 journalctl -u a5flask | 修复入口、依赖、环境变量或文件权限 |
| 写文件时报权限错误 | 核对写入路径与服务沙箱限制 | 将业务数据放到授权目录,不要使用 chmod -R 777 |
| 请求返回 500 | 按请求时间查看应用 traceback | 修复业务代码或依赖服务,不要反复重启掩盖异常 |
常用日志命令:
sudo tail -n 50 /var/log/nginx/a5flask.error.log
sudo journalctl -u a5flask --since "10 minutes ago" --no-pager
sudo journalctl -u a5flask -f
如果服务因连续失败触发启动限制,先修复日志指出的问题,再解除限制:
sudo systemctl reset-failed a5flask
sudo systemctl start a5flask
不要只提高重启次数。数据库不可达、密钥缺失或模块导入错误,不会因为重启更多次而自行恢复。
六、验收与回滚检查项
上线前按以下顺序验收:
systemctl is-enabled a5flask返回enabled,systemctl is-active a5flask返回active。- Gunicorn 仅监听
127.0.0.1:8000,公网没有开放该端口。 - 本机直连 Gunicorn、本机经过 Nginx、外部经过域名,三处健康检查均通过。
- 真实业务接口正常,数据库连接、上传目录等依赖分别验证,而不只检查
/healthz。 - 可以从 journal 和 Nginx 日志定位同一时间段的请求与错误。
- 正式开放敏感业务前,HTTPS 证书、域名覆盖范围和续期机制已经验证。
还应在允许短暂中断的测试窗口执行一次:
sudo systemctl restart a5flask
curl --fail --max-time 5 http://127.0.0.1:8000/healthz
重启会中断或短暂影响正在处理的请求,首次部署可在引入业务流量前完成,不应在未知负载下直接操作。
首次部署没有旧版本可恢复,回滚目标是撤销本次入口和服务,保留文件供排查。确认 /etc/nginx/sites-enabled/a5flask 确实是本次创建的符号链接后执行:
sudo unlink /etc/nginx/sites-enabled/a5flask
sudo nginx -t && sudo systemctl reload nginx
sudo systemctl disable --now a5flask
这会移除该站点的 Nginx 入口并停止应用,不删除代码、虚拟环境或业务数据。若本次还修改了 DNS、安全组或已有配置,应分别恢复原记录、撤销新增规则,并从备份恢复原配置后重新检查。
回滚完成后,核对服务已停止、开机自启已取消、Nginx 配置有效、其他网站仍可访问。保留错误日志与部署文件,确认故障原因后再进行下一次部署。
本文由A5数据原创发布,转载请注明出处:https://www.a5idc.com/helpcontent/4113.html



