在Ubuntu上从零开始编译并运行Home Assistant源码并集成HACS与小米开源的Ha Xiaomi Home

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

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来安装的则对没有容器化部署的不友好。故写本篇。