中文 English

告别卡死 20 分钟！从零安装冬瓜 HAOS 保姆级教程：破除原版网络死锁、3 分钟傻瓜刷机与 8124 伴侣全自动接管（附三端一键工具箱）

发布时间: 2026-10-29 · 阅读量 --
homeassistant HA 智能家居 新手教程 Beginner 自动化 Automation 故障排查 Troubleshooting 自托管 Self-hosting

如果你在智能家居论坛或视频网站搜过 Home Assistant（简称 HA），你一定被那些酷炫的全屋3D楼层图、跨品牌无感联动（苹果 HomeKit 丝滑控制米家、美的空调与国家电网电费预警）馋得心痒痒。

然而，残酷的现实是：超过 80% 满怀热情的新手，甚至都没能活着见到 Home Assistant 的注册登录界面，就已经在安装的第一步彻底崩溃退坑了。

多少人兴冲冲地买来小主机、腾出旧电脑或者在 NAS 里建好虚拟机，千辛万苦刷入官方原版 HAOS 镜像，开机后打开浏览器，迎面而来的却是那句让人绝望的英文： Preparing Home Assistant (this can take up to 20 minutes or more)… 说好的 20 分钟，结果你从晚上八点等到凌晨两点，进度圈还在不知疲倦地空转；偶尔刷新一下，干脆弹出刺眼的红字报错 Error installing Home Assistant。好不容易折腾进去了，又发现里面空空如也——没有 HACS 社区商店，下载任何国内插件都提示连接 GitHub 超时，连最基础的小米、美的设备都接不进去。

难道普通人想在家里搭一套稳定好用的智能家居中枢，就非得先考一个 Linux 运维与网络工程专家证吗？

当然不需要！国内开源社区打造的冬瓜 HAOS（wghaos），正是为了彻底终结这一痛点而生。它不仅在底层内置了国内高速镜像源与预装核心环境，更首创了「8124 冬瓜伴侣」全中文可视化驾驶舱。今天这篇保姆级长文，就带你从底层根因讲起，手把手教你用最傻瓜的方式 3 分钟刷入冬瓜 HAOS，哪怕你是零代码基础的纯小白，也能一次点亮、拎包入住！

原创题图：告别卡死 20 分钟！冬瓜 HAOS 零门槛保姆级安装全攻略

图 1：本文原创题图。全景展示从破除原版网络死锁、三分钟傻瓜写盘到 8124 冬瓜伴侣可视化接管的完整交付链路。

问题背景与表现：为什么原版 HAOS 总把新手卡在门外？

在动手安装之前，我们先复盘一下无数智能家居新手在安装官方原版 Home Assistant OS 时遭遇的三大典型翻车现场：

  1. 表现一：永恒的「20 分钟准备中」死循环 镜像顺利写入硬盘、设备正常开机并获取到了局域网地址。但当你满怀期待地打开浏览器访问 8123 端口时，页面一直停留在蓝白相间的「正在准备 Home Assistant」界面。后台日志每隔几分钟就重复一次超时重试，等上一整晚也无法进入创建账号界面。

  2. 表现二：黑底白字的 ha > 命令行恐慌 把显示器接到主机上，屏幕上既没有熟悉的图形桌面，也没有安装进度条，只有一串英文启动字符和一个绿色的 ha > 光标在闪烁，并且顶部赫然提示 Home Assistant Core: landingpage。新手完全不知道系统究竟是在正常下载，还是已经死机变砖。

  3. 表现三：进得去系统，却寸步难行 哪怕趁着半夜网络通畅侥幸完成了初始化，进入系统后立刻遭遇第二波毒打：官方默认不带 HACS（Home Assistant 社区应用商店），想装个小米官方集成、美的局域网插件或者网上国网电费插件，全都因为无法拉取海外代码仓库而频频报错，每走一步都要手动敲命令改配置。

问题分析与底层根因：跨国海淘毛坯房 vs. 精装拎包入住

为什么一个几十兆、几百兆的系统镜像，开机后却要联网折腾这么久？我们用小学生都能听懂的「买房装修」大比方，结合底层容器架构来扒开它的真实根因。

原创根因图：原版跨国海淘毛坯房与冬瓜版精装拎包入住公寓对比

图 2：小学生秒懂比方。为什么原版 HAOS 像「开机才去海外海淘家具的毛坯房」，而冬瓜 HAOS 则是「配齐国内专线与物业管家的精装房」。

1. 原版 HAOS 的真相：你刷进去的其实只是个「空壳毛坯房」

很多新手误以为：我下载了官方几百 MB 的 HAOS 镜像刷进硬盘，Home Assistant 主程序就已经在硬盘里了。 其实完全不是！ 为了压缩体积并保持永远最新，官方 HAOS 镜像里真正装的，只是一个极简的 Linux 底座、一个名叫 Supervisor 的包工头，以及一个只有几 MB 大小的临时占位网页（也就是你看到的 landingpage，俗称「毛坯房看房牌」）。

当你第一次插上电源开机时，包工头 Supervisor 才刚刚睡醒，开始临时去海外跨国采购真正的「床、沙发、家电」（即高达数 GB 的 homeassistant 核心容器镜像）。在这个过程中，它必须连续闯过四大残酷的网络关卡：

2. 冬瓜 HAOS 是如何从根因上破局的？

搞清楚了上面四大根因，你就能瞬间明白为什么冬瓜 HAOS（wghaos）被国内玩家尊称为「救命神器」：

  1. 底层指向 r.hassbus.com 国内高速镜像源 + haos-turbo 加速引擎： 冬瓜团队在系统底层将所有核心容器与加载项仓库重定向至专门维护的国内高速镜像节点（如 r.hassbus.com），并内置了 haos-turbo 加速服务。别人跨国海淘家具要卡一整夜，冬瓜版直接从同城中心仓极速发货，几分钟满速拉完！
  2. 首创 8124 冬瓜伴侣（可视化物业大堂管家）： 彻底告别黑盒盲等！开机后直接打开 8124 端口的中文网页，当前正在初始化第几步、32 层容器下载到了第几层、网络通不通、时间准不准，像查顺丰快递物流一样一清二楚。
  3. 预置 HACS 极速版与 19 项一键自愈工具： 出厂即帮你配好了极速版 HACS 社区商店和常用基础组件；万一遇到晚高峰网络波动、忘记密码或 Supervisor 抽风，在网页上点一下红色按钮就能一键换源、一键同步时间、一键修复，全程无需敲一行代码！

新手选型避坑：为什么强烈推荐冬瓜 HAOS 而不是裸跑 Docker？

很多稍微懂一点 NAS 或 Linux 的朋友会问：「我直接在群晖或软路由的 Docker 里拉一个 homeassistant/home-assistant 容器不就行了吗？干嘛非要装整套冬瓜 HAOS 系统？」

这是一个会让新手在未来三年里后悔无数次的经典分岔路！我们再用一个「独栋精装别墅 vs. 合租单间」的比方来彻底讲透：

原创选型图：冬瓜 HAOS 独栋别墅与 Docker 容器单间的本质区别及硬件选型矩阵

图 3：原创选型避坑图。裸跑 Docker 容器天生阉割了加载项商店与 Supervisor 总管，而冬瓜 HAOS 则是功能满血的独栋智能别墅。

对号入座：你的硬件该下载哪个冬瓜 HAOS 镜像？

截至 2026 年 10 月，冬瓜 HAOS 官方最新稳定版本为 18.3.1（可前往官方固件站 fw.wghaos.com 或官网 wghaos.com 获取）。请根据你手头的硬件对号入座：

你的硬件环境 推荐下载的冬瓜固件类型 文件名特征与核心优势
PVE / 群晖 VMM / 爱快 / VMware 虚拟机（最推荐新手） 64 位 Win10PE 万能安装版 ISO win10pex64-wg-haos18.3.1.iso：挂载光驱开机双击脚本即装完，免去手动转盘与扩容烦恼
X86 物理小主机（如 N100 / J4125 / 旧笔记本） 64 位 Win10PE 万能安装版 ISO 或 PC 原生版 用 Ventoy U 盘启动 PE 一键写盘，底层刷入 haos_x86-64-pc_cn-18.3.1，直接调用真实 CPU 指令集
老旧 32 位引导主板（如 Z3735F 收银机/平板主板） 32 位 IA32 专用 PE 安装版 ISO win10pex86-wg-haos18.3.1.iso：专治奇葩 32 位 UEFI 主板无法引导 64 位系统的难题
直接导入虚拟磁盘的老玩家（ESXi / VirtualBox 等） X86-64 VM 虚拟机专用镜像 haos_x86-64-vm_cn-18.3.1…img.xz：采用 QEMU 通用驱动，注意导入后需手动将虚拟硬盘扩容至 32GB+
ARM 电视盒子 / 开发板（树莓派 / 斐讯 N1 / X88Pro20 等） 对应机型的 ARM 专属刷机包 按芯片型号（如 RK3566、S905X3、H618、树莓派 4/5）下载专用包，配合 8122 冬瓜工具箱写入 eMMC

[!TIP] 小白无脑首选方案：只要你用的是普通电脑、X86 小主机、软路由虚拟机（PVE / 爱快）或群晖 NAS 虚拟机，一律推荐下载 win10pex64-wg-haos18.3.1.iso（PE 万能安装镜像）！它把复杂的底层写盘和分区扩容全包在了图形化界面里，真正做到零门槛。

保姆级实操第一步：虚拟机（PVE / NAS）与物理机黄金参数配置

下面我们以目前最主流、最稳妥的 PVE 虚拟机（群晖 VMM / VMware / 物理机 BIOS 设置同理） 为例，手把手带你完成安装前的黄金参数设定。

这里有两个哪怕老手也经常栽跟头的致命开关，我们先用大白话搞懂它们：

  1. 为什么要把 BIOS 改成 OVMF (UEFI)，绝对不能用默认的 SeaBIOS？ 打个比方：老式 SeaBIOS (Legacy MBR) 就像几十年前的老式铁片机械钥匙，而现代的冬瓜 HAOS 系统大门装的是智能电子芯片门禁（UEFI GPT 分区表）。如果你拿着老式铁钥匙去捅电子门禁，开机的第一秒就会直接黑屏卡死在 Booting from Hard Disk…，永远进不去系统！
  2. 为什么虚拟机的 CPU 类别强烈建议选 host？ 默认的虚拟 CPU（如 kvm64 或 qemu64）就像隔着一个翻译官传话，很多现代 CPU 的加密与加速指令集被屏蔽了；而选择 host（宿主直通），相当于让冬瓜 HAOS 直接借用你物理机 CPU 的真实大脑，不仅内置的 x86-64-pc 原生版固件能满血运行，初始化解压容器的速度也能快上一倍！

详细建机四步曲（对照真实截图操作）

  1. 上传 ISO 镜像并选择操作系统介质： 将下载好的 win10pex64-wg-haos18.3.1.iso 上传到虚拟机的 ISO 镜像库中。点击「创建虚拟机」，在「操作系统」标签页选择刚才上传的 PE 镜像文件，客户机操作系统类别保持默认的 Linux 即可。

  2. 系统固件（核心避坑点！必选 OVMF UEFI）： 切换到「系统」标签页，严格按照下图红框指示进行配置：

真实截图：虚拟机系统配置页面将 BIOS 设定为 OVMF UEFI 模式

图 4：真实配置截图（节点信息已脱敏）。在系统选项卡中，BIOS 必须下拉选择 OVMF (UEFI)，并取消勾选下方的「添加 EFI 磁盘」。

  1. 磁盘与 CPU 配置（SATA 32GB+ 与 Host 内核直通）：
    • 在「磁盘」标签页中，将总线/设备选为 SATA（微 PE 环境对 SATA 硬盘识别最稳，无需额外打 VirtIO 驱动），磁盘大小分配 32 GiB 或以上；
    • 切换到「CPU」标签页，按照下图红框指示设置：

真实截图：虚拟机 CPU 配置页面分配 2 核心并将类别选为 host 直通

图 5：真实配置截图（节点信息已脱敏）。CPU 核心建议 2 核起步，右侧「类别」下拉滑到最底部选择 host（真实内核直通）。

保姆级实操第二步：WinPE 三分钟傻瓜式一键刷入硬盘

无论你是配置好了上面的虚拟机，还是用 Ventoy 把 ISO 放进 U 盘插在了物理小主机上，接下来的刷机过程简单到连小学生都能闭着眼睛完成：

  1. 启动进入微 PE 桌面： 点击虚拟机「启动」并打开控制台窗口（物理机开机按快捷键选择从 U 盘 UEFI 启动）。等待约 30 秒，你会看到一个清爽的蓝色星空 Windows 10 PE 桌面，桌面上静静地躺着一个图标：「双击安装冬瓜HAOS到硬盘」。

  2. 双击运行并输入数字 1 回车： 双击该桌面图标，会弹出一个黑色的命令行安装器窗口，自动列出内置的冬瓜 HAOS 固件包编号。你只需要在键盘上敲一个数字 1，然后按下回车键（Enter）！

真实截图：在 WinPE 桌面运行安装脚本输入数字 1 自动将冬瓜 HAOS 写入硬盘

图 6：真实刷机截图。输入数字 1 回车后，脚本以近 50 MB/s 的速度全自动将冬瓜 HAOS 镜像写入目标硬盘，耗时仅约 2 分钟。

  1. 看到「安装完成」后：关机 -> 拔光盘/U盘 -> 重新开机！ 等待大约 2 分钟，窗口底部会清晰打印出： 冬瓜HAOS X86-PC版安装完成！可以关机重启了！！！

    [!IMPORTANT] 新手最容易忘的动作（必看！）： 先将虚拟机或物理机彻底关机：

    • 如果你是物理机：关机后务必拔掉 U 盘，再按电源键开机！
    • 如果你是 PVE / 群晖 / VMware 虚拟机：关机后进入虚拟机的「硬件 -> CD/DVD 光驱」，选择「不使用任何介质（移除 ISO 挂载）」，然后再点击启动！否则下次开机它又会重新进一遍 PE 桌面！

首次开机不迷路：小学生秒懂的「黄金三端口」与可视化接管

拔掉 U 盘（或卸下虚拟光驱）重新开机后，真正的魔法开始了！

以前装原版 HAOS，开机后你只能对着屏幕干瞪眼。而在冬瓜 HAOS 中，系统为你准备了三个各司其职的网页端口。为了让你彻底分清它们，我们把冬瓜 HAOS 比作一栋刚刚交付的「未来智能大厦」：

原创架构图：智能大厦的三个窗口 8124 冬瓜伴侣、7681 网页终端与 8123 主界面分工

图 7：原创「智能大厦三窗口」比方。开机先去 8124 物业大堂看装修进度，需要查底层水电去 7681 工程通道，装修 100% 完毕后再从 8123 正门拎包入住！

第一站：打开 8124 冬瓜伴侣（物业监控大堂）

设备开机后等待约 2~3 分钟，打开同一局域网下的电脑或手机浏览器，在地址栏输入： http://homeassistant.local:8124/ （如果路由器不支持 .local 域名解析，也可以直接用路由器后台查到的设备局域网地址加 :8124 访问）。

映入眼帘的就是冬瓜 HAOS 最引以为傲的独门武器——冬瓜 HAOS 伴侣（工作台）：

真实截图：冬瓜 HAOS 伴侣 8124 端口实时展示四阶段初始化进度与容器下载层数

图 8：冬瓜伴侣（8124 端口）真实初始化截图（右上角局域网地址已脱敏）。四阶段进度条、七大核心容器状态与镜像拉取层数一目了然。

看看这张界面有多贴心：

  1. 顶部状态栏：直接显示当前主机网络与 Supervisor 网络是否正常，以及磁盘空间占用比例；
  2. 四阶段初始化进度条：将首次开机过程拆解为 1 初始化系统 → 2 预装集成 → 3 预装加载项 → 4 启动完成 四个可视节点；
  3. 七大组件健康灯：实时显示 supervisor、cli、dns、audio、observer、multicast、core 七个底层容器哪些已经打上绿勾 ✓，哪些正在转圈启动；
  4. 实时拉取层数进度：右下角精确到「已完成 8/32 层、当前下载大小与总进度百分比」，让你彻底告别原版 HAOS 的盲目焦虑！

当你在 8124 页面看到四个阶段全部打勾、总进度达到 100%，并弹出「初始化完成，请先重启系统」的提示框时，点击红色的「重启」按钮，等待 1 分钟，你的智能家居系统就彻底装好了！

第二站：认识 7681 网页终端与伴侣 19 项一键自愈神技

在等待或日常使用过程中，如果你是个喜欢探究底层的极客，或者遇到了特殊网络环境故障，冬瓜 HAOS 还提供了两套免工具排障方案：

1. 7681 端口：免装 SSH 客户端的网页命令行（TTYD）

不需要在电脑上安装 Putty、Xshell 或配置繁琐的 SSH 密钥，直接在浏览器访问： http://homeassistant.local:7681/ 即可在网页里直通系统后台终端：

真实截图：通过 7681 端口直接在浏览器打开 Home Assistant 命令行终端

图 9：7681 端口 TTYD 网页终端真实截图（内网地址已做脱敏遮蔽）。在网页内即可直查系统版本、网络接口状态与实时安装日志。

2. 冬瓜伴侣「常规维护」：专治疑难杂症的 19 个红色按钮

对于不喜欢敲命令的新手，点击 8124 冬瓜伴侣左侧菜单的「常规维护」（注：需先点击右上角使用 HA 账号或创建本地伴侣管理员登录），你会打开一个堪称「智能家居急诊室」的百宝箱：

真实截图：冬瓜 HAOS 伴侣常规维护面板内置 19 项一键修复与管理工具

图 10：冬瓜伴侣「常规维护」真实截图。将原本需要资深工程师敲几十行命令才能搞定的排障操作，全部浓缩成了点一下就能生效的红色按钮。

这里挑几个对新手最有用的救命按钮重点介绍：

第三站：正式入住 8123 主界面与首日必做三件事

当 8124 伴侣提示初始化完成并重启后，在浏览器访问： http://homeassistant.local:8123/ （或者直接点击伴侣右上角的红色「HA 登录页」按钮），久违的蓝色小房子欢迎界面就会秒级跃然屏上！

真实截图：冬瓜 HAOS 初始化完成后在 8123 端口呈现的欢迎创建智能家居页面

图 11：8123 端口 Home Assistant 官方欢迎页面真实截图。点击「创建我的智能家居」即可开始你的全屋自动化之旅（或直接从旧备份包一键还原）。

点击「创建我的智能家居」后，请务必顺手完成以下首日必做三件事，为后续稳定运行打下地基：

  1. 用户名强烈建议使用纯英文小写： 「姓名」可以填中文昵称（显示在左下角），但登录用的「用户名」请务必使用纯英文（如 admin 或你的英文名），避免个别老旧第三方插件在调用路径或认证接口时因中文字符出现编码兼容性问题。
  2. 检查并确认「公制单位（Metric）」与时区： 在定位与单位设置步骤中，确认时区为 Asia/Shanghai，单位制式选择「公制（摄氏度 °C、千克、千米）」。如果漏选导致温度显示成了华氏度（°F），可随时在「设置 → 系统 → 通用」中改回公制并点击保存。
  3. 立即打第一个纯净基线备份： 刚装好系统、HACS 和基础环境都健康就绪时，进入「设置 → 系统 → 备份」，点击右下角创建一个名为 Clean-Baseline-18.3.1 的完整备份并下载到电脑保存。有了这个「复活币」，以后你再怎么大胆折腾新插件，随时都能在 3 分钟内还原回刚装好时的完美状态！

三端零依赖一键自动化工具箱：从镜像校验到三端口就绪巡检

虽然冬瓜 HAOS 已经把刷机简化到了极致，但很多新手在实际操作时依然会遇到：「不知道该去哪复制最新 18.3.1 镜像直链」「PVE 建虚拟机时怕手滑选错 BIOS 和磁盘参数」「开机后打不开页面，分不清到底是 .local 域名没解析出来，还是 8124 还在拉取镜像」。

为了把「保姆级体验」做到极致，我将官方固件源匹配、本地 SHA256 下载校验、PVE 黄金参数生成，以及 8124 / 7681 / 8123 三端口并发探针与就绪守候逻辑，封装成了一个零第三方依赖的跨平台开源工具箱（wghaos-beginner-toolkit）：

原创流水线图：三端零依赖自动化辅助工具箱从固件匹配到三端口巡检闭环

图 12：原创工具箱流水线。固件匹配与建机指令生成、三端口并发探针巡检、就绪守候与脱敏健康报告三步闭环。

工具箱完整压缩包下载：冬瓜 HAOS 新手一键安装与三端口巡检工具包 (ZIP)。

工具箱核心安全设计

方法一：人工一键全自动执行指南（三大操作系统全覆盖）

请根据你手头电脑的操作系统，复制对应的一键脚本直接运行：

1. Windows 11（PowerShell 7 / Windows PowerShell）

打开 PowerShell 窗口，执行以下命令即可一键完成固件规划、下载校验与三端口开机巡检：

# 1. 下载并解压冬瓜 HAOS 新手辅助工具包（或直接使用已解压目录）
$ToolkitUrl = "https://blog.margrop.net/downloads/home-assistant-wghaos-beginner-install-guide/wghaos-beginner-toolkit.zip"
Invoke-WebRequest -Uri $ToolkitUrl -OutFile "wghaos-beginner-toolkit.zip"
Expand-Archive -Path "wghaos-beginner-toolkit.zip" -DestinationPath ".\wghaos-toolkit" -Force
Set-Location ".\wghaos-toolkit"

# 2. 设置目标主机名（默认使用 mDNS 域名，不硬编码任何完整内网 IP）
$env:WGHAOS_HOST = "homeassistant.local"

# 3. 三步全自动执行：生成黄金参数 -> 探测三端口状态 -> 守候 8123 就绪
.\windows-11.ps1 plan --edition x86-64-pe
# 如需自动下载官方 18.3.1 PE 镜像并校验 SHA256，取消下一行注释：
# .\windows-11.ps1 fetch --edition x86-64-pe --out-dir .\downloads
.\windows-11.ps1 probe
.\windows-11.ps1 wait --timeout 1200 --interval 15

2. Ubuntu 26.04 LTS（Bash）

在 Ubuntu 26.04 终端或 PVE 宿主机 Shell 中，一键运行：

#!/usr/bin/env bash
set -euo pipefail

# 1. 获取并解压零依赖工具箱
mkdir -p ./wghaos-toolkit && cd ./wghaos-toolkit
curl -fsSL "https://blog.margrop.net/downloads/home-assistant-wghaos-beginner-install-guide/wghaos-beginner-toolkit.zip" -o toolkit.zip
unzip -oq toolkit.zip

# 2. 指定局域网目标主机标识
export WGHAOS_HOST="homeassistant.local"

# 3. 预览 18.3.1 固件源与 UEFI 建机指令、探测 8124/7681/8123 端口并守候就绪
bash ubuntu-26.04.sh plan --edition x86-64-pe
# 如需直接拉取官方固件镜像，取消下一行注释：
# bash ubuntu-26.04.sh fetch --edition x86-64-pe --out-dir ./downloads
bash ubuntu-26.04.sh probe
bash ubuntu-26.04.sh wait --timeout 1200 --interval 15

3. macOS 27（Zsh）

在 macOS 27 的终端（Terminal / iTerm2）中，直接粘贴执行：

#!/usr/bin/env zsh
set -euo pipefail

# 1. 下载并进入工具箱目录
mkdir -p ./wghaos-toolkit && cd ./wghaos-toolkit
curl -fsSL "https://blog.margrop.net/downloads/home-assistant-wghaos-beginner-install-guide/wghaos-beginner-toolkit.zip" -o toolkit.zip
unzip -oq toolkit.zip

# 2. 设置目标主机地址（优先通过 Bonjour/mDNS 自动发现）
export WGHAOS_HOST="homeassistant.local"

# 3. 一键执行规格检查、三端口连通性诊断与初始化就绪守候
zsh macos-27.sh plan --edition x86-64-pe
# 如需自动下载官方镜像并计算 SHA256 校验值，取消下一行注释：
# zsh macos-27.sh fetch --edition x86-64-pe --out-dir ./downloads
zsh macos-27.sh probe
zsh macos-27.sh wait --timeout 1200 --interval 15

方法二：交给你的 AI 运维 Agent 全自动配置与巡检

如果你正在使用 Claude Code、Codex、OpenClaw 或 Gemini CLI 等本地 AI Agent 助手，无需自己动手敲命令，直接把下面这段标准提示词发给你的 Agent，它就会全自动帮你完成从环境检查到三端口就绪验收的全过程：

你现在是我的 Home Assistant 与冬瓜 HAOS (wghaos) 专属自动化部署专家。
请帮我按以下严格的安全规范，完成冬瓜 HAOS 18.3.1 的安装准备与开机三端口巡检：

1. 下载并解压 wghaos-beginner-toolkit 工具箱，运行 plan 子命令核对本地剩余磁盘空间，并根据我的硬件环境（X86 物理机 / PVE 虚拟机）输出对应的 18.3.1 官方固件地址与 UEFI (OVMF) + CPU host 建机参数；
2. 若本地尚无固件镜像，调用 fetch 子命令从官方源下载对应镜像并验证 SHA256 完整性（严禁直接对宿主机系统盘执行 dd 覆写操作）；
3. 在设备开机后，运行 probe 子命令并发探测 homeassistant.local 的 8124（冬瓜伴侣）、7681（TTYD 终端）和 8123（HA 主界面）三个端口；
4. 若 8124 在线而 8123 尚未就绪，调用 wait 子命令每隔 15 秒自动轮询一次，直到 8123 端口成功响应，或提示我前往 8124 伴侣点击重启；
5. 生成本地巡检报告 wghaos-readiness-report.md，提醒我完成英文用户名创建、公制单位（Metric）设定与首次纯净基线备份；
6. 整个执行与报告生成过程中，严禁在日志或文件中泄露任何完整的局域网 IP 地址或完整的计算机主机名。

新手常见高频问题深度 Q&A

Q1：为什么设备开机好几分钟了，浏览器输入 http://homeassistant.local:8124 和 :8123 都打不开？

这是新手遇到频率排名第一的问题，通常由以下三个原因之一引起，按顺序排查 1 分钟即可定位：

  1. 光猫与二级路由器跨网段隔离（最常见）： 很多家庭宽带入户有一个运营商光猫（一级路由），自己又买了一个无线路由器（二级路由）。如果你把冬瓜 HAOS 主机插在了光猫上，而你的手机和电脑连的是二级路由器的 Wi-Fi，它们根本不在同一个局域网段内！请务必把 HA 主机、电脑、手机全部接在同一个路由器下（且切勿误插到光猫的 IPTV 专用口）。
  2. 路由器不支持 .local (mDNS) 域名解析： 部分老旧路由器或开启了 AP 隔离的网络会拦截 mDNS 广播。此时只需登录你的路由器管理后台，在「已连接设备 / DHCP 客户端列表」里找到名为 homeassistant 的设备，用它获取到的真实局域网地址加上 :8124 访问即可（如果你是带屏幕的冬瓜盒子，机身小屏幕也会每隔 90 秒轮询显示当前的 LAN IP，注意不要把显示为网关的 GATE IP 当成设备地址）。
  3. 虚拟机网卡没选桥接： 如果是 VMware Workstation 或 VirtualBox，请检查虚拟机网络适配器是否设置为了「桥接模式（Bridged）」，不要选 NAT 模式。

Q2：为什么我的虚拟机开机后一直黑屏卡在 Booting from Hard Disk...，或者重启后又进了 PE 桌面？

Q3：如果正好赶上晚上用网高峰（18:00 - 20:00），初始化进度条卡在某一层不动了怎么办？

完全不用重刷系统！这正是冬瓜 HAOS 伴侣大显身手的时候：

  1. 打开 http://homeassistant.local:8124/，点击右上角登录伴侣；
  2. 进入左侧的「常规维护」标签页；
  3. 先点击「同步系统时间」确保时钟准确，再点击「系统换源」切换到另一个空闲的高速镜像节点；
  4. 如果发现 supervisor 容器反复重启，直接点击页面提示的「修复 Su 启动故障」或重启系统，伴侣会自动断点续传完成剩余初始化。

Q4：我是直接导入 .img.xz 虚拟磁盘镜像的老玩家，为什么装几个插件就提示磁盘空间不足？

为了控制固件下载体积，冬瓜官方发布的原生镜像包初始分区较小。

Q5：如果以后忘记了 Home Assistant 的登录密码，需要重装系统吗？

绝对不需要重装！ 在原版 HAOS 里忘掉密码，你得接显示器敲命令行调 auth reset；而在冬瓜 HAOS 里，你只需要打开 8124 端口的冬瓜伴侣，进入「常规维护 → 修改 HA 密码」，直接输入你的 HA 用户名和新密码点确定，几秒钟就能无损找回账号控制权。

Q6：给冬瓜 HAOS 设置静态地址（固定局域网地址）有什么需要注意的避坑点？

为了防止路由器重启后设备地址变动，推荐在安装完成后进入 HA 的「设置 → 系统 → 网络 → 配置网络接口 → IPv4」将其设为静态地址，或者在路由器后台为其配置「DHCP 静态地址绑定（最推荐）」。

[!WARNING] 换路由器前的保命提醒： 如果你在 HA 内部写死了静态地址，将来某天你家里更换了新品牌的路由器（导致家里网段发生变化），在拆下旧路由器之前，请务必先进入 HA 把网络改回「自动获取（DHCP）」再关机！否则换上新路由器后，死守旧网段地址的 HA 主机将无法与新路由器通信（万一忘了，也可以接显示器键盘在命令行输入 net up end0 –ipv4-method auto 一键恢复动态获取）。

参考资料与开源致谢

文中的 Home Assistant 与冬瓜 HAOS 界面标志与名称分别归属于其各自官方团队与开源社区。文内全部架构与比方信息图均为本文原创矢量绘制，实操截图均来自真实安装环境与官方实测文档，所有局域网 IP、节点名称与个人标识已严格执行不透明脱敏处理。

评论

使用 GitHub 登录后即可评论，中英文版本共用同一讨论。 在 GitHub 上参与讨论

本文阅读量 --