先说问题:智能家居为什么需要一个「中枢」
智能家居玩到最后,家里往往是这个局面:灯是米家的,插座是涂鸦的,空调伴侣是博联的,摄像头又是另一个 App。每个品牌一套云、一套 App,设备之间互不说话——想让「开门亮灯」这种跨品牌联动跑起来,光靠各家自己的云服务基本没戏。更麻烦的是断网即残废:宽带一断,全屋智能退回手动时代;厂商云服务关停,设备直接变砖的新闻也出过不止一次。
Home Assistant(下文简称 HA)就是为了解决这件事而生的开源中枢。它跑在你自己家里的服务器、NAS 或小主机上,把各品牌设备统一接进来,用一套规则做联动。HA 的核心理念是本地优先:设备控制和自动化逻辑全部在局域网内完成,不依赖任何厂商云,断网照样跑。
它的家底也确实厚:官方与社区集成超过两千个,Zigbee、Z-Wave、蓝牙、Wi-Fi、MQTT 各种协议都能收编;更新节奏是每月一个大版本,社区活跃度在自建圈里数一数二。
本篇主线:对比三种部署方式并选定 Docker 版 → Compose 部署与设备直通 → 初始化与核心概念 → 接入设备(含 MQTT 与 Frigate 联动)→ 自动化三段式实战 → 仪表盘 → 安全远程访问 → 备份与排障。
部署方式对比:Docker 版、HAOS、树莓派
HA 有四种官方安装形态,选错了后面全是别扭。先拉个表:
| 部署方式 | 形态 | 优点 | 缺点 | 适合人群 |
|---|---|---|---|---|
| HAOS(虚拟机) | 完整操作系统镜像跑在虚拟机里 | 功能最全:带 Supervisor、插件商店、一键备份恢复 | 独占一台虚拟机,资源开销大,与其他服务隔离 | 有 PVE/ESXi 环境、想省心 |
| HAOS(树莓派/小主机裸装) | 镜像直接刷进 SD 卡或硬盘 | 同上,且即插即用 | 整台设备被 HA 独占;SD 卡寿命是隐患 | 愿意给 HA 一台专属设备 |
| Docker 容器版(Container) | 单个容器跑核心服务 | 轻量、与现有 Docker 服务共存、迁移就是搬目录 | 没有 Supervisor 和插件商店,附加服务要自己用容器补 | 已经有 Docker 宿主机/NAS |
| Core(Python 虚拟环境) | 直接装 Python 包 | 最灵活 | 依赖全靠自己维护,升级容易翻车 | 开发者,不推荐日常用 |
本文走 Docker 容器版,理由很实际:看这篇的朋友多半已经有一台跑着 Docker 的 NAS 或小主机,HA 作为一个普通容器塞进去即可,不用为它单独开虚拟机,更不用独占一台设备。代价是没有插件商店——但插件的本质就是预打包的容器(比如 Mosquitto、Zigbee2MQTT),自己写进 Compose 里反而更透明可控。排障一节会再细说这个差异。
WARNING先泼盆冷水:HA 对宿主机的时间、网络发现协议都比较敏感。如果你的 Docker 宿主机本身网络环境复杂(多层 NAT、VLAN 隔离),设备自动发现会打折扣,这类问题在后面排障里有对应条目。
Docker Compose 部署
先建目录,再写 Compose 文件:
mkdir -p /opt/homeassistant/configcd /opt/homeassistantdocker-compose.yml:
services: homeassistant: image: ghcr.io/home-assistant/home-assistant:stable container_name: homeassistant restart: unless-stopped network_mode: host environment: - TZ=Asia/Shanghai volumes: - ./config:/config - /etc/localtime:/etc/localtime:ro devices: - /dev/ttyUSB0:/dev/ttyUSB0 # Zigbee/Z-Wave USB 协调器,没有可删掉这一段启动:
docker compose up -ddocker compose logs -f homeassistant # 看到启动完成字样后 Ctrl+C 退出几个关键点逐个说清:
为什么用 network_mode: host? HA 大量依赖局域网广播协议做设备发现:mDNS、SSDP、DHCP 嗅探全是广播包。容器走默认 bridge 网络时这些广播进不来,自动发现会残废一片。host 模式让容器直接共用宿主机网络栈,8123 端口直接落在宿主机上,省去端口映射,发现协议也全部通畅。代价是少了网络隔离,所以宿主机本身的防火墙要管好,千万不要图省事再把 8123 端口从路由器映射到公网,远程访问的正确姿势在后面专门讲。
时区要双保险。 环境变量 TZ 和挂载 /etc/localtime 两个都写上。HA 里大量自动化是按时间触发的,时区错了,所有定时都会跟着错位,排障一节有真实翻车场景。
设备直通按需加。 如果你用 USB 的 Zigbee 协调器(比如 Sonoff ZBDongle、CC2652 系列),就用 devices 把串口透传进容器。先在宿主机上确认设备路径:
ls -l /dev/serial/by-id/强烈建议在集成里填 by-id 路径而不是 /dev/ttyUSB0——后者会随着插拔顺序漂移,今天认的是协调器,明天可能就变成别的 USB 设备了。
初始化与核心概念
浏览器打开 http://宿主机IP:8123,首次访问进入初始化向导:创建管理员账号(这就是你以后登录 HA 的主账号,密码强度别马虎)、设置家庭名称与地理位置(经纬度用于算日出日落,自动化里要用)、选择上报与否的匿名统计。向导走完进入主界面,系统通常已经自动发现了局域网里的一部分设备,先别急着点,理解四个概念再动手:
- 设备(Device):一个物理硬件,比如一盏灯、一个传感器,在「设置 → 设备与服务」里以卡片形式存在。
- 实体(Entity):设备提供的每一个可读可控的「点」。一盏灯可能有开关、亮度、色温三个实体;一个温湿度传感器有温度、湿度、电量三个实体。自动化和仪表盘操作的都是实体,实体 ID 形如
light.living_room、sensor.temperature,后面写 YAML 全靠它。 - 区域(Area):客厅、卧室、书房这样的逻辑分组,把设备归到区域里,仪表盘和语音控制都会清爽很多。
- 集成(Integration):连接某个品牌或协议的「驱动」,在「设置 → 设备与服务 → 添加集成」里安装。
接入设备:发现、集成与 MQTT
自动发现:host 网络模式下,HA 会把局域网里支持的设备直接推到「设置 → 设备与服务」页面的待配置区,点进去按提示走完即可,米家、Yeelight、HomeKit 设备、飞利浦 Hue 桥等常见硬件大多能这样进来。
手动添加集成:没被发现的设备,在同一页面右下角「添加集成」,搜品牌名,按官方文档填 IP、Token 等参数。局域网直连类集成(如小米的 Xiaomi Miot)优先选本地模式,能不走云就别走云。
MQTT 接入:大量 DIY 设备和第三方网关走 MQTT 协议。HA 容器版没有插件商店,自备一个 Mosquitto 容器即可,写进同一个 Compose:
mosquitto: image: eclipse-mosquitto:2 container_name: mosquitto restart: unless-stopped ports: - "1883:1883" volumes: - ./mosquitto/config:/mosquitto/config - ./mosquitto/data:/mosquitto/datamosquitto/config/mosquitto.conf 最小配置:
listener 1883allow_anonymous falsepassword_file /mosquitto/config/pwfilepersistence truepersistence_location /mosquitto/data/生成密码文件后重启容器,再在 HA 里「添加集成 → MQTT」,填宿主机 IP 与账号密码完成对接。之后 Zigbee2MQTT、Tasmota 刷机设备、ESPHome 之外的自制传感器都能经这条通道进来。
与监控联动:如果你按本系列上一篇部署了 Frigate AI 监控,它原生就通过 MQTT 把「检测到人/车」的事件发出来,HA 订阅后就能实现「院子里检测到人 → 自动开院灯并推送通知」,两个系统是天生一对。
自动化实战:先搞懂三段式
HA 自动化的骨架永远是三段:trigger(什么事发生了)→ condition(现在满不满足条件)→ action(执行什么动作),三段齐全才是一条能跑的自动化。界面上可以可视化拖拽创建,但写 YAML 更直观也便于备份,配置都落在 config/automations.yaml 里(在 configuration.yaml 中需有 automation: !include automations.yaml,默认模板已包含)。
例一:日落自动开玄关灯
- id: sunset_entry_light alias: 日落开玄关灯 description: 太阳落山后自动打开玄关灯 trigger: - platform: sun event: sunset offset: "-00:15:00" # 提前 15 分钟,天刚擦黑就亮灯 condition: [] action: - service: light.turn_on target: entity_id: light.entry_light data: brightness_pct: 80 mode: singlesun 触发器用的就是初始化时填的经纬度,这也是为什么向导那一步不能乱填。offset 为负表示日落前触发,天没全黑灯先亮,体验好得多。
例二:夜间人体感应开夜灯
- id: night_motion_light alias: 夜间人体感应夜灯 trigger: - platform: state entity_id: binary_sensor.hallway_motion to: "on" condition: - condition: time after: "23:00:00" before: "06:00:00" - condition: state entity_id: light.hallway_night_light state: "off" action: - service: light.turn_on target: entity_id: light.hallway_night_light data: brightness_pct: 15 # 深夜只给 15% 亮度,不晃眼 - delay: "00:02:00" - service: light.turn_off target: entity_id: light.hallway_night_light mode: restart # 期间再次感应到人,重新计时这条把三段式用全了:触发是人体传感器状态变 on;条件双保险——只在 23 点到次日 6 点之间、且灯当前是关着的才执行;动作是低亮度开灯、延时两分钟、关灯。mode: restart 是关键细节:人还在走廊里活动时传感器会重复触发,计时从头来,避免灯在人眼前熄灭。
改完 YAML 不用重启容器,在「开发者工具 → YAML」里点「重新加载自动化」即可生效。
仪表盘 Lovelace 基础
仪表盘(Lovelace)是 HA 的门面,默认会自动按区域生成概览页。想自己掌控,就在任意仪表盘右上角点「编辑仪表盘 → 原始配置编辑器」,或者直接写 YAML。最常用的几类卡片:实体卡、按钮卡、温湿度图表卡、摄像头卡。一个最小的自定义视图示例:
views: - title: 客厅 path: living cards: - type: entities title: 灯光 entities: - light.living_room_main - light.living_room_ambient - type: sensor entity: sensor.living_room_temperature graph: line hours_to_show: 24 - type: tile entity: binary_sensor.hallway_motion name: 走廊人体感应建议节奏:先用自动生成的概览页跑一阵子,摸清自己每天真正看的是哪几个实体,再动手做精简版仪表盘——一上来就追求花哨大屏,多半是给自己挖坑。
远程访问:走反代,不裸奔
人在外面想看家里状态,需求很正当,但做法分高下。最差的做法是路由器端口映射把 8123 直接怼到公网:HA 的登录页这些年被扫描器盯得很紧,8123 裸奔公网约等于把家门钥匙挂在门把手上。
正确姿势是走本系列讲过的 Nginx Proxy Manager 反向代理:给 HA 配一个子域名(如 ha.example.com),由 NPM 终止 HTTPS 再转发到内网 8123。HA 侧需要告诉它自己身后有反代,在 configuration.yaml 里加:
http: use_x_forwarded_for: true trusted_proxies: - 172.17.0.1 # 改成你 NPM 容器实际所在的网段/网关地址少了这段,HA 会因为代理头不被信任而拒绝登录或日志里刷屏报错,这是反代接入 HA 最常见的坑。账号侧再补两道锁:管理员密码用密码管理器生成的长随机串,并在「个人资料 → 安全性」里开启双因素认证。更多自建服务的暴露面收敛思路,可以连同 自建服务安全与访问控制 一起看。
WARNING注意:如果你的 NPM 和 HA 不在同一台机器、或不在同一 Docker 网络里,
trusted_proxies要填的是「NPM 向 HA 发起连接时,HA 看到的来源 IP」。填错的表现是登录时报 400 或反复跳回登录页,先查这个,不要先怀疑密码。
备份:配置目录就是全部家当
容器版备份思路异常简单:HA 的全部状态——配置、自动化、仪表盘、集成凭据、历史数据库——都在挂载出来的 config 目录里。停容器后整目录打包,就是一份完整备份:
cd /opt/homeassistantdocker compose stoptar czf ha-backup-$(date +%F).tar.gz config/docker compose start注意两点:一是打包前最好停容器,运行中直接拷 home-assistant_v2.db 可能拷到写一半的数据库;二是这个压缩包里有各设备的 Token 和你的账号哈希,备份文件本身就是敏感数据,存放和传输都要当密钥对待。异地留存、版本保留策略这类通用方法论,本系列的 自建服务备份与迁移 讲得更系统,建议照着那套给 HA 也排上日程。HAOS 版自带的一键快照在容器版没有对应物,但整目录打包恢复起来同样是一条命令的事,并不吃亏。
常见问题与排障
Q:为什么我的 HA 里没有「插件商店」(加载项)? 这是容器版与 HAOS 的固有差异,不是装坏了。Supervisor 和加载项只属于 HAOS。容器版的解法是把需要的附加服务(Mosquitto、Zigbee2MQTT、ESPHome、Node-RED 等)各自用 Docker 容器部署,再通过集成接入 HA——本文的 Mosquitto 就是这么来的。功能一个不少,只是管理入口分散在 Compose 文件里。
Q:设备频繁掉线、状态不更新怎么办? 按顺序查:先看设备本身是否在线(品牌 App 或路由器客户端列表里确认);再看协议通道——Zigbee 设备查协调器日志和信号强度(LQI),很多掉线是距离与干扰(协调器插在 USB 3.0 口旁边是经典干扰源,加一根 USB 延长线往往立竿见影);Wi-Fi 设备查是不是路由器开了 AP 隔离或设备被分到了访客网络;最后才去怀疑 HA 本身,看「设置 → 系统 → 日志」里对应集成的报错。
Q:自动化写了却不触发,怎么排查?
固定四步:一查触发器实体 ID 是否写对(去「开发者工具 → 状态」里核对实体当前状态与 ID,一个字母都不能错);二查条件是否把自己拦了(在「设置 → 自动化」里打开这条自动化的「跟踪」功能,能看到每次触发在哪一段被挡下);三查自动化本身是否被禁用、或 mode 设置导致还在运行中拒绝新触发;四手动点自动化的「运行」按钮验证动作段本身能执行——动作能跑、自动不跑,问题一定在触发或条件段。
Q:定时自动化总是差几个小时执行?
九成是时区问题。依次确认:宿主机 timedatectl 显示的时区、Compose 里 TZ 环境变量、HA「设置 → 系统 → 常规」里的时区三者必须一致,都是 Asia/Shanghai。只改了 HA 界面没改容器时区的,日出日落类触发器会继续按 UTC 算,表现就是定时错乱但时钟显示正常,特别有迷惑性。
Q:改了 configuration.yaml 后 HA 起不来?
先看日志定位:docker compose logs homeassistant 会明确指出哪个文件哪一行语法错误。养成习惯:改 YAML 前在「开发者工具 → YAML」点「检查配置」,通过了再重载或重启。YAML 对缩进零容忍,混用 Tab 和空格是最常见死因。
小结
这一篇把 Home Assistant 的容器版从选型一路走到了能长期跑的状态:host 网络保住设备发现、设备直通收编 Zigbee、MQTT 打通 DIY 设备、自动化用 trigger/condition/action 三段式写、远程访问只走反代加双因素、备份就是定期打包 config 目录。它和本系列其他服务的关系也顺手打通了:Frigate 供事件、NPM 管入口、备份体系兜底。
HA 的水很深,仪表盘美化、能源管理、语音助手、复杂场景联动都还能再各写一篇。但把这一篇的骨架立稳,家里设备从「各管各的」变成「一个中枢说了算」,智能家居才算真正入了门。