外观
群晖虚拟机安装冬瓜 HAOS 并接入米家设备（转载整理）
约 3813 字大约 13 分钟
2026-10-06
原文作者：冬瓜（群晖 NAS 安装教程）、leem（Xiaomi Home 接入教程）。本文按实际使用顺序整合、改写两篇教程，未转载原文截图。群晖安装教程以其提供的 冬瓜 HAOS 18.2 ISO 为例；Xiaomi Home 知识库页面另列有自己的示例版本，不能据此认定两篇文章在同一版本环境下测试。镜像、界面与集成版本请以原站和设备实际情况为准。
生成说明：本文由 OpenAI Codex 辅助整理，并经校对后发布，整理时间为 2026/10/06。
想在群晖 NAS 上运行 Home Assistant，又希望把米家设备接入其中，可以先用 Virtual Machine Manager（VMM）安装冬瓜 HAOS，再配置 Xiaomi Home 集成。下面把两个独立教程串成一条操作路径：准备镜像 → 创建虚拟机 → 写入虚拟硬盘 → 初始化 HA → 授权米家账号 → 验证设备。本文是资料整理，未在具体 NAS 型号上实机验证。
两篇原文记录的环境并不相同，阅读时不要把版本号混成一套：
| 来源 | 原文标注的版本或场景 |
|---|---|
| 群晖安装教程 | 冬瓜 HAOS 18.2 ISO、群晖 VMM |
| Xiaomi Home 知识库 | 冬瓜 HAOS 17.3、Core 2026.6.4、Xiaomi Home 0.4.7 |
这些数字仅用于识别原文示例，不代表当前最新版，也不保证相互兼容。实际下载、升级和选择集成版本前，以原站最新说明与当前 HA 系统状态为准。
开始前核对
- 确认机型和资源。在群晖套件中心确认 NAS 能安装 VMM，并查看 CPU、内存和剩余空间。VMM 只支持部分机型；可运行多少台虚拟机还取决于可用内存，见群晖说明。不要把 NAS 的全部内存分给 HA 虚拟机。
- 准备 VMM 存储。检查是否已有可供 VMM 使用的存储空间。群晖的 VMM 存储帮助说明，VMM 虚拟机存储需要 Btrfs 存储空间；若首次配置向导没有可选卷，先检查卷类型和剩余容量。
- 下载镜像。从冬瓜 HAOS 原安装教程的版本下载入口取得对应 ISO，核对文件扩展名、架构和版本。本文跟随原文的 ISO 安装路径；群晖 VMM 也支持导入磁盘镜像，但那是另一种流程，不能把
img文件改名为iso后照做。 - 确认网络。记录 NAS 的 IP、局域网网段和路由器地址。例如 NAS 在
192.168.31.x网段，HA 虚拟机也应接到能取得该网段地址的虚拟交换机。手机、电脑能访问 HA，且设备网络符合原知识库的同一局域网要求时，后续配置较容易核对。 - 准备账号。准备一台能打开 DSM 的电脑，以及已登录米家 App 的手机。先确认待导入设备在米家 App 的正确账号、家庭和地区下。米家授权阶段需要手机扫码或账号验证。
先把这些信息记下来，之后排错会快很多：
| 项目 | 自己的值 | 用在何处 |
|---|---|---|
| DSM 管理 IP | 按实际填写 | 安装 VMM、打开虚拟机控制台 |
| VMM 存储空间 | 按实际填写 | 放置 ISO 和虚拟硬盘 |
| 虚拟交换机／网络 | 按实际填写 | 让 HA 接入家庭网络 |
| HA 虚拟机 IP | 创建后填写 | 访问 8123、8124、7681 端口 |
| 米家账号的地区和家庭 | 按实际填写 | 选择导入设备范围 |
一、在群晖安装并初始化 VMM
- 登录 DSM，打开套件中心，搜索 Virtual Machine Manager 并安装。若搜不到或提示不支持，先核对 NAS 型号与 DSM 版本，不要继续套用后面的界面步骤。
- 第一次打开 VMM 时，跟随向导选择用于虚拟机的存储空间。完成后到 VMM 的存储空间页面，确认所选卷可用、剩余空间足够；如果显示空间不足，先处理存储问题。
- 到 VMM 的网络页面，找到连接家庭局域网的虚拟交换机。记录其名称，创建虚拟机时要选它。若选到了隔离网络，HA 可能已正常启动，却无法从手机或电脑访问。
二、上传镜像并创建虚拟机
上传 ISO
在 VMM 的映像档／映像文件 → ISO 文件 → 新增中，选择从电脑上传已下载的冬瓜 HAOS ISO，并选择存放它的 VMM 存储空间。上传完成后，检查列表中的文件名和状态，再继续。群晖映像档帮助说明，ISO 所在存储空间必须可供这台虚拟机使用；手动上传时不要关闭或刷新浏览器。
创建虚拟机
在 VMM 的虚拟机 → 新增／创建中打开向导，按页面逐项核对：
| 页面 | 应检查的内容 |
|---|---|
| 操作系统与存储 | 选择运行 Linux 的虚拟机；存储空间选刚才准备好的 VMM 存储 |
| 名称与计算资源 | 给虚拟机取易辨认的名称，例如 WinterMelon-HAOS；CPU、内存按 NAS 剩余资源分配，不照抄别人的机型数值 |
| 虚拟硬盘 | 新建一块专供 HAOS 使用的虚拟硬盘，确认容量和接口；稍后的安装会覆盖这块盘的内容 |
| 网络 | 将虚拟网卡接到前一步记录的家庭局域网虚拟交换机 |
| 启动媒体 | 选择刚上传的冬瓜 HAOS ISO 作为启动镜像 |
| 权限与摘要 | 确认当前 DSM 账号有管理权限；提交前复核 ISO、虚拟硬盘和网络选择 |
群晖的虚拟机帮助列有这些向导项目，以及虚拟硬盘接口、虚拟网卡、启动 ISO 等选项。不同 DSM 版本的按钮文字可能稍有区别。原冬瓜教程主要以截图展示各页设置，本文没有把截图中的硬件参数当作通用推荐值。
从 ISO 写入 HAOS
- 创建完成后启动虚拟机，点连接打开 VMM 控制台。先确认看到 ISO 的启动环境；如果直接显示“找不到启动设备”，回到设置检查 ISO 是否挂载、启动媒体是否正确。
- 按原教程，进入桌面后双击“安装冬瓜 HAOS 到硬盘”；在随后出现的安装菜单中输入
1并回车。确认安装目标是刚创建的虚拟硬盘，再执行写入。安装会覆盖目标盘，不应选到保存其他系统或数据的磁盘。 - 等待写入完成。原文给出启动约两分钟、写盘约三分半钟的示例，但实际速度取决于 NAS 性能和存储负载；以控制台提示完成为准。
- 按教程关闭虚拟机，卸载安装 ISO，或将虚拟硬盘调整到 ISO 之前的启动顺序，然后再开机。检查控制台是否进入 HAOS，而不是又回到安装环境。
写盘结束并不等于 Home Assistant 已经初始化完成。第一次从虚拟硬盘启动后，冬瓜 HAOS 还会准备预装的应用和集成。此时先保持虚拟机运行，不要因为网页暂时打不开就重新写盘。
三、完成首次初始化
原教程提供两种查看初始化状态的入口：
| 入口 | 原教程地址 | 用途 |
|---|---|---|
| 冬瓜 HAOS 伴侣 | http://homeassistant.local:8124/ | 查看图形化初始化信息 |
| TTYD | http://homeassistant.local:7681/ | 在终端中运行 ha-install -t 查看进度 |
建议先在控制台或路由器的设备列表中找到 HA 虚拟机 IP，填回前面的记录表。homeassistant.local 依赖局域网名称解析，部分电脑或网络环境可能无法识别；这时用查到的 IP 代替主机名即可，例如 http://<HA的IP>:8124/。端口对应的服务和访问协议仍以当前镜像实际提供的地址为准。
在伴侣或 TTYD 确认初始化完成后，按原教程重启，再打开 https://homeassistant.local:8123。如果当前安装页给出的是 http，就按其提示访问；不要在不确认的情况下反复更改证书或反向代理。看到 Home Assistant 的首次注册页面后创建管理员账号，完成地点、时区等基本设置，并确认能够再次登录。到这里才进入米家接入阶段。
四、接入 Xiaomi Home
冬瓜 HAOS 的知识库教程称其镜像预装 Xiaomi Home。先到 Home Assistant 的设置 → 设备与服务查看是否能搜索到该集成。如果升级后集成缺失，原教程提供了通过冬瓜伴侣“在线小工具 → 集成 → 安装 xiaomi_home 集成”重新安装的路径；也可参考小米官方项目的 HACS 安装说明。安装或更新后若页面仍找不到集成，先检查 HA 是否需要重新加载或重启，再核对集成版本和安装位置。
按向导登录米家
- 在 HA 中打开设置 → 设备与服务 → 添加集成，搜索 Xiaomi Home。不同版本的“设备与服务”也可能写作“集成与服务”。
- 阅读集成提示并勾选确认，进入下一步。原知识库随后要求勾选集成网络配置与检测网络依赖项，依次等待检查完成。若网络检查失败，先确认 HA 虚拟机已取得 IP、能访问所需网络，再继续授权。
- 点击“请点击此处进行登录”，使用米家 App 扫码；如果选择账号登录，按页面完成短信等验证。确认页面显示的授权对象后再同意授权。
- 若授权后出现白页，先看浏览器地址栏。原知识库的处理方法是：当回调网址中的主机名确为
homeassistant.local、而你的网络无法解析它时，只把这个主机名替换成 HA 虚拟机的局域网 IP，保留协议、端口、路径和查询参数，再回车。先确认整个回调仍指向自己的 HA，避免把授权信息发往其他地址。 - 返回 HA 后，选择需要导入的米家家庭。若 HA 与米家 App 中的家庭和房间名称已经一一对应，可按向导使用名称匹配；若还没有规划，先采用默认导入方式，后续在 HA 整理区域。
- 检查向导显示的可导入设备列表，按需要选择，再点完成。到设置 → 设备与服务 → Xiaomi Home查看设备、实体数量，并找一台可控设备测试状态读取和开关等操作，确认接入成功。
这一步是把米家设备导入 Home Assistant，不会把 HA 中的其他设备反向同步到米家 App。小米官方项目也明确说明两者的方向和支持范围；部分蓝牙、红外及虚拟设备不受支持，具体仍以项目说明及实际导入结果为准。
五、设备变化后更新列表
以后在米家 App 添加、移除设备，或想改变导入范围时，到设置 → 设备与服务 → 已配置 → Xiaomi Home → 配置，选择更新设备列表。知识库中的完整检查顺序可以简化为：
- 打开 Xiaomi Home 集成卡片的配置，勾选需要更新的项目，进入设备列表更新向导。
- 如以前做过设备筛选，检查筛选选项及列出的设备，避免把原本排除的设备重新导入，或把需要的设备排除掉。
- 勾选确认更新；若向导询问本地网卡，选择 HA 虚拟机实际使用的接口。原教程中的
endX是其盒子环境的例子，群晖虚拟机里的接口名可能不同。 - 在提交页复核选择，确认修改并完成。回到集成卡片检查设备数量，再查看一台新设备是否生成了可用实体。
若设备没有出现，先核对米家 App 中的账号、家庭与地区，接着检查 HA 网络和集成的设备筛选设置。Xiaomi Home 不保证所有设备品类都能导入；原知识库建议对不适配的设备按需研究 Xiaomi Miot，但应先确认不会重复导入同一设备。
六、遇到问题时怎么查
| 现象 | 先检查什么 |
|---|---|
| VMM 没有可用存储 | NAS 机型、Btrfs 卷、VMM 存储空间及剩余容量 |
| 上传了 ISO，虚拟机却不能启动 | 镜像上传是否完整、ISO 是否挂载、启动媒体和虚拟硬盘设置 |
| 写盘后又回到安装界面 | 是否仍从 ISO 启动；关机后卸载 ISO 或调整启动顺序 |
| HAOS 控制台正常，网页打不开 | 虚拟机是否取得 IP、是否接对虚拟交换机、电脑与 HA 是否互通，以及使用的端口和协议 |
| 小米授权后白屏 | 回调网址是否仍包含无法解析的 homeassistant.local；只在核对目的地后替换主机名 |
| 米家 App 有设备，HA 中没有 | 登录账号、地区、家庭、设备筛选与 Xiaomi Home 支持范围；再尝试更新设备列表 |
| 设备已导入但不能控制 | 先核对设备和实体状态，再看集成诊断、网络与云端连接；不要把“已导入”直接当作“可本地控制” |
排查顺序建议从虚拟机是否正常启动开始，再看局域网连通、HA 页面、米家授权，最后看单个设备。这样可以避免在底层网络未通时反复重装集成。
使用时留意
小米官方项目说明，Xiaomi Home 采用 OAuth 登录，不会在 HA 中保存米家账号密码；但账号相关的设备信息、证书和令牌会保存在 HA 配置中。备份、迁移虚拟机或分享配置文件时，应保护这些数据。如果怀疑令牌泄露，可按官方项目文档中的路径在米家账号管理页面取消授权。
“设备能在 HA 中看到”也不等于“所有操作都走局域网”。小米官方说明，没有满足条件的中枢网关时，控制命令可能经小米云转发；其局域网控制选项只适用于部分同网段 IP 设备，且项目文档提示可能出现异常。只有确有需要并理解设备支持范围时再调整该选项。
原文与参考资料：冬瓜 HAOS 群晖安装教程 · 冬瓜 HAOS Xiaomi Home 知识库教程 · 小米 Xiaomi Home 集成项目 · 群晖 VMM 帮助