在 NAS 上跑 Home Assistant：部署方式怎么选，有哪些坑
先搞清楚四种安装方式的区别
Home Assistant 官方提供四种安装形态，选错了后面会反复踩坑：
| 方式 | 说明 | 支持 Add-on（插件） | 适合 |
|---|---|---|---|
| HA OS | 完整操作系统，通常装在独立主机/虚拟机 | ✅ | 官方推荐，功能最全 |
| Container | 纯 Docker 容器 | ❌ | NAS 上最常见 |
| Core | Python 环境直接跑 | ❌ | 开发调试 |
| Supervised | 在通用 Linux 上加管理层 | ✅ | 已不推荐新装 |
在 NAS 上，绝大多数情况是 Container 方式。 因为 NAS 本身有操作系统，你不会为了 HA 单独装一套 HA OS，最多是在 NAS 的虚拟机里跑 HA OS。
这里有个必须提前知道的限制：Container 版不支持 Add-on（插件商店）。
Add-on 是 HA OS 生态里那些一键安装的应用（比如 Zigbee2MQTT、ESPHome、Mosquitto 代理、文件编辑器）。用 Docker 版的话，这些都需要你自己用 Docker 单独部署，然后通过集成连接。这不是不能解决，但要多花功夫。
Docker 部署要点
用官方镜像 ghcr.io/home-assistant/home-assistant，容器配置有几个关键点：
端口：Web 界面默认 8123。
配置目录：必须把配置目录挂载到宿主机，否则容器重建后所有配置丢失。通常是 config 目录。
时区：容器默认 UTC，不设置的话自动化里的时间判断会差 8 小时。通过环境变量 TZ=Asia/Shanghai 设置。
host 网络模式：这是 HA 的一个特殊之处。HA 需要发现局域网内的设备（mDNS、SSDP、DHCP 监听），用 bridge 模式会导致大量设备发现失败。建议用 network_mode: host，代价是端口直接占用宿主机，不能再跑其他占用 8123 的服务。
一个典型的 docker-compose.yml 结构：
services:
homeassistant:
image: ghcr.io/home-assistant/home-assistant:stable
container_name: homeassistant
network_mode: host
volumes:
- ./config:/config
- /etc/localtime:/etc/localtime:ro
environment:
- TZ=Asia/Shanghai
restart: unless-stoppedUSB 设备直通：Zigbee / Z-Wave 的必答题
如果你要用 Zigbee 或 Z-Wave 设备（绝大多数智能家居传感器走这两个协议），就需要一个 USB 协调器（比如常见的 Sonoff ZBDongle、ConBee 等），而 Docker 容器默认看不到宿主机的 USB 设备。
挂载方式：
devices:
- /dev/ttyUSB0:/dev/ttyUSB0几个实操要点：
设备路径会变。 /dev/ttyUSB0 在重启后可能变成 ttyUSB1，尤其是插了多个 USB 串口设备时。更稳的做法是用 by-id 路径：
devices:
- /dev/serial/by-id/usb-ITEAD_SONOFF_Zigbee_3.0_USB_Dongle_Plus_xxx-if00-port0:/dev/ttyUSB0先用 ls /dev/serial/by-id/ 查到实际路径，再写进配置。
权限问题。 容器需要有访问该设备的权限。部分 NAS 系统需要在宿主机上调整设备权限，或者给容器加 privileged（不推荐，除非必要）。
USB 延长线很有必要。 Zigbee 协调器直接插在 NAS 背面，会被金属机箱屏蔽，信号质量明显下降。用一根 USB 延长线把它拉开几十厘米，效果立竿见影。这不是玄学，2.4GHz 频段（Zigbee 和 Wi-Fi 共用）很容易受干扰。
与 Wi-Fi 信道错开。 Zigbee 常用信道 15/20/25，与 Wi-Fi 的 2.4G 信道有重叠区域。如果 Zigbee 设备经常掉线，检查一下 Wi-Fi 用的是哪个信道。
与 NAS 本身做集成
HA 跑在 NAS 上，顺带可以把 NAS 也纳入监控：
- SMB/传感器集成：读取 NAS 的磁盘使用率、共享文件夹容量
- SNMP：大部分成品 NAS 支持 SNMP，可以采集 CPU、内存、温度、网络流量
- Ping / 设备追踪：监控 NAS 是否在线
反过来，HA 的数据也值得备份到 NAS 上。HA 的备份功能可以生成快照文件，建议定期把快照复制到 NAS 的独立目录——因为 HA 容器就在 NAS 上，只存在容器内的备份等于没有备份。
资源占用与性能预期
HA 本身很轻。一个只跑几十个设备的 HA 实例，内存占用通常在 300–800MB，CPU 占用很低。即便是 J4125 这类入门处理器也完全够用。
真正的资源消耗来自附加组件：
- 数据库：HA 默认用 SQLite，历史记录多了之后数据库会膨胀到几个 GB，且会持续写盘。建议配置
recorder只记录需要的实体，并设置合理的保留天数 - MariaDB：设备多、历史长时建议换 MariaDB，性能更好
- 附加容器：MQTT 代理、Zigbee2MQTT、ESPHome 等，每个都要占一点
关于数据库写盘：这是 HA 跑在 NAS 上时最常见的”副作用”——它会持续写 SQLite，导致硬盘无法休眠。如果你在意休眠，可以在 HA 里把 recorder 的提交间隔调大，或者干脆接受这个事实。
常见的坑
一、host 网络模式下的端口冲突。 用了 host 模式后，HA 直接占用宿主机的 8123。如果 NAS 上已经有服务占用这个端口，要么改 HA 的端口（server: port: 8124），要么改其他服务。
二、升级要谨慎。 HA 每月发布大版本，偶尔会有破坏性变更。升级前务必：
- 先做完整备份
- 看一下 Release Notes 里的 “Breaking Changes” 部分
- 不要在急需使用智能家居的时间点升级
三、时间不同步。 如果容器时区没设对，所有基于时间的自动化都会错乱。这是新手最常见的问题之一。
四、host 模式与部分 NAS 系统的网络栈冲突。少数成品 NAS 的 Docker 实现对 host 模式支持不佳，此时只能退回 bridge 模式，代价是设备发现功能受损。这种情况可以考虑用 macvlan 给容器分配独立 IP，是 host 和 bridge 之间的折中方案。
到底值不值得折腾
如果你的需求只是”远程控制几个智能插座”，厂商自带的 App 就够了，没必要上 HA。
HA 的价值在于跨品牌联动——把小米的传感器、Aqara 的开关、涂鸦的插座、Broadlink 的遥控器统一到一个平台，写出”人回家且光线暗则开灯”这类真正的自动化。设备品牌越多、联动需求越复杂，HA 的价值越大。
