马来西亚服务器如何部署uWSGI应用,启动配置与访问验证要点有哪些
马来西亚服务器首次部署 uWSGI 应用时,核心目标是让 Python Web 应用由 uWSGI 稳定托管,并通过本机回环地址或 Nginx 对外提供访问。推荐先让 uWSGI 监听 127.0.0.1:8000,完成应用、进程和日志验证后,再由 Nginx 监听公网端口,这样应用端口不会直接暴露在互联网中。
下面以 Ubuntu 22.04/24.04、Python 3、Flask WSGI 应用为例,演示从准备环境、安装依赖、编写启动配置,到 systemd 启动、Nginx 转发、外部访问验证和回滚的完整过程。马来西亚机房不会改变 uWSGI 的安装方式,但应额外确认云平台安全组、实例防火墙、IPv4 地址和域名解析是否指向同一台服务器;文中的域名、端口和应用名称均为示例。
uWSGI 与 Nginx 组成的部署方式,可用于承载网站、业务后台和接口服务。A5idc数据提供马来西亚吉隆坡等地区的物理服务器,配置涵盖不同的处理器、存储和网络线路选择,为 Python 应用提供部署所需的计算与网络资源;同时提供香港、日本、新加坡等地区的服务器方案,适用于面向不同地区用户的业务部署。
一、部署范围与准备条件
本次部署只覆盖一个首次运行的 WSGI 应用,采用以下拓扑:
| 组件 | 示例设置 | 作用 |
|---|---|---|
| 操作系统 | Ubuntu 22.04/24.04 | 提供 Python、systemd 和 Nginx 运行环境 |
| 应用目录 | /srv/uwsgi-demo | 保存代码、虚拟环境和 uWSGI 配置 |
| 服务账号 | appsvc | 以非 root 身份运行应用 |
| uWSGI 监听 | 127.0.0.1:8000 | 仅接受本机转发和验证请求 |
| Nginx 监听 | 80 | 接收域名或公网 IP 的 HTTP 请求 |
| WSGI 入口 | app:app | 表示 app.py 文件中的 app 对象 |
开始前准备以下信息:
- 具备服务器 sudo 权限,且已经通过 SSH 登录实例。
- 已确认实例的公网 IPv4 地址;如果使用域名,A 记录应指向该地址。
- 应用能够以 WSGI 形式启动。Flask 常见入口是
app:app,Django 项目通常是项目名.wsgi:application。 - 已确认应用需要的 Python 版本和依赖。不要把本地开发机的虚拟环境目录直接复制到服务器,应该在服务器上重新创建。
- 已决定是否开放公网 80 端口。首次验证可以先只做本机测试,避免在服务未确认前调整防火墙。
先核对系统、Python、内存和端口占用情况:
cat /etc/os-release
python3 --version
sudo systemctl --version | head -n 1
free -h
sudo ss -lntp
预期能看到 Ubuntu 版本和 Python 3.x 版本。ss 没有列出 127.0.0.1:8000 并不代表异常,只表示该端口目前尚未被其他程序使用。如果 8000 已被占用,应先记录占用进程,不要直接结束不明进程;后续可以更换为 8001,并同步修改 uWSGI 与 Nginx 配置。
二、安装系统依赖并创建应用目录
Ubuntu 环境可以安装 Python 虚拟环境、编译工具和 Nginx。uWSGI 通过 pip 安装时可能需要编译,因此首次部署准备 build-essential 和对应的 Python 开发包更稳妥。
sudo apt update
sudo apt install -y python3 python3-venv python3-pip python3-dev build-essential nginx curl
这一步只更新软件包索引并安装列出的软件,不会修改应用代码。安装完成后验证关键程序:
python3 --version
pip3 --version
nginx -v
curl --version | head -n 1
创建专用服务账号和应用目录:
sudo adduser --system --group --home /srv/uwsgi-demo appsvc
sudo install -d -o appsvc -g appsvc -m 0750 /srv/uwsgi-demo
appsvc 只用于运行本示例服务,应用进程不会以 root 身份启动。install -d 创建的目录范围仅为 /srv/uwsgi-demo,不会改变其他目录的权限;如果服务器上已经存在同名账号或目录,应先检查现状,不要重复覆盖。
验证账号和目录:
id appsvc
sudo stat -c '%U:%G %a %n' /srv/uwsgi-demo
预期目录所有者为 appsvc:appsvc,权限示例为 750。如果已有代码需要部署到此目录,应使用备份或版本发布目录替换,不要直接覆盖正在运行的文件。
三、创建虚拟环境并安装 uWSGI
在应用目录创建独立虚拟环境,避免系统 Python 包与当前应用互相影响:
sudo -u appsvc python3 -m venv /srv/uwsgi-demo/.venv
sudo -u appsvc /srv/uwsgi-demo/.venv/bin/python -m pip install --upgrade pip
新建依赖文件 /srv/uwsgi-demo/requirements.txt。下面的 Flask 只是便于演示 WSGI 入口,实际项目应替换为项目自身的依赖清单:
Flask>=3.0,<4
uWSGI>=2.0,<3
安装依赖并记录安装结果:
sudo -u appsvc /srv/uwsgi-demo/.venv/bin/pip install -r /srv/uwsgi-demo/requirements.txt
sudo -u appsvc /srv/uwsgi-demo/.venv/bin/pip freeze
sudo -u appsvc /srv/uwsgi-demo/.venv/bin/uwsgi --version
如果 uwsgi 安装阶段提示编译器、Python 头文件或链接器缺失,先查看错误中缺少的系统包,再补装对应依赖。不要把系统中另一个 Python 环境里的 uWSGI 路径直接写进服务配置。验证时应确认 which 和版本命令指向 /srv/uwsgi-demo/.venv/bin/。
四、准备一个可验证的 WSGI 应用
将应用代码保存为 /srv/uwsgi-demo/app.py。真实项目可以保留自己的业务逻辑,但需要提供一个可调用的 WSGI 对象:
from flask import Flask
app = Flask(__name__)
@app.get('/')
def index():
return 'uWSGI application is running\n', 200
@app.get('/healthz')
def healthz():
return 'ok\n', 200
这里的 app 是 Flask 应用对象,所以 uWSGI 配置中的模块入口写作 app:app。如果文件名改为 main.py,入口就应改为 main:app;如果入口名称拼错,uWSGI 会在启动日志中报告模块导入失败。
写入代码后,先不用启动 uWSGI,直接用虚拟环境检查模块是否可以导入:
sudo -u appsvc sh -c 'cd /srv/uwsgi-demo && .venv/bin/python -c "from app import app; print(app.name)"'
预期输出应用名称,通常为 app。如果出现 ModuleNotFoundError,先检查当前目录、文件名和依赖安装位置;如果出现语法错误,应先修正代码,再进入服务配置阶段。
五、编写 uWSGI 启动配置
创建 /srv/uwsgi-demo/uwsgi.ini:
[uwsgi]
chdir = /srv/uwsgi-demo
module = app:app
home = /srv/uwsgi-demo/.venv
master = true
processes = 2
threads = 2
http-socket = 127.0.0.1:8000
vacuum = true
die-on-term = true
need-app = true
各配置项的用途如下:
chdir确保 uWSGI 从应用目录加载模块。module指定 WSGI 入口,格式为Python模块:对象名。home让 uWSGI 使用本应用的虚拟环境。master负责管理 worker;processes和threads是示例值,实际数量应按内存和应用类型调整。http-socket让 uWSGI 直接提供 HTTP 协议,便于使用curl验证,也便于 Nginx 使用proxy_pass转发。need-app在应用加载失败时让启动失败,而不是启动一个没有可用应用的空进程。die-on-term配合 systemd 的停止信号使用,vacuum用于退出时清理 uWSGI 资源。
这里选择 http-socket,因此 Nginx 必须使用 proxy_pass http://127.0.0.1:8000。如果改用 uWSGI 原生协议的 socket = 127.0.0.1:8000,Nginx 配置也必须改为 uwsgi_pass 并加载相应参数,不能混用两种协议。

先做配置和入口验证:
sudo -u appsvc /srv/uwsgi-demo/.venv/bin/uwsgi --version
sudo -u appsvc sh -c 'cd /srv/uwsgi-demo && .venv/bin/python -c "from app import app; print(app)"'
sudo -u appsvc sh -c 'test -r /srv/uwsgi-demo/uwsgi.ini && echo config-readable'
这些命令只验证文件、Python 入口和 uWSGI 可执行文件,不会留下后台服务。预期分别能看到版本、应用对象表示和 config-readable。
六、使用 systemd 管理启动和重启
创建 /etc/systemd/system/uwsgi-demo.service:
[Unit]
Description=uWSGI demo application
After=network-online.target
Wants=network-online.target
[Service]
Type=simple
User=appsvc
Group=appsvc
WorkingDirectory=/srv/uwsgi-demo
Environment=PYTHONUNBUFFERED=1
ExecStart=/srv/uwsgi-demo/.venv/bin/uwsgi --ini /srv/uwsgi-demo/uwsgi.ini
Restart=on-failure
RestartSec=5
NoNewPrivileges=true
PrivateTmp=true
[Install]
WantedBy=multi-user.target
保存后重新加载 systemd,并启动服务:
sudo systemctl daemon-reload
sudo systemctl enable --now uwsgi-demo.service
sudo systemctl status uwsgi-demo.service --no-pager
enable --now 会同时设置开机启动并立即启动服务。首次执行不应直接假定成功,应根据 status 的结果继续检查。若状态为 active (running),再查看监听端口和日志:
sudo ss -lntp | grep ':8000'
sudo journalctl -u uwsgi-demo.service -n 50 --no-pager
预期监听地址为 127.0.0.1:8000,而不是 0.0.0.0:8000。日志中不应持续出现导入错误、权限错误或 worker 反复退出。示例中的 processes = 2 只代表启动两个 worker,不代表实际容量;内存较小的实例可以先使用一个进程,确认应用稳定后再调整。
进行本机直连验证:
curl -i http://127.0.0.1:8000/
curl -i http://127.0.0.1:8000/healthz
预期返回类似以下内容:
HTTP/1.1 200 OK
Content-Type: text/html; charset=utf-8
uWSGI application is running
健康检查接口预期返回 200 和 ok。如果本机请求失败,先不要配置 Nginx;只有 uWSGI 直接访问成功,才有必要继续排查反向代理。
七、配置 Nginx 对外转发
创建 /etc/nginx/sites-available/uwsgi-demo:
server {
listen 80;
server_name example.com;
location / {
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_pass http://127.0.0.1:8000;
}
}
将 example.com 替换为实际域名。如果暂时没有域名,可以先写服务器公网 IPv4 地址;直接用 IP 访问时,Nginx 的 server_name 匹配应与请求头一致。为了避免修改默认站点,先创建本次配置的软链接:
sudo ln -s /etc/nginx/sites-available/uwsgi-demo /etc/nginx/sites-enabled/uwsgi-demo
sudo nginx -t
nginx -t 预期显示 syntax is ok 和 test is successful。只有测试成功后才执行重载:
sudo systemctl reload nginx
sudo systemctl status nginx --no-pager
如果服务器仍启用 Ubuntu 默认站点,使用同一 IP 访问时可能被默认站点抢先匹配。此时先备份默认配置,再确认它确实是冲突来源:
sudo cp -a /etc/nginx/sites-enabled/default /etc/nginx/sites-enabled/default.before-uwsgi
确认后再将默认站点临时移出启用目录。该动作会影响默认站点,但不会删除文件,回滚时可移回原路径:
sudo mv /etc/nginx/sites-enabled/default /etc/nginx/sites-enabled/default.disabled
sudo nginx -t
sudo systemctl reload nginx
如果只需要本机验证,可以先不调整默认站点,使用指定 Host 头测试本次 server 块:
curl -i -H 'Host: example.com' http://127.0.0.1/
八、开放端口并进行外部访问验证
先确认 Nginx 在本机已监听 80:
sudo ss -lntp | grep ':80'
curl -i -H 'Host: example.com' http://127.0.0.1/healthz
如果本机返回 200 OK,再检查服务器防火墙。使用 UFW 的系统可以先查看状态,不要在不了解现有规则时直接重置防火墙:
sudo ufw status verbose
只有确认业务需要公网 HTTP,且云平台安全组也允许 80/TCP 时,才添加规则:
sudo ufw allow 80/tcp
sudo ufw status numbered
该规则会让公网访问服务器的 80 端口,影响范围是整台服务器的 HTTP 入口;若需要撤回本次规则,可以使用:
sudo ufw delete allow 80/tcp
如果云平台另有安全组、网络 ACL 或边界防火墙,还要在对应控制台放行 80/TCP。马来西亚服务器的公网访问是否成功,不能只看操作系统内的 UFW;云平台入口策略和 DNS 解析同样会影响结果。
从服务器外部网络测试,不要只在服务器本机执行:
curl -4 -i http://example.com/healthz
curl -4 -i http://服务器公网IPv4/healthz
预期结果为 HTTP 200 和响应正文 ok。如果使用域名,先核对解析结果:
dig +short example.com A
解析出的 IPv4 应与服务器公网 IPv4 一致。若服务器同时配置 IPv6,而 AAAA 记录指向了尚未放行 80 端口的地址,部分客户端可能优先走 IPv6,因此应分别检查 A 和 AAAA 记录,或在 IPv6 尚未配置时不要发布错误的 AAAA 记录。
九、常见异常及处理顺序
故障排查应从外到内、从低风险检查开始,不要一出现 502 就重装 uWSGI。
| 现象 | 优先检查 | 处理方向 |
|---|---|---|
| systemd 为 failed | systemctl status 和 journalctl | 检查入口、虚拟环境路径、权限和端口冲突 |
ModuleNotFoundError | WorkingDirectory、module、依赖安装路径 | 确认文件名和 app:app 是否匹配,并在同一虚拟环境中安装依赖 |
Address already in use | `sudo ss -lntp | grep ':8000'` |
| 本机 8000 连接被拒绝 | systemd 状态、监听地址和日志 | 服务未启动、启动后退出,或配置监听了其他端口 |
| Nginx 返回 502 | uWSGI 监听、Nginx proxy_pass、uWSGI 日志 | 两端端口必须一致,且配置协议应为 HTTP 转发 |
| 返回 404 | 应用路由和请求路径 | /healthz 与 / 是两个不同路径,先请求已定义的路由 |
| 外部超时 | 云安全组、UFW、Nginx 监听和 DNS | 逐层确认 80/TCP 是否放行,以及域名是否指向正确地址 |
| 权限 denied | namei -l /srv/uwsgi-demo/app.py | 确认 appsvc 对目录和文件有读取权限,不要为了省事给整个目录 777 |
查看最近日志时,可以同时观察 Nginx 和 uWSGI:
sudo journalctl -u uwsgi-demo.service -n 100 --no-pager
sudo journalctl -u nginx.service -n 100 --no-pager
sudo tail -n 50 /var/log/nginx/error.log
如果 uWSGI 日志显示应用加载成功,但 Nginx 仍返回 502,重点检查 http-socket 与 proxy_pass 是否配套,以及配置修改后是否执行了 nginx -t 和 reload。若 uWSGI 直接返回 200,而外部访问失败,问题通常已经移到 Nginx、DNS、安全组或防火墙层面。
十、验收检查与回滚方法
完成首次部署后,按以下顺序验收:
systemctl is-enabled uwsgi-demo.service返回enabled。systemctl is-active uwsgi-demo.service返回active。ss -lntp显示 uWSGI 仅监听127.0.0.1:8000,没有把应用端口直接暴露到公网。curl http://127.0.0.1:8000/healthz返回200和ok。nginx -t检查通过,且 Nginx 服务处于运行状态。- 通过域名或公网 IP 访问
/healthz返回200。 - 重启 uWSGI 后再次访问,确认 systemd 能自动拉起服务:
sudo systemctl restart uwsgi-demo.service
sleep 2
sudo systemctl is-active uwsgi-demo.service
curl -i http://127.0.0.1:8000/healthz
回滚前先保留应用代码、uwsgi.ini、systemd 单元和 Nginx 配置的备份。首次部署若需要撤回,只停用本次新增服务和站点,不要删除不属于本次部署的文件:
sudo systemctl disable --now uwsgi-demo.service
sudo nginx -t
如果要撤回 Nginx 本次新增的软链接,必须先确认该路径确实由本次部署创建,再执行:
sudo unlink /etc/nginx/sites-enabled/uwsgi-demo
sudo systemctl reload nginx
若此前临时移出了默认站点,可恢复备份路径:
sudo mv /etc/nginx/sites-enabled/default.disabled /etc/nginx/sites-enabled/default
sudo nginx -t
sudo systemctl reload nginx
应用目录和服务账号是否删除,应在确认没有其他服务引用后再决定。删除目录或账号会造成数据和权限信息丢失,不应作为常规回滚步骤。对于需要保留现场的故障,优先停服务、恢复旧配置并保存日志;确认回滚后的 Nginx 配置、端口监听和外部访问均符合预期,再处理遗留文件。
本文由A5数据原创发布,转载请注明出处:https://www.a5idc.com/helpcontent/8248.html



