1. 为什么第13版还在折腾树莓派智能家居如果你翻过我之前发的那几版记录会发现一个规律前几版都在堆功能从第10版开始我反而在砍功能。第13版的核心思路就一句话——把能跑变成跑不坏。这套系统现在管着我家三层楼的灯光、窗帘、空调、新风和两个温湿度采集点7×24小时连续跑了四个多月中间只因为一次路由器固件升级重启过一次。这篇文章不讲怎么点亮第一颗LED那种内容网上太多了我讲的是当你把树莓派当成家里基础设施之后真正会遇到的工程问题。先说清楚这套系统适合谁看。如果你手上有一块树莓派4B或者树莓派5已经装好了系统想让家里的设备联动起来并且希望这套东西半年后还能稳定工作那这篇就是写给你的。如果你还在纠结买树莓派还是买成品网关我建议先看完第2节再决定。整套方案的技术栈是HomeAssistant 做设备接入与自动化中枢NodeRED 做复杂逻辑编排nginx 做反向代理和统一入口这三个东西各司其职不要混着用这是第13版最大的架构调整。为什么是第13版因为前12版我踩过的坑基本都集中在三个地方设备掉线后自动化静默失效、外网访问配置混乱、以及树莓派本身因为SD卡或电源问题假死。这一版针对性地做了三件事所有关键自动化加了心跳检测、用nginx把内网所有服务收敛到一个入口、把系统盘从SD卡换成了SSD。下面逐层拆开讲。2. 硬件选型与系统底座的取舍逻辑2.1 树莓派4B还是5以及为什么我最后选了4B热词里树莓派5 pcie开发板 m.2 hat 原型和树莓派5上部署自己训练的yolov5模型出现频率很高说明不少人在往树莓派5上迁移。我实测过树莓派5跑HomeAssistant性能确实好但有两个现实问题一是功耗和发热明显高于4B我家弱电箱空间小夏天箱内温度能到45度4B加个散热片就够5代必须上主动散热二是树莓派5的PCIe接口虽然能接M.2 SSD但配套的HAT和SSD选型还在磨合期我遇到过某品牌HAT在特定内核版本下识别不稳定的情况。所以第13版我仍然用树莓派4B 8GB版本做主力系统盘用USB3.0接口的SSD。这里有个关键细节树莓派4B的USB3.0接口和2.4GHz WiFi有干扰如果你用USB3.0 SSD建议把WiFi关掉走有线网否则2.4G设备很多智能家居传感器就是2.4G会频繁掉线。我就是因为这个原因把家里Zigbee网关挪到了USB延长线上离树莓派本体远了30厘米掉线率直接降下来了。对比项树莓派4B 8GB树莓派5 8GB日常功耗约3-5W约5-8W满载温度无主动散热65-70度80度以上SSD方案成熟度USB3.0成熟PCIe HAT仍在迭代HomeAssistant流畅度足够更流畅我的选择主力观望2.2 系统盘从SD卡换成SSD这是稳定性的分水岭前12版里我至少换过5张SD卡症状都是跑一两个月后系统变卡、日志写入失败、最后直接起不来。SD卡的擦写寿命和随机写入性能根本扛不住HomeAssistant这种持续写数据库的负载。第13版换成SSD之后最直观的变化是数据库写入不再卡顿历史曲线加载快了一个数量级。换盘的操作路径是先用树莓派官方的烧录工具把系统写到SSD然后修改启动顺序让树莓派优先从USB启动。具体做法是在SD卡系统里执行一次sudo raspi-config进Advanced Options里的Boot Order选USB Boot。确认能从SSD启动后把SD卡拔掉。这里有个坑第一次从USB启动时不要插着SD卡否则它可能还是从SD卡引导。另外SSD建议选带独立供电的硬盘盒或者用带供电的USB Hub树莓派4B的USB口供电能力有限SSD瞬时电流不够会导致系统随机重启。2.3 系统版本与换源的实际操作热词里树莓派修改源树莓派trixie换源树莓派4b安装ubuntu20.04都指向同一个问题国内网络环境下装包慢。我第13版用的是树莓派官方的64位系统基于Debian换源这一步必须做否则装HomeAssistant依赖能等到你怀疑人生。换源的核心是改两个文件/etc/apt/sources.list和/etc/apt/sources.list.d/raspi.list。把里面的域名替换成国内镜像站即可。改完之后执行sudo apt update sudo apt upgrade -y注意换源后如果apt update报GPG错误说明镜像站的密钥没同步换一个镜像站重试即可不要强行忽略签名。我不推荐在树莓派上装Ubuntu Server来跑HomeAssistant虽然热词里树莓派4b安装ubuntu20.04很热但官方系统对树莓派硬件的支持更完整尤其是GPIO和摄像头模块。除非你有特殊需求否则官方64位系统是最省心的选择。3. HomeAssistant作为中枢的接入与避坑3.1 安装方式的选择Supervised还是ContainerHomeAssistant有三种装法OS、Supervised、Container。第13版我用的是Supervised原因是它既能用Add-on商店装NodeRED、Mosquitto这些一键搞定又能让我在底层系统上做自己的事比如跑nginx、跑自定义脚本。Container方式最轻量但Add-on用不了所有东西都得自己用Docker编排维护成本高。OS方式最省心但系统被锁死你没法在宿主机上装nginx。Supervised的安装有个硬性要求系统必须是64位且Docker版本要符合要求。我踩过的坑是先用脚本装了旧版Docker结果Supervised安装脚本检测不通过。正确顺序是先按官方文档装好符合版本要求的Docker和OS-Agent再跑Supervised安装脚本。装完之后用ha supervisor info确认状态是healthy。3.2 设备接入Zigbee、WiFi和蓝牙的分工我家设备分三类接入Zigbee设备门窗传感器、人体传感器、部分灯具通过USB棒接入用ZHA集成。Zigbee的好处是低功耗、自组网但信道冲突是大坑。2.4G WiFi和Zigbee都挤在2.4G频段我把Zigbee信道固定在25WiFi的2.4G固定在1或11避开重叠。WiFi设备空调伴侣、部分插座直接走局域网。这类设备的问题是IP地址会变所以我在路由器里给每个设备做了DHCP静态绑定否则HomeAssistant里配置的IP一失效实体就变unavailable。蓝牙设备温湿度计用树莓派板载蓝牙接入。蓝牙的坑是距离和干扰隔一堵墙信号就弱我最后在二楼加了一个ESP32做蓝牙代理通过ESPHome接入。提示Zigbee USB棒一定要用USB延长线直接插在树莓派USB口上会被USB3.0的电磁干扰影响这是很多人Zigbee网络不稳定的根本原因。3.3 数据库选型默认SQLite够不够用HomeAssistant默认用SQLite存历史数据。我前几版一直用默认的到第12版时发现历史页面加载要好几秒因为数据库已经几百MB了。第13版我换成了MariaDB通过Add-on安装配置里把recorder指向MariaDB。换完之后历史查询明显变快而且可以设置数据保留策略比如只保留30天避免数据库无限膨胀。配置的关键是在configuration.yaml里加recorder: db_url: mysql://用户名:密码core-mariadb:3306/数据库名 purge_keep_days: 30purge_keep_days这个参数很重要不设的话数据库会一直涨。我设的30天既能看到月度趋势又不会占太多空间。4. NodeRED承担复杂自动化的边界4.1 什么逻辑该放NodeRED什么该留在HomeAssistant这是第13版想清楚的一个问题。HomeAssistant自带的自动化适合简单的如果...就...比如人体传感器触发就开灯。但一旦涉及多条件、延时、状态判断、循环用HA的YAML写会非常痛苦。NodeRED的图形化流程在这种场景下优势明显。我的划分原则是设备状态变化直接触发的、单条件的自动化留在HA涉及多个设备协同、需要计时器或状态机的放NodeRED。举个例子晚上回家开门自动开玄关灯这种放HA根据室内外温差和湿度决定新风和空调怎么配合运行这种放NodeRED。4.2 一个真实的能耗联动流程拆解热词里nodered 能耗是个有意思的点。我做了个简单的能耗联动通过智能插座采集几个大功率电器的功率在NodeRED里做累加和判断。流程大致是智能插座通过MQTT上报功率到Mosquitto。NodeRED订阅MQTT主题用function节点做单位换算和累加。当某个电器连续运行超过设定时长且总功率超过阈值触发提醒或自动关闭。这个流程里最关键的是function节点的容错。MQTT消息可能丢功率值可能是null如果不做判断直接算流程会报错甚至卡死。我在function节点开头统一做了类型检查if (msg.payload null || isNaN(msg.payload)) { return null; }返回null表示不往下传这样脏数据就被过滤掉了。4.3 NodeRED和HomeAssistant的通信方式NodeRED通过Add-on安装后用node-red-contrib-home-assistant-websocket这个节点包和HA通信。配置时需要生成一个长期访问令牌Long-Lived Access Token在HA的个人资料页里创建。这个令牌不要硬编码在流程里而是配在节点的Server配置里这样换令牌时只改一处。我踩过的坑是NodeRED重启后有时连不上HA日志显示websocket断开。原因是HA重启时NodeRED没跟着重启重连逻辑没生效。解决办法是在NodeRED的Server配置里把重连间隔设短一点并且给关键流程加个启动时触发的注入节点确保重启后状态能同步。5. nginx统一入口的配置实战5.1 为什么要在内网也上nginx很多人觉得nginx是给外网访问用的内网直接记IP加端口就行。但当你家里有HomeAssistant8123、NodeRED1880、Mosquitto1883、还有几个自建的小服务时记端口就是灾难。第13版我用nginx做内网统一入口所有服务通过子路径或子域名访问比如ha.家里.local、nodered.家里.local。nginx的另一个作用是给这些服务加上HTTPS。HomeAssistant和NodeRED默认都是HTTP内网传输虽然风险低但浏览器对HTTP页面限制越来越多比如某些API需要安全上下文。用nginx做TLS终止后端服务还是HTTP但对外统一是HTTPS。5.2 反向代理HomeAssistant的关键配置HomeAssistant对反向代理有要求配置不对会出现400 Bad Request或者登录后跳转异常。核心是传递正确的Host头和X-Forwarded-For。我的nginx配置片段location / { proxy_pass http://127.0.0.1:8123; 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_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection upgrade; }最后两行是WebSocket支持HomeAssistant的前端大量用WebSocket不配这两行页面会一直转圈。同时HA的configuration.yaml里要加http: use_x_forwarded_for: true trusted_proxies: - 127.0.0.1trusted_proxies不配的话HA会拒绝来自代理的请求。5.3 自签名证书与内网HTTPS热词里nginx 配置自签名证书 ssl 交互式方法说明很多人卡在证书这步。内网用自签名证书完全够用浏览器会提示不安全但点继续访问就行。生成证书的命令openssl req -x509 -nodes -days 3650 -newkey rsa:2048 \ -keyout /etc/nginx/ssl/home.key \ -out /etc/nginx/ssl/home.crt \ -subj /CNhome.local然后在nginx里配置443端口监听指向这两个文件。-days 3650是十年有效期省得年年换。如果你有域名可以用Lets Encrypt签正式证书但内网设备用自签名更简单不依赖外网。5.4 多服务共存的路径规划nginx部署多个web项目时路径规划要提前想好。我的方案是用不同端口区分而不是用子路径。原因是很多Web应用包括HA和NodeRED对子路径支持不好前端资源路径会错乱。所以nginx监听443然后按server_name区分服务内网域名后端地址HomeAssistantha.home.local127.0.0.1:8123NodeREDnr.home.local127.0.0.1:1880文件服务file.home.local127.0.0.1:8080这样每个服务都以为自己在根路径不会有资源加载问题。域名解析靠路由器里的本地DNS或者每台设备的hosts文件。6. 稳定性工程让系统跑四个月不重启6.1 心跳检测与自动化失效的兜底这是第13版最重要的改进。前几版遇到过Zigbee传感器掉线后自动化静默失效人走了灯还亮着。解决办法是给关键设备加心跳检测在NodeRED里定时检查设备最后上报时间超过阈值就发通知并且把相关自动化切到安全状态比如灯默认关闭。具体做法是用HA的last_changed属性或者更可靠的是在NodeRED里维护一个时间戳。我用的方案是每个关键传感器触发时更新一个全局变量NodeRED每分钟检查一次超过10分钟没更新就告警。这个逻辑不复杂但能救命。6.2 电源与散热的实际处理树莓派假死十有八九是电源问题。我用的是5V 3A的官方电源之前图便宜用过某品牌5V 2.5A满载时电压跌到4.7V以下系统直接重启。SSD加上USB棒加上树莓派本体峰值电流不小电源余量必须留够。散热方面弱电箱里我加了个小风扇用树莓派的GPIO控制温度超过55度自动开。温度读取用vcgencmd measure_temp在NodeRED里定时执行。这个风扇噪音不大但能让箱内温度降10度左右。6.3 日志与监控出问题时怎么查系统跑久了出问题是必然的。关键是出问题时能快速定位。我做了三层监控系统层用htop看CPU和内存用df -h看磁盘。磁盘满了是常见故障HomeAssistant日志和数据库会吃空间。服务层HomeAssistant的Supervisor页面能看到各Add-on状态NodeRED有日志面板。业务层关键自动化执行后在NodeRED里写一条日志到文件出问题时能回溯当时到底触发了没有。提示给树莓派配一个UPS或者至少一个能撑10分钟的移动电源能避免大部分因为瞬时断电导致的系统损坏。SSD虽然比SD卡抗造但突然断电还是可能损坏文件系统。7. 几个容易被忽略的细节7.1 时间同步与定时任务树莓派没有RTC实时时钟断电后时间会乱。HomeAssistant和NodeRED的定时自动化都依赖准确时间。第13版我确保NTP同步正常并且在NodeRED的定时流程里加了时间校验如果系统时间和NTP服务器差太多先同步再执行。7.2 备份策略Supervised自带备份功能可以备份到本地或网络存储。我的策略是每周自动备份一次保留最近4份备份文件放到NAS上。备份不只是防系统崩溃更重要的是改配置改坏了能回滚。我有次改nginx配置把HA搞挂了就是靠备份快速恢复的。7.3 关于免费nginx网站和nginx下载教程的提醒热词里这两个词说明很多人在找nginx的入门资料。我的建议是nginx官方文档就是最好的教程不要去看那些二手转载的。安装直接用系统包管理器sudo apt install nginx不要自己去编译源码除非你有特殊模块需求。编译安装的nginx升级麻烦而且容易和系统包冲突。7.4 树莓派引脚和扩展的注意事项热词里树莓派4b引脚功能图树莓派pico控制舵机说明有人在玩硬件扩展。如果你要在树莓派上接传感器注意3.3V和5V的区别树莓派GPIO是3.3V逻辑直接接5V传感器会烧。用电平转换模块或者选3.3V兼容的传感器。我早期烧过一个超声波模块就是因为没注意电压。8. 写在最后的一点个人体会这套系统从第1版折腾到第13版最大的感悟是智能家居的难点不在智能在家居。让灯能语音控制很简单让灯在你想开的时候永远能开才是真功夫。第13版砍掉了很多花哨功能把精力放在稳定性上结果反而更好用了。如果你正准备做类似的项目我的建议是先把HomeAssistant跑稳再考虑NodeRED最后才上nginx。不要一上来就追求大而全先把一个房间的设备接进来跑一周看看稳定性再逐步扩展。遇到问题先看日志日志里基本都有答案。这套东西没有标准答案适合你家的就是最好的。
树莓派智能家居第13版：HomeAssistant+NodeRED+nginx稳定性实战
1. 为什么第13版还在折腾树莓派智能家居如果你翻过我之前发的那几版记录会发现一个规律前几版都在堆功能从第10版开始我反而在砍功能。第13版的核心思路就一句话——把能跑变成跑不坏。这套系统现在管着我家三层楼的灯光、窗帘、空调、新风和两个温湿度采集点7×24小时连续跑了四个多月中间只因为一次路由器固件升级重启过一次。这篇文章不讲怎么点亮第一颗LED那种内容网上太多了我讲的是当你把树莓派当成家里基础设施之后真正会遇到的工程问题。先说清楚这套系统适合谁看。如果你手上有一块树莓派4B或者树莓派5已经装好了系统想让家里的设备联动起来并且希望这套东西半年后还能稳定工作那这篇就是写给你的。如果你还在纠结买树莓派还是买成品网关我建议先看完第2节再决定。整套方案的技术栈是HomeAssistant 做设备接入与自动化中枢NodeRED 做复杂逻辑编排nginx 做反向代理和统一入口这三个东西各司其职不要混着用这是第13版最大的架构调整。为什么是第13版因为前12版我踩过的坑基本都集中在三个地方设备掉线后自动化静默失效、外网访问配置混乱、以及树莓派本身因为SD卡或电源问题假死。这一版针对性地做了三件事所有关键自动化加了心跳检测、用nginx把内网所有服务收敛到一个入口、把系统盘从SD卡换成了SSD。下面逐层拆开讲。2. 硬件选型与系统底座的取舍逻辑2.1 树莓派4B还是5以及为什么我最后选了4B热词里树莓派5 pcie开发板 m.2 hat 原型和树莓派5上部署自己训练的yolov5模型出现频率很高说明不少人在往树莓派5上迁移。我实测过树莓派5跑HomeAssistant性能确实好但有两个现实问题一是功耗和发热明显高于4B我家弱电箱空间小夏天箱内温度能到45度4B加个散热片就够5代必须上主动散热二是树莓派5的PCIe接口虽然能接M.2 SSD但配套的HAT和SSD选型还在磨合期我遇到过某品牌HAT在特定内核版本下识别不稳定的情况。所以第13版我仍然用树莓派4B 8GB版本做主力系统盘用USB3.0接口的SSD。这里有个关键细节树莓派4B的USB3.0接口和2.4GHz WiFi有干扰如果你用USB3.0 SSD建议把WiFi关掉走有线网否则2.4G设备很多智能家居传感器就是2.4G会频繁掉线。我就是因为这个原因把家里Zigbee网关挪到了USB延长线上离树莓派本体远了30厘米掉线率直接降下来了。对比项树莓派4B 8GB树莓派5 8GB日常功耗约3-5W约5-8W满载温度无主动散热65-70度80度以上SSD方案成熟度USB3.0成熟PCIe HAT仍在迭代HomeAssistant流畅度足够更流畅我的选择主力观望2.2 系统盘从SD卡换成SSD这是稳定性的分水岭前12版里我至少换过5张SD卡症状都是跑一两个月后系统变卡、日志写入失败、最后直接起不来。SD卡的擦写寿命和随机写入性能根本扛不住HomeAssistant这种持续写数据库的负载。第13版换成SSD之后最直观的变化是数据库写入不再卡顿历史曲线加载快了一个数量级。换盘的操作路径是先用树莓派官方的烧录工具把系统写到SSD然后修改启动顺序让树莓派优先从USB启动。具体做法是在SD卡系统里执行一次sudo raspi-config进Advanced Options里的Boot Order选USB Boot。确认能从SSD启动后把SD卡拔掉。这里有个坑第一次从USB启动时不要插着SD卡否则它可能还是从SD卡引导。另外SSD建议选带独立供电的硬盘盒或者用带供电的USB Hub树莓派4B的USB口供电能力有限SSD瞬时电流不够会导致系统随机重启。2.3 系统版本与换源的实际操作热词里树莓派修改源树莓派trixie换源树莓派4b安装ubuntu20.04都指向同一个问题国内网络环境下装包慢。我第13版用的是树莓派官方的64位系统基于Debian换源这一步必须做否则装HomeAssistant依赖能等到你怀疑人生。换源的核心是改两个文件/etc/apt/sources.list和/etc/apt/sources.list.d/raspi.list。把里面的域名替换成国内镜像站即可。改完之后执行sudo apt update sudo apt upgrade -y注意换源后如果apt update报GPG错误说明镜像站的密钥没同步换一个镜像站重试即可不要强行忽略签名。我不推荐在树莓派上装Ubuntu Server来跑HomeAssistant虽然热词里树莓派4b安装ubuntu20.04很热但官方系统对树莓派硬件的支持更完整尤其是GPIO和摄像头模块。除非你有特殊需求否则官方64位系统是最省心的选择。3. HomeAssistant作为中枢的接入与避坑3.1 安装方式的选择Supervised还是ContainerHomeAssistant有三种装法OS、Supervised、Container。第13版我用的是Supervised原因是它既能用Add-on商店装NodeRED、Mosquitto这些一键搞定又能让我在底层系统上做自己的事比如跑nginx、跑自定义脚本。Container方式最轻量但Add-on用不了所有东西都得自己用Docker编排维护成本高。OS方式最省心但系统被锁死你没法在宿主机上装nginx。Supervised的安装有个硬性要求系统必须是64位且Docker版本要符合要求。我踩过的坑是先用脚本装了旧版Docker结果Supervised安装脚本检测不通过。正确顺序是先按官方文档装好符合版本要求的Docker和OS-Agent再跑Supervised安装脚本。装完之后用ha supervisor info确认状态是healthy。3.2 设备接入Zigbee、WiFi和蓝牙的分工我家设备分三类接入Zigbee设备门窗传感器、人体传感器、部分灯具通过USB棒接入用ZHA集成。Zigbee的好处是低功耗、自组网但信道冲突是大坑。2.4G WiFi和Zigbee都挤在2.4G频段我把Zigbee信道固定在25WiFi的2.4G固定在1或11避开重叠。WiFi设备空调伴侣、部分插座直接走局域网。这类设备的问题是IP地址会变所以我在路由器里给每个设备做了DHCP静态绑定否则HomeAssistant里配置的IP一失效实体就变unavailable。蓝牙设备温湿度计用树莓派板载蓝牙接入。蓝牙的坑是距离和干扰隔一堵墙信号就弱我最后在二楼加了一个ESP32做蓝牙代理通过ESPHome接入。提示Zigbee USB棒一定要用USB延长线直接插在树莓派USB口上会被USB3.0的电磁干扰影响这是很多人Zigbee网络不稳定的根本原因。3.3 数据库选型默认SQLite够不够用HomeAssistant默认用SQLite存历史数据。我前几版一直用默认的到第12版时发现历史页面加载要好几秒因为数据库已经几百MB了。第13版我换成了MariaDB通过Add-on安装配置里把recorder指向MariaDB。换完之后历史查询明显变快而且可以设置数据保留策略比如只保留30天避免数据库无限膨胀。配置的关键是在configuration.yaml里加recorder: db_url: mysql://用户名:密码core-mariadb:3306/数据库名 purge_keep_days: 30purge_keep_days这个参数很重要不设的话数据库会一直涨。我设的30天既能看到月度趋势又不会占太多空间。4. NodeRED承担复杂自动化的边界4.1 什么逻辑该放NodeRED什么该留在HomeAssistant这是第13版想清楚的一个问题。HomeAssistant自带的自动化适合简单的如果...就...比如人体传感器触发就开灯。但一旦涉及多条件、延时、状态判断、循环用HA的YAML写会非常痛苦。NodeRED的图形化流程在这种场景下优势明显。我的划分原则是设备状态变化直接触发的、单条件的自动化留在HA涉及多个设备协同、需要计时器或状态机的放NodeRED。举个例子晚上回家开门自动开玄关灯这种放HA根据室内外温差和湿度决定新风和空调怎么配合运行这种放NodeRED。4.2 一个真实的能耗联动流程拆解热词里nodered 能耗是个有意思的点。我做了个简单的能耗联动通过智能插座采集几个大功率电器的功率在NodeRED里做累加和判断。流程大致是智能插座通过MQTT上报功率到Mosquitto。NodeRED订阅MQTT主题用function节点做单位换算和累加。当某个电器连续运行超过设定时长且总功率超过阈值触发提醒或自动关闭。这个流程里最关键的是function节点的容错。MQTT消息可能丢功率值可能是null如果不做判断直接算流程会报错甚至卡死。我在function节点开头统一做了类型检查if (msg.payload null || isNaN(msg.payload)) { return null; }返回null表示不往下传这样脏数据就被过滤掉了。4.3 NodeRED和HomeAssistant的通信方式NodeRED通过Add-on安装后用node-red-contrib-home-assistant-websocket这个节点包和HA通信。配置时需要生成一个长期访问令牌Long-Lived Access Token在HA的个人资料页里创建。这个令牌不要硬编码在流程里而是配在节点的Server配置里这样换令牌时只改一处。我踩过的坑是NodeRED重启后有时连不上HA日志显示websocket断开。原因是HA重启时NodeRED没跟着重启重连逻辑没生效。解决办法是在NodeRED的Server配置里把重连间隔设短一点并且给关键流程加个启动时触发的注入节点确保重启后状态能同步。5. nginx统一入口的配置实战5.1 为什么要在内网也上nginx很多人觉得nginx是给外网访问用的内网直接记IP加端口就行。但当你家里有HomeAssistant8123、NodeRED1880、Mosquitto1883、还有几个自建的小服务时记端口就是灾难。第13版我用nginx做内网统一入口所有服务通过子路径或子域名访问比如ha.家里.local、nodered.家里.local。nginx的另一个作用是给这些服务加上HTTPS。HomeAssistant和NodeRED默认都是HTTP内网传输虽然风险低但浏览器对HTTP页面限制越来越多比如某些API需要安全上下文。用nginx做TLS终止后端服务还是HTTP但对外统一是HTTPS。5.2 反向代理HomeAssistant的关键配置HomeAssistant对反向代理有要求配置不对会出现400 Bad Request或者登录后跳转异常。核心是传递正确的Host头和X-Forwarded-For。我的nginx配置片段location / { proxy_pass http://127.0.0.1:8123; 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_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection upgrade; }最后两行是WebSocket支持HomeAssistant的前端大量用WebSocket不配这两行页面会一直转圈。同时HA的configuration.yaml里要加http: use_x_forwarded_for: true trusted_proxies: - 127.0.0.1trusted_proxies不配的话HA会拒绝来自代理的请求。5.3 自签名证书与内网HTTPS热词里nginx 配置自签名证书 ssl 交互式方法说明很多人卡在证书这步。内网用自签名证书完全够用浏览器会提示不安全但点继续访问就行。生成证书的命令openssl req -x509 -nodes -days 3650 -newkey rsa:2048 \ -keyout /etc/nginx/ssl/home.key \ -out /etc/nginx/ssl/home.crt \ -subj /CNhome.local然后在nginx里配置443端口监听指向这两个文件。-days 3650是十年有效期省得年年换。如果你有域名可以用Lets Encrypt签正式证书但内网设备用自签名更简单不依赖外网。5.4 多服务共存的路径规划nginx部署多个web项目时路径规划要提前想好。我的方案是用不同端口区分而不是用子路径。原因是很多Web应用包括HA和NodeRED对子路径支持不好前端资源路径会错乱。所以nginx监听443然后按server_name区分服务内网域名后端地址HomeAssistantha.home.local127.0.0.1:8123NodeREDnr.home.local127.0.0.1:1880文件服务file.home.local127.0.0.1:8080这样每个服务都以为自己在根路径不会有资源加载问题。域名解析靠路由器里的本地DNS或者每台设备的hosts文件。6. 稳定性工程让系统跑四个月不重启6.1 心跳检测与自动化失效的兜底这是第13版最重要的改进。前几版遇到过Zigbee传感器掉线后自动化静默失效人走了灯还亮着。解决办法是给关键设备加心跳检测在NodeRED里定时检查设备最后上报时间超过阈值就发通知并且把相关自动化切到安全状态比如灯默认关闭。具体做法是用HA的last_changed属性或者更可靠的是在NodeRED里维护一个时间戳。我用的方案是每个关键传感器触发时更新一个全局变量NodeRED每分钟检查一次超过10分钟没更新就告警。这个逻辑不复杂但能救命。6.2 电源与散热的实际处理树莓派假死十有八九是电源问题。我用的是5V 3A的官方电源之前图便宜用过某品牌5V 2.5A满载时电压跌到4.7V以下系统直接重启。SSD加上USB棒加上树莓派本体峰值电流不小电源余量必须留够。散热方面弱电箱里我加了个小风扇用树莓派的GPIO控制温度超过55度自动开。温度读取用vcgencmd measure_temp在NodeRED里定时执行。这个风扇噪音不大但能让箱内温度降10度左右。6.3 日志与监控出问题时怎么查系统跑久了出问题是必然的。关键是出问题时能快速定位。我做了三层监控系统层用htop看CPU和内存用df -h看磁盘。磁盘满了是常见故障HomeAssistant日志和数据库会吃空间。服务层HomeAssistant的Supervisor页面能看到各Add-on状态NodeRED有日志面板。业务层关键自动化执行后在NodeRED里写一条日志到文件出问题时能回溯当时到底触发了没有。提示给树莓派配一个UPS或者至少一个能撑10分钟的移动电源能避免大部分因为瞬时断电导致的系统损坏。SSD虽然比SD卡抗造但突然断电还是可能损坏文件系统。7. 几个容易被忽略的细节7.1 时间同步与定时任务树莓派没有RTC实时时钟断电后时间会乱。HomeAssistant和NodeRED的定时自动化都依赖准确时间。第13版我确保NTP同步正常并且在NodeRED的定时流程里加了时间校验如果系统时间和NTP服务器差太多先同步再执行。7.2 备份策略Supervised自带备份功能可以备份到本地或网络存储。我的策略是每周自动备份一次保留最近4份备份文件放到NAS上。备份不只是防系统崩溃更重要的是改配置改坏了能回滚。我有次改nginx配置把HA搞挂了就是靠备份快速恢复的。7.3 关于免费nginx网站和nginx下载教程的提醒热词里这两个词说明很多人在找nginx的入门资料。我的建议是nginx官方文档就是最好的教程不要去看那些二手转载的。安装直接用系统包管理器sudo apt install nginx不要自己去编译源码除非你有特殊模块需求。编译安装的nginx升级麻烦而且容易和系统包冲突。7.4 树莓派引脚和扩展的注意事项热词里树莓派4b引脚功能图树莓派pico控制舵机说明有人在玩硬件扩展。如果你要在树莓派上接传感器注意3.3V和5V的区别树莓派GPIO是3.3V逻辑直接接5V传感器会烧。用电平转换模块或者选3.3V兼容的传感器。我早期烧过一个超声波模块就是因为没注意电压。8. 写在最后的一点个人体会这套系统从第1版折腾到第13版最大的感悟是智能家居的难点不在智能在家居。让灯能语音控制很简单让灯在你想开的时候永远能开才是真功夫。第13版砍掉了很多花哨功能把精力放在稳定性上结果反而更好用了。如果你正准备做类似的项目我的建议是先把HomeAssistant跑稳再考虑NodeRED最后才上nginx。不要一上来就追求大而全先把一个房间的设备接进来跑一周看看稳定性再逐步扩展。遇到问题先看日志日志里基本都有答案。这套东西没有标准答案适合你家的就是最好的。
