树莓派系统装好了Python环境也配好了Flask写的应用能在本机跑通了——走到这一步说明第一个阶段已经完成。但我得泼一盆冷水现在的状态离“服务器”还差得很远。Flask自带的Werkzeug服务器是开发调试时用的单进程、单线程家里路由器一抖动、手机多刷两个页面它就卡住了进程崩溃了不会自动恢复日志更是想怎么打就怎么打。想让树莓派真正变成一个7x24小时稳定运行的家庭服务器就得用NginxuWSGIFlask这套组合把项目重新包装一遍。这篇是系列第二篇我直接把架构从项目结构、uWSGI配置、Nginx反代到开机自启和问题排查完整讲一遍实测基于树莓派4B4核2GB/4GB内存均适用系统为Ubuntu 22.04。如果你看过系列第一篇应该已经完成了基础系统配置、Python虚拟环境和Flask依赖安装。这篇不再重复那些步骤但每个配置项我都会讲清楚“为什么这么做”而不是只给一份能跑的配置就完事。1. 树莓派上为什么非要把简单Flask应用拆成三层架构很多人觉得“杀鸡焉用牛刀”树莓派上跑个小服务直接python app.py不就完了这句话在开发环境对了一半在生产环境基本全错。服务器和开发机最大的区别在于它要一直跑、要同时处理多个请求、要在极端情况下保持可用而树莓派资源又紧巴巴的架构设计必须既有性能又省资源。1.1 开发服务器和生产服务器的本质差别Flask自带的Werkzeug服务器默认是单进程、单线程它存在的意义是让开发者在本地调试时能快速看到改动效果。用一句话概括它能服务“一个浏览器里的一个请求”扛不住“多个设备的同时访问”更保证不了稳定性。uWSGI是WSGI服务器负责真正运行Python应用。它可以开多个worker进程、每个进程再开多个线程把树莓派的4个核心用起来还能做优雅重启、超时控制、请求排队这些“服务器该做的事”。Nginx则是入口层负责接收外部HTTP请求、托管静态文件、把动态请求转交给uWSGI。它像一个前台不关心后台Python代码怎么跑只负责把请求接到正确的房间。我用一张表把三个组件的职责分清楚组件职责类比Flask写业务逻辑处理路由和视图饭店的厨房uWSGI运行Python应用管理进程与线程后厨的厨师团队Nginx接收HTTP请求服务静态文件代理动态请求前台和传菜窗口很多新手直接跳过Nginx让uWSGI监听HTTP端口暴露出去。这确实能跑但意味着uWSGI既要处理应用逻辑又要处理静态文件、连接管理、安全防护——这些锅它背不动。Nginx在处理静态文件上比Python快一个数量级内存占用还低自然分工才是稳定运行的根基。1.2 这套组合在树莓派上能承担什么角色树莓派做服务器不像云服务器那样带宽大、配置高。它的优势是本地可控、GPIO可操作适合做家庭场景里的边缘节点。我用这套架构跑过的典型任务包括家庭内网的温度/湿度监控面板浏览器直接访问看数据曲线一个简单的MQTT消息中转页方便手机查看设备上线状态摄像头推流前的Web管理入口统一处理登录和设备配置一些自己写的JSON API服务比如给Home Assistant或其他硬件调用的接口。这些场景的共同点请求量不大但需要长期稳定、重启自动恢复、日志可查。NginxuWSGIFlask这套组合正好在“够用”和“专业”之间取了平衡。如果你只是临时跑个脚本那确实不需要这套架构但只要你打算让服务长期运行一步到位搭好它是值得的。2. 按“可部署”的标准重构Flask项目结构与WSGI入口我在系列第一篇搭的开发环境项目通常是随便一个目录、一个app.py、直接python app.py跑起来。生产部署前必须把项目结构调整成可部署的形态。部署和开发最大的区别是你不知道进程会在哪个目录下被拉起也不知道Python模块能不能被正确导入所以项目根目录和工作目录必须明确WSGI入口必须稳定。2.1 一个最小可部署的项目骨架以一个简单的“树莓派系统监控面板”为例项目放在/home/ubuntu/flask-app//home/ubuntu/flask-app/ ├── app.py ├── requirements.txt ├── uwsgi.ini └── static/ └── style.cssrequirements.txt内容就是当前虚拟环境里的核心依赖。别偷懒用pip freeze requirements.txt导出全部包那会带上一堆传递依赖重装时容易版本冲突。手动写需要的依赖反而更干净flask3.0.0 uwsgi2.0.24这里把uWSGI也写进requirements是合理的因为部署机就是树莓派本身不存在交叉安装问题。2.2 WSGI入口与Flask应用工厂的配合方式app.py不只是写代码它有一个重要任务对外暴露一个app对象。这个对象就是uWSGI配置文件里的module app:app所指向的“调用目标”。一个最简单的可部署入口长这样from flask import Flask, jsonify app Flask(__name__) app.route(/) def index(): return jsonify({message: flask app is running}) if __name__ __main__: app.run(host0.0.0.0, port5000)注意if __name__ __main__这块。开发时执行python app.py它用开发服务器启动部署时uWSGI会通过app:app直接加载应用对象根本不会走到app.run()所以这个入口写两用最方便。如果你的项目用了工厂模式create_app()uWSGI配置里就要写成module app:create_app(),callable app。对大多数小型树莓派项目单模块方式已经足够清晰不必刻意上工厂模式。2.3 本地先用开发服务器确认业务逻辑改完项目结构先在本地用开发服务器跑一遍确认业务逻辑没问题再上uWSGI。这一步能省掉后面一半的排错时间。我用的是cd /home/ubuntu/flask-app source venv/bin/activate flask --app app run --host0.0.0.0 --port5000浏览器访问http://树莓派IP:5000能看到JSON返回就说明Flask代码、路由、依赖都是正常的。如果这一步都出错先把业务代码调通别着急部署。记住部署只是在正常的应用外面套一层壳壳不能解决代码本身的Bug。3. uWSGI在ARM板子上的安装实测与配置参数逐项拆解uWSGI是这套架构里最“挑环境”的一环。树莓派是ARM架构跟x86服务器完全不同编译安装经常缺这个缺那个如果直接用系统包管理去装版本又老得掉渣。这节把我踩过的坑和最终可用的配置完整写出来。3.1 ARM架构下uWSGI安装的几个拦路虎在Ubuntu 22.04上直接apt install uwsgi确实能装但装出来的版本往往是配套系统Python的和你虚拟环境里的Python版本不一定一致容易导致“module找不到”的诡异问题。我推荐在虚拟环境里用pip安装cd /home/ubuntu/flask-app source venv/bin/activate pip install uwsgi如果你的Python版本是3.10默认源通常有ARM的wheel包能直接装上。如果遇到从源码编译的情况大概率会报缺少Python.h。这个文件的对应位置是Python开发头文件需要sudo apt update sudo apt install python3-dev gcc装完再重试pip install uwsgi。这里多说一句树莓派编译uWSGI耗时会比云服务器长大概两三分钟别以为卡死了。看到Installed字样才算成功。3.2 uwsgi.ini核心参数逐项说明安装好之后在项目目录创建uwsgi.ini。我给出的配置是实测稳定运行过几个月的每个参数后面跟上注释[uwsgi] master true chdir /home/ubuntu/flask-app module app:app socket /tmp/flask_app.sock chmod-socket 664 uid ubuntu gid www-data vacuum true die-on-term true processes 4 threads 2 buffer-size 32768 harakiri 60 max-requests 500 logto /var/log/flask_app_uwsgi.logsocket用的是Unix Socket而不是HTTP端口这是为了让Nginx通过内部通道接请求而不是暴露一个公网端口。uid和gid表示uWSGI以root启动后把worker进程降权为普通用户ubuntu组切换为www-data。这样Nginx以www-data运行才能访问socket文件。chmod-socket 664是socket文件的权限。如果不设默认权限是755Nginx用户组可能没有写权限必然502。vacuum true表示进程退出时自动删除socket文件避免下次启动时“文件已存在”的报错。die-on-term true配合systemd使用收到终止信号时uWSGI优雅退出而不是暴力直接杀进程。processes 4是因为树莓派4B有4个核心。如果你的树莓派是3B4核心也可以4B最稳。每个worker占用内存约30-50MB4个进程对2GB内存来说压力不大。max-requests 500是每个worker处理500个请求后自动重启防止内存泄漏累积。这个参数在长期运行里特别重要。3.3 跑起来之后的端口、Socket与日志核对配置写完第一次启动建议前台跑方便直接看输出cd /home/ubuntu/flask-app source venv/bin/activate uwsgi --ini uwsgi.ini如果一切正常终端会显示WSGI app 0 ... ready in X seconds之类的信息并且能看到4个worker进程。然后另外开一个终端检查socket文件是否存在ls -l /tmp/flask_app.sock正常输出应该包含srw-rw-r--的权限位属主是ubuntu属组是www-data。这一步直接决定Nginx能不能连通我曾在这里卡了半小时原因就是忘了加gid www-data。如果启动失败看日志不会骗人。常见错误有两类一是ModuleNotFoundError: No module named flask说明uWSGI用的是系统Python而不是虚拟环境的Python解决办法是用venv/bin/uwsgi启动或者在ini里加virtualenv /home/ubuntu/flask-app/venv参数二是bind(): No such file or directory通常是socket的父目录不存在检查/tmp是否可写。4. Nginx接入uWSGI反向代理、Unix Socket与静态资源分流Nginx在上层负责把外部请求接进来。这一节先讲清楚一个关键问题为什么不用端口而是用Unix Socket再给出一份可以直接改的配置。4.1 为什么用Unix Socket而不是TCP端口很多教程里uWSGI配置用的是http-socket或socket 127.0.0.1:8000Nginx再proxy_pass http://127.0.0.1:8000。这种方式能跑但多了一层TCP连接建立和断开的开销。树莓派性能有限每一点不必要的开销都值得省。Unix Socket走的是内核内部通信不经过网络协议栈延迟更低、吞吐更高还天然避免了“端口被外部扫描”的安全风险。同样的请求量下Unix Socket大约能让CPU占用降低几个百分点内存占用也更稳。所以生产环境我强烈推荐Unix Socket而不是TCP端口。唯一的注意点就是权限Nginx进程www-data用户必须能访问socket文件。上一节配置里的uid、gid、chmod-socket三件套就是为这一步准备的。4.2 一份可以直接改的Nginx站点配置安装Nginxsudo apt install nginx安装完默认会在/etc/nginx/sites-available/下生成default我们不碰它而是新建一个站点配置文件。sudo nano /etc/nginx/sites-available/flask_app内容如下server { listen 80; server_name _; location / { include uwsgi_params; uwsgi_pass unix:/tmp/flask_app.sock; } location /static { alias /home/ubuntu/flask-app/static; expires 7d; } }location /里的include uwsgi_params会加载Nginx自带的UWSGI协议参数这是一堆HTTP头部的映射配置直接引入即可。uwsgi_pass unix:/tmp/flask_app.sock是核心把动态请求转给uWSGI。location /static让静态文件直接由Nginx返回不经过Python这一条对性能提升非常明显。启用站点并测试sudo ln -s /etc/nginx/sites-available/flask_app /etc/nginx/sites-enabled/ sudo nginx -t sudo systemctl reload nginxnginx -t输出syntax is ok且test is successful才继续。如果输出host not found in upstream检查uwsgi_pass后面的socket路径和uWSGI实际产生的socket路径是否一致。4.3 静态文件、上传大小与HTTPS扩展如果你的Flask应用涉及文件上传比如摄像头截图保存或者用户传配置Nginx默认只允许1MB请求体需要调大server { listen 80; server_name _; client_max_body_size 20m; location / { include uwsgi_params; uwsgi_pass unix:/tmp/flask_app.sock; } }内网环境可能用不上HTTPS但如果想把服务暴露到公网或者手机浏览器总是警告“不安全”可以在Nginx上挂自签名证书。生成方式一句话sudo mkdir -p /etc/nginx/ssl cd /etc/nginx/ssl sudo openssl req -x509 -nodes -days 365 -newkey rsa:2048 \ -keyout server.key -out server.crt -subj /CNraspberrypi.local然后在server块里加listen 443 ssl; ssl_certificate /etc/nginx/ssl/server.crt; ssl_certificate_key /etc/nginx/ssl/server.key;自签名证书适合个人局域网使用浏览器会提示“不受信任”点继续访问即可。如果你有域名建议用正式证书或者内网DNS的通配证书这部分以后单独写。5. 开机自启、权限问题与实际故障排查记录架构搭完还要让它在断电重启后自己爬起来否则就不叫服务器了。这一节讲systemd托管uWSGI再给出我在树莓派上遇到过的几类典型故障和排查思路。5.1 systemd单元文件让uWSGI自动托管我不用crontab或rc.local来启动uWSGI而是用systemd因为它能实现“崩溃自动重启、开机自启、日志集中管理”。新建服务文件sudo nano /etc/systemd/system/flask_app.service[Unit] DescriptionFlask App uWSGI Service Afternetwork.target [Service] Typesimple WorkingDirectory/home/ubuntu/flask-app ExecStart/home/ubuntu/flask-app/venv/bin/uwsgi --ini /home/ubuntu/flask-app/uwsgi.ini Restartalways RestartSec10 StandardOutputsyslog StandardErrorsyslog SyslogIdentifierflask_app [Install] WantedBymulti-user.target重点解释几个地方ExecStart使用的是虚拟环境里的uwsgi绝对路径这样绕开了PATH和默认Python版本问题。Restartalways表示进程退出后10秒自动拉起配合uWSGI的die-on-term true既做到崩溃重启又保证正常停止时不冲突。这个单元没有写Userubuntu是因为uWSGI要以root权限启动才能切换到uid ubuntu和gid www-data。如果你不想让root启动就得把socket权限改成让ubuntu用户能创建但Nginx能读比如通过ACL新手阶段不建议折腾。保存后执行sudo systemctl daemon-reload sudo systemctl enable flask_app sudo systemctl start flask_app sudo systemctl status flask_app看到active (running)就代表托管成功。以后要重启服务就sudo systemctl restart flask_app比以前手动杀进程再启动省心太多。5.2 最常见的几种故障现象与排查链路故障一浏览器访问直接502 Bad Gateway。我遇到90%的502都跟socket有关。排查链路固定为先看ls -l /tmp/flask_app.sock如果socket不存在看uWSGI日志如果socket存在用curl --unix-socket /tmp/flask_app.sock http://localhost/测试看uWSGI是否直接返回结果。如果直接返回正常问题就在Nginx侧检查uwsgi_pass路径和Nginx运行用户是否有socket访问权限。故障二页面能打开但静态文件404。这是Nginxlocation /static的路径问题。alias的路径末尾要带/然后本地sudo ls -l /home/ubuntu/flask-app/static确认文件确实存在。还有个细节alias会把请求路径直接映射到指定目录而root会把路径拼在后面。这里用了alias所以请求/static/style.css对应的是/home/ubuntu/flask-app/static/style.css。故障三uWSGI日志疯狂刷Permission denied。大概率是socket目录权限问题。最常见的场景是/run/flask_app/这类自定义目录不存在或者属主不是uWSGI运行用户。要么换回简单的/tmp要么提前mkdir -p并chown ubuntu:www-data。我建议新手直接沿用/tmp没那么多权限事。故障四内存不够导致服务偶发崩掉。树莓派2GB内存跑4个worker Nginx 系统大概还剩800MB如果还在跑Python爬虫或编译任务内存就很紧张。在htop里看到内存占用80%以上就把processes降到2先保证稳定。树莓派不是云服务器稳定比性能重要。5.3 树莓派资源受限时的调参建议很多人在树莓派上盲目照搬PC服务器的优化参数结果适得其反。我实测下来4B4核/2GB的几个关键建议是参数建议值说明uWSGI processes2-44核可开4内存紧就2uWSGI threads2每个worker开2个线程够用max-requests300-500防内存泄漏累积harakiri60单个请求超过60秒杀掉防卡死Nginx worker_processes2默认4也可以但2更省内存keepalive_timeout10缩短连接保持时间另外uWSGI日志如果不管会越来越大撑爆SD卡。可以加一个log-maxsize 5000000约5MB参数让日志自动轮转logto /var/log/flask_app_uwsgi.log log-maxsize 5000000这样单文件超过5MB会按序号切分不会无限膨胀。我在实际运行中最满意的反而是这套架构在树莓派上的“存在感”——很轻几乎感觉不到它在跑。只要你把项目结构、socket权限、systemd这三个关键点照顾到后面就真的只剩“代码写得怎么样”这一个变量了。每次想加新功能在这个骨架上继续垒就行不需要推翻重来。如果你后面准备在这个架构上再接MQTT、摄像头推流或者更多GPIO应用Nginx入口统一管着扩展起来非常顺手。