第2章环境搭建

第二课：环境搭建——在树莓派/Docker/虚拟机中安装HA Core与HA OS

好，咱们正式开始动手了。

上一课聊了Home Assistant能干什么，这一课咱们直接落地。说白了，就是让你把HA跑起来，能打开那个漂亮的界面。

我个人习惯把安装方式分成三类：树莓派裸机、Docker容器、虚拟机。每种都有它的适用场景。我当年入坑时，第一台设备就是树莓派3B+，插着网线放在弱电箱里，一跑就是两年多，稳得很。

一、先搞清楚：HA Core 和 HA OS 有什么区别？

很多新手会懵，我简单解释一下。

HA OS：完整的操作系统。刷到SD卡上，插电就能用。自带管理界面，傻瓜式升级。适合树莓派、虚拟机。
HA Core：核心程序。需要你自己装Python环境、依赖库。适合Docker、或者你想在现有Linux系统上跑。

嗯，这里要注意：如果你选HA OS，它自带了一个叫“Supervisor”的管理器，装插件、备份都很方便。HA Core就没有这些，得自己折腾。

我的建议：新手直接上HA OS。别跟自己过不去。我见过太多人在环境依赖上卡了两天，最后放弃了。

二、方案一：树莓派安装HA OS（最推荐）

这是最经典的玩法。树莓派功耗低、体积小，7x24小时开着也不心疼电费。

2.1 准备工作

树莓派3B+ / 4B / 5（建议4B起步，2GB内存够用，4GB更宽裕）
32GB以上SD卡（Class 10速度）
读卡器、网线（首次配置建议有线）
下载工具：Raspberry Pi Imager 或 Balena Etcher

2.2 刷写系统

去Home Assistant官网下载HA OS的树莓派镜像。我用的是Raspberry Pi Imager，选“自定义镜像”就行。

# 步骤很简单：
1. 打开 Raspberry Pi Imager
2. 选择设备：树莓派4
3. 选择镜像：haos_rpi4-xx.img
4. 选择SD卡
5. 点击写入，等几分钟

刷完后，把SD卡插回树莓派，插上网线、电源。等个5分钟左右。

2.3 首次访问

在浏览器输入 http://homeassistant.local:8123。如果不行，去路由器后台找树莓派的IP地址，比如 http://192.168.1.100:8123。

我第一次搞的时候，死活连不上。后来发现是路由器没开mDNS。嗯，换个浏览器或者清一下DNS缓存试试。

避坑：我曾经遇到过SD卡速度太慢，导致系统启动后频繁卡死。后来换了三星的EVO Plus，再也没出过问题。别省那几十块钱。

三、方案二：Docker安装HA Core（适合已有Linux服务器）

如果你手头有台NAS或者云服务器，Docker是最干净的方式。我现在的生产环境就是Docker跑的，升级、回滚都方便。

3.1 前提条件

已安装Docker和Docker Compose
系统：Ubuntu 20.04+ / Debian 11+ / CentOS 7+
内存建议2GB以上

3.2 拉取镜像并启动

# 创建目录
mkdir -p /opt/homeassistant/config
cd /opt/homeassistant

# 启动容器（直接跑）
docker run -d \
  --name homeassistant \
  --restart=unless-stopped \
  -v /opt/homeassistant/config:/config \
  -v /etc/localtime:/etc/localtime:ro \
  --network=host \
  ghcr.io/home-assistant/home-assistant:stable

这里用了 --network=host，说白了就是让容器直接使用宿主机网络。这样你发现设备时不会出现网络隔离的问题。我踩过这个坑，用bridge模式死活找不到小米网关。

3.3 用Docker Compose管理（推荐）

# docker-compose.yml
version: '3'
services:
  homeassistant:
    container_name: homeassistant
    image: ghcr.io/home-assistant/home-assistant:stable
    volumes:
      - ./config:/config
      - /etc/localtime:/etc/localtime:ro
    restart: unless-stopped
    network_mode: host

然后执行 docker-compose up -d。等个一两分钟，访问 http://你的IP:8123 就行。

小技巧：Docker版本升级特别简单。拉取新镜像，重启容器即可。我一般每个月更新一次，从来没出过兼容问题。

四、方案三：虚拟机安装HA OS（适合Windows/Mac用户）

如果你不想买树莓派，又不想搞Linux，虚拟机是最快的体验方式。我用VMware Workstation跑过，也用过VirtualBox，都挺稳。

4.1 下载镜像

去HA官网下载 haos_ova-xx.qcow2.xz 文件。这是专门给虚拟机用的。

4.2 创建虚拟机

配置项	推荐值
操作系统	Linux / 其他 64-bit
内存	2GB（最低1GB）
CPU	2核
磁盘	32GB（动态分配）
网络	桥接模式（重要！）

网络一定要选桥接模式。用NAT的话，你后面发现设备会出问题。我刚开始用NAT，结果Zigbee网关死活连不上，折腾了一下午才发现是网络模式的问题。

4.3 导入镜像并启动

以VMware为例：

1. 新建虚拟机，选择“自定义”
2. 硬件兼容性选 Workstation 16.x
3. 稍后安装操作系统
4. 选择 Linux -> 其他 Linux 5.x 内核 64-bit
5. 分配2GB内存，2核CPU
6. 网络选桥接
7. 磁盘选32GB，单文件
8. 创建完成后，编辑虚拟机设置
9. 移除默认的虚拟硬盘，添加现有磁盘
10. 选择你下载的 .qcow2 文件
11. 启动虚拟机

启动后，屏幕会显示IP地址。记下来，浏览器访问 http://那个IP:8123。

注意：虚拟机方式不适合长期跑生产环境。因为宿主机一重启，HA也跟着断。我建议只用来测试和学习。

五、首次启动与初始化配置

不管用哪种方式，第一次打开 http://你的IP:8123 时，都会看到一个初始化向导。

5.1 创建管理员账户

填用户名、密码。这个账户是最高权限，别搞丢了。我习惯用 admin 加一个强密码，然后记在密码管理器里。

5.2 设置家庭位置

地图上点一下你的家。这个位置用于日出日落、天气等自动化。精度不用太高，大概到街道级别就行。

5.3 选择时区和单位

选 Asia/Shanghai，单位选公制。温度用摄氏度，风速用公里/小时。这些后面都能改，但一步到位省事。

5.4 设备发现

HA会自动扫描局域网内的智能设备。你可能会看到小米网关、Philips Hue、Sonoff等。如果有，直接点配置就行。没有也别急，后面我们会专门讲设备接入。

我的习惯：首次配置完成后，我会立刻做一个系统备份。在“配置 -> 系统 -> 备份”里，点创建备份。这样万一搞坏了，一键恢复。我吃过亏，有一次装插件把系统搞崩了，没备份，只能重装。

六、总结一下三种方案的选型

方案	适合人群	稳定性	维护难度
树莓派 + HA OS	新手、长期运行	★★★★★	★☆☆☆☆
Docker + HA Core	已有Linux服务器	★★★★☆	★★★☆☆
虚拟机 + HA OS	测试、学习	★★★☆☆	★★☆☆☆

我个人最推荐树莓派方案。你想想看，一个几十块钱的小板子，插上电就能跑，功耗才5瓦，一年电费不到30块。我家里那台树莓派4B，已经连续跑了800多天没重启过。稳如老狗。

📚 课程目录

第二课：环境搭建——在树莓派/Docker/虚拟机中安装HA Core与HA OS

一、先搞清楚：HA Core 和 HA OS 有什么区别？

二、方案一：树莓派安装HA OS（最推荐）

2.1 准备工作

2.2 刷写系统

2.3 首次访问

三、方案二：Docker安装HA Core（适合已有Linux服务器）

3.1 前提条件

3.2 拉取镜像并启动

3.3 用Docker Compose管理（推荐）

四、方案三：虚拟机安装HA OS（适合Windows/Mac用户）

4.1 下载镜像

4.2 创建虚拟机

4.3 导入镜像并启动

五、首次启动与初始化配置

5.1 创建管理员账户

5.2 设置家庭位置

5.3 选择时区和单位

5.4 设备发现

六、总结一下三种方案的选型