手把手教程：使用Docker Compose部署HomeAssistant，整合米家与HomeKit

Home Assistant是一个功能强大的开源智能家居自动化平台，其核心目标是协助用户集中控制和自动化家庭内的各类设备与服务。该平台卓越之处在于能够将来自不同品牌、采用不同协议的智能设备无缝整合到一个统一的界面中，从而让用户得以构建高度定制化的智能家居生态系统。

核心安装步骤

本文选择通过Docker Compose方式进行部署，这种方法便于管理且环境隔离性好。

Docker Compose 配置文件

services:
  homeassistant:
    image: homeassistant/home-assistant:latest
    container_name: homeassistant
    network_mode: host
    ports:
      - 8123:8123
    environment:
      - TZ=Asia/Shanghai
    volumes:
      - ./config:/config
    restart: unless-stopped

平台配置与使用指南

成功启动容器后，在浏览器地址栏中输入 http://你NAS的IP地址:8123 即可访问Home Assistant的Web管理界面。

初次启动与基础设置

进入界面后，点击“创建我的智能家居”按钮开始初始化设置。

首先需要创建一个管理员账户，请根据提示填写用户名、密码等信息。

系统会尝试自动检测您的地理位置，如果定位不准确，可以手动在地图上点击或输入具体位置。

在后续的信息共享设置页面，保持默认选项即可，然后点击“下一步”。

至此，基础设置已经完成。

您将成功进入Home Assistant的主仪表板界面。

调整系统单位制

初始设置的温度单位可能为华氏度，我们需要将其调整为国内常用的摄氏度。

点击左下角用户名进入“设置”菜单，然后找到并进入“系统”选项。

在系统设置中，点击打开“通用”子菜单。

在单位制选项中，将温度单位修改为“摄氏度”（°C），修改后务必点击右下角的“保存”按钮。

配置外网访问支持

如果您希望通过外网链接（例如本文演示的飞牛NAS自带的外网访问功能）访问Home Assistant，可能会遇到“400 Bad Request”错误。

此时需要查看Home Assistant的日志。日志中通常会显示类似“untrusted proxy 172.17.0.1”的错误信息，这表示该代理IP未被信任。

解决方法是修改配置文件。进入Docker Compose中映射的config目录，找到名为 configuration.yaml 的核心配置文件。

用文本编辑器打开该文件，在适当位置添加以下配置代码（将日志中报错的IP地址填入trusted_proxies列表中，可以添加多个信任代理）。

http:
  use_x_forwarded_for: true
  trusted_proxies:
    - 172.17.0.1

配置提示：

• 如果您为容器创建了自定义网络，trusted_proxies应填写该网络显示的网关地址。
• 如果使用默认的桥接（bridge）网络，则填写桥接网络的网关地址。
• 如果像本例一样使用了host网络模式，则需填写“::1”。

修改保存配置文件后，回到Home Assistant的“开发者工具”->“YAML配置”页面，点击“检查配置”无误后，选择“重启 Home Assistant”服务以使更改生效。

安装HACS社区商店

HACS是一个强大的第三方集成商店，可以方便地安装众多插件。首先，在映射的config目录下，新建一个名为 custom_components 的文件夹。

访问HACS的GitHub发布页面，下载最新的压缩包文件。 https://github.com/hacs/integration/releases

将下载的压缩包解压，将其中的 hacs 文件夹完整地放入刚才创建的 custom_components 目录内。

放置完成后，同样需要重启Home Assistant服务来加载新的自定义组件。

重启后，进入“设置” -> “设备与服务”。

点击右下角的“添加集成”按钮。

在搜索框中输入“HACS”，找到后点击进行安装。

在确认页面上勾选所有选项，然后点击“提交”。

系统会提供一个链接和验证码。点击链接跳转到GitHub进行授权（需要一个GitHub账号），并输入页面上显示的验证码。

授权成功后，回到Home Assistant，为HACS选择一个在侧边栏显示的位置，点击“完成”。

此时，左侧导航栏就会显示出“HACS”的入口。

点击进入，就可以浏览和安装海量的第三方集成、前端主题等插件了。

集成小米智能家居设备

在HACS中搜索“Xiaomi”，会出现多个相关集成。

“Xiaomi Home”是小米官方提供的集成，“Xiaomi Miot Auto”则是第三方开发的功能更广泛的集成。建议可以先尝试安装官方版本，如果对设备兼容性或功能不满意，再更换为第三方版本。

找到“Xiaomi Home”集成，点击右下角的“下载”按钮进行在线安装（也支持手动下载后放入custom_components目录）。

下载完成后，页面会提示需要重启Home Assistant系统。

重启后，在HACS的“已下载集成”列表中，可以看到“Xiaomi Home”已经安装成功。

现在开始配置集成。再次进入“设置” -> “设备与服务”。

点击右下角的“添加集成”。

搜索“Xiaomi”，选择我们刚才安装的“Xiaomi Home”集成。

等待集成初始化。

阅读说明后，勾选确认框，点击“下一步”。

重要提示：下一步会显示一个形如http://homeassistant.local:8123/...的回调链接。请先尝试在浏览器中直接访问http://homeassistant.local:8123，看是否能正常打开你的Home Assistant界面。如果不能，后续的账号授权步骤可能会失败，但也有对应的解决方法。

点击“下一步”进入账号授权环节。

点击提供的链接，跳转到小米账号登录页面。

输入你的小米账号和密码，完成登录和授权操作。

正常情况下，授权成功后会跳转回一个提示成功的页面。如果未看到此页面，说明前面的本地域名解析可能有问题，请按照以下步骤解决。

在授权等待页面，按键盘F12打开开发者工具，在控制台网络（Network）标签页中，找到一条包含http://homeassistant.local:8123/api/webhook/xxxx的请求，复制这个完整的URL。

新建浏览器标签页，将复制的URL中的homeassistant.local部分替换为你Home Assistant服务器的实际内网IP地址，然后访问这个修改后的链接。

如果操作后提示already_in_progress，可以尝试重启Home Assistant后重新开始添加集成流程。

成功完成授权后，就可以选择要添加到Home Assistant的米家设备了。

建议勾选“导入设备”和“同步房间名”选项，然后点击“下一步”。

系统会列出账号下的所有设备。你可以在此页面为设备分配区域，或直接点击“跳过并完成”快速结束。

添加成功后，所有小米设备都会出现在“设备与服务”的集成列表中。

点击任意设备，可以在详情页中直接进行开关、调节等控制操作。

回到主“概览”仪表板，可以手动添加卡片，将所有小米设备的状态和控制面板集中展示。

搭建HomeKit桥接

安装HomeKit桥接的主要目的，是让苹果设备（iPhone、iPad、Mac等）用户能够通过原生“家庭”App方便地控制已接入Home Assistant的各类设备，特别是米家设备。

进入“设置” -> “设备与服务”。

点击“添加集成”。

搜索“homekit”，选择出现的官方集成。

在集成类型中选择“HomeKit Bridge”。

点击“提交”进入下一步配置。你可以在此选择要将哪些设备或区域暴露给HomeKit，也可以全选后直接提交。

再次确认提交，系统会提示稍后注意通知信息。

为这个桥接器设置一个名称和归属区域，点击“完成”。

完成后，注意查看Home Assistant界面左下角的“通知”区域。

通知里会显示一个二维码和PIN码。打开苹果设备上的“家庭”App，点击“添加配件”，然后扫描此二维码即可将HomeKit桥接添加到家庭中。

重要提示： 如果手机扫描二维码后无法找到设备，请首先检查部署Home Assistant的Docker容器是否使用了host网络模式。如果不是，请修改Docker Compose配置为network_mode: host，然后删除已添加的HomeKit桥接集成，重新添加并生成新的二维码进行扫描。

成功添加桥接后，苹果“家庭”App中会看到一个名为“Home Assistant Bridge”的配件。

接下来，你可以将桥接下的各个设备（如小米灯具、插座等）单独添加到“家庭”App的常用房间或顶部控制中心，从而实现通过iPhone下拉控制中心或Siri进行快速控制。

平台总结与评价

Home Assistant作为一款开源智能家居自动化平台，其最突出的优势在于强大的兼容性与集成能力，能够有效打破不同品牌智能设备间的生态壁垒，实现真正的集中化管理和场景联动。本文简要介绍了通过Docker部署Home Assistant，并整合小米智能家居与苹果HomeKit生态的基本流程，使得iPhone用户也能便捷地操控米家设备。无论您是希望打造复杂的自动化场景，还是仅仅想要一个统一的管理界面来简化日常操作，Home Assistant都是一个极具潜力且值得深入探索的选择。

综合评价：

• 平台推荐度：⭐⭐⭐⭐（实现多生态设备联动的核心枢纽）
• 使用体验：⭐⭐⭐⭐（功能丰富，可扩展性极强，社区活跃）
• 部署难度：⭐⭐（利用Docker后步骤清晰，门槛适中）