第1章：安装HA Core — 在Debian/Ubuntu上手动搭建Home Assistant Core
说实话，我第一次接触Home Assistant时，也纠结过到底用哪种安装方式。HA OS、Docker、Core……选项太多，反而让人无从下手。我个人习惯是：如果你想真正理解HA的底层逻辑，手动安装Core绝对是最好的起点。你想想看，自己动手搭一遍，后面出啥问题都不慌。
这一章，我们就来走一遍完整的流程。目标是在一台干净的Debian或Ubuntu服务器上，用Python虚拟环境把Home Assistant Core跑起来。
1.1 准备工作：系统环境检查
在动手之前，先确认你的系统是Debian 11/12或Ubuntu 20.04/22.04/24.04。我建议用Ubuntu 22.04 LTS，因为社区支持最成熟，踩坑的人少。
登录服务器后，先更新包索引：
sudo apt update
sudo apt upgrade -y
然后安装必要的系统工具：
sudo apt install -y python3 python3-dev python3-venv python3-pip \
build-essential libffi-dev libssl-dev \
libjpeg-dev zlib1g-dev autoconf \
libtool pkg-config libturbojpeg0-dev
sudo apt autoremove 清理掉没用的包。干净的环境能少很多莫名其妙的依赖问题。
1.2 创建专用用户（推荐）
嗯，这里要注意：千万不要用root用户跑HA。我在项目中遇到过有人图省事直接用root，结果权限混乱，后面想迁移都费劲。
创建一个叫 homeassistant 的系统用户：
sudo useradd -r -m -s /bin/bash homeassistant
然后切换到该用户：
sudo -u homeassistant -H -s
1.3 创建Python虚拟环境
虚拟环境说白了就是给HA一个独立的小房间，不会和系统里的其他Python程序打架。我刚开始用Python时不懂这个，全局装了一堆包，最后版本冲突到崩溃……
先创建目录并进入：
mkdir -p /srv/homeassistant
cd /srv/homeassistant
创建虚拟环境：
python3 -m venv .
激活虚拟环境：
source bin/activate
激活后，你会看到命令行前面多了 (homeassistant) 前缀，这就说明你已经在虚拟环境里了。
1.4 安装Home Assistant Core
在虚拟环境里，用pip安装HA Core：
pip3 install homeassistant
这个过程会下载很多依赖包，大概需要3-5分钟。如果你在墙内网络，可能会慢一些。我建议提前配好pip国内镜像源：
pip3 config set global.index-url https://mirrors.aliyun.com/pypi/simple/
--no-cache-dir 参数重新安装。
1.5 首次启动与配置
安装完成后，启动HA进行初始化：
hass
第一次启动会创建配置文件目录 ~/.homeassistant，并自动下载前端资源。这个过程大概需要1-2分钟。你会看到类似这样的日志：
2024-01-15 10:30:22.123 INFO (MainThread) [homeassistant.core] Starting Home Assistant
2024-01-15 10:30:25.456 INFO (MainThread) [homeassistant.bootstrap] Home Assistant initialized in 3.33s
看到 Home Assistant initialized 就说明启动成功了。此时打开浏览器，访问 http://你的服务器IP:8123，就能看到HA的初始化配置页面。
1.6 配置开机自启（Systemd服务）
手动启动太麻烦，我们把它做成系统服务。先退出当前hass进程（按Ctrl+C），然后创建服务文件：
sudo nano /etc/systemd/system/home-assistant@homeassistant.service
写入以下内容：
[Unit]
Description=Home Assistant Core
After=network.target
[Service]
Type=simple
User=homeassistant
ExecStart=/srv/homeassistant/bin/hass -c "/home/homeassistant/.homeassistant"
Restart=on-failure
RestartSec=5s
[Install]
WantedBy=multi-user.target
然后启用并启动服务：
sudo systemctl enable home-assistant@homeassistant.service
sudo systemctl start home-assistant@homeassistant.service
检查状态：
sudo systemctl status home-assistant@homeassistant.service
如果显示 active (running)，恭喜你，HA Core已经稳定运行了。
1.7 核心知识体系
下面这张图帮你理清整个安装流程的逻辑：
1.8 常见问题速查
| 问题现象 | 可能原因 | 解决办法 |
|---|---|---|
| pip安装超时 | 网络问题或源太慢 | 配置国内镜像源，或使用代理 |
| hass命令找不到 | 虚拟环境未激活 | 执行 source /srv/homeassistant/bin/activate |
| 8123端口无法访问 | 防火墙未放行 | sudo ufw allow 8123 |
| 服务启动失败 | 配置文件权限错误 | 检查 .homeassistant 目录属主是否为homeassistant用户 |
核心要点总结：
- 用虚拟环境隔离HA的Python依赖，这是最佳实践
- 创建专用系统用户运行HA，保证安全性和可维护性
- 配置Systemd服务实现开机自启，省去手动启动的麻烦
- 首次启动后，浏览器访问8123端口完成初始化配置
好了，到这里HA Core就装好了。你可能会问：为什么不用Docker？嗯，Docker确实方便，但虚拟环境方式让你能直接看到HA的每一个文件、每一个日志。后面调试自定义组件或排查问题时，这种透明感会帮你大忙。
下一章，我们会进入HA的配置世界，从核心文件 configuration.yaml 开始，一步步搭建你的第一个智能家居场景。