Docker Compose 部署 Home Assistant + HACS 商店安装指南

相关链接

• Home Assistant 官网：https://www.home-assistant.io
• HACS 官网：https://hacs.xyz
• Home Assistant 文档：https://www.home-assistant.io/docs/

为什么选 Home Assistant

如果你折腾智能家居，Home Assistant（简称 HA）几乎是绕不开的平台：

• 统一管理：支持 2000+ 设备品牌，把米家、HomeKit、涂鸦、飞利浦 Hue 等全拢到一起
• 本地运行：数据不经过云端，响应快、隐私安全
• 自动化引擎：可视化编排自动化，比各品牌 App 强得多
• 仪表盘：自定义卡片式 UI，一个页面看全家设备状态
• 社区生态：HACS 商商店里有海量自定义组件和主题

简单说：HA 是智能家居的"中枢大脑"。

第一步：Docker Compose 部署

创建项目目录

1
2

mkdir -p ~/homeassistant/config
cd ~/homeassistant

编写 docker-compose.yml

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

version: "3.8"

services:
  homeassistant:
    image: ghcr.io/home-assistant/home-assistant:stable
    container_name: homeassistant
    restart: unless-stopped
    network_mode: host
    volumes:
      - ./config:/config
    environment:
      - TZ=Asia/Shanghai

说明：

• network_mode: host：HA 需要用 host 网络来发现局域网设备（米家、HomeKit、Chromecast 等），用桥接模式会发现不了设备
• 数据持久化：./config 挂载到容器内，所有配置、插件、数据库都在这里面
• 时区：设为 Asia/Shanghai，确保自动化时间触发正确
• 重启策略：异常退出自动重启

国内拉取 ghcr.io 镜像可能较慢，可在 OrbStack 中配置镜像加速，或直接 docker pull 时加上代理。

启动服务

1

docker compose up -d

等待约 1-2 分钟，HA 首次启动需要初始化数据库和安装依赖。查看日志确认启动完成：

1

docker logs -f homeassistant

看到 Home Assistant initialized 就说明启动成功了。

第二步：初始设置

访问 Web 界面

浏览器打开：

1

http://localhost:8123

如果是远程服务器，把 localhost 换成服务器 IP。首次加载可能需要 1-2 分钟。

准备阶段

首次访问会看到 “Preparing Home Assistant” 页面，等待初始化完成。

创建账户

1. 点击 “Create my smart home”（创建我的智能家居）
2. 填写管理员信息：
   • Name：你的名字（如 Dick）
   • Username：登录用户名
   • Password：登录密码（建议 12 位以上）
3. 点击 “Create Account”

设置位置

• 输入你的城市名或直接在地图上点击定位
• 这会影响天气、日出日落等实体的数据
• Unit System：选 Metric（公制）
• Time Zone：确认是 Asia/Shanghai

完成设置

1. 勾选是否分享匿名统计数据（随意）
2. 点击 “Finish” 进入主界面

此时你已经能看到 HA 的仪表盘了。

第三步：安装 HACS 社区商店

HACS（Home Assistant Community Store）是一个第三方商店，可以浏览和安装社区开发的：

• 自定义组件（Integrations）：新增设备支持、功能增强
• 前端卡片（Frontend）：自定义仪表盘卡片、主题
• 自动化插件（AppDaemon / Python Scripts）

前提条件

• Home Assistant 已完成初始设置
• 有一个 GitHub 账号（HACS 依赖 GitHub API）

方法一：一键脚本安装（推荐）

SSH 登录服务器，执行：

1

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

等待脚本执行完成，看到 HACS has been installed 即可。

方法二：手动安装

如果一键脚本失败，可以手动操作：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

# 进入 HA 配置目录
cd ~/homeassistant/config

# 下载 HACS 最新版本
wget https://github.com/hacs/integration/releases/latest/download/hacs.zip

# 解压到 custom_components 目录
mkdir -p custom_components/hacs
unzip hacs.zip -d custom_components/hacs

# 清理
rm hacs.zip

重启 Home Assistant

安装完成后必须重启：

1

docker restart homeassistant

或在 HA 界面中：设置 → 系统 → 右上角 ⋯ → 重新启动

配置 HACS

1. 进入 设置 → 设备与服务 → 添加集成
2. 搜索 HACS，点击选中
3. 勾选所有选项（AppDaemon、NetDaemon、自定义组件、模板、主题），点击提交
4. 弹出 GitHub 授权页面：
   • 点击链接打开 GitHub
   • 输入页面上显示的授权码
   • 授权 HACS 访问你的 GitHub
5. 授权成功后回到 HA，HACS 配置完成

使用 HACS

配置完成后，左侧菜单会出现 HACS 入口：

• 下载：浏览和安装社区组件、卡片、主题
• 集成：管理已安装的自定义集成
• 前端：管理卡片和主题
• 关于：查看 HACS 版本信息

第一次打开 HACS 会花几分钟注册所有仓库，之后就正常了。

第四步：推荐安装的 HACS 插件

装好 HACS 后，这几个插件强烈推荐：

安装方式：HACS → 下载 → 搜索插件名 → 点击下载 → 重启 HA（仅集成需要重启，卡片和主题不需要）

常见问题

容器启动后无法访问 8123 端口

1
2
3
4
5
6

# 检查容器状态
docker ps -a
# 查看日志
docker logs homeassistant
# 检查端口占用
lsof -i :8123

发现不了局域网设备

• 确认 network_mode: host 已设置
• 检查 HA 所在机器和设备在同一网段
• 部分设备（如米家蓝牙）需要蓝牙支持，Docker 中蓝牙透传较复杂，建议用蓝牙网关

HACS 授权失败

• 确保网络能访问 GitHub（可能需要代理）
• 尝试重新配置：设置 → 设备与服务 → HACS → 配置 → 重新授权

配置文件在哪

所有配置都在 ~/homeassistant/config/ 目录下：

1
2
3
4
5
6
7

config/
├── configuration.yaml   # 主配置文件
├── automations.yaml     # 自动化
├── scenes.yaml          # 场景
├── scripts.yaml         # 脚本
├── custom_components/   # 自定义组件（HACS 安装的）
└── www/                 # 前端资源

更新 Home Assistant

1
2

docker compose pull
docker compose up -d

更新前建议备份 config 目录。

总结

Home Assistant + HACS 的组合是智能家居玩家必备，Docker 部署方便迁移和备份。配合米家、HomeKit 等集成，一个平台管理全屋设备，自动化的上限取决于你的想象力。