前言
在智能家居系统的管理与控制领域，CasaOS 和 Home Assistant 都是非常受欢迎的开源解决方案。
本文将介绍如何在 Linux 系统中安装 CasaOS，并通过 CasaOS 部署 Home Assistant，同时安装 HACS 极速版（Home Assistant Community Store）。本教程尤其适合国内网络环境下的用户参考。
一、安装 CasaOS
1.1 系统要求
- 操作系统：Linux，推荐使用 Ubuntu 20.04 或更高版本
- 内存：至少 2 GB
- 存储空间：至少 10 GB
- 网络环境：稳定的互联网连接
- 用户权限：具备
sudo或 root 权限
1.2 更新系统软件包
在终端中执行以下命令：
sudo apt update && sudo apt upgrade -y1.3 下载并安装 CasaOS
执行 CasaOS 官方一键安装命令：
curl -fsSL https://get.casaos.io | sudo bash安装脚本会自动下载 CasaOS，并安装运行所需的相关组件和依赖。
1.4 启动 CasaOS
安装完成后，可以执行以下命令启动 CasaOS 服务：
sudo systemctl start casaos设置 CasaOS 开机自动启动：
sudo systemctl enable casaos查看 CasaOS 服务运行状态：
sudo systemctl status casaos1.5 访问 CasaOS
打开浏览器，在地址栏中输入：
http://<服务器IP地址>例如，服务器的局域网 IP 地址为 192.168.1.100，则访问：
http://192.168.1.100首次访问时，根据页面提示创建 CasaOS 管理员账户，并完成初始化设置。
二、在 CasaOS 中部署 Home Assistant
CasaOS 支持通过应用商店一键安装 Home Assistant，也可以手动创建 Docker 容器。
建议优先使用 CasaOS 应用商店进行安装。
2.1 通过 CasaOS 应用商店安装
- 登录 CasaOS Web 管理界面。
- 打开左侧菜单中的“应用商店”。
- 搜索：
Home Assistant- 找到 Home Assistant 后，点击“安装”。
- 等待镜像下载和容器创建完成。
安装完成后，可以直接从 CasaOS 首页打开 Home Assistant。
2.2 手动部署 Home Assistant
如果已经通过 CasaOS 应用商店完成安装，可以跳过本节。
创建 Home Assistant 配置目录
执行以下命令：
mkdir -p ~/homeassistant/config创建并运行 Home Assistant 容器
sudo docker run -d \
--name homeassistant \
--privileged \
--restart unless-stopped \
-e TZ=Asia/Shanghai \
-v ~/homeassistant/config:/config \
--network=host \
homeassistant/home-assistant:latest主要参数说明：
| 参数 | 作用 |
|---|---|
--name homeassistant | 将容器名称设置为 homeassistant |
--privileged | 为容器提供访问部分硬件设备所需的权限 |
--restart unless-stopped | 设备重启后自动启动容器 |
-e TZ=Asia/Shanghai | 将时区设置为中国标准时间 |
-v ~/homeassistant/config:/config | 将配置文件保存到宿主机目录 |
--network=host | 使用宿主机网络模式 |
三、启动并访问 Home Assistant
3.1 检查容器状态
执行以下命令：
sudo docker ps -a | grep homeassistant如果容器正在正常运行，应当可以看到类似以下状态：
Up也可以查看 Home Assistant 的运行日志：
sudo docker logs -f homeassistant按下 Ctrl + C 可以退出日志查看。
3.2 访问 Home Assistant
在浏览器中打开：
http://<服务器IP地址>:8123例如：
http://192.168.1.100:8123首次启动 Home Assistant 可能需要等待几分钟。
进入页面后，根据向导完成以下设置：
- 创建管理员账户。
- 设置家庭名称。
- 设置所在地区和时区。
- 选择是否共享匿名统计信息。
- 添加自动发现的智能家居设备。
四、安装 HACS 极速版
4.1 安装要求
安装 HACS 极速版前，需要确保：
- Home Assistant 已安装并正常运行
- 可以访问 Home Assistant 的配置目录
- 宿主机可以正常访问互联网
- 已安装
wget和bash - 当前用户具有配置目录的写入权限
4.2 找到 Home Assistant 配置目录
如果使用 CasaOS 应用商店安装 Home Assistant，可以按照以下步骤查找配置目录：
- 登录 CasaOS。
- 找到 Home Assistant 应用。
- 点击应用右上角的设置按钮。
- 查看容器的卷映射或存储目录。
- 找到映射到容器
/config的宿主机目录。
如果使用本文中的 Docker 命令手动安装，配置目录通常为：
~/homeassistant/config4.3 进入配置目录
例如，配置目录为 ~/homeassistant/config，执行：
cd ~/homeassistant/config确认当前目录：
pwd4.4 执行 HACS 极速版安装命令
在 Home Assistant 配置目录中执行：
wget -O - https://get.hacs.vip | bash -安装脚本会自动下载相关文件，并将其写入 Home Assistant 的 custom_components 目录。
4.5 不同安装方式的操作说明
HAOS、Hass.io 或 Supervisor 版本
如果使用的是 Home Assistant OS、Hass.io 或 Supervisor 版本，可以通过以下方式执行安装命令：
- Terminal & SSH 加载项
- SSH 终端
- 宿主机终端
Home Assistant Core 或 Docker 版本
如果使用的是 Home Assistant Core 或 Docker 版本，需要先通过 SSH 登录宿主机，然后进入 Home Assistant 的配置目录，再执行安装命令。
例如：
cd ~/homeassistant/config
wget -O - https://get.hacs.vip | bash -五、重启 Home Assistant
安装完成后，需要重启 Home Assistant。
如果容器名称为 homeassistant，执行：
sudo docker restart homeassistant也可以在 CasaOS 管理界面中找到 Home Assistant 应用，然后点击“重启”。
等待几分钟后，再次访问：
http://<服务器IP地址>:8123六、在 Home Assistant 中添加 HACS
重启 Home Assistant 后，按照以下步骤添加 HACS：
- 登录 Home Assistant。
- 点击左侧菜单中的“设置”。
- 进入“设备与服务”。
- 点击右下角的“添加集成”。
- 搜索：
HACS- 选择 HACS。
- 根据页面向导完成授权和初始化配置。
如果搜索不到 HACS，可以尝试：
- 确认 Home Assistant 已彻底重启。
- 清除浏览器缓存。
- 使用无痕模式重新登录。
- 检查
custom_components/hacs目录是否存在。 - 查看 Home Assistant 日志中是否存在相关报错。
七、HACS 极速版简介
HACS 是 Home Assistant 常用的第三方集成与前端资源管理工具，可以用于安装：
- 第三方集成
- 前端主题
- Lovelace 卡片
- 自动化组件
- 自定义插件
由于部分国内网络环境访问 GitHub 的速度较慢，HACS 极速版通过镜像或加速服务改善相关资源的下载体验。
需要注意的是，镜像服务和加速地址可能会发生变化。如果安装或下载失败，应以项目最新说明为准。
八、常见问题
8.1 CasaOS 无法启动
首先查看 CasaOS 服务状态：
sudo systemctl status casaos尝试重新启动服务：
sudo systemctl restart casaos如果仍然无法启动，可以检查：
- 系统依赖是否安装完整
- Docker 服务是否正常
- 磁盘空间是否充足
- 系统网络是否正常
- 相关端口是否被其他程序占用
查看 Docker 状态：
sudo systemctl status docker启动 Docker：
sudo systemctl start docker设置 Docker 开机自动启动：
sudo systemctl enable docker8.2 Home Assistant 无法访问
检查容器是否正在运行：
sudo docker ps -a | grep homeassistant如果容器已经停止，可以尝试启动：
sudo docker start homeassistant查看容器日志：
sudo docker logs --tail 100 homeassistant同时检查：
- 服务器 IP 地址是否正确
- 端口
8123是否被占用 - 防火墙是否放行
8123端口 - Home Assistant 是否仍在进行首次初始化
- 容器是否因为配置错误而反复重启
如果使用 Ubuntu 防火墙，可以放行端口：
sudo ufw allow 8123/tcp8.3 HACS 极速版安装失败
首先确认已经进入 Home Assistant 配置目录：
pwd然后确认目录是否具有写入权限：
ls -la检查 wget 是否已经安装：
wget --version如果未安装，可以执行：
sudo apt update
sudo apt install wget -y重新执行安装命令：
wget -O - https://get.hacs.vip | bash -如果仍然失败，可以检查：
- 网络是否能够访问安装地址
- 配置目录是否正确
- 当前用户是否具有写入权限
- Home Assistant 是否已完整停止或重启
custom_components目录是否创建成功
8.4 安装后搜索不到 HACS
检查 HACS 目录是否存在：
ls -la ~/homeassistant/config/custom_components/hacs如果使用的是其他配置目录，请将命令中的路径替换为实际路径。
然后重启 Home Assistant：
sudo docker restart homeassistant重新登录 Home Assistant，并在“设置”→“设备与服务”→“添加集成”中搜索 HACS。
8.5 Home Assistant 容器不断重启
查看容器状态：
sudo docker ps -a查看详细日志：
sudo docker logs --tail 200 homeassistant常见原因包括：
- 配置文件格式错误
- 配置目录权限不足
- 磁盘空间不足
- Docker 镜像下载不完整
- 第三方集成不兼容
- 宿主机时间或时区异常
如果问题出现在安装 HACS 后，可以暂时移除 HACS 目录进行排查：
mv ~/homeassistant/config/custom_components/hacs \
~/homeassistant/config/custom_components/hacs_backup然后重新启动 Home Assistant：
sudo docker restart homeassistant九、结语
通过以上步骤，你已经完成了以下操作：
- 在 Linux 系统中安装 CasaOS。
- 通过 CasaOS 或 Docker 部署 Home Assistant。
- 找到 Home Assistant 配置目录。
- 安装并配置 HACS 极速版。
- 完成 Home Assistant 的基础访问与故障排查。
CasaOS 提供了直观的 Docker 应用管理界面，Home Assistant 则能够集中管理各类智能家居设备。结合 HACS 后，还可以安装更多第三方集成、主题和前端卡片，进一步扩展智能家居系统的功能。