搭建HomeAssistant，并通过Ulanzi StreamDeck控制米家设备

前言

想用一个统一的平台控制家里所有智能设备？想用酷炫的Ulanzi StreamDeck物理按键一键控制米家设备？本教程将手把手教你从零开始搭建HomeAssistant（简称HA），并实现对米家设备的控制。无需Linux基础，WIndows 和 macOS 都适用，0经验也能轻松上手！

一、安装Docker环境

HomeAssistant推荐在Docker容器中运行，我们先安装Docker：

1.访问Docker官网下载页面：https://www.docker.com

2.根据自己的系统选择下载，这里先以WIndows系统举例，实际想要时刻能够进行智能家居控制，Docker和HA需要不间断运行，这种情况下macOS的低功耗更适合做HA的主机。

本篇作为入门介绍就不讨论用树莓派等，使用开发板运行HA的方案了

下载Docker Desktop

3. 双击下载的Docker Desktop Installer.exe运行安装，安装完成如下图

安装完成

4.点击Close后，通过桌面图标打开Docker软件，使用如图的选项，因为WSL是Docker的必要环境，这里我们让Docker自动更新WSL，但同时因为Windows的兼容性问题，大家可能会遇到WSL的安装/更新失败的问题，稍后我会在QA中列举一下常见的WSL安装/更新中常遇到的问题。

首次运行Docker Desktop配置界面

5.接下来我们来到了Docker的主界面，需要我们登录账号，我们跳过一下注册过程，来到登录后的界面

注册账号过程遇到网络问题可能需要借助魔法上网

登录后Docker Desktop主界面

注意：首次启动Docker较慢，请耐心等待，直到看到"Docker Desktop is running"提示。

成功启动

至此，Docker环境已成功部署完成。接下来的配置步骤将会像拼装积木一样简单顺畅，您很快就能体验到智能家居带来的便捷与乐趣。

二、下载并运行HomeAssistant容器

1.选中Docker Desktop左侧Images选项，点击上方搜索，输入hass，点击如图中的选中的右侧Pull按钮

搜索hass镜像

2.我们可以看到已经开始下载，在主页面中可以看到进度条，我们等待一下下载过程

下载过慢或没有响应，可能也需要开启魔法上网

下载镜像

下载镜像

3.点击hass右侧的运行按钮运行hass镜像，点击Optional Settings展开更多参数，在Ports栏中填入8123，这一步是将容器内的端口映射到我们本机的8123端口，之后我们点击Run开始运行镜像。

理论上是可以映射到本机的任意端口的，如果出现端口占用现象，可以填写其他端口，随之而然在后面的访问HA过程中，就需要通过localhost: + 填写端口 的方式来访问HA页面

通过镜像创建容器

设置容器运行参数

如果忘记设置Ports，可以删掉创建出来的容器，重复第3步。

4.成功运行后，界面会跳转到Container，通过返回和点击HA可以在下面两个页面切换，此时HA已经安装完成了，我们可以通过localhost:8123来访问HA主页了，但是稍等一下，我们快速安装一下米家的HA插件。

成功运行HA容器

容器列表

三、安装Xiaomi Home集成

1.我们直接点击Exec，进入容器内命令行界面

进入容器命令行

2.复制以下四行命令，通过鼠标右键呼出粘贴选项，粘贴并回车执行，如下图中显示 Please restart Home Assistant表示安装成功，成功重启后Docker中的配置已经全部完成，接下来让我们进入HA页面的配置。

cd /config
git clone https://github.com/XiaoMi/ha_xiaomi_home.git
cd ha_xiaomi_home
./install.sh /config

通过命令安装米家HA插件

放一下米家HA插件的官方链接：https://github.com/XiaoMi/ha_xiaomi_home/blob/main/doc/README_zh.md

四、首次配置HomeAssistant

1.等待HA成功启动，打开浏览器访问：http://localhost:8123，首次进入会看到欢迎界面，选择"创建我的第一个智能家居"，设置用户名和密码（牢记这些信息），输入家庭名称和位置（可随意填写），完成基础设置后会进入HA登录界面，输入我们刚刚设置的用户名和密码，进入HA主界面

首次访问HA

主界面

2.添加米家设备，点击设置->设备与服务，点击右下角的添加集成，在弹出的对话框中搜索并选择Xiaomi Home，根据提示完成小米账号的登录

注意我们需要认证跳转地址是localhost:8123，后面会提到跳转方法

登录小米账号

2.登录完成后修改跳转地址

登录成功后会跳转一个链接，并且提示无法请求，这里我们直接将浏览器上方显示的链接http://homeassistant.local:8123/api/webhook/*** 替换为 http://localhost:8123/api/webhook/*** 并按下回车进行跳转，然后返回上一个标签页HA的页面，可以看到登录成功了。

也有概率出现没有任何响应，笔者中间操作间隔了几分钟，第一次登录出现了没有响应的情况，这时可以从头再登录一次，将HA页面等待登录的弹窗关闭，重新选择Xiaomi Home，登录并修改跳转链接。

首次登录完显示请求失败

修改请求域名为localhost:8123后再次跳转

3.添加设备并通过实体控制设备

登录成功后，勾选我们要加入控制的家庭组设备，点击下一步，会一一确认我们的设备，通常在米家设置好后可以点击跳过并完成

登录成功，勾选我们要加入控制的家庭组设备

可以选择跳过并完成

回到HA的概览界面，我们可以看到我们米家中的设备以及控制实体

设备和实体列表

现在我们已经可以在HA页面上对这些设备进行控制了，通过点击各个设备下的实体切换按钮或是功能按钮，对该设备进行控制。

默认家中的设备是和当前电脑处于同一局域网，不然没法进行控制哦

4.创建HA访问令牌

通过如下步骤，我们可以创建并得到访问令牌，我们会在Ulanzi StreamDeck的控制中用到他，最好找个地方把他保存起来。

创建令牌

记得保存好这个令牌

五、通过Ulanzi StreamDeck来控制米家

1.首先在Ulanzi StreamDeck的官网下载并安装驱动

2.在他们的应用商店中搜索并安装Home Assistant插件

3.在Ulanzi Studio驱动中配置HA插件

这里我们看到需要HA服务器链接，其实就是我们运行的HA容器。

如果HA容器是在本机运行，Ulanzi Studio也在本机，那么Server Url我们直接填写http://localhost:8123

还有种情况是HA容器是在其他机器比如macOS上，我们日常在Windows上使用Ulanzi Studio，这时Server Url需要填写macOS的ip，例如http://192.168.1.103:8123

而另一个参数Access Token就是我们刚刚创建的访问令牌。

配置HA插件

查看运行HA容器主机的ip

输入访问令牌并点击下方的Connect，成功的话我们会进入实体配置的界面

配置实体的界面

示例按键配置：

• 按键1：灯开关

Custom Icon 和 Title主要是配置显示在Ulanzi Deck按键上的信息， 下方的Run Action是配置控制设备功能的区域，比如是开关类的设备，我们首先选择Domain是Button，Service是Press，在Target Entity中选择想要控制的设备，这就完成了一个设备实体的配置。

• 按键2：窗帘开关

常见问题解决

Q: Docker提示WSL安装失败

A: 有一些别人的解决方案可以参考一下 https://www.cnblogs.com/taylorshi/p/13586922.html

Q: HA网页打不开怎么办？ A: 检查hass的容器创建时是否设置Ports。检查Docker是否正常运行，尝试重启Docker服务

Q: 米家设备无法同步？ A: 检查账号是否正确，尝试更换登录方式（如扫码登录）

结语

至此，你已经成功搭建了HomeAssistant中枢，并通过Ulanzi StreamDeck实现了对米家设备的物理按键控制。HA的强大之处在于它的无限可能，后续你还可以接入更多品牌设备，打造真正智能的家居体验。