Home Assistant 本地部署与 MQTT 设备接入实战：从 Docker 安装到自动化规则

摘要

智能家居平台最怕"云一断全家失联"。本文用一台闲置 x86 小主机，通过 Docker 把 Home Assistant（HA）与 Mosquitto（MQTT broker）部署在局域网内，再把一个 ESP32 温湿度传感器接入，写出第一条"温度高于 28℃ 自动开风扇"的自动化规则。所有步骤均可复现，适合想把设备掌控权收回本地的朋友。

一、为什么要在本地跑 Home Assistant

很多Wi-Fi 插座、灯泡默认走厂商云，断网就只剩手动开关。Home Assistant 是开源的本地中枢，把不同品牌设备统一到一个面板，且自动化逻辑完全跑在你自己机器上。它支持 MQTT、Zigbee、Z-Wave、HTTP 等协议，扩展性强，社区插件（add-on）丰富。

最低硬件建议：x86 或 ARM 小主机 2GB 内存即可；系统用 Debian 12，已装好 Docker 与 docker-compose。

二、用 Docker Compose 部署 HA 与 Mosquitto

新建目录 ~/ha 并写入 docker-compose.yml：

version: "3"
services:
  homeassistant:
    image: ghcr.io/home-assistant/home-assistant:stable
    container_name: homeassistant
    restart: unless-stopped
    network_mode: host
    volumes:
      - ./config:/config
      - /etc/localtime:/etc/localtime:ro
  mosquitto:
    image: eclipse-mosquitto:2
    container_name: mosquitto
    restart: unless-stopped
    ports:
      - "1883:1883"
    volumes:
      - ./mosq/config:/mosquitto/config
      - ./mosq/data:/mosquitto/data

network_mode: host 让 HA 能直接发现局域网设备。Mosquitto 需一个最简配置 mosq/config/mosquitto.conf：

listener 1883
allow_anonymous true
persistence true
persistence_location /mosquitto/data/

执行 docker compose up -d，等约 1 分钟后访问 http://主机IP:8123 完成初始化向导即可进入面板。

三、在 HA 中接入 MQTT 设备

进入设置 → 设备与服务 → 添加集成 → 搜索 "MQTT"，填写 broker 地址为宿主机 IP、端口 1883。我用一个 ESP32 烧录了开源固件，每隔 10 秒向主题 home/livingroom/sensor 发布：

{"temperature": 27.5, "humidity": 61}

在 configuration.yaml 里声明这个传感器：

mqtt:
  sensor:
    - name: "客厅温度"
      state_topic: "home/livingroom/sensor"
      value_template: "{{ value_json.temperature }}"
      unit_of_measurement: "°C"
    - name: "客厅湿度"
      state_topic: "home/livingroom/sensor"
      value_template: "{{ value_json.humidity }}"
      unit_of_measurement: "%"

改完执行开发者工具 → 检查配置 → 重新加载 MQTT，概览里就能看到实时数值。

四、编写第一条自动化规则

目标：客厅温度超过 28℃ 自动打开智能风扇（假设风扇通过 MQTT 主题 home/livingroom/fan/set 接收 ON/OFF）。在 configuration.yaml 同级创建 automations.yaml：

- id: auto_fan_hot
  alias: "高温自动开风扇"
  trigger:
    - platform: numeric_state
      entity_id: sensor.ke_ting_wen_du
      above: 28
  action:
    - service: mqtt.publish
      data:
        topic: "home/livingroom/fan/set"
        payload: "ON"

entity_id 用自动化编辑器里的实体对象 ID（可在设置 → 实体中查看）。保存后在设置 → 自动化里启用，用吹风机给传感器加热即可看到风扇动作。

五、常见坑与排查

主题收不到数据：先用 mosquitto_sub -h 主机IP -t 'home/#' 订阅验证设备确实在发，再查 HA 的 MQTT 集成是否连接。
实体 ID 乱码：中文 name 会被转成拼音实体 ID，建议 name 用英文避免后期维护困惑。
配置不生效：HA 缓存配置，必须"重新加载"对应集成，而不是只 restart 容器。
断电自启：compose 里已设 restart: unless-stopped，但宿主Docker 本身要开机自启（systemctl enable docker）。

小结

本地部署 HA 的核心价值是"控制权回家"。本文演示了最小闭环：Docker 起服务 → MQTT 接设备 → YAML 写规则。后续可叠加 Zigbee 网关、通知、能耗统计，逐步把全家智能化收拢到一台你完全掌控的主机上。