安装 HomeAssistant

适用于『mac』

安装 UTM 虚拟机

下载 UTM

地址：https://mac.getutm.app/

使用 Debain 镜像

地址：https://cdimage.debian.org/cdimage/archive/12.8.0/arm64/iso-cd/

安装过程中所做的任何设置均可在安装完成后根据需要自行修改，因此请勿将安装阶段的配置视为最终的永久设置。

设置主机 hostname，本文设置为 debian，可根据自身习惯或喜好进行设置。

可以跳过 domain 设置

设置 root 用户密码

再次输入确认密码

创建普通用户，本文设置为 piliqiu

设置普通用户密码

确认普通用户密码

选择时区，选择 Eastern，系统时区和时间可以在系统安装完毕后自行设置。

进行硬盘分区，如果自身没有特殊需求默认即可。

不打算安装图形界面，选择最后一项即可，为了远程方便同时选择了 SSH 组件

安装完成重启

清除 usb 驱动器，不再使用 usb 中的系统启动，使用已经安装好的系统启动。

网络改为桥接，桥接接口自己都试试，看那个可以上网，就使用那个接口。

在 MacOS 系统中，无法将复制的内容粘贴到通过 UTM 虚拟机运行的 Debian 系统内。目前使用 WindTerm 通过 SSH 连接至 Debian 系统。

连接前，通过在 Debian 中执行 ip addr show 命令获取其 IPv4 地址，再使用 SSH 工具进行远程连接。

安装 Docker 环境

通过 Docker 的 APT 仓库安装

在开始前，先设置代理

1 2 3

# 只在本次会话生效 export http_proxy=http://IP:端口 export https_proxy=http://IP:端口

查看 Codename

1
2
3
4
5
6
7
8

# 查看你的 Debian 版本代号
lsb_release -a

# 输出示例
Distributor ID: Debian
Description:    Debian GNU/Linux 12 (bookworm)
Release:        12
Codename:       bookworm

📌 关键点：你需要记住 Codename（如 bookworm, bullseye），这是添加 Docker 软件源时要用到的。

常见 Debian 版本代号对照表

安装必要依赖工具

1

sudo apt install -y ca-certificates curl gnupg lsb-release

解释：

• ca-certificates: 用于 HTTPS 证书验证
• curl: 下载文件
• gnupg: 导入 GPG 密钥
• lsb-release: 获取发行版信息

Docker 官方 GPG 公钥

创建密钥环目录并导入密钥：

1
2

sudo mkdir -p /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/debian/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg

添加 Docker 的 APT 软件源

使用前面查到的 Codename（比如 bookworm）来构建源地址。

执行以下命令（自动获取 codename）：

1
2

echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/debian $(lsb_release -cs) stable" | \
sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

如果你是 Debian 12 (bookworm)，这条命令就会写入：

1

deb [arch=amd64 signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/debian bookworm stable

再次更新 APT 包索引

1

sudo apt update

因为我们刚刚添加了新的软件源，必须重新加载。

安装 Docker 引擎及相关组件

1

sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

各组件说明：

验证 Docker 是否安装成功

检查版本：

1

sudo docker --version

正常输出类似：

1

Docker version 25.0.5, build xxxxxxx

安装 Homeassistant

1
2
3
4
5
6
7
8
9

docker run -d \
  --name homeassistant \
  --privileged \
  --restart=unless-stopped \
  -e TZ=Asia/Shanghai \
  -v /PATH_TO_YOUR_CONFIG:/config \
  -v /run/dbus:/run/dbus:ro \
  --network=host \
  ghcr.io/home-assistant/home-assistant:stable

📌 记得替换 /PATH_TO_YOUR_CONFIG 为你的实际配置路径，例如：

1

-v /home/piliqiu/homeassistant/config:/config

安装后，访问 http://ip:8123 打开 HomeAssistant 初始化页面，我用 Chrome 浏览器打不开，换成 Safari 浏览器就可以，很奇怪。

解决：设置 -> 隐私与安全性 -> 本地网络 -> Google Chrome