HomeAssistant 智能家居平台搭建指南

基于 Docker 部署 HomeAssistant，集成 HACS 应用商店和 Xiaomi Home 插件

项目概述

访问地址: http://localhost:8123/

功能特点：

• 🏠 开源智能家居自动化平台
• 🔌 支持 1000+ 设备集成
• 📱 手机 App 远程控制
• 🤖 强大的自动化规则引擎
• 🎨 可自定义仪表盘

---

系统架构

┌─────────────────────────────────────────────────────────────┐
│                     HomeAssistant                            │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│  ┌──────────┐    ┌──────────┐    ┌──────────┐              │
│  │  HACS    │    │XiaomiHome│    │ 自动化   │              │
│  │ 应用商店 │    │ 小米集成 │    │  规则   │              │
│  └──────────┘    └──────────┘    └──────────┘              │
│                                                              │
│  ┌─────────────────────────────────────────────────────────┐│
│  │                    设备集成层                            ││
│  │  灯光 | 传感器 | 摄像头 | 门锁 | 空调 | ...              ││
│  └─────────────────────────────────────────────────────────┘│
│                                                              │
└─────────────────────────────────────────────────────────────┘

---

部署步骤

1. Docker 部署

bash
# 创建目录
mkdir -p ~/homeassistant/config && cd ~/homeassistant

# 创建 docker-compose.yml
cat > docker-compose.yml << 'EOF'
services:
  homeassistant:
    image: homeassistant/home-assistant:latest
    container_name: homeassistant
    restart: unless-stopped
    volumes:
      - ./config:/config
    environment:
      - TZ=Asia/Shanghai
    ports:
      - "8123:8123"
    privileged: true
EOF

# 启动服务
docker compose up -d

2. 初始配置

1. 打开 http://localhost:8123/
2. 创建管理员账号（用户名 + 密码）
3. 设置安装名称、时区等信息
4. 完成初始化

---

HACS 安装

HACS (Home Assistant Community Store) 是第三方应用商店。

安装方法

bash
# 进入容器执行安装脚本
docker exec homeassistant bash -c \
  "cd /config/custom_components && curl -sL 'https://get.hacs.xyz' | bash -"

# 重启 HomeAssistant
docker restart homeassistant

配置 HACS

1. 设置 → 设备与服务 → 添加集成
2. 搜索 "HACS"
3. 按提示完成 GitHub 授权
4. 重启生效

---

Xiaomi Home 集成

安装插件

在 HACS 中搜索 "Xiaomi Home" 并安装。

配置步骤

1. 设置 → 设备与服务 → 添加集成
2. 搜索 "Xiaomi Home"
3. 填写配置信息：
   • 登录地区: 中国大陆
   • 语言: 简体中文
   • 集成网络配置: 首次建议勾选

获取访问令牌

如果集成需要 Token：

1. 打开 HomeAssistant
2. 点击左下角用户名/头像
3. 滚动到「长期访问令牌」
4. 点击「创建令牌」
5. 输入名称并复制 Token

---

常见问题

1. macOS Docker 网络限制

macOS Docker Desktop 不支持 host 网络模式，Xiaomi Home 的本地控制功能可能受限。

解决方案：

• 云端控制正常使用
• 本地发现设备可能需要手动添加

2. 容器重启后配置丢失

确保使用了 volume 挂载：

yaml
volumes:
  - ./config:/config

3. HACS 无法连接 GitHub

可能需要配置代理或使用镜像站。

---

目录结构

~/homeassistant/
├── docker-compose.yml      # Docker 配置
└── config/                 # HomeAssistant 配置目录
    ├── configuration.yaml  # 主配置文件
    ├── automations.yaml    # 自动化配置
    ├── scripts.yaml        # 脚本配置
    └── custom_components/  # 自定义组件
        └── hacs/           # HACS 插件

---

常用命令

bash
# 启动服务
docker compose up -d

# 查看日志
docker logs -f homeassistant

# 重启服务
docker restart homeassistant

# 进入容器
docker exec -it homeassistant bash

---

推荐插件

插件	功能
Xiaomi Home	小米设备集成
Xiaomi Miot Auto	小米设备自动发现
HACS	应用商店
Browser Mod	浏览器控制
Lovelace UI	仪表盘美化

---

更新日志

2026-03-29

• ✅ Docker 部署完成
• ✅ HACS 安装成功
• ✅ Xiaomi Home 集成配置

---

最后更新: 2026-03-29