home-assistant

项目地址： https://github.com/home-assistant/core

官方文档： https://www.home-assistant.io/docs/

开发者文档： https://developers.home-assistant.io/

最新版本： 2026.10.4（GitHub Releases 与 Docker 镜像 tag 一致，截至 2026-10）

安装形态： Home Assistant OS / Supervised / Container / Core（pip）

许可证： Apache-2.0

概述

Home Assistant 是一个本地优先的开源家庭自动化平台。它把上千种设备与云服务统一成「实体（entity）」，再通过状态机、自动化规则、脚本与仪表盘把它们编排起来。数据与逻辑都跑在你自己的机器上，不依赖厂商云。

对脚本与自动化最关键的几层：

• 实体与状态：每个设备暴露为 domain.name（如 light.study），状态 + 属性构成当前值
• 服务（service/action）：light.turn_on、climate.set_temperature 这类可调用动作，是自动化与 API 的执行单位
• 自动化与脚本：YAML 或 UI 定义的 triggers/conditions/actions 三段式规则
• REST API：/api/*，用长期访问令牌鉴权，适合外部程序读写状态、触发服务
• WebSocket API：/api/websocket，支持实时订阅事件、订阅触发器、批量取状态
• 模板（Jinja2）：{{ states('sensor.x') }} 在自动化与 /api/template 中计算动态值

环境准备

方式一：Home Assistant OS（推荐给家庭用户）

在 Raspberry Pi / NUC / 虚拟机上刷写官方镜像，得到受管系统（含 Supervised、Add-ons、备份）。安装入口见 https://www.home-assistant.io/installation/。首次启动后浏览器访问 http://<ip>:8123 完成引导。

方式二：Docker Container

docker run -d \
  --name homeassistant \
  --restart=unless-stopped \
  --privileged \
  --network=host \
  -e TZ=Asia/Shanghai \
  -v /path/to/config:/config \
  -v /run/dbus:/run/dbus:ro \
  ghcr.io/home-assistant/home-assistant:stable

要点：

• -v /path/to/config:/config 必须持久化，否则升级即丢配置；
• --network=host 让设备发现（mDNS/SSDP）正常工作，端口直接是 8123；
• 需要直通 USB 设备（Zigbee/Z-Wave 棒）时加 --device /dev/ttyUSB0:/dev/ttyUSB0；
• 关机给足时间：docker run --stop-timeout 60，否则容易损坏数据库。

# compose.yaml
services:
  homeassistant:
    image: ghcr.io/home-assistant/home-assistant:stable
    container_name: homeassistant
    restart: unless-stopped
    network_mode: host
    privileged: true
    stop_grace_period: 60s
    environment:
      TZ: Asia/Shanghai
    volumes:
      - ./config:/config
      - /run/dbus:/run/dbus:ro

方式三：Core（pip，仅开发/调试）

python3 -m venv .venv
source .venv/bin/activate
pip install homeassistant==2026.10.4
hass --config ./config --debug