4010 字
20 分钟
自建服务实战:Home Assistant 打造智能家居中枢
2026-11-15

先说问题:智能家居为什么需要一个「中枢」#

智能家居玩到最后,家里往往是这个局面:灯是米家的,插座是涂鸦的,空调伴侣是博联的,摄像头又是另一个 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 文件:

Terminal window
mkdir -p /opt/homeassistant/config
cd /opt/homeassistant

docker-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 协调器,没有可删掉这一段

启动:

Terminal window
docker compose up -d
docker 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 把串口透传进容器。先在宿主机上确认设备路径:

Terminal window
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/data

mosquitto/config/mosquitto.conf 最小配置:

listener 1883
allow_anonymous false
password_file /mosquitto/config/pwfile
persistence true
persistence_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: single

sun 触发器用的就是初始化时填的经纬度,这也是为什么向导那一步不能乱填。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 目录里。停容器后整目录打包,就是一份完整备份:

Terminal window
cd /opt/homeassistant
docker compose stop
tar 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 的水很深,仪表盘美化、能源管理、语音助手、复杂场景联动都还能再各写一篇。但把这一篇的骨架立稳,家里设备从「各管各的」变成「一个中枢说了算」,智能家居才算真正入了门。

自建服务实战:Home Assistant 打造智能家居中枢
https://www.anexns.cloudns.org/posts/selfhost-home-assistant/
作者
Anexns
发布于
2026-11-15
许可协议
CC BY-NC-SA 4.0