Mac 安装 Homeassistant -

piliqiu

2025-09-14 约 600 字预计阅读 3 分钟 - 次阅读

使用 UTM 安装 Debain

下载 UTM

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

/images/posts/Mac安装Homeassistant/1.png — (`图1`)

下载 Debain 镜像

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

/images/posts/Mac安装Homeassistant/2.png — (`图2`)

使用 UTM 安装 Debain

提示

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

/images/posts/Mac安装Homeassistant/39.png — (`选择 NO 不启用网络镜像`)

/images/posts/Mac安装Homeassistant/40.png — (`选择 NO 不启用数据统计共享`)

/images/posts/Mac安装Homeassistant/3.png — (`图3`)

/images/posts/Mac安装Homeassistant/4.png — (`图4`)

/images/posts/Mac安装Homeassistant/5.png — (`图5`)

/images/posts/Mac安装Homeassistant/6.png — (`图6`)

/images/posts/Mac安装Homeassistant/7.png — (`图7`)

/images/posts/Mac安装Homeassistant/8.png — (`图8`)

/images/posts/Mac安装Homeassistant/9.png — (`图9`)

/images/posts/Mac安装Homeassistant/10.png — (`图10`)

/images/posts/Mac安装Homeassistant/11.png — (`图11`)

/images/posts/Mac安装Homeassistant/12.png — (`图12`)

/images/posts/Mac安装Homeassistant/13.png — (`图13`)

/images/posts/Mac安装Homeassistant/14.png — (`图14`)

/images/posts/Mac安装Homeassistant/15.png — (`图15`)

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

/images/posts/Mac安装Homeassistant/16.png — (`图16`)

可以跳过 domain 设置

/images/posts/Mac安装Homeassistant/17.png — (`图17`)

设置 root 用户密码

/images/posts/Mac安装Homeassistant/18.png — (`图18`)

再次输入确认密码

/images/posts/Mac安装Homeassistant/19.png — (`图19`)

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

/images/posts/Mac安装Homeassistant/20.png — (`图20`)

/images/posts/Mac安装Homeassistant/21.png — (`图21`)

设置普通用户密码

/images/posts/Mac安装Homeassistant/22.png — (`图22`)

确认普通用户密码

/images/posts/Mac安装Homeassistant/23.png — (`图23`)

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

/images/posts/Mac安装Homeassistant/24.png — (`图24`)

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

/images/posts/Mac安装Homeassistant/25.png — (`图25`)

/images/posts/Mac安装Homeassistant/26.png — (`图26`)

/images/posts/Mac安装Homeassistant/27.png — (`图27`)

/images/posts/Mac安装Homeassistant/28.png — (`图28`)

/images/posts/Mac安装Homeassistant/29.png — (`图29`)

/images/posts/Mac安装Homeassistant/30.png — (`图30`)

/images/posts/Mac安装Homeassistant/31.png — (`图31`)

/images/posts/Mac安装Homeassistant/32.png — (`图32`)

/images/posts/Mac安装Homeassistant/33.png — (`图33`)

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

/images/posts/Mac安装Homeassistant/34.png — (`图34`)

安装完成重启

/images/posts/Mac安装Homeassistant/35.png — (`图35`)

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

/images/posts/Mac安装Homeassistant/36.png — (`图36`)

/images/posts/Mac安装Homeassistant/37.png — (`图37`)

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

/images/posts/Mac安装Homeassistant/38.png — (`图38`)

提示

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

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

安装 Docker 环境

通过 Docker 的 APT 仓库安装

查看 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 版本代号对照表

Debian 版本	代号（Codename）
Debian 12	bookworm
Debian 11	bullseye
Debian 10	buster

安装必要依赖工具

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)，这条命令就会写入：

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

再次更新 APT 包索引

sudo apt update

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

安装 Docker 引擎及相关组件

1

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

各组件说明：

组件	作用
docker-ce	Docker 社区版主程序
docker-ce-cli	Docker 命令行工具
containerd.io	容器运行时
docker-buildx-plugin	支持多平台构建
docker-compose-plugin	提供 docker compose 命令（v2）

验证 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

安装 hacs

之前我映射的目录是 /home/piliqiu/homeassistant/config

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21


# 1. 进入 config 目录
cd /home/piliqiu/homeassistant/config

# 2. 创建 custom_components（如果还没有）
mkdir -p custom_components/hacs

# 3. 进入 hacs 目录
cd custom_components/hacs

# 4. 下载 HACS 最新版本
curl -sL https://github.com/hacs/integration/releases/latest/download/hacs.zip -o hacs.zip

# 5. 安装 unzip（如果未安装）
sudo apt update && sudo apt install unzip -y

# 6. 解压并清理
unzip hacs.zip
rm hacs.zip

# 7. 修复权限，确保容器能读取
chmod -R 777 /home/piliqiu/homeassistant/config/*

安装后需要重启容器

/images/posts/Mac安装Homeassistant/41.png — (`图41`)

/images/posts/Mac安装Homeassistant/42.png — (`图42`)

/images/posts/Mac安装Homeassistant/43.png — (`图43`)

/images/posts/Mac安装Homeassistant/44.png — (`图44`)

/images/posts/Mac安装Homeassistant/45.png — (`图45`)

/images/posts/Mac安装Homeassistant/46.png — (`图46`)

彩云天气

在 HACS 中搜索 彩云天气，安装 彩云天气 和 Colorfulclouds Weather Card

/images/posts/Mac安装Homeassistant/47.png — (`图47`)

申请 彩云天气 的 key

/images/posts/Mac安装Homeassistant/48.png — (`图48`)

/images/posts/Mac安装Homeassistant/49.png — (`图49`)

/images/posts/Mac安装Homeassistant/50.png — (`图50`)

/images/posts/Mac安装Homeassistant/51.png — (`图51`)

/images/posts/Mac安装Homeassistant/52.png — (`图52`)

免费用户是 1000 次，修改数据刷新间隔，延长使用时间

/images/posts/Mac安装Homeassistant/53.png — (`图53`)

配置后，重启 homeassistant

新增网页卡片

/images/posts/Mac安装Homeassistant/60.png — (`图60`)

/images/posts/Mac安装Homeassistant/59.png — (`图59`)

选择实体(家庭)、配置和次要信息(例如：湿度)

/images/posts/Mac安装Homeassistant/61.png — (`图61`)

翻页时钟

地址：https://github.com/liaoliao007/leoha/

之前 homeassistant 映射的目录是 /home/piliqiu/homeassistant/config

将仓库中 www 目录下的 clock 文件夹放到 /home/piliqiu/homeassistant/config/www 目录下

/images/posts/Mac安装Homeassistant/54.png — (`图54`)

/home/piliqiu/homeassistant/config/
├── ...（其他文件）
└── www/
    └── clock/
        ├── __init__.py
        ├── index.html
        ├── script.js
        └── style.css

/local/clock/index.html 中的 local 表示 www

/images/posts/Mac安装Homeassistant/58.png — (`图58`)

windy天气

/images/posts/Mac安装Homeassistant/55.png — (`图55`)

/images/posts/Mac安装Homeassistant/56.png — (`图56`)

复制网页嵌入代码

/images/posts/Mac安装Homeassistant/57.png — (`图57`)

/images/posts/Mac安装Homeassistant/62.png — (`图62`)

从之前的嵌入代码中复制 src 中的内容粘贴到这里

/images/posts/Mac安装Homeassistant/63.png — (`图63`)

/images/posts/Mac安装Homeassistant/64.png — (`图64`)