一、速览：为什么你需要一个"智能家居管家"

入门

你家里可能有智能灯泡、智能插座、摄像头，它们来自不同品牌，各自用各自的 App，彼此不联通。想实现"开门自动亮灯"这种跨品牌联动，基本做不到。

Home Assistant（简称 HA）就是来解决这个问题的。它是一个开源的家庭自动化平台，相当于给所有智能设备请了一个统一管家。你只需要把设备接入 HA，就能在一个界面里控制所有设备，还能设置自动化规则，让设备根据你的生活习惯自己动起来。

这个项目有 9 万多 Star，是全球最活跃的开源智能家居项目之一。它最大的特点是本地控制：你的设备数据默认只存在你自己家的服务器上，不经过任何云端，隐私性比用厂商的云服务好得多。

读完本文，你会学会：用 Docker 在 10 分钟内部署 HA，接入第一批设备，写出第一条自动化规则，并了解日常维护的必备操作。

二、快速部署：Docker 一键搞定

入门

部署 HA 之前，你需要准备一台常开的设备。因为它是你的智能家居管家，必须 24 小时待命，不能像电脑一样随便关机。

推荐两种选择：

• 树莓派 4 或更高版本：功耗低，专门为这类用途设计，是官方推荐方案
• 家里的旧电脑或 NAS：性能更强，适合接入大量设备

无论用哪种，都需要先安装 Docker。Docker 是一种把软件打包成"集装箱"、随处可运行的工具，它让 HA 的安装和升级变得非常简单。如果你用的是树莓派，建议直接刷官方的 Home Assistant OS 镜像，自带 Docker 环境；如果用的是 Linux 服务器，先执行以下命令安装 Docker：

curl -fsSL https://get.docker.com | sh

安装完成后，创建一个目录存放 HA 的配置，然后启动容器：

mkdir -p /opt/homeassistant/config

docker run -d \
  --name homeassistant \
  --restart=unless-stopped \
  -e TZ=Asia/Shanghai \
  -v /opt/homeassistant/config:/config \
  -p 8123:8123 \
  ghcr.io/home-assistant/home-assistant:stable

这条命令的意思是：启动一个名为 homeassistant 的容器，把本地的 /opt/homeassistant/config 目录映射到容器里（配置会存在这里），并把容器的 8123 端口暴露到宿主机。TZ 是时区变量，设为上海时间。

注意：如果你的服务器上已经装了其他服务占用了 8123 端口，可以把命令最后的 -p 8123:8123 改成 -p 8124:8123，这样就用 8124 端口访问。

启动后，在浏览器里访问 http://你的服务器IP:8123，就能看到 HA 的欢迎页面了。首次打开会让你创建管理员账号和家庭名称，按提示填写即可。

三、配置详解：目录结构和核心文件

进阶 · 推荐细读

HA 跑起来之后，所有配置都保存在你映射的 /opt/homeassistant/config 目录里。了解这个目录的结构，对后续维护很重要。

config/
├── configuration.yaml   # 主配置文件
├── .storage/            # 系统自动生成的配置（不要手动改）
├── custom_components/   # 第三方集成插件
└── home-assistant.log   # 运行日志

其中 configuration.yaml 是核心，它用 YAML 格式（一种用缩进表示层级关系的纯文本格式，类似购物清单）描述 HA 的行为。默认情况下你不需要改它，因为 HA 的绝大部分配置都可以在网页界面上完成。

但有些场景需要手动编辑这个文件，比如添加自定义的自动化规则。下面是一个最小示例：

## 基础配置
homeassistant:
  name: 我的家
  latitude: 39.90
  longitude: 116.40
  unit_system: metric
  time_zone: Asia/Shanghai

## 日志级别
logger:
  default: info

建议：每次修改 configuration.yaml 之前先备份一份。改完后，到"开发者工具 → YAML"页面重新加载配置，不需要重启整个服务。

设备接入是 HA 最核心的操作。HA 把每种设备接入方式称为集成，它支持超过 3000 种集成。你可以在网页界面的"设置 → 设备与服务"里搜索你的设备品牌，比如小米、飞利浦、苹果 HomeKit，点击添加并按提示授权即可。

四、功能导览：仪表盘、集成与自动化

进阶 · 推荐细读

设备接入后，你会看到一个默认的仪表盘，上面显示所有已接入设备的实时状态。这个界面可以自由拖拽和自定义，你可以把最常用的设备放在首页，不用每次翻找。

仪表盘的核心操作：

• 添加卡片：点击右上角的编辑按钮，选择"添加卡片"，可以添加灯光控制、温度曲线、摄像头画面等
• 分组管理：把同一房间的设备拖到同一个区域，比如"客厅""卧室"，方便统一管理
• 自定义主题：在"设置 → 仪表盘 → 主题"里可以切换深色模式或安装第三方主题

接入设备只是第一步，HA 的杀手级功能是自动化。它让你用"当……就……"的逻辑把设备串起来。比如"当大门打开，就打开客厅灯"。

在"设置 → 自动化"里点击"创建自动化"，你会看到一个可视化编辑器：

• 触发条件：选择"实体状态变化"，然后选"门磁传感器"的状态变为"开启"
• 执行动作：选择"调用服务"，然后选"客厅灯"的"打开"服务
• 保存：点击保存后这个自动化就生效了

对于更复杂的逻辑，HA 提供了自动化脚本的 YAML 写法。下面是一个"日落时自动打开阳台灯"的示例：

alias: 日落开灯
trigger:
  - platform: sun
    event: sunset
action:
  - service: light.turn_on
    target:
      entity_id: light.balcony

这段配置的意思是：当太阳落山时，打开阳台灯。trigger 是触发条件，action 是执行动作，这是自动化最基本的两个要素。

除了自动化，HA 还支持语音控制。你可以接入 Google Home、小爱同学或苹果 Siri，通过语音命令控制设备。在"设置 → 语音助手"里可以配置，但需要额外部署语音管道组件，建议先把基础玩熟再探索。

五、常见问题排查

进阶 · 推荐细读

部署和使用过程中，有几个问题是新手最容易遇到的。

问题 1：网页打不开或显示"无法访问此网站"

最常见的原因是容器没起来或端口没映射对。先检查容器状态：

docker ps -a | grep homeassistant

如果状态显示 Exited，说明容器崩溃了，查看日志：

docker logs homeassistant

如果状态是 Up，但网页还是打不开，检查防火墙是否放行了 8123 端口：

sudo ufw allow 8123

问题 2：设备接入时搜索不到

先确认你的设备与 HA 在同一局域网内。很多智能设备默认开启 AP 隔离（设备间无法互相访问），需要在路由器设置里关闭。另外，部分设备需要在"设备与服务"里输入设备的 IP 地址手动添加，而不是自动搜索。

问题 3：配置改了不生效

HA 的 YAML 配置对格式很敏感。缩进必须用空格，不能用 Tab；冒号后面必须跟一个空格。改完配置后，到"开发者工具 → YAML"页面点击"检查配置"，如果有语法错误会直接提示。

问题 4：容器重启后配置丢失

这是数据卷映射没做对。检查启动命令里是否写了 -v /opt/homeassistant/config:/config，如果没有，容器删除后配置就全没了。建议在启动命令中加上 --restart=unless-stopped，这样服务器重启后 HA 会自动恢复运行。

重要：HA 的配置都在 /config 目录里，定期备份这个目录就相当于备份了整个系统。最简单的方式是把整个目录打包下载到本地。

六、运维进阶：反向代理、备份与升级

深入 · 老手可选

当你出门在外，想用手机流量访问家里的 HA 时，就需要配置反向代理。反向代理是一个中转站，它让外部请求安全地转发到你家里的 HA 服务上，同时还能加上 HTTPS 加密。

最常用的方案是 Caddy 加 DuckDNS。DuckDNS 提供免费的动态域名，Caddy 自动申请免费 HTTPS 证书。在服务器上安装 Caddy 后，编辑 Caddyfile：

你的域名.duckdns.org {
    reverse_proxy 127.0.0.1:8123
}

这样，浏览器访问 https://你的域名.duckdns.org 就能安全地连到 HA 了。

备份策略：HA 在"设置 → 系统 → 备份"里提供了内置备份功能，可以手动或定时把整个配置打包下载。建议每周备份一次，并把备份文件同步到网盘或另一台电脑上。

升级方法：HA 的升级很频繁，每月都有新版本。升级前先备份，然后执行：

docker pull ghcr.io/home-assistant/home-assistant:stable

docker stop homeassistant && docker rm homeassistant

然后用之前的启动命令重新创建容器。因为配置在数据卷里，升级不会影响你的设备和自动化设置。

到这里，你已经完成了从零到一的全过程：部署了 HA，接入了设备，写了自动化，还掌握了日常维护的基本操作。剩下的就是慢慢探索，把更多设备接进来，让这个"管家"越来越懂你的生活习惯。

项目信息

参考链接

• GitHub 仓库
• 项目主页

延伸阅读

想继续探索？这些同领域的教程可能也适合你：

• 「sh」中文使用教程
• 「watchtower」中文使用教程
• 「awesome-ops-system」中文使用教程