Flask生产部署：uWSGI+Nginx在Ubuntu 18.04上的实战配置

1. 项目概述：为什么 Flask 应用不能直接暴露给公网？

在 Ubuntu 18.04 上用 uWSGI + Nginx 部署 Flask，这事儿我干过不下三十次——从学生作业系统、内部数据看板，到日均请求量破十万的轻量级 API 网关。很多人第一次写完 flask run 能访问，就以为部署完成了，结果把开发服务器直接扔到公网上，不出三天准出事。这不是危言耸听：Flask 自带的 Werkzeug 开发服务器 明确声明不适用于生产环境 ，它单线程、无超时控制、不支持长连接复用、没有请求队列缓冲，更别提静态文件缓存、SSL 终止、负载均衡这些刚需功能了。你用 python app.py 启动的服务，本质上是个“调试探针”，不是“生产网关”。

核心关键词 Flask、uWSGI、Nginx、Ubuntu 18.04 在这里不是并列关系，而是清晰的三层协作链：Flask 是业务逻辑层（Python Web 框架），uWSGI 是应用服务器层（负责将 HTTP 请求翻译成 Python 可理解的 WSGI 协议调用，并管理进程/线程生命周期），Nginx 是反向代理与 Web 服务器层（处理 TCP 连接、SSL 解密、静态资源服务、请求分发、DDoS 缓冲）。这三者缺一不可，就像厨房里：Flask 是厨师（做菜），uWSGI 是传菜员兼后厨调度（把客人点单准确转达给厨师，并控制上菜节奏），Nginx 是前台经理（接待客人、验票、分流、处理投诉、保管菜单和餐具）。你不能让厨师直接站在门口拉客，也不能让前台经理亲自炒菜。

这个方案特别适合 Flask 开发者、中小团队运维、独立开发者、教学实验环境 。它不依赖 Docker 或 Kubernetes 这类重型编排工具，所有组件都可直接通过 apt 和 pip 安装，配置文件纯文本、可版本化、可审计。Ubuntu 18.04 虽已进入 ESM（扩展安全维护）阶段，但其内核稳定、软件源成熟、文档丰富，仍是很多遗留系统和教育场景的首选基线。我见过太多人跳过这一步，直接上 Docker Compose，结果连 nginx -t 都配不对，最后发现根本问题是没搞懂 Nginx 的 location 匹配优先级和 uWSGI 的 socket 权限模型。所以这篇内容不讲花哨概念，只讲你在终端里敲的每一行命令背后的真实意图，以及那些只有踩过坑才懂的细节。

2. 整体架构设计与技术选型逻辑

2.1 为什么是 uWSGI 而不是 Gunicorn 或 mod_wsgi？

在 Flask 生产部署的“三剑客”（uWSGI、Gunicorn、mod_wsgi）中，我坚持在 Ubuntu 18.04 上首选 uWSGI，理由非常实际，不是教科书式的“性能对比”，而是基于真实运维场景的权衡：

• 进程模型灵活性 ：uWSGI 支持 prefork、threaded、gevent、asyncio 多种模式，且能动态调整 worker 数量（ --processes auto ）。Gunicorn 默认只支持 prefork，虽然简单，但在高并发短连接场景下，worker 进程数固定会导致资源浪费或瓶颈；而 uWSGI 的 cheaper 子系统可以按需启停 worker，实测在流量波峰波谷明显的内部系统中，内存占用比 Gunicorn 低 35% 左右。

• 信号与热重载控制 ：uWSGI 提供 --touch-reload 参数，只需 touch /path/to/app.py 就能触发平滑重启，无需 kill 进程。Gunicorn 依赖 --reload ，但该模式仅用于开发，生产禁用；而 kill -s HUP 对 Gunicorn 的 reload 行为不如 uWSGI 的 --master + --reload 组合稳定。我在一个需要每小时更新规则库的风控 API 中，用 uWSGI 的 --touch-reload 配合 cron，实现了零中断更新。

• 与 Nginx 的 socket 协作深度 ：uWSGI 原生支持 Unix domain socket（如 /run/uwsgi/app.sock ），权限控制粒度细（ chmod-socket 、 chown-socket ），且 Nginx 的 uwsgi_pass 指令对 uWSGI socket 的错误检测（如 socket 文件不存在、权限不足）反馈更明确。Gunicorn 也支持 socket，但其默认行为更倾向 TCP 端口，而端口冲突、防火墙策略、TIME_WAIT 积压等问题，在 Ubuntu 18.04 的 systemd 管理下更难排查。

提示：mod_wsgi 是 Apache 的原生模块，性能优秀，但 Apache 在现代轻量级 API 场景中配置冗余、内存开销大，且 Ubuntu 18.04 的 Apache2 默认配置与 Flask 的 WSGI 路径常有冲突（如 .wsgi 文件解析问题），调试成本远高于 uWSGI+Nginx 组合。

2.2 为什么 Nginx 是不可替代的反向代理？

有人问：“我用 uWSGI 直接监听 80 端口不行吗？”——理论上可以，但实践中等于裸奔。Nginx 的核心价值不在“转发”，而在“防护”与“卸载”：

• SSL 终止（TLS Termination） ：Nginx 原生支持 OCSP Stapling、HSTS、TLS 1.3，且证书热加载（ nginx -s reload 不中断连接）。若让 uWSGI 自己处理 HTTPS，它必须加载私钥，一旦进程崩溃，私钥可能泄露；而 Nginx 作为前置，uWSGI 只需走本地 HTTP 或 Unix socket，完全规避私钥暴露风险。

• 静态文件零拷贝服务 ：Flask 的 send_from_directory 是 Python 层读取文件再返回，每请求一次磁盘 I/O。Nginx 的 location /static 配置启用 sendfile on ，由内核直接 DMA 传输，实测在 1MB 图片服务中，QPS 提升 4.2 倍，CPU 占用下降 68%。

• 请求缓冲与防刷 ：Nginx 的 client_max_body_size 、 client_header_timeout 、 limit_req （漏桶限流）能有效拦截恶意大包、慢速攻击（Slowloris）、暴力请求。uWSGI 的 harakiri 参数虽能杀掉超时请求，但它是事后处理；Nginx 的 proxy_read_timeout 是事前阻断，更高效。

• IPv6 双栈支持 ：Ubuntu 18.04 的 Nginx 包默认编译支持 IPv6，只需在 listen 指令中加 [::]:80 ，即可同时响应 IPv4/IPv6 请求。而 uWSGI 的 http-socket 对 IPv6 的兼容性在旧版本中不稳定，曾导致某高校教务系统在纯 IPv6 校园网中无法访问。

2.3 Ubuntu 18.04 的特殊考量：LTS 版本的“稳”与“旧”

Ubuntu 18.04 是一个典型的“长周期稳定版”，其 apt 源中的软件包版本偏旧，但这恰恰是优势：

• uWSGI 版本锁定 ：Ubuntu 18.04 的 python3-uwsgi 包版本为 2.0.17.1，该版本对 Python 3.6（系统默认）兼容完美，无 ImportError: cannot import name 'soft_unicode' 等常见于新版 uWSGI 与旧 Flask 的兼容问题。而 pip install 的最新版 uWSGI（如 2.0.25）在 18.04 上需手动编译，易因 gcc 版本或 libpcre3-dev 缺失失败。

• Nginx 版本可靠 ： nginx-full 包版本为 1.14.0，虽非最新，但修复了 CVE-2018-16843 等关键漏洞，且其 upstream 模块对 uWSGI 的 uwsgi_param 支持成熟，不会出现 502 Bad Gateway 因 uwsgi_pass 解析失败。

• systemd 服务管理统一 ：Ubuntu 18.04 全面采用 systemd，uWSGI 和 Nginx 均可通过 systemctl 管理，日志统一归集到 journalctl -u nginx 或 journalctl -u uwsgi ，无需额外配置 logrotate。我见过太多人在 CentOS 7 上用 SysV init 脚本管理 uWSGI，结果 service uwsgi restart 时 worker 进程残留，导致端口占用。

注意：不要试图用 apt update && apt upgrade 升级整个系统到 20.04，这会破坏原有服务依赖。LTS 版本的价值在于“冻结”，而非“升级”。我们只升级必要组件（如 OpenSSL 补丁），其他保持原样。

3. 核心细节解析与实操要点

3.1 Flask 应用的最小化改造：从开发到生产

一个能跑通 flask run 的应用，离生产还差三步：路径隔离、配置分离、异常兜底。这不是代码风格问题，而是安全与可观测性的硬性要求。

第一步：绝对路径隔离
Flask 默认从当前工作目录（ pwd ）查找模板和静态文件。生产环境中，uWSGI 的工作目录是 /var/www/myapp ，而你的代码可能在 /opt/myapp 。若不显式指定， render_template('index.html') 会去 /var/www/myapp/templates/ 找，必然 404。解决方案是在 create_app() 中强制设置：

import os
from flask import Flask

def create_app():
    app = Flask(__name__,
        # 显式指定根目录，避免相对路径歧义
        root_path='/opt/myapp',
        # 模板和静态文件路径必须为绝对路径
        template_folder='/opt/myapp/templates',
        static_folder='/opt/myapp/static'
    )
    return app

第二步：配置分离与环境变量注入
绝不能在代码里写 app.config['SECRET_KEY'] = 'hardcoded' 。Ubuntu 18.04 的 systemd 服务支持 EnvironmentFile ，我们创建 /etc/default/myapp ：

# /etc/default/myapp
SECRET_KEY=your-32-byte-secret-here
DATABASE_URL=postgresql://user:pass@localhost/mydb
FLASK_ENV=production

然后在 Flask 中读取：

import os
from flask import Flask

def create_app():
    app = Flask(__name__)
    # 从环境变量加载配置，覆盖默认值
    app.config.from_mapping(
        SECRET_KEY=os.environ.get('SECRET_KEY', 'dev-key'),
        DATABASE_URL=os.environ.get('DATABASE_URL', 'sqlite:///dev.db')
    )
    return app

第三步：全局异常处理器与日志规范
开发时 debug=True 会显示详细 traceback，生产必须关闭，并提供用户友好的错误页：

@app.errorhandler(500)
def internal_error(error):
    app.logger.error('Server Error: %s', (error))
    return render_template('500.html'), 500

@app.errorhandler(Exception)
def unhandled_exception(e):
    app.logger.error('Unhandled Exception: %s', (e))
    return render_template('500.html'), 500

同时，强制日志输出到 syslog，便于 journalctl 统一查看：

import logging
from logging.handlers import SysLogHandler

def create_app():
    app = Flask(__name__)
    # 配置日志输出到 syslog
    handler = SysLogHandler(address='/dev/log')
    handler.setLevel(logging.INFO)
    app.logger.addHandler(handler)
    app.logger.setLevel(logging.INFO)
    return app

实操心得：我曾在一个图书管理系统中，因未设置 root_path ，uWSGI 启动后所有静态 CSS 加载 404，排查了 2 小时才发现是 static_folder 路径错误。教训是： 永远用 ls -l /opt/myapp/static 确认路径存在且可读，再启动服务 。

3.2 uWSGI 配置文件的 7 个生死参数

uWSGI 的配置是部署成败的关键， .ini 文件不是越长越好，而是每个参数都有明确目的。以下是我在 Ubuntu 18.04 上验证过的最小可行配置 /etc/uwsgi/apps-available/myapp.ini ：

[uwsgi]
# 1. 应用入口：指向 Flask 工厂函数
module = wsgi:app
# 2. Python 路径：确保能 import wsgi 模块
pythonpath = /opt/myapp
# 3. 进程模型：prefork + master，稳定第一
master = true
processes = 4
# 4. Socket：Unix domain socket，比 TCP 更快更安全
socket = /run/uwsgi/myapp.sock
# 5. Socket 权限：Nginx 用户（www-data）必须可读写
chmod-socket = 664
chown-socket = www-data:www-data
# 6. 安全加固：降低权限，避免 root 运行
uid = www-data
gid = www-data
# 7. 日志与监控：输出到 systemd journal
logto = /dev/log
log-format = %(addr) - %(user) [%(ltime)] "%(method) %(uri) %(proto)" %(status) %(size) "%(referer)" "%(uagent)"

参数详解与避坑点：

• module = wsgi:app ： wsgi.py 是入口文件名， app 是其中创建的 Flask 实例或工厂函数名。若用工厂函数（如 create_app() ），必须写 module = wsgi:create_app 。我曾因写成 wsgi:application （Django 风格）导致 uWSGI 启动失败，日志只显示 ImportError ，实际是找不到 application 变量。

• pythonpath ：这是 Python 的 sys.path ，不是文件系统路径。 /opt/myapp 必须包含 wsgi.py ，且 wsgi.py 所在目录不能有 __init__.py （否则会被当作包导入，路径解析异常）。

• chmod-socket = 664 ：关键！Nginx 进程以 www-data 用户运行，uWSGI socket 文件权限必须允许 www-data 组写入。 664 表示 owner（www-data）可读写，group（www-data）可读写，other 可读。若设为 644 ，Nginx 无法连接 socket，报错 connect() to unix:/run/uwsgi/myapp.sock failed (13: Permission denied) 。

• uid/gid = www-data ：uWSGI 主进程以 root 启动（因需绑定低端口或创建 socket），但 worker 进程必须降权。 www-data 是 Ubuntu 18.04 的标准 web 用户，Nginx 也用此用户，权限一致，避免跨用户文件访问问题。

• logto = /dev/log ：Ubuntu 18.04 的 systemd-journald 默认监听 /dev/log ，uWSGI 日志会自动归集到 journalctl -u uwsgi 。若写 logto = /var/log/uwsgi/myapp.log ，需手动创建目录、设置权限、配置 logrotate，多此一举。

提示：uWSGI 启动后，用 ls -l /run/uwsgi/myapp.sock 确认 socket 文件存在，且属主为 www-data:www-data ，权限为 srw-rw-r-- （注意开头的 s 表示 socket 类型）。这是排查 502 错误的第一步。

3.3 Nginx 配置的 5 个核心指令与 location 匹配陷阱

Nginx 配置的核心是 server 块内的 location 规则。新手常犯的错误是把所有请求都 proxy_pass 给 uWSGI，导致静态文件也走 Python，性能崩盘。正确做法是 动静分离 。

标准配置 /etc/nginx/sites-available/myapp ：

server {
    listen 80;
    listen [::]:80;
    server_name myapp.example.com;

    # 1. 根路径：交由 uWSGI 处理动态请求
    location / {
        include         uwsgi_params;
        uwsgi_pass      unix:/run/uwsgi/myapp.sock;
        uwsgi_read_timeout 300;
        # 传递客户端真实 IP（重要！否则 Flask 中 request.remote_addr 是 127.0.0.1）
        uwsgi_param     X-Real-IP $remote_addr;
        uwsgi_param     X-Forwarded-For $proxy_add_x_forwarded_for;
        uwsgi_param     X-Forwarded-Proto $scheme;
    }

    # 2. 静态文件：Nginx 直接服务，不经过 uWSGI
    location /static {
        alias /opt/myapp/static/;
        expires 1h;
        add_header Cache-Control "public, immutable";
    }

    # 3. 上传文件临时目录（如 Flask-Uploads）
    location /uploads {
        alias /opt/myapp/uploads/;
        # 防止用户上传 .php 文件被 Nginx 执行
        location ~ \.php$ {
            deny all;
        }
    }

    # 4. 健康检查端点：Nginx 自己返回，不转发
    location /healthz {
        return 200 "OK";
        add_header Content-Type text/plain;
    }

    # 5. 错误页：自定义 50x 页面
    error_page 500 502 503 504 /50x.html;
    location = /50x.html {
        root /usr/share/nginx/html;
    }
}

location 匹配陷阱详解：

• location / 与 location /static 的优先级：Nginx 的 location 匹配遵循 最长前缀匹配 原则。 /static/css/app.css 会匹配 location /static ，而非 location / ，因为 /static 比 / 更长。这是正确的。

• alias vs root ： alias /opt/myapp/static/ 表示将 /static/xxx 映射到 /opt/myapp/static/xxx ；而 root /opt/myapp/static 会映射到 /opt/myapp/static/static/xxx ，多了一层 static ，导致 404。这是最常踩的坑，务必记清： alias 是 替换整个匹配路径 ， root 是 追加路径 。

• uwsgi_param 的必要性：Flask 的 request.remote_addr 默认是 uWSGI 进程的 IP（127.0.0.1），而非真实用户 IP。 X-Real-IP 和 X-Forwarded-For 参数由 Nginx 设置，uWSGI 会将其注入 WSGI 环境，Flask 才能通过 request.headers.get('X-Real-IP') 获取真实 IP。没有这行，所有日志里的 IP 都是 127.0.0.1 。

• uwsgi_read_timeout 300 ：uWSGI 处理一个请求的最长等待时间。若 Flask 视图中有耗时数据库查询或外部 API 调用，必须调高此值，否则 Nginx 会主动断开连接，返回 504 Gateway Timeout。我在线上一个报表导出接口中，将此值设为 1800 （30 分钟）。

注意：配置完成后，必须执行 sudo nginx -t 测试语法，再 sudo systemctl reload nginx 。 nginx -t 是唯一可靠的语法检查器，比任何 IDE 插件都准。

4. 实操过程与完整部署流程

4.1 环境准备：Ubuntu 18.04 的 6 个初始化步骤

部署前，先清理系统环境，避免依赖冲突。以下命令需逐条执行，顺序不可乱：

1. 更新系统并安装基础工具

   sudo apt update && sudo apt upgrade -y
   sudo apt install -y python3-pip python3-dev build-essential libssl-dev libffi-dev
   

   说明： build-essential 提供 gcc， libssl-dev 和 libffi-dev 是 uWSGI 编译必需的头文件。Ubuntu 18.04 的 python3-dev 包含 Python.h，缺失会导致 pip install uwsgi 编译失败。

2. 创建应用目录与用户

   sudo mkdir -p /opt/myapp
   sudo chown -R $USER:$USER /opt/myapp
   # 创建专用用户，避免用 root 或 www-data 运行代码
   sudo adduser --disabled-password --gecos "" myappuser
   sudo usermod -a -G www-data myappuser
   sudo chown -R myappuser:www-data /opt/myapp
   

3. 安装 uWSGI（使用 apt，非 pip）

   sudo apt install -y python3-uwsgi
   # 验证安装
   uwsgi --version  # 应输出 2.0.17.1
   

4. 安装 Nginx 并禁用默认站点

   sudo apt install -y nginx
   sudo systemctl stop nginx
   sudo rm /etc/nginx/sites-enabled/default
   sudo systemctl start nginx
   # 验证 Nginx 运行：curl http://localhost 返回 welcome page
   

5. 创建 uWSGI 应用目录结构

   cd /opt/myapp
   # 创建必要目录
   mkdir -p templates static uploads
   # 创建 wsgi.py 入口文件
   cat > wsgi.py << 'EOF'
   

from myapp import create_app app = create_app() EOF

创建应用主模块（示例）

cat > myapp/ init .py << 'EOF' from flask import Flask

def create_app(): app = Flask( name ) @app.route('/') def hello(): return "Hello from Flask on uWSGI + Nginx!" return app EOF

6. **设置 systemd 服务文件**  
创建 `/etc/systemd/system/uwsgi-myapp.service`：
```ini
[Unit]
Description=uWSGI instance to serve myapp
After=network.target

[Service]
User=myappuser
Group=www-data
WorkingDirectory=/opt/myapp
EnvironmentFile=/etc/default/myapp
ExecStart=/usr/bin/uwsgi --ini /etc/uwsgi/apps-available/myapp.ini

[Install]
WantedBy=multi-user.target

4.2 配置启用与服务启动：8 个关键命令

完成上述准备后，按顺序执行以下命令，每一步都需验证输出：

1. 启用 uWSGI 应用配置

   sudo ln -s /etc/uwsgi/apps-available/myapp.ini /etc/uwsgi/apps-enabled/myapp.ini
   sudo systemctl daemon-reload
   sudo systemctl start uwsgi
   sudo systemctl enable uwsgi
   # 验证：sudo systemctl status uwsgi，应显示 active (running)
   

2. 验证 uWSGI socket 是否创建

   ls -l /run/uwsgi/myapp.sock
   # 输出应类似：srw-rw-r-- 1 www-data www-data 0 Jun 10 10:00 /run/uwsgi/myapp.sock
   

3. 启用 Nginx 站点配置

   sudo ln -s /etc/nginx/sites-available/myapp /etc/nginx/sites-enabled/myapp
   sudo nginx -t  # 必须显示 "syntax is ok, test is successful"
   sudo systemctl reload nginx
   

4. 测试 Nginx 到 uWSGI 的连通性

   # 用 curl 模拟 Nginx 的请求头
   curl -H "Host: myapp.example.com" http://localhost/
   # 应返回 "Hello from Flask..."
   

5. 测试静态文件服务

   # 创建测试文件
   echo "test css" | sudo tee /opt/myapp/static/test.css
   curl http://localhost/static/test.css
   # 应返回 "test css"
   

6. 测试健康检查端点

   curl http://localhost/healthz
   # 应返回 "OK"
   

7. 检查日志（双通道验证）

   # uWSGI 日志
   sudo journalctl -u uwsgi -n 20 -f
   # Nginx 访问日志
   sudo tail -f /var/log/nginx/access.log
   # 此时访问 http://localhost，两处日志应同步出现记录
   

8. 开放防火墙（如启用）

   sudo ufw allow 'Nginx Full'
   sudo ufw status verbose  # 确认 80/443 端口开放
   

实操心得：第 4 步 curl -H "Host..." 是最关键的连通性测试。它绕过了 DNS 和 server_name 匹配，直接验证 Nginx 的 location / 是否正确转发到 uWSGI。如果这步失败，90% 的原因是 uwsgi_pass 路径错误或 socket 权限问题。我习惯把这个命令写成 alias： alias testuwsgi='curl -H "Host: x" http://localhost/' ，随时快速验证。

4.3 SSL 配置：Let's Encrypt 的 4 步自动化

生产环境必须启用 HTTPS。Ubuntu 18.04 的 certbot 包完美支持 Nginx 插件：

1. 安装 certbot

   sudo apt install -y python3-certbot-nginx
   

2. 获取证书（需域名已解析到服务器 IP）

   sudo certbot --nginx -d myapp.example.com
   # 按提示输入邮箱，同意协议，选择是否重定向 HTTP 到 HTTPS
   

3. 验证证书自动配置
   certbot 会自动修改 /etc/nginx/sites-available/myapp ，添加 listen 443 ssl 块，并配置证书路径。检查：

   sudo nginx -t  # 确保语法正确
   sudo systemctl reload nginx
   

4. 设置自动续期
   certbot 已创建 systemd timer：

   sudo systemctl list-timers | grep certbot
   # 应显示 certbot.timer，每周日凌晨 02:22 执行
   # 手动测试续期：sudo certbot renew --dry-run
   

注意： certbot 修改的 Nginx 配置中， ssl_certificate 指向 /etc/letsencrypt/live/myapp.example.com/fullchain.pem ， ssl_certificate_key 指向 privkey.pem 。这些文件权限为 600 ，仅 root 可读，Nginx 主进程以 root 运行，故可安全加载。

5. 常见问题与排查技巧实录

5.1 502 Bad Gateway：uWSGI 与 Nginx 的握手失败

这是部署中最常见的错误，原因集中在 socket 通信层。按以下顺序排查：

典型案例 ：某次部署后， ls -l /run/uwsgi/myapp.sock 显示属主是 root:root ，权限 600 。原因是 uWSGI 配置中漏写了 chown-socket 。解决：在 myapp.ini 中添加 chown-socket = www-data:www-data ，然后 sudo systemctl restart uwsgi 。

5.2 404 Not Found：静态文件或路由找不到

404 分两类：动态路由 404（Flask 层）和静态文件 404（Nginx 层）。区分方法：看 Nginx 的 access.log 中的 status 字段。

• 动态路由 404 ： access.log 中 status=404 ，但 upstream_addr 字段为空（表示未转发到 uWSGI）。原因：Nginx 的 location / 未匹配到请求，或 server_name 不匹配。检查 curl -H "Host: wrong-domain.com" http://localhost/ 是否也 404。

• 静态文件 404 ： access.log 中 status=404 ，且 upstream_addr 有值（如 127.0.0.1:5000 ），说明请求被错误地 proxy_pass 到了 uWSGI。原因： location /static 规则未生效。检查 location 顺序，确保 /static 在 / 之前；检查 alias 路径是否拼写错误。

快速验证 ：

# 直接访问 uWSGI（绕过 Nginx）
curl --unix-socket /run/uwsgi/myapp.sock http://localhost/
# 若返回正常，证明 Flask 和 uWSGI OK，问题在 Nginx 配置
# 若也 404，问题在 Flask 的路由或路径配置

5.3 504 Gateway Timeout：请求处理超时

当 Flask 视图执行时间超过 uwsgi_read_timeout ，Nginx 主动断开。排查思路：

1. 确认超时值 ： grep uwsgi_read_timeout /etc/nginx/sites-enabled/myapp
2. 检查 Flask 视图耗时 ：在视图中加日志：

   import time
   start = time.time()
   # 你的耗时操作
   app.logger.info(f"View took {time.time()-start:.2f}s")
   

3. 临时调高 timeout ：在 Nginx 配置中将 uwsgi_read_timeout 改为 1800 ，测试是否解决。
4. 优化代码 ：若确认是数据库慢查询，加索引；若是外部 API，加超时和重试。

经验 ：我处理过一个导出 Excel 的接口，原始代码用 pandas.DataFrame.to_excel 生成大文件，耗时 120 秒。改为流式生成（ xlsxwriter 的 add_worksheet + write_row ），耗时降至 8 秒， uwsgi_read_timeout 保持 300 即可。

5.4 日志混乱：如何精准定位问题

uWSGI 和 Nginx 日志分散，需关联分析。我的标准排查流程：

1. 从 Nginx access.log 找请求 ID ：
   192.168.1.100 - - [10/Jun/2024:10:30:22 +0000] "GET /api/data HTTP/1.1" 502 166 "-" "curl/7.68.0"
   记下时间 10:30:22 和状态码 502 。

2. 查 Nginx error.log 同一时间点 ：
   2024/06/10 10:30:22 [error] 1234#1234: *5 connect() to unix:/run/uwsgi/myapp.sock failed (13: Permission denied) ...
   确认是权限问题。

3. 查 uWSGI journal 同一时间点 ：
   sudo journalctl -u uwsgi --since "2024-06-10 10:30:00" --until "2024-06-10 10:31:00"
   若无输出，证明 uWSGI 根本没收到请求，问题在 Nginx 到 socket 的链路。

终极技巧 ：在 uWSGI 配置中加 stats = 127.0.0.1:9191 ，然后 curl http://127.0.0.1:9191 获取实时 worker 状态，查看哪些 worker 在 busy，哪个在 idle，直观判断是负载不均还是单点故障。

5.5 权限地狱：Ubuntu 18.04 的经典权限组合

Ubuntu 18.04 的权限模型是 www-data 用户的核心。以下是必须遵守的权限矩阵：

| 文件/目录 | 所有者 | 所属组 | 权限 | 说明 |