Hass-Panel - 开源智能家居控制面板

news2025/5/23 3:48:21

文章目录

- ▎项目介绍：
- 预览图
- ▎主要特性
- 安装部署
- - Docker方式正式版
  - Home Assistant Addon方式
  - 详细安装方式
  - - 1. Home Assistant 插件安装（推荐）
    - 2. Docker 安装
    - 命令功能说明：
    - 3. Docker Compose 安装
    - 升级说明
    - Docker Compose 版本升级
- 功能配置
- - 支持的卡片类型
  - 卡片管理
- 开发
- 使用指南
- - 系统概述
  - - 1. 初始化
    - 2. 系统首页
    - 3. 系统配置
- 常见问题
- 关注我的CDDN博客

▎项目介绍：

一个智能家居控制面板，它使用 Home Assistant 的 Websocket API，并支持作为 Home Assistant 操作系统的插件部署。
丰富的设备支持：灯光控制、空调控制、窗帘控制、传感器监控、摄像头查看、场景控制。

预览图

在这里插入图片描述

▎主要特性

📱 响应式设计，支持移动端和桌面端
🔧 高度可配置，自由拖拽布局
🚀 PWA支持，可安装到桌面
🎨 美观的用户界面：

支持亮色/暗色/跟随系统三种主题模式
毛玻璃效果卡片设计
主题色滚动条
优化的移动端视图

👥 多用户管理系统，支持JWT认证
🔐 安全的密码加密存储
🎥 强大的摄像头支持：

WebRTC/ONVIF/RTSP协议支持
HLS流自动检测和切换
优化的视频流播放体验

🔌 丰富的设备支持:

灯光控制
空调控制
窗帘控制
传感器监控
摄像头查看
场景控制
用电量统计
插座控制
服务器监控
PVE虚拟机监控
通用实体卡片（支持自定义配置和分组显示）

安装部署

系统使用 SQLite 数据库进行配置存储
首次使用需要完成系统初始化流程
摄像头功能需要正确配置 ONVIF/RTSP 地址

Docker方式正式版

docker run \
  --name hass-panel \
  --restart unless-stopped \
  --network host \
  -v ./data/:/config/hass-panel \
  -d \
  ghcr.io/mrtian2016/hass-panel:latest

安装完成后直接打开机器的5123端口即可使用

Home Assistant Addon方式

https://my.home-assistant.io/redirect/supervisor_add_addon_repository/?repository_url=https%3A%2F%2Fkkgithub.com%2Fmrtian2016%2Fhass-panel

或者手动添加：

在Home Assistant的侧边栏中，点击"配置" -> “加载项” -> “加载项商店”
点击右上角的三个点，选择"存储库"
添加存储库地址：https://kkgithub.com/mrtian2016/hass-panel
点击"添加"并刷新页面
在加载项商店中找到并安装"Hass Panel"
启动后即可在侧边栏访问

详细安装方式

1. Home Assistant 插件安装（推荐）

方式一：一键添加（推荐）#
点击下面的按钮将 Hass-Panel 添加到您的 Home Assistant：

添加到Home Assistant

方式二：手动添加#
在 Home Assistant 的侧边栏中，点击"配置" -> “加载项” -> “加载项商店”
点击右上角的三个点，选择"存储库"
添加存储库地址：https://github.com/mrtian2016/hass-panel
点击"添加"并刷新页面
在加载项商店中找到并安装"Hass Panel"
启动后即可在侧边栏访问

2. Docker 安装

使用以下命令启动 Hass-Panel：

docker run \
  --name hass-panel \
  --restart unless-stopped \
  --network host \
  -v ./data/:/config/hass-panel \
  -d \
  registry.cn-hangzhou.aliyuncs.com/hass-panel/hass-panel:latest

命令功能说明：

创建一个名为 hass-panel 的容器
设置容器自动重启
将配置文件保存在主机的 ./data/ 目录
使用最新版本的 Hass-Panel 镜像
访问地址：http://your-docker-host:5123

3. Docker Compose 安装

如果您更喜欢使用 Docker Compose 来管理容器，可以按照以下步骤操作：

创建一个 docker-compose.yml 文件，内容如下：

version: '3'
services:
  hass-panel:
    container_name: hass-panel
    image: registry.cn-hangzhou.aliyuncs.com/hass-panel/hass-panel:latest
    restart: unless-stopped
    network_mode: host
    volumes:
      - ./data:/config/hass-panel

在 docker-compose.yml 文件所在目录运行以下命令启动服务：

docker-compose up -d

这将创建并启动 Hass-Panel 容器，配置与 Docker 安装方式相同。

访问地址：http://your-docker-host:5123

升级说明

Home Assistant 插件版本升级#
在 Home Assistant 的加载项商店中找到 Hass Panel
点击"更新"按钮
等待更新完成后重启插件
Docker 版本升级#

拉取最新镜像

docker pull registry.cn-hangzhou.aliyuncs.com/hass-panel/hass-panel:latest

停止并删除旧容器

docker stop hass-panel
docker rm hass-panel

使用新镜像重新创建容器

docker run \
  --name hass-panel \
  --restart unless-stopped \
  -v ./data/:/config/hass-panel \
  -d \
  registry.cn-hangzhou.aliyuncs.com/hass-panel/hass-panel:latest

Docker Compose 版本升级

在 docker-compose.yml 文件所在目录运行以下命令升级服务：

-拉取最新镜像并重新创建容器

docker-compose pull
docker-compose up -d

功能配置

支持的卡片类型

时间卡片 (TimeCard)
天气卡片 (WeatherCard) - 支持AQI国际化和风向指示
灯光状态卡片 (LightStatusCard)
房间灯光概览卡片 (LightOverviewCard)
传感器卡片 (SensorCard)
媒体播放器卡片 (MediaPlayerCard)
大型媒体播放器卡片 (MaxPlayerCard)
窗帘控制卡片 (CurtainCard)
电量监控卡片 (ElectricityCard) - 优化的电压、电流和功率显示
路由器监控卡片 (RouterCard) - 支持运行时间显示
NAS监控卡片 (NASCard) - 改进的存储信息显示
摄像头卡片 (CameraCard) - 支持多种视频流协议
空调控制卡片 (ClimateCard)
人体传感器卡片 (MotionCard)
净水器卡片 (WaterPurifierCard)
光照传感器卡片 (IlluminanceCard)
快捷指令面板 (ScriptPanel)
插座状态卡片 (SocketCard)
通用实体卡片 (UniversalCard) - 支持自定义实体配置和分组显示
PVE监控卡片 (PVECard) - 虚拟机监控
服务器监控卡片 (ServerCard)
每日一言卡片 (DailyQuoteCard)
家庭人员状态卡片 (FamilyCard)

卡片管理

支持显示/隐藏控制
支持拖拽排序
支持自定义大小(桌面端)
支持添加/编辑/删除卡片（带确认保护）
支持自定义布局
支持响应式布局
支持实体智能搜索和自动补全

开发

# 安装依赖
npm install

# 启动开发服务器
npm start

# 构建生产版本
npm run build

使用指南

系统概述

本系统是一个基于 Home Assistant 的可视化控制面板，提供了丰富的卡片组件和直观的操作界面，帮助您更便捷地管理智能家居设备。主要功能包括设备状态监控、智能控制、自动化管理等。

1. 初始化

Home Assistant 面板初始化页面，包含管理员账号设置和 Home Assistant 连接配置
在这里插入图片描述

在初始化页面中，您需要填写以下信息：

管理员用户名：设置您的管理员账号用户名
管理员密码：设置一个安全的管理员密码
确认密码：再次输入管理员密码进行确认
HomeAssistant地址：输入您的 Home Assistant 实例地址
格式示例：http://homeassistant.local:8123
请确保地址可以正确访问到您的 Home Assistant 实例
HomeAssistant Token（可选）：
如果您的 Home Assistant 启用了长期访问令牌认证，请在此处输入
如果不输入则登录成功后会自动跳转至 Home Assistant 登录页面获得授权
填写完所有必要信息后，点击"初始化系统"按钮完成设置。系统将使用这些信息创建管理员账号并跳转至登录页面。

2. 系统首页

登录成功后会进入系统首页。

系统首页
在这里插入图片描述

在系统首页的左上角，有六个功能按钮：

**夜间模式切换：**点击可以在明亮模式和夜间模式之间切换，方便夜间使用
**国际化：**切换系统显示语言，支持多语言界面
**配置：**打开系统配置面板，可以进行系统相关设置
**编辑：**进入页面编辑模式，可以调整卡片大小、位置
**切换列数：**调整页面显示的列数，优化布局展示
**全屏：**切换全屏显示模式，获得更大的显示空间