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，所以装完必须重启再添加集成：

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

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

设备接入：Xiaomi Home

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

接入流程：

1. 在 HACS 中搜索并安装 Xiaomi Home，重启 HA
2. 设置 → 设备与服务 → 添加集成 → 搜索"Xiaomi Home" → 下一步
3. 点击"请点击此处进行登录"，使用小米账号登录
4. 授权完成后设备自动同步进 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 是基础框架，安装最简单：

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

Bubble Card

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

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

More Info Card

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

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