macOS 使用 Docker 安装 Home Assistant 智能家居平台

Home Assistant 是一个开源的智能家居平台，支持数千种智能设备和服务的集成。本文介绍如何在 macOS 上使用 Docker 快速部署 Home Assistant。

前置条件

macOS 系统
已安装 Docker Desktop

检查 Docker 是否正常运行：

docker info

安装步骤

1. 创建配置目录

首先创建一个目录用于存放 Home Assistant 的配置文件：

mkdir -p ~/homeassistant/config

2. 拉取镜像

从 GitHub Container Registry 拉取官方镜像：

docker pull ghcr.io/home-assistant/home-assistant:stable

镜像大小约 1.5GB，下载时间取决于网络速度。

3. 启动容器

使用以下命令启动 Home Assistant 容器：

docker run -d \
  --name homeassistant \
  --restart=unless-stopped \
  -e TZ=Asia/Shanghai \
  -v ~/homeassistant/config:/config \
  -p 8123:8123 \
  ghcr.io/home-assistant/home-assistant:stable

参数说明：

-d: 后台运行
--name homeassistant: 容器名称
--restart=unless-stopped: 自动重启策略
-e TZ=Asia/Shanghai: 设置时区（根据你的位置修改）
-v ~/homeassistant/config:/config: 挂载配置目录
-p 8123:8123: 映射端口

> 注意：如果需要访问外网（如 GitHub），可能需要配置代理：

> -e http_proxy=http://host.docker.internal:7890 \
> -e https_proxy=http://host.docker.internal:7890 \
>

4. 验证运行状态

docker ps --filter name=homeassistant

看到 Up 状态表示容器已成功运行。

访问 Home Assistant

打开浏览器访问：

http://localhost:8123

首次访问需要等待 1-2 分钟让系统完成初始化。

初始配置

首次访问时需要完成以下设置：

创建管理员账户 - 设置用户名和密码
设置家庭位置 - 用于天气预报、日出日落计算等
发现设备 - Home Assistant 会自动扫描局域网内的智能设备
添加集成 - 可以手动添加各种智能设备和服务的集成

常用管理命令

查看实时日志
docker logs -f homeassistant
重启容器
docker restart homeassistant
停止容器
docker stop homeassistant
启动容器
docker start homeassistant
更新到最新版本
docker pull ghcr.io/home-assistant/home-assistant:stable
docker stop homeassistant
docker rm homeassistant
然后重新运行 docker run 命令

配置文件

所有配置文件保存在挂载的 config 目录中，主要文件包括：

configuration.yaml - 主配置文件
automations.yaml - 自动化规则
scripts.yaml - 脚本配置
scenes.yaml - 场景配置

常见问题

端口被占用

如果 8123 端口被占用，可以修改映射端口：

-p 8124:8123

然后通过 http://localhost:8124 访问。

容器名称冲突

如果提示容器名称已存在，先删除旧容器：

docker rm -f homeassistant

时区不正确

确保 -e TZ=Asia/Shanghai 参数正确设置，或根据你的位置修改时区。

安装 HACS (Home Assistant Community Store)

HACS 是 Home Assistant 的社区商店，可以方便地安装第三方集成、主题、Lovelace 卡片等。

1. 创建 custom_components 目录

mkdir -p ~/homeassistant/config/custom_components

2. 下载并安装 HACS

cd ~/homeassistant/config/custom_components
curl -L -o hacs.zip https://github.com/hacs/integration/releases/latest/download/hacs.zip
unzip -o hacs.zip -d hacs
rm hacs.zip

3. 重启 Home Assistant

docker restart homeassistant

4. 配置 HACS

打开 Home Assistant Web 界面
进入设置 → 设备与服务 → 添加集成
搜索 HACS 并点击添加
按照提示使用 GitHub 账户授权（需要 GitHub 账户）
授权完成后即可使用 HACS

5. 使用 HACS

配置完成后，在侧边栏会出现 HACS 入口，可以浏览和安装：

集成 - 第三方设备和服务集成
前端 - Lovelace 自定义卡片和主题
自动化 - 蓝图和自动化模板

HACS 常用第三方集成推荐

Xiaomi Miot Auto - 小米设备本地化控制
Sonoff LAN - Sonoff 设备局域网控制
LocalTuya - 涂鸦设备本地控制
Mushroom Cards - 美观的 Lovelace 卡片

参考链接

[Home Assistant 官网](https://www.home-assistant.io/)
[Home Assistant 文档](https://www.home-assistant.io/docs/)
[Home Assistant 集成列表](https://www.home-assistant.io/integrations/)
[HACS 官网](https://hacs.xyz/)
[HACS GitHub](https://github.com/hacs/integration)