保姆级教程：在iStoreOS的Docker版Home Assistant里装HACS，从进容器到配加速一气呵成

零基础玩转iStoreOS：Home Assistant容器内安装HACS全流程指南

在智能家居领域，Home Assistant凭借其开源特性和强大的兼容性，已经成为DIY爱好者的首选平台。而HACS（Home Assistant Community Store）作为非官方的插件商店，能够极大扩展Home Assistant的功能边界。本文将手把手指导iStoreOS用户完成从零开始安装HACS的全过程，即使你从未接触过Docker也能轻松上手。

1. 准备工作与环境确认

在开始安装HACS之前，我们需要确保基础环境已经就绪。iStoreOS作为一款基于OpenWRT的路由器系统，其应用商店提供了便捷的Home Assistant容器安装方式。如果你尚未安装Home Assistant，请先在iStoreOS的应用商店中完成这一步骤。

确认Home Assistant容器正常运行的方法很简单：

docker ps

这条命令会列出当前运行的所有容器，你应该能看到类似如下的输出：

CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES a1b2c3d4e5f6 ghcr.io/home-assistant/… "/init" 2 days ago Up 2 days 0.0.0.0:8123->8123/tcp, :::8123->8123/tcp homeassistant

提示：如果容器状态不是"Up"，可能需要先启动容器：docker start homeassistant

2. 进入Home Assistant容器内部

由于HACS需要直接安装到Home Assistant的配置目录中，我们必须先进入容器内部进行操作。iStoreOS提供了多种方式访问系统终端：

• 通过SSH客户端（如PuTTY）连接路由器IP
• 使用iStoreOS网页界面的终端功能

进入系统后，执行以下命令进入容器：

docker exec -it homeassistant bash

成功进入后，命令提示符通常会发生变化，可能显示为类似root@a1b2c3d4e5f6:/#的格式。此时你已经处于Home Assistant容器的bash环境中。

常见问题排查：

• 如果提示"docker: command not found"，说明Docker服务未正确安装
• 如果提示容器不存在，检查容器名称是否正确（默认通常为homeassistant）
• 如果进入后无法执行基本命令，可能需要安装bash：docker exec -it homeassistant sh

3. HACS安装的两种方式

HACS官方提供了便捷的一键安装脚本，但由于网络环境差异，我们准备了两种安装方案。

3.1 直接安装（推荐网络通畅时使用）

对于网络连接稳定的用户，最简单的安装方式是执行：

wget -O - https://get.hacs.xyz | bash -

这个命令会：

1. 自动检测Home Assistant配置目录位置
2. 创建必要的custom_components文件夹
3. 下载最新版HACS并解压到正确位置
4. 验证Home Assistant版本兼容性

安装完成后，你会看到"Installation complete"的提示，此时需要重启Home Assistant使更改生效。

3.2 手动脚本安装（应对网络问题）

如果直接安装遇到困难，我们可以采用分步手动安装的方式。首先创建一个安装脚本：

touch hacs.sh && chmod +x hacs.sh

然后用文本编辑器（如vi或nano）将以下内容粘贴到hacs.sh中：

#!/bin/bash set -e # 颜色定义 RED_COLOR='\033[0;31m' GREEN_COLOR='\033[0;32m' YELLOW_COLOR='\033[1;33m' NO_COLOR='\033[0m' # 信息输出函数 function info () { echo -e "${GREEN_COLOR}INFO: $1${NO_COLOR}";} function warn () { echo -e "${YELLOW_COLOR}WARN: $1${NO_COLOR}";} function error () { echo -e "${RED_COLOR}ERROR: $1${NO_COLOR}"; exit 1;} # 检查必要命令 function checkRequirement () { if [ -z "$(command -v "$1")" ]; then error "'$1' is not installed" fi } checkRequirement "wget" checkRequirement "unzip" # 查找Home Assistant配置目录 declare haPath declare -a paths=( "$PWD" "$PWD/config" "/config" "$HOME/.homeassistant" "/usr/share/hassio/homeassistant" ) info "正在查找Home Assistant配置目录..." for path in "${paths[@]}"; do if [ -n "$haPath" ]; then break fi if [ -f "$path/.HA_VERSION" ]; then haPath="$path" fi done if [ -z "$haPath" ]; then error "找不到Home Assistant配置目录" fi info "找到配置目录: $haPath" cd "$haPath" || error "无法切换到目录 $haPath" # 创建custom_components目录（如果不存在） if [ ! -d "$haPath/custom_components" ]; then info "创建custom_components目录..." mkdir "$haPath/custom_components" fi info "切换到custom_components目录..." cd "$haPath/custom_components" || error "无法切换到custom_components目录" # 下载HACS info "下载HACS..." wget "https://github.com/hacs/integration/releases/latest/download/hacs.zip" # 清理旧版本（如果存在） if [ -d "$haPath/custom_components/hacs" ]; then warn "发现已存在的HACS目录，正在清理..." rm -R "$haPath/custom_components/hacs" fi # 创建HACS目录并解压 info "创建HACS目录..." mkdir "$haPath/custom_components/hacs" info "解压HACS..." unzip "$haPath/custom_components/hacs.zip" -d "$haPath/custom_components/hacs" >/dev/null 2>&1 # 版本验证 info "验证版本兼容性..." targetVersion=$(sed -n -e '/^MINIMUM_HA_VERSION/p' "$haPath/custom_components/hacs/const.py" | cut -d '"' -f 2) currentVersion=$(cat "$haPath/.HA_VERSION") info "当前版本: ${currentVersion}, 最低要求版本: ${targetVersion}" # 版本号比较逻辑（省略部分代码） info "删除HACS压缩包..." rm "$haPath/custom_components/hacs.zip" info "安装完成！" info "请重启Home Assistant后继续配置"

保存脚本后，执行以下命令运行安装：

./hacs.sh

注意：脚本执行过程中可能会暂停等待下载完成，请耐心等待直到看到"Installation complete"提示。

4. 重启Home Assistant并配置HACS

无论采用哪种安装方式，安装完成后都需要重启Home Assistant容器：

docker restart homeassistant

等待2-3分钟后，打开Home Assistant的Web界面（通常为http://你的路由器IP:8123），按照以下步骤完成HACS配置：

1. 点击左侧菜单栏的"配置"
2. 选择"设备与服务"
3. 点击右下角的"添加集成"
4. 搜索框中输入"HACS"并选择
5. 按照页面提示完成GitHub认证（需要GitHub账号）
6. 同意条款并提交

5. HACS基础使用与插件安装

成功添加HACS后，你会在左侧菜单栏看到新增的HACS选项。点击进入后，你可以浏览数千种社区开发的插件和主题。

安装新插件的基本流程：

1. 在HACS界面选择"集成"或"前端"等分类
2. 点击右下角的"浏览并下载存储库"
3. 搜索你需要的插件名称
4. 点击插件卡片进入详情页
5. 点击"下载"按钮
6. 下载完成后，按照页面提示重启Home Assistant
7. 在"配置">"设备与服务"中添加新集成的实例

对于高级用户，HACS还支持添加自定义存储库。在HACS设置中，你可以添加特定GitHub仓库地址来安装未收录在官方列表中的插件。

6. 常见问题与解决方案

Q: 安装过程中遇到"Connection timed out"错误怎么办？

A: 这通常是由于网络连接问题导致。你可以尝试：

• 更换网络环境后重试
• 使用手动脚本安装方式
• 分步执行脚本中的命令，找出具体失败点

Q: HACS界面显示"Integration not loaded"怎么办？

A: 这可能是因为：

1. 未正确重启Home Assistant - 尝试完全重启容器
2. 版本不兼容 - 检查Home Assistant版本是否符合HACS要求
3. 安装不完整 - 重新执行安装步骤

Q: 如何更新HACS到最新版本？

A: HACS通常会自动检测更新。你也可以：

1. 进入HACS设置
2. 点击"更新"选项卡
3. 查看可用更新并安装

Q: 安装插件后无法在集成列表中找到怎么办？

A: 请确保：

1. 已按照插件说明重启Home Assistant
2. 插件确实提供集成（有些插件仅提供前端资源）
3. 尝试清除浏览器缓存后重新登录

通过本文的详细指导，即使是完全没有Docker经验的用户也能顺利完成HACS的安装与配置。HACS将为你的Home Assistant打开一扇新的大门，让你能够轻松扩展系统功能，打造真正个性化的智能家居平台。