目录
- [1. 前言&&叠甲](#1. 前言&&叠甲)
- [2. 使用的环境](#2. 使用的环境)
- [3. 相关链接](#3. 相关链接)
- [4. 前期步骤](#4. 前期步骤)
-
- [4.1 安装路径提前说明](#4.1 安装路径提前说明)
- [4.2 Ubuntu 相关依赖安装](#4.2 Ubuntu 相关依赖安装)
- [4.3 Python源码编译安装](#4.3 Python源码编译安装)
-
- [4.3.1 编译安装](#4.3.1 编译安装)
- [4.3.2 换源](#4.3.2 换源)
- [4.3.3 环境变量](#4.3.3 环境变量)
- [5. 构建Home Assistant源码](#5. 构建Home Assistant源码)
-
- [5.1 clone源码](#5.1 clone源码)
- [5.2 创建虚拟Python环境](#5.2 创建虚拟Python环境)
- [5.3 安装项目依赖](#5.3 安装项目依赖)
- [5.4 安装项目](#5.4 安装项目)
- [5.5 运行项目](#5.5 运行项目)
- [5.6 查看配置文件夹](#5.6 查看配置文件夹)
- [5.7 补充相关](#5.7 补充相关)
- [6. 访问Home Assistant](#6. 访问Home Assistant)
-
- [6.1 首次运行创建用户](#6.1 首次运行创建用户)
- [6.2 选择家的位置](#6.2 选择家的位置)
- [6.3 进入首页](#6.3 进入首页)
- [7. 安装HACS](#7. 安装HACS)
-
- [7.1 下载HACS包](#7.1 下载HACS包)
- [7.2 将hacs放置对应位置](#7.2 将hacs放置对应位置)
- [7.3 添加HACS](#7.3 添加HACS)
- [7.4 HACS绑定GitHub](#7.4 HACS绑定GitHub)
- [8. 安装小米的Ha Xiaomi Home](#8. 安装小米的Ha Xiaomi Home)
-
- [8.1 三种安装方式](#8.1 三种安装方式)
-
- [8.1.1 源码构建形式](#8.1.1 源码构建形式)
- [8.1.2 单独文件形式](#8.1.2 单独文件形式)
- [8.1.3 使用HACS安装Ha Xiaomi Home](#8.1.3 使用HACS安装Ha Xiaomi Home)
- [8.2 重启后添加Ha Xiaomi Home到Home Assistant](#8.2 重启后添加Ha Xiaomi Home到Home Assistant)
-
- [8.2.1 账号授权认证和地址回调](#8.2.1 账号授权认证和地址回调)
- [9. 总结](#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
相关GitHub仓库链接如下
https://github.com/home-assistant/core
4. 前期步骤
4.1 安装路径提前说明
为方便使用，本篇安装都位于~/HomeAssistant-All/目录下，包括Python、Home Assistant。
4.2 Ubuntu 相关依赖安装
bash
# 更新
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。
bash
# 位于 ~/HomeAssistant-All/Python-3.13.5/
sudo ./configure --enable-optimizations
sudo make -j$(nproc)
sudo make altinstall
由于Python源码编译较慢，若机器配置较低可能需要数分钟至十数分钟。安装完成后为如下。
安装完毕后，可以执行
bash
~/HomeAssistant-All/Python-3.13.5/python看到如下则表明Python安装成功，可以使用Ctrl+D退出。
4.3.2 换源
bash
mkdir -p ~/.pip
vim ~/.pip/pip.conf在里面输入如下，即使用清华源。
bash
[global]
index-url = https://pypi.tuna.tsinghua.edu.cn/simple
timeout = 10
trusted-host = pypi.tuna.tsinghua.edu.cn4.3.3 环境变量
此处环境变量不与系统的冲突，做到输入命令python313方可运行。
bash
vim ~/.bashrc
bash
# 然后划到最后，输入
export PATH="$HOME/HomeAssistant-All/Python-3.13.5/bin:$PATH"
alias python313='python3.13'
alias pip313='pip3.13'
bash
# 生效环境变量
source ~/.bashrc新开终端，输入python313即可正常使用Python3.13.5。
5. 构建Home Assistant源码
5.1 clone源码
将源码clone到本地~/HomeAssistant-All/home-assistant-core/文件夹
bash
git clone https://github.com/home-assistant/core.git home-assistant-core进入该文件夹，cd home-assistant-core。
默认的clone下来的，可能是dev分支，dev分支push比较活跃，不清楚有没有bug。可以使用如下命令查看和切换成稳定的master分支，或者是其他分支。
bash
# 查看当前分支
git branch
# 本地没有master分支，从远程拉取
git checkout -b master origin/master
# 若本地有master分支，则切换到本地的master分支
git checkout master
# 更新分支代码
git pull5.2 创建虚拟Python环境
直接覆盖原本Python安装的环境，可能会带来依赖冲突。所以创建一个虚拟的Python环境，所有依赖都安装到这个环境中，不会出现依赖问题。若因为某些原因环境出问题了，只需要删除虚拟环境再建即可。
此处使用Python虚拟环境，名为venv313。
bash
# 创建虚拟环境
python313 -m venv venv313
# 激活环境
source venv313/bin/activate
bash
# 更新相关软件包
pip install --upgrade pip setuptools wheel
5.3 安装项目依赖
bash
pip install -r requirements_all.txt为什么使用requirements_all而不是requirements_test，是因为all能安装所有依赖。test只有部分依赖，若运行中代码走到没有安装的依赖，则会默认安装，走的是pip的默认源，可能因为网络问题无法下载，导致运行报错。
安装all的项目依赖会耗时较长时间，可能为十数分钟。安装完成后如下显示
5.4 安装项目
bash
pip install -e .
5.5 运行项目
直接运行命令
bash
hass即可启动项目。默认第一次运行，会在如图的~/.homeassistant/文件夹下创建配置文件。出现下图即说明已经成功在运行了。
使用http://ip:8123可直接访问。
5.6 查看配置文件夹
bash
cd ~/.homeassistant/运行如上命令，即可进入Home Assistant的配置文件夹。可以修改端口号等信息，此处不再赘述。
5.7 补充相关
本篇全篇运行于基于VMware的Ubuntu中。若也有相同的，建议对VMware配置做网络上的桥接，方便手机连接。
6. 访问Home Assistant
浏览器访问http://ip:8123即可访问。
6.1 首次运行创建用户
点击创建我的智能家居，输入用户名和密码即可创建。
输入相关信息后，点击创建账户，我这边没有任何反应，然后去看运行日志，发现有报错。
bash
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/
bash
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/，使用如下命令即可。
bash
cd ~/.homeassistant/
clone https://github.com/XiaoMi/ha_xiaomi_home.git xiaomi_home_gitclone完毕后，进入目录
bash
cd xiaomi_home_git/运行构建命令，将构建产物复制到~/.homeassistant/custom_components/。
bash
# 给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目录运行命令即可。
bash
# 更新至最新的代码
git pull
# 构建并复制最新产物
./install.sh ~/.homeassistant/
# 完成后重启Home Assistant8.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来安装的则对没有容器化部署的不友好。故写本篇。