HomeAssistant

Home Assistant 是本地优先的智能家居中枢：各品牌设备统一接入，自动化在家庭内网执行。本篇记录我的实例从部署到插件体系的搭建过程——Docker 部署、HACS、米家设备接入、Cloudflare Tunnel 外网访问、前端卡片。

安装：Docker Compose

Container 部署的关键决策是网络模式：智能家居的设备自动发现依赖组播协议，而组播包无法穿越 Docker 的 NAT 桥接网络，因此必须用 host 网络让容器共享宿主机网络栈。

我的配置

services:
  homeassistant:
    container_name: homeassistant
    image: "homeassistant/home-assistant:stable"
    volumes:
      - /data2/homeassistant/config:/config
      - /etc/localtime:/etc/localtime:ro
      - /run/dbus:/run/dbus:ro
    restart: unless-stopped
    privileged: true
    network_mode: host
    environment:
      TZ: Asia/Shanghai

各关键项的原因：

配置项	原因
`network_mode: host`	mDNS、SSDP、HomeKit 等发现协议走组播，bridge 网络下设备发现直接失效；host 模式下 Web 界面直接占用宿主机 8123 端口
`privileged: true`	Zigbee/Z-Wave 网关多为 USB 串口设备，特权模式免去逐个 `--device` 映射，新设备插入即可见
`/run/dbus:/run/dbus:ro`	蓝牙集成需要经 D-Bus 与宿主机系统服务通信
`/data2/homeassistant/config:/config`	HA 的全部状态（集成、自动化、数据库）收敛在这一个目录，备份迁移只需拷贝它
`:stable` 标签	跟随官方稳定版；HA 每月一个大版本且常有破坏性变更，求稳可改为固定版本号

启动初始化

启动后访问 http://宿主机IP:8123 完成初始化。

HACS：社区插件商店

HACS 是社区维护的插件市场。Container 部署没有官方 Add-on 商店，第三方集成和前端卡片都通过 HACS 分发，它以自定义集成（custom_components）的形式装进配置目录。

安装

容器内执行官方脚本，HACS 会被下载到 /config/custom_components/ 下——/config 已挂载宿主机目录，容器重建不会丢：

docker exec -it homeassistant bash -c "wget -O - https://get.hacs.xyz | bash -"

前提

容器能访问 GitHub，网络不通时先解决代理。

启用

HA 只在启动时加载 custom_components，所以装完必须重启再添加集成：

重启容器
进入"设置"→"设备与服务"
点击右下角的"添加集成"
在搜索框中输入 HACS，点击它，按照提示完成 GitHub 授权登录

授权是必要前提：HACS 的本质是 GitHub 仓库的下载入口。之后从 HACS 安装的每个集成，同样需要重启才会加载。

设备接入：Xiaomi Home

米家设备通过 Xiaomi Home 集成接入，设备清单从小米账号同步而来——因此前提是设备已先在米家 App 完成配网，HA 不负责配网。

接入流程：

在 HACS 中搜索并安装 Xiaomi Home，重启 HA
设置 → 设备与服务 → 添加集成 → 搜索"Xiaomi Home" → 下一步
点击"请点击此处进行登录"，使用小米账号登录
授权完成后设备自动同步进 HA

登录回调跳转失败

授权后浏览器会跳转到 http://homeassistant.local:8123/... 并打不开：homeassistant.local 是 HA 默认的内部主机名，只在支持 mDNS 的局域网内有效，用 IP 或 Tunnel 域名访问时该地址不存在。手动把地址栏域名改成实际访问 HA 的地址（路径和参数不变）即可完成回调。

根治办法：设置 → 系统 → 网络 → Home Assistant URL 配置实际地址，后续所有 OAuth 回调都会直接使用它。

外网访问：Cloudflare Tunnel

家庭宽带通常没有公网 IP，外网访问用 Cloudflare Tunnel：cloudflared 主动向 Cloudflare 边缘节点建立出站隧道，外网流量经隧道回源到 HA，不需要公网地址、不需要开放路由器端口，HTTPS 由 Cloudflare 托管终结。

必须配置可信代理

隧道请求的源 IP 全部变成 cloudflared 的地址，而 HA 默认拒绝反向代理转发的请求（防止伪造 X-Forwarded-For 头绕过 IP 封禁），不配置可信代理时外网访问直接返回 400 Bad Request。

我的配置

编辑 configuration.yaml：

http:
  use_x_forwarded_for: true
  trusted_proxies:
    - 127.0.0.1
    - ::1
    - 172.17.0.0/16      # 保留以防万一
    - 192.168.1.100      # 保留以防万一

配置项	原因
`use_x_forwarded_for: true`	让 HA 从 X-Forwarded-For 头取真实访客 IP，否则登录日志全是代理地址，IP 封禁还会误伤代理本身；该选项只有在可信代理之后才能开启
`127.0.0.1` / `::1`	cloudflared 与 HA 同机部署时走回环地址（HA 是 host 网络，本机回源的源 IP 就是回环）
`172.17.0.0/16`	Docker 默认网桥网段，cloudflared 跑在容器里时源 IP 落在这一段
`192.168.1.100`	内网保留地址

改完重启容器生效。

前端卡片

卡片库通过 HACS 的"前端"频道安装，装完自动注册为 Lovelace 资源，无需手动配置，编辑仪表盘时在卡片选择器里直接搜索即可使用。

卡片	定位	安装要点
Mushroom	基础框架：按钮、滑块、芯片等全套卡片	仅前端频道安装
Bubble Card	前端卡片 + 后端配套集成	两处都要装
More Info Card	实体详情弹窗渲染为常驻卡片	前端频道安装 + 配置实体 ID

Mushroom

Mushroom 是基础框架，安装最简单：

在 HA 左侧边栏进入 HACS
点击顶部的"前端"（Frontend）标签页
点击右下角的"浏览并下载存储库"（或"+"号）按钮
搜索 Mushroom，找到"Lovelace Mushroom"（核心卡片库，包含所有 Mushroom 卡片：按钮、滑块、芯片等）
点击卡片进入详情页，再点击右下角的"下载"按钮
下载完成后，根据提示刷新页面即可

Bubble Card

Bubble Card 分前端卡片和后端配套集成两部分，两处都要装：

HACS 搜索安装 Bubble Card Tools（集成，装完重启 HA）
前端频道搜索安装 Bubble Card

More Info Card

More Info Card 解决的是实体详情的常驻展示问题：仪表盘上的普通实体卡片只显示状态和开关，完整属性与控制项必须点开"更多详情"弹窗才能看到。这个卡片把弹窗的内容直接渲染成一张卡片，让某个设备的完整详情固定在仪表盘上，省去每次点击。

在 HACS 的"前端"板块搜索并下载 more-info-card
刷新 HA 界面，进入仪表盘编辑模式，点击"添加卡片"，搜索并选择"自定义：More Info Card"
在卡片配置界面的"实体"字段填入要固定显示详情的设备实体 ID（例如 light.bedroom）
保存后，该设备的完整详情卡片就直接显示在仪表盘上

自动化（Automation）

自动化是 HA 的核心能力："触发条件 → 满足条件 → 执行动作"三段式 YAML，在 配置 → 自动化 中可视化创建，底层是 YAML：

alias: 天黑开灯                    # 自动化名称
triggers:
  - trigger: sun                  # 触发:日落
    event: sunset
conditions:
  - condition: state              # 条件:有人在家才执行
    entity_id: person.zhangsan
    state: home
actions:
  - action: light.turn_on         # 动作:开灯
    target:
      entity_id: light.living_room
mode: single                      # 单次执行,避免重复触发叠加

要素	作用	示例
`triggers`	何时触发	时间、状态变化、设备事件、太阳位置
`conditions`	触发后是否满足	实体状态、时间范围、数值条件
`actions`	执行什么	开/关设备、调用服务、发送通知
`mode`	并发处理	single（默认）/ queued / parallel / restart

Add-on 体系

Add-on 是 HA 的"应用商店"：在 Supervised/HAOS 安装方式下，Add-on 以 Docker 容器运行，为 HA 扩展第三方能力（容器版没有 Add-on，需外部容器自己跑）：

常用 Add-on	用途
File editor	网页端编辑配置文件
Terminal & SSH	远程命令行管理
Node-RED	可视化流式自动化（比 YAML 更适合复杂逻辑）
Zigbee2MQTT	Zigbee 设备接入
ESPHome	自制 ESP 设备管理
Mosquitto MQTT broker	MQTT 消息中间件

Add-on 在 设置 → Add-ons 中浏览安装，每个 Add-on 独立配置网络端口与数据目录；与集成（Integration，接入设备协议）不同，Add-on 是"额外应用"，集成是"设备接入适配器"。