使用 HACS 和 Catppuccin 自定义界面

最近更新:

介绍

Home Assistant 是一款开源智能家居和 IoT 自动化平台。通过 HACS（Home Assistant Community Store），用户可以为 Home Assistant 安装社区维护的自定义集成、Dashboard 前端组件和主题，进一步扩展功能与调整界面风格。

在前面的教程中，我们已经在 reComputer RK3576 上部署了 Home Assistant Container，并使用 Modbus TCP 创建了温湿度监控 Dashboard。本教程将在同一设备上安装 HACS，使用 Catppuccin Theme 自定义 Home Assistant 的界面，并验证现有监控页面可以继续正常使用。

Home Assistant Container 不提供 Home Assistant OS / Supervised 的内置 Apps（旧称 Add-ons） 管理功能，但可以安装 HACS。HACS 不是 Apps 商店，也不会为 Container 版提供 Supervisor。本文通过 SSH 和 Docker 命令操作配置文件。

开始使用

硬件准备

  • reComputer RK3576 一台，已安装可正常联网的 ARM64 Linux 系统。
  • Windows、macOS 或 Linux 电脑一台，用于 SSH 和浏览器操作。
  • 可访问 GitHub、HACS 下载站点的网络环境。

软件准备

项目实测环境
开发板reComputer RK3576
操作系统Armbian（Debian 12 Bookworm，ARM64）
Home Assistant 安装方式Home Assistant Container（Docker）
Docker 容器名称homeassistant
配置目录/home/seeed/homeassistant/config/
HACS2.0.5
Catppuccin Themev2.1.3
Web 访问http://<RK3576_IP>:8123

请先完成前一篇《在 reComputer RK3576 上安装 Home Assistant》中的 Docker 安装和初始化操作。若需要演示温湿度 Dashboard，也可以先完成《在 reComputer RK3576 上使用 Home Assistant 集成 Modbus TCP》。本教程不要求必须安装 Modbus 集成。

配置路径 /home/seeed/homeassistant/config/ 对应示例用户 seeed；若用户名或配置挂载目录不同，请使用实际路径。

在 RK3576 终端检查 Home Assistant 容器：

bash
sudo docker ps --filter name=homeassistant

应能看到名称为 homeassistant 的容器处于 Up 状态。

可选：备份当前配置

在添加自定义组件前，建议备份已有配置和 Dashboard 数据。以下命令会短暂停止 Home Assistant，以便获取一致的文件备份：

bash
sudo docker stop homeassistant
sudo tar -czf "$HOME/homeassistant-config-backup.tar.gz" -C "$HOME/homeassistant" config
sudo docker start homeassistant
ls -lh "$HOME/homeassistant-config-backup.tar.gz"

该压缩包保存的是 Home Assistant 配置目录，不包含存放在其他位置的 Modbus 模拟器脚本等独立文件。请将备份复制到电脑或外部存储设备，不要只保存在 RK3576 上。如果使用 Home Assistant WebUI 的加密备份，另需安全保存其备份加密密钥。

在 Home Assistant Container 中安装 HACS

步骤 1：进入 Home Assistant Docker 容器

通过 SSH 登录 RK3576，运行：

bash
sudo docker exec -it homeassistant bash

进入后可以通过以下命令确认配置路径：

bash
pwd

当前环境通常位于 /config。

步骤 2：运行 HACS 官方安装脚本

在容器内部执行：

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

安装脚本会将 HACS 下载到 Home Assistant 的自定义集成目录。该命令来自 HACS 官方 Container 安装说明；执行前请确认下载域名与网络环境可信。

安装完成后，检查文件是否存在：

bash
ls -l /config/custom_components/hacs/manifest.json

如果能够看到 manifest.json，说明 HACS 集成文件已经写入配置目录。文件存在并不等于 WebUI 授权完成，还需要继续配置 HACS 集成。

步骤 3：重启 Home Assistant

退出容器：

bash
exit

在 RK3576 主机终端执行：

bash
sudo docker restart homeassistant

等 Home Assistant 恢复运行后，在浏览器访问：

text
http://<RK3576_IP>:8123

在 WebUI 中配置 HACS

步骤 4：添加 HACS 集成

  1. 打开 Home Assistant，进入 Settings → Devices & services。
  2. 点击页面右下角的 Add integration。
  3. 搜索 HACS 并选择对应集成。如果没有出现 HACS，请先强制刷新浏览器页面，并确认已重启容器。
  4. 在首次出现的 HACS 确认窗口中，阅读有关日志、无 Add-ons、第三方组件兼容性及故障处理的四项说明，理解后勾选确认并点击 Submit。

添加 HACS 集成

步骤 5：通过 GitHub 完成授权

HACS 通过 GitHub 的设备授权流程连接社区仓库：

  1. Home Assistant 弹窗显示 Waiting for device activation，以及一组 XXXX-XXXX 格式的设备授权码。
  2. 保持该弹窗打开，在浏览器另开页面：https://github.com/login/device。
  3. 登录自己的 GitHub 账号，输入弹窗中的授权码，点击 Continue。
  4. 按 GitHub 页面提示选择 Authorize HACS。
  5. 返回 Home Assistant，等待授权完成。如果出现地区选择等收尾选项，按提示完成。

安全提示： 授权码仅用于当前设备授权，请勿将授权码、访问令牌或备份密钥发布到 Wiki 截图中。授权码过期时，可重新开始 HACS 添加流程获取新码。

通过 GitHub 完成 HACS 授权

步骤 6：确认 HACS 已成功安装

进入 Settings → Devices & services → Integrations → HACS，可以看到已配置的 HACS 集成。

配置完成后，在 HACS 页面可以浏览社区仓库和已下载的组件。

确认 HACS 集成安装成功

此时刷新 Home Assistant 页面，左侧导航栏通常会出现 HACS 入口。

使用 HACS 安装 Catppuccin 主题

步骤 7：检查主题配置

通过 SSH 在 RK3576 主机中执行：

bash
sudo nano /home/seeed/homeassistant/config/configuration.yaml

确认配置文件内已有以下内容：

yaml
frontend:
  themes: !include_dir_merge_named themes

如果文件中已存在 frontend:，不要重复创建第二个 frontend:，应当在现有 frontend: 下添加或保留 themes: 配置。此前通过 Home Assistant Container 安装教程创建的配置可能已经包含这段内容。

保存后，可运行官方配置检查命令：

bash
sudo docker exec homeassistant python -m homeassistant --script check_config --config /config

只有在首次添加或更改 configuration.yaml 的主题目录配置时才需要重启 Home Assistant：

bash
sudo docker restart homeassistant

步骤 8：在 HACS 下载 Catppuccin Theme

  1. 在 Home Assistant 左侧导航栏点击 HACS。
  2. 搜索 Catppuccin，选择 Catppuccin Theme。
  3. 点击 Download，打开版本确认窗口。
  4. 保持默认推荐版本（实测为 v2.1.3），点击右下角 DOWNLOAD。

本次实测中，下载界面显示主题存储路径为：

text
/config/themes/catppuccin/catppuccin.yaml

通过 HACS 下载 Catppuccin Theme

提示： “Need a different version?” 用于选择其他版本，首次安装通常无需手动选择旧版本。

步骤 9：重新加载主题

下载完成后，进入 Home Assistant：

Settings → Tools → Actions

找到并执行动作：

text
frontend.reload_themes

这样可在不重启容器的情况下重新加载已安装的主题。若界面没有显示该动作，也可以通过 sudo docker restart homeassistant 重启后再刷新浏览器。

步骤 10：选择 Catppuccin Mocha 主题

  1. 点击 Home Assistant 左下角用户头像进入个人设置（Profile）。
  2. 找到 Theme 部分，点击主题下拉菜单。
  3. 在列表中选择 Catppuccin Mocha。
  4. 选中后，界面通常会立即切换为深色主题。

主题选项的风格说明：

主题风格
Catppuccin Latte浅色，适合明亮环境
Catppuccin Frappé柔和灰蓝深色
Catppuccin Macchiato深灰蓝色
Catppuccin Mocha深色紫蓝风格，适合监控大屏展示
Catppuccin Auto Latte Mocha随明暗模式自动切换对应风格

运行结果

RK3576 实际应用 Catppuccin Mocha 后，已有的 Modbus TCP 监控 Dashboard 切换为深色配色，温湿度 Gauge 和历史曲线仍正常显示。

reComputer RK3576 上的 Catppuccin Mocha 深色主题

如果已经完成之前的 Modbus TCP 教程，可以点击左侧 RK3576 Modbus Monitoring，在新主题下继续查看温湿度 Gauge 和历史曲线。主题切换只改变前端视觉样式，不会修改 Modbus 寄存器地址或传感器数据采集逻辑。

下面的演示展示主题切换前已创建的 Modbus TCP Dashboard，用作前置功能参考，并非深色主题的展示。

主题切换前的 Modbus TCP 监控演示

常见问题

下载了主题，但个人设置中没有出现 Catppuccin

  1. 确认 configuration.yaml 包含 frontend: themes: !include_dir_merge_named themes 的正确 YAML 缩进。
  2. 确认 /config/themes/catppuccin/catppuccin.yaml 已存在（路径以 HACS 实际显示为准）。
  3. 执行 frontend.reload_themes，必要时重启容器并刷新浏览器。

总结

本教程在 reComputer RK3576 的 Home Assistant Container 环境中完成了 HACS 安装、GitHub 授权、社区主题下载和深色主题切换。这展示了 RK3576 不仅可以作为 Modbus TCP 数据采集与监控节点，还能够运行具备可扩展 Web 界面的本地 AIoT 管理平台。

如果需要进一步扩展，可以使用 HACS 安装与当前 Home Assistant 版本兼容的 Dashboard 自定义卡片，或通过 Home Assistant 原生集成添加智能灯光、摄像头等设备。第三方组件应评估维护状态和兼容性。

参考资料