Home Assistant

Home Assistant是什么？

Home Assistant官网

Home Assistant 是一款开源免费的智能家居中枢系统，核心目标是打破不同品牌智能设备的 “生态壁垒”，让来自小米、华为、苹果、飞利浦等不同厂商的设备实现统一管理、联动控制，同时以 “本地化运行” 保障隐私安全，为用户提供高度定制化的智能家居体验。无论是新手用户还是技术专家，都能通过它搭建符合自身需求的智能生活场景。

  • 开源免费：无订阅费、无功能限制，代码完全开放，社区持续迭代优化；
  • 生态庞大：官方维护的设备集成库持续更新，社区活跃（论坛、GitHub、小红书等），遇到问题能快速找到解决方案；
  • 高度自由：从界面到自动化逻辑，几乎所有细节都可自定义，不被厂商绑定；
  • 长期稳定：作为开源项目已运营多年，更新频率稳定（每月一次大版本更新），兼容新旧设备，避免 “设备淘汰” 问题

部署

Home Assistant提供两种不同的安装类型。HA OS操作系统是推荐的安装类型。

  1. 下载Balena Etcher
    用于将系统传输到SD卡和U盘中
  2. 下载系统镜像文件
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    ## 参数说明
    generic # 通用版本
    aarch64 # 64位ARM架构设备
    x86-64 # 64位x86框架设备
    green # Home Assistant Green 专用硬件
    khahas # Khadas 品牌的开发板
    odroid # ODROID 系列开发板
    ova # 适用于支持 OVA 导入的虚拟化平台
    rpi # Raspberry Pi（树莓派）系列开发板
    thinker # Thinker Board 系列开发板
    yellow # Home Assistant Yellow 硬件
    .img.xz # 经 xz 压缩的原始磁盘镜像，用于物理设备（如开发板、电脑）的全新安装。
    .qcow2.xz # 经 xz 压缩的 QEMU 虚拟机镜像，适用于 KVM、Proxmox 等虚拟化平台。
    .vdi.zip # 经 zip 压缩的 VirtualBox 虚拟机镜像。
    .vmdk.zip # 经 zip 压缩的 VMware 虚拟机镜像。
    .raucb # 基于 RAUC 的升级包，用于已安装系统的 OTA 或离线更新
  3. 使用Balena Etcher将下载好的镜像文件烧录至储存设备中（U盘/SD卡）
  4. 插入需要安装系统的设备，bios中修改第一启动项为储存设备。重启开始安装

安装

1
2
3
4
5
6
7
8
9
docker run -d \
  --name homeassistant \
  --privileged \
  --restart=unless-stopped \
  -e TZ=Asia/Shanghai \
  -v /PATH_TO_YOUR_CONFIG:/config \
  -v /run/dbus:/run/dbus:ro \
  --network=host \
  ghcr.io/home-assistant/home-assistant:stable
1
2
3
4
# 参数说明
/PATH_TO_YOUR_CONFIG # 指向要存储配置并运行的文件夹,替换成自己的
/run/dbus #是可选的,但如果计划使用蓝牙集成,则需要使用。
TZ #设置时区

运行该后打开http://<主机IP>:8123访问Home Assistant

更新

  1. 拉取最新的稳定版镜像
    1
    docker pull ghcr.io/home-assistant/home-assistant:stable
  2. 停止并删除旧容器
    1
    2
    3
    4
    5
    # 停止旧容器（容器名称为之前设置的 "homeassistant"）
    docker stop homeassistant

    # 删除旧容器（删除后仅容器本身被移除，配置数据因挂载目录保留）
    docker rm homeassistant
  3. 用新镜像启动容器
    确保参数与初次部署时一致，尤其是 -v 挂载目录和 –network=host 等关键参数
    1
    2
    3
    4
    5
    6
    7
    8
    9
    docker run -d \
      --name homeassistant \
      --privileged \
      --restart=unless-stopped \
      -e TZ=Asia/Shanghai \
      -v /PATH_TO_YOUR_CONFIG:/config \
      -v /run/dbus:/run/dbus:ro \
      --network=host \
      ghcr.io/home-assistant/home-assistant:stable

删除

  1. 停止运行中的容器
    1
    2
    # 替换--name homeassistant中的名称
    docker stop homeassistant
  2. 删除容器
    1
    docker rm homeassistant
  3. 删除配置数据目录
    1
    2
    # 替换为你的实际配置目录（务必确认路径正确，避免误删！）
    sudo rm -rf /PATH_TO_YOUR_CONFIG
  4. 查看本地的 Home Assistant 镜像 ID
    1
    2
    docker images | grep home-assistant
    # 例如ghcr.io/home-assistant/home-assistant   stable   a1b2c3d4e5f6   2天前    1.2GB
  5. 删除镜像
    1
    docker rmi a1b2c3d4e5f6

安装

  1. 创建文件夹并进入
    1
    mkdir homeassistant && cd homeassistant
  2. 创建docker-compose.yml
    1
    nano docker-compose.yml
  3. 编辑docker-compose.yml并Ctrl + X按Y，Enter保存
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    services:
      homeassistant:
        container_name: homeassistant # 容器名称
        image: "ghcr.io/home-assistant/home-assistant:stable" # 镜像（稳定版）
        volumes:
          - /PATH_TO_YOUR_CONFIG:/config # 配置目录映射（需替换为实际路径）
          - /etc/localtime:/etc/localtime:ro # 同步主机时区（只读）
          - /run/dbus:/run/dbus:ro #挂载dbus服务（可选，如果计划使用蓝牙集成,则需要使用）
        restart: unless-stopped # 重启策略
        privileged: true # 特权模式（访问硬件）
        network_mode: host # 主机网络模式（设备发现必需）
  4. 启动容器
    1
    docker compose up -d
    运行该后打开http://<主机IP>:8123访问Home Assistant

更新

  1. 进入homeassistant的docker-compose.yml所在文件夹
  2. 重启服务，应用新镜像
    1
    docker compose up -d

删除

  1. 进入homeassistant的docker-compose.yml所在文件夹
  2. 停止并删除容器及关联网络
    1
    docker compose down
  3. 删除配置数据目录
    1
    2
    # 替换为你的实际配置目录（务必确认路径正确，避免误删！）
    sudo rm -rf /PATH_TO_YOUR_CONFIG
  4. 查看本地的 Home Assistant 镜像 ID
    1
    2
    docker images | grep home-assistant
    # 例如ghcr.io/home-assistant/home-assistant   stable   a1b2c3d4e5f6   2天前    1.2GB
  5. 删除镜像
    1
    docker rmi a1b2c3d4e5f6

HACS(第三方应用商城)

  1. 进入Home Assistant配置文件夹
    1
    cd /assistant/data  # Docker配置文件中/PATH_TO_YOUR_CONFIG的位置
  2. 创建并进入对应文件夹
    1
    mkdir custom_components/hacs && cd custom_components/hacs
  3. 下载hacs文件
    1
    wget https://github.com/hacs/integration/releases/download/2.0.5/hacs.zip
  4. 解压文件
    1
    2
    3
    unzip hacs.zip
    ## 如果没有安装解压工具unzip首先进行安装
    sudo apt update && sudo apt install unzip
  5. 重启 Home Assistant 容器
    1
    2
    3
    # 回到 docker-compose.yml 所在目录
    # 重启容器
    docker-compose restart homeassistant
  6. 打开 Home Assistant 后台设置->设备与服务->添加集成->搜索 HACS,首次添加会提示 “需要 GitHub 访问令牌”，按以下步骤获取