目录
- 1. 前言&&叠甲
- 2. 使用的环境
- 3. 相关链接
- 4. 前期步骤
- 4.1 安装路径提前说明
- 4.2 Ubuntu 相关依赖安装
- 4.3 Python源码编译安装
- 4.3.1 编译安装
- 4.3.2 换源
- 4.3.3 环境变量
- 5. 构建Home Assistant源码
- 5.1 clone源码
- 5.2 创建虚拟Python环境
- 5.3 安装项目依赖
- 5.4 安装项目
- 5.5 运行项目
- 5.6 查看配置文件夹
- 5.7 补充相关
- 6. 访问Home Assistant
- 6.1 首次运行创建用户
- 6.2 选择家的位置
- 6.3 进入首页
- 7. 安装HACS
- 7.1 下载HACS包
- 7.2 将hacs放置对应位置
- 7.3 添加HACS
- 7.4 HACS绑定GitHub
- 8. 安装小米的Ha Xiaomi Home
- 8.1 三种安装方式
- 8.1.1 源码构建形式
- 8.1.2 单独文件形式
- 8.1.3 使用HACS安装Ha Xiaomi Home
- 8.2 重启后添加Ha Xiaomi Home到Home Assistant
- 8.2.1 账号授权认证和地址回调
- 9. 总结
1. 前言&&叠甲
本文章为全文皆慢慢敲的文字,本人非专业人士,难免存在遗漏和错误,请指出即可。若有更好方案,欢迎提出。
为什么会写这篇文章?因为搜索了一段时候,发现很少有介绍从零开始编译Home Assistant
源码的教程和视频,大多是使用docker或者使用Nas,定制化/可修改程度不高?
同时由于官方的方案仅剩下为数不多的几个,主要是基于HA OS
(也就是做成了镜像系统),或者是Container。一个是镜像封装了,不方便自定义和使用系统,另一个是不太利于没有Docker环境。本篇想在裸机系统上部署,并且随时能切换Git版本从而随时升级,故写此篇。
2. 使用的环境
操作系统版本:Ubuntu-Desktop 24.04.2 LTS。
Home Assistant版本:2025.7.1
,但是是GitHub的最新dev构建。但是由于是源码部署,所以可以随时升级。
Python版本:3.13.5,源码构建。否则可能会影响Ubuntu内置的3.12。2025.7版本的Home Assistant
需要Python3.13。
3. 相关链接
本篇编写时候的相关安装包/软件的链接如下,可以参考换成最新的
https://releases.ubuntu.com/24.04/ubuntu-24.04.2-desktop-amd64.iso
https://www.python.org/ftp/python/3.13.5/Python-3.13.5.tgz
相关GitHub仓库链接如下
https://github.com/home-assistant/core
https://github.com/hacs/integration
https://github.com/XiaoMi/ha_xiaomi_home
4. 前期步骤
4.1 安装路径提前说明
为方便使用,本篇安装都位于~/HomeAssistant-All/
目录下,包括Python、Home Assistant。
4.2 Ubuntu 相关依赖安装
# 更新
sudo apt update# 安装Home Assistant需要的依赖,和其他一些常用的工具。但不包括Nginx、Python等
sudo apt install -y autoconf automake avahi-daemon bluez build-essential ca-certificates curl ffmpeg gdebi git gnupg gnupg2 htop libavcodec-dev libavdevice-dev libavformat-dev libavutil-dev libbz2-dev libcap2-bin libffi-dev libgdbm-compat-dev libgdbm-dev libglib2.0-dev libjpeg-dev liblzma-dev libncursesw5-dev libnss3-dev libopenjp2-7-dev libpython3-dev libreadline-dev libsqlite3-dev libssl-dev libswscale-dev libtiff5-dev libtool libturbojpeg0-dev libudev-dev libxml2-dev libxmlsec1-dev libxslt1-dev libyaml-dev lrzsz lsb-release lsof neofetch net-tools openssh-server p7zip-full rar rsync software-properties-common tk-dev tmux tree unrar unzip uuid-dev vim wget xz-utils zip zlib1g-dev
以上依赖安装较为缓慢。由于下载的Ubuntu镜像默认使用的是清华的安装源,所以在网络上还是没有问题的。若不是,请自行换源。出现如下表明安装完成。
4.3 Python源码编译安装
4.3.1 编译安装
为了防止干扰Ubuntu自带的Python版本,此处Python仅在安装文件夹中进行。若本机已经有Python3.13的环境,直接跳过至构建Home Assistant源码
即可。
将下载的Python源码包Python-3.13.5.tgz
解压到~/HomeAssistant-All/
,进入该目录cd Python-3.13.5/
。
然后开始编译Python。
# 位于 ~/HomeAssistant-All/Python-3.13.5/
sudo ./configure --enable-optimizations
sudo make -j$(nproc)
sudo make altinstall
由于Python源码编译较慢,若机器配置较低可能需要数分钟至十数分钟。安装完成后为如下。
安装完毕后,可以执行
~/HomeAssistant-All/Python-3.13.5/python
看到如下则表明Python安装成功,可以使用Ctrl+D
退出。
4.3.2 换源
mkdir -p ~/.pip
vim ~/.pip/pip.conf
在里面输入如下,即使用清华源。
[global]
index-url = https://pypi.tuna.tsinghua.edu.cn/simple
timeout = 10
trusted-host = pypi.tuna.tsinghua.edu.cn
4.3.3 环境变量
此处环境变量不与系统的冲突,做到输入命令python313方可运行。
vim ~/.bashrc
# 然后划到最后,输入
export PATH="$HOME/HomeAssistant-All/Python-3.13.5/bin:$PATH"
alias python313='python3.13'
alias pip313='pip3.13'
# 生效环境变量
source ~/.bashrc
新开终端,输入python313
即可正常使用Python3.13.5。
5. 构建Home Assistant源码
5.1 clone源码
将源码clone到本地~/HomeAssistant-All/home-assistant-core/
文件夹
git clone https://github.com/home-assistant/core.git home-assistant-core
进入该文件夹,cd home-assistant-core
。
默认的clone下来的,可能是dev分支,dev分支push比较活跃,不清楚有没有bug。可以使用如下命令查看和切换成稳定的master分支,或者是其他分支。
# 查看当前分支
git branch# 本地没有master分支,从远程拉取
git checkout -b master origin/master# 若本地有master分支,则切换到本地的master分支
git checkout master# 更新分支代码
git pull
5.2 创建虚拟Python环境
直接覆盖原本Python安装的环境,可能会带来依赖冲突。所以创建一个虚拟的Python环境,所有依赖都安装到这个环境中,不会出现依赖问题。若因为某些原因环境出问题了,只需要删除虚拟环境再建即可。
此处使用Python虚拟环境,名为venv313
。
# 创建虚拟环境
python313 -m venv venv313
# 激活环境
source venv313/bin/activate
# 更新相关软件包
pip install --upgrade pip setuptools wheel
5.3 安装项目依赖
pip install -r requirements_all.txt
为什么使用requirements_all
而不是requirements_test
,是因为all能安装所有依赖。test只有部分依赖,若运行中代码走到没有安装的依赖,则会默认安装,走的是pip的默认源,可能因为网络问题无法下载,导致运行报错。
安装all的项目依赖会耗时较长时间,可能为十数分钟。安装完成后如下显示
5.4 安装项目
pip install -e .
5.5 运行项目
直接运行命令
hass
即可启动项目。默认第一次运行,会在如图的~/.homeassistant/
文件夹下创建配置文件。出现下图即说明已经成功在运行了。
使用http://ip:8123
可直接访问。
5.6 查看配置文件夹
cd ~/.homeassistant/
运行如上命令,即可进入Home Assistant的配置文件夹。可以修改端口号等信息,此处不再赘述。
5.7 补充相关
本篇全篇运行于基于VMware的Ubuntu中。若也有相同的,建议对VMware配置做网络上的桥接,方便手机连接。
6. 访问Home Assistant
浏览器访问http://ip:8123
即可访问。
6.1 首次运行创建用户
点击创建我的智能家居
,输入用户名和密码即可创建。
输入相关信息后,点击创建账户
,我这边没有任何反应,然后去看运行日志,发现有报错。
KeyError: 'component.onboarding.area.living_room'
不知道是版本问题,还是什么问题。但是不影响使用。用户已经创建,此处需要重启应用。即使用Ctrl + C
停止运行,再使用hass
运行,再刷新网页即可。
6.2 选择家的位置
登录后,出现要选择家的位置。可以在输入框中输入中文的城市名称。
这个地图有时候需要特殊网络才能搜索。但是不影响选择。可以缩放地图后,拖动地图定位的标点,来选择到自己所在的城市。
6.3 进入首页
无脑下一步后,即可进入首页,如图
那么,至此为止,初级的Home Assistant
部署运行完成。
下面将介绍如何添加HACS、如何添加小米的Ha Xiaomi Home
(两者可独立安装,也可以Ha Xiaomi Home通过HACS安装)。
7. 安装HACS
HACS官方的GitHub链接:https://github.com/hacs/integration/releases
。
此处使用官方构建的HACS的release安装到Home Assistant中。
7.1 下载HACS包
打开https://github.com/hacs/integration/releases
,下载最新版的hacs.zip
文件。
7.2 将hacs放置对应位置
进入到Home Assistant的配置文件夹~/.homeassistant/
cd ~/.homeassistant/
在该文件夹位置新建一个名为custom_components
的文件夹。
进入该custom_components
的文件夹,将hacs.zip
文件解压到这个文件夹中,保留最外层的文件夹,如图。
7.3 添加HACS
完成后,重启Home Assistant
应用,进入路径设置-设备与服务
。
点击右下角添加集成
按钮,搜索hacs,可以看到一个右侧有橙色方块的栏目(代表“自定义集成”),选择后点击提交
。
7.4 HACS绑定GitHub
提交完成后,需要点击转圈的下方的链接,进行GitHub的授权。同时下方小字有8个字符的配对码,需要复制粘贴至GitHub进行授权方可使用。
然后点击Authorize hacs
即可完成,如图结果出现即可关闭该页面。
完成后如图所示界面,可以看到侧边有HACS的入口了。
点击HACS,可以看到有较多可下载的扩展组件。
如果出现如图的报错,could_not_register
则请排查,Home Assistant
主机是否无法访问GitHub。
至此,HACS集成进Home Assistant
已完成。
8. 安装小米的Ha Xiaomi Home
小米在2024年底开源了自家的Home Assistant
的组件,GitHub链接:https://github.com/XiaoMi/ha_xiaomi_home
。至此可以很方便地将米家生态接入到Home Assistant
。
8.1 三种安装方式
Ha Xiaomi Home
官方介绍了3种接入方式,分别是源码、HACS、单独文件形式。此篇都将介绍。
这三种方法都是将Ha Xiaomi Home
的代码文件复制到指定位置(~/.homeassistant/custom_components/
)后,重启Home Assistant
应用,从而可以在添加集成
的地方搜索并添加小米的Home Assistant
集成,并设置账号信息。
所以三种方法均写至复制完成,提示重启为止。重启之后的操作将在后面一小节的添加Ha Xiaomi Home到Home Assistant
中有写。
8.1.1 源码构建形式
源码形式的话,可以将源码clone至本地任何位置,但请
不要同时:
- 将源码clone至
~/.homeassistant/custom_components/
- 将clone的文件夹命名为
xiaomi_home
- 否则在构建的时候,将会出现覆盖性问题。可以适当修改文件名。
此处将源码clone至~/.homeassistant/xiaomi_home_git/
,使用如下命令即可。
cd ~/.homeassistant/
clone https://github.com/XiaoMi/ha_xiaomi_home.git xiaomi_home_git
clone完毕后,进入目录
cd xiaomi_home_git/
运行构建命令,将构建产物复制到~/.homeassistant/custom_components/
。
# 给install.sh运行权限。当然也可以自行设置更小的权限。
chmod +x install.sh
# 将构建产物复制到~/.homeassistant/custom_components/。其中,custom_components路径不要手动添加,因为在install.sh脚本中已经自带该路径,若添加了则会变成~/.homeassistant/custom_components/custom_components/xiaomi_home/从而无法识别。
./install.sh ~/.homeassistant/
运行后出现如下提示,即成功:Xiaomi Home installation is completed. Please restart Home Assistant.
。根据提示重启Home Assistant
即可。
一至三的方法(选其一)添加完毕后,都需要重启Home Assistant
。重启后,需要将Ha Xiaomi Home
集成到Home Assistant
并添加账号。
后续更新Ha Xiaomi Home
的方式,在Ha Xiaomi Home
的Git目录运行命令即可。
# 更新至最新的代码
git pull
# 构建并复制最新产物
./install.sh ~/.homeassistant/
# 完成后重启Home Assistant
8.1.2 单独文件形式
打开https://github.com/XiaoMi/ha_xiaomi_home/releases
链接,下载最新的xiaomi_home.zip
的压缩包。
进入到Home Assistant
的配置文件夹~/.homeassistant/
,在该文件夹位置新建一个名为custom_components
的文件夹(如果已有,或者在上面HACS中有操作,则不必新建)。
进入该custom_components
的文件夹,将hacs.zip
文件解压到这个文件夹中,保留最外层的文件夹,如图。将压缩包解压到该文件。
至此,Ha Xiaomi Home
已经添加到Home Assistant
。现在需要重启Home Assistant
方可使用。下面介绍如何使用HACS来添加。
一至三的方法(选其一)添加完毕后,都需要重启Home Assistant
。重启后,需要将Ha Xiaomi Home
集成到Home Assistant
并添加账号。
8.1.3 使用HACS安装Ha Xiaomi Home
点击HACS栏目,搜索栏中输入Ha Xiaomi Home
,看到stars数较多的即是官方的集成。
点击进入后,点击右下角的download,将会自动下载到本地。但是该方法如果在网络不佳的时候将会无法下载。此时建议使用上一种方式。
安装完成后,点击HACS选项卡,可以看到Xiaomi Home
在列表中,并且是Pending restart
,这时候重启Home Assistant
即可。
一至三的方法(选其一)添加完毕后,都需要重启Home Assistant
。重启后,需要将Ha Xiaomi Home
集成到Home Assistant
并添加账号。
8.2 重启后添加Ha Xiaomi Home到Home Assistant
不论是直接文件复制形式,还是HACS添加,完成后需要集成进Home Assistant
。重启Home Assistant
应用,进入路径设置-设备与服务
。
点击右下角添加集成
按钮,使用英文搜索xiaomi,可以看到其中一个右侧有橙色方块
的栏目(代表“自定义集成”),选择该有橙色的栏目后点击,按照说明一步步即可。
8.2.1 账号授权认证和地址回调
一步步进行后,在拉起小米账号登录前,有一个步骤,这里需要点击蓝字的请点击此处进行登录
才能拉起小米的账号授权。
确认授权后,将会跳转到一个新的页面,网址的格式为:http://homeassistant.local:8123/api/webhook/1261686089886280620?code=xxxxxxxxxxxxxxxx
。
显然,这个网页是无法访问的。可以看到访问的域名是homeassistant.local
,这个域名是不存在的,ping该域名也没有ip的解析。这个域名猜测是在做HAOS或者container的时候,写入到系统的hosts指向的本地地址。
有两种解决办法,最简单的就是,手动将访问的域名前缀homeassistant.local:8123
修改为目前访问的ip:8123
,然后回车访问即可。或者可以在本机的hosts文件中,手动配置指向Home Assistant
的ip的条目。
这里使用直接修改ip访问。回车访问后,这个页面稍等几秒即变成空白页,或者被关闭。然后手动打开刚刚的授权页面,稍等几秒即可看到已经成功授权了。然后只要勾选要导入的设备即可。
需要等待一段时间添加完毕后即可使用。添加完成后,可以在概览
处看到原本在米家中的设备。
9. 总结
至此,在Ubuntu上从零开始编译并运行Home Assistant
源码并集成HACS
与小米开源的Ha Xiaomi Home
的讲述完毕。
本篇为了不使用官方的镜像,不使用Container,直接裸Ubuntu系统部署并运行Home Assistant
,为的是能够有更好的安装空间。现在太多教程在教如何使用各家Nas来安装Home Assistant
,对于没有Nas的人比较不友好。使用Docker来安装的则对没有容器化部署的不友好。故写本篇。