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

如果你在智能家居论坛或视频网站搜过 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，哪怕你是零代码基础的纯小白，也能一次点亮、拎包入住！

图 1：本文原创封面图。专为手机微信端重新排版绘制的高对比度大字版全流程图解。

1

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

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

1.1

永恒转圈的准备中死循环

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

1.2

黑底白字的命令行恐慌

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

1.3

进得去系统却装不上国内插件

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

2

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

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

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

2.1

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

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

2.2

原版首次开机必闯的海外网络关卡

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

• NTP 跨国对时关卡（隐蔽杀手）：很多新买的小主机或刚建的虚拟机主板时钟错乱，原版开机默认连接海外时间服务器校时；一旦超时导致系统时间停留在过去，后续所有 HTTPS 加密下载都会因为「TLS 证书尚未生效」被当场拒绝。
• 版本清单拉取关卡：包工头需要访问 version.home-assistant.io 查询当前最新的 Core 与插件版本号，一旦解析受阻，包工头连「该买哪款家具」都不知道，直接原地罢工。
• GHCR 跨国容器拉取关卡（卡死主因）：核心组件（core、cli、dns、audio、observer、multicast）全部托管在 ghcr.io，仅 Core 主镜像就含 32 层、解压后近 2GB，国内直连只要任何一层连接重置就会推倒重来。
• 内置 DNS 转发死锁关卡：原版系统的 hassio_dns 默认启用了海外加密 DNS 转发，在部分家庭光猫与路由器拓扑下极易触发域名解析死循环。

2.3

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

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

• 底层直连国内高速镜像源与加速引擎：系统底层将所有核心容器与加载项仓库重定向至专门维护的国内高速镜像节点（如 r.hassbus.com），并内置 haos-turbo 加速服务，如同从同城中心仓极速发货，几分钟满速拉完。
• 首创 8124 冬瓜伴侣可视化物业大堂：开机后直接打开 8124 端口的中文网页，当前正在初始化哪个阶段、32 层容器下载到了第几层、网络通不通、时间准不准，像查顺丰快递物流一样一清二楚。
• 预置 HACS 极速版与图形化自愈工具：出厂即配好极速版 HACS 社区商店和基础组件；遇到网络波动、忘记密码或服务异常，在网页上点一下红色按钮就能换源、同步时间或自动修复，全程无需敲代码。

3

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

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

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

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

3.1

独栋精装别墅与合租单间的本质差距

Docker 容器版：只租了光秃秃的卧室单间

Docker 容器版里面只有 Home Assistant Core 本体，完全阉割掉了 Supervisor（大总管）和「加载项商店（Add-on Store）」。当你看别人的教程说「去加载项商店点一下安装 Mosquitto MQTT、Zigbee2MQTT、Node-RED、网上国网插件或 Filebrowser」时，打开自己的 Docker 版 HA 会绝望地发现设置菜单里根本没有「加载项」入口。每装一个周边工具，都得自己手写复杂的 Docker Compose、配置容器网络桥接、映射 USB 蓝牙与串口权限，且不支持官方整机全量快照迁移。

冬瓜 HAOS 完整版：买下整栋精装智能别墅

冬瓜 HAOS 是一个完整的专用操作系统（OS 底座 + Supervisor 总管 + Core 核心 + 加载项商店 + 冬瓜伴侣）。所有周边插件在商店里点一下鼠标就自动装好并打通内部网络；备份时打包成单个 .tar 归档文件，将来换新机器直接上传就能原样恢复。

3.2

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

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

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

4

虚拟机（PVE / NAS）与物理机黄金参数配置

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

4.1

决定成败的核心引导与内核开关

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

为什么 BIOS 必须选 OVMF (UEFI)，绝不能用 SeaBIOS？

打个比方：老式 SeaBIOS (Legacy MBR) 就像几十年前的老式铁片机械钥匙，而现代的冬瓜 HAOS 系统大门装的是智能电子芯片门禁（UEFI GPT 分区表）。如果你拿着老式铁钥匙去捅电子门禁，开机的第一秒就会直接黑屏卡死在 Booting from Hard Disk...，永远进不去系统！

为什么虚拟机 CPU 类别强烈建议选 host 直通？

默认的虚拟 CPU（如 kvm64 或 qemu64）就像隔着一个翻译官传话，很多现代 CPU 的加密与加速指令集被屏蔽了；而选择 host（宿主直通），相当于让冬瓜 HAOS 直接借用你物理机 CPU 的真实大脑，不仅内置的 x86-64-pc 原生版固件能满血运行，初始化解压容器的速度也能大幅提升！

4.2

虚拟机硬件与固件配置实操（对照真实截图）

上传 ISO 镜像并选择系统介质

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

系统固件设定：必选 OVMF (UEFI)

切换到「系统」标签页，严格按照下图红框指示进行配置：

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

• 显卡与机型：保持默认即可（或选 q35）。
• BIOS 固件类型：必须下拉选择 OVMF (UEFI)（群晖 VMM 或 VMware 同样勾选 UEFI；物理机请在主板 BIOS 启动项中开启 UEFI 引导）。
• 添加 EFI 磁盘：使用 PE 安装法时，取消勾选此项即可。

磁盘、CPU Host 直通与桥接网络设定

切换到「磁盘」与「CPU」标签页，按照下图红框指示完成硬件分配：

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

• 磁盘总线与容量：在「磁盘」标签页中，将总线选为 SATA（微 PE 对 SATA 识别最稳），磁盘大小分配 32 GiB 或以上。
• CPU 核心与类别：核心数建议分配 2 至 4 核，右侧「类别」下拉滑到最底部选择 host。
• 内存与桥接网络：内存分配 2048 MB（2G）至 4096 MB（4G）；网络保持默认的桥接模式（vmbr0），确保虚拟机与电脑、手机处在同一个路由器网段下。

5

WinPE 傻瓜式图形化写盘全流程

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

5.1

启动进入微 PE 桌面环境

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

5.2

双击运行脚本并输入数字确认写盘

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

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

5.3

写盘完成后的关机拔盘与卸载光驱铁律

等待大约 2 分钟，窗口底部会清晰打印出：冬瓜HAOS X86-PC版安装完成！可以关机重启了！！！

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

6

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

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

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

图 7：原创「智能大厦三扇大门」比方。开机先去 8124 物业大堂看装修进度，查底层日志去 7681 设备机房，装修完毕后再从 8123 正门拎包入住。

6.1

打开 8124 冬瓜伴侣（物业监控大堂）

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

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

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

看看这张界面有多贴心：

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

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

6.2

认识 7681 网页终端与伴侣图形化自愈神技

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

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

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

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

• 如果你想看首次安装时的底层实时跑码日志，只需在终端里输入 ha-install -t 回车即可；
• 冬瓜 HAOS 甚至还贴心地准备了一个孪生终端端口 7680（默认直接进入底层 Linux Bash 环境），方便高阶玩家执行底层系统指令。

冬瓜伴侣「常规维护」：专治疑难杂症的救命按钮

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

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

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

• 系统换源：如果觉得当前镜像下载偏慢，点一下即可秒切国内其他高速镜像节点；
• 同步系统时间：一键强制校准系统时钟，专治因主板没电或 NTP 受阻引发的无法联网报错；
• HACS 管理：支持一键安装或修复「原版 HACS」与国内加速的「极速版 HACS」；
• 修改 HA 密码：万一哪天忘记了 Home Assistant 登录密码，再也不用去翻官方命令行文档，来这里点一下直接重置；
• 冬瓜甄选仓库 & Supervisor 面板：一键把 Supervisor 管理面板和冬瓜精选国内加载项商店添加到你的 HA 侧边栏；
• 修复 HA 启动超时 / 安全模式：当某个第三方插件把系统搞崩导致 8123 进不去时，在 8124 点一下即可移除自编译阻塞任务或进入安全模式救砖！

6.3

正式入住 8123 主界面与首日必做配置

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

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

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

登录用户名强烈建议使用纯英文小写

「姓名」可以填中文昵称（显示在左下角），但登录用的「用户名」请务必使用纯英文（如 admin 或你的英文名），避免个别老旧第三方插件在调用路径或认证接口时因中文字符出现编码兼容性问题。

检查并确认公制单位与上海时区

在定位与单位设置步骤中，确认时区为 Asia/Shanghai，单位制式选择「公制（摄氏度 °C、千克、千米）」。如果漏选导致温度显示成了华氏度（°F），可随时在「设置 → 系统 → 通用」中改回公制并点击保存。

立即创建首个纯净基线备份

刚装好系统、HACS 和基础环境都健康就绪时，进入「设置 → 系统 → 备份」，点击右下角创建一个名为 Clean-Baseline-18.3.1 的完整备份并下载到电脑保存。有了这个「复活币」，以后你再怎么大胆折腾新插件，随时都能在几分钟内还原回刚装好时的完美状态！

7

跨平台零依赖自动化工具箱：从镜像校验到端口就绪巡检

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

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

图 12：原创工具箱流水线。环境探针与黄金参数生成、SHA256 完整性校验、三端口并发巡检与就绪守候闭环。

工具箱完整压缩包下载：冬瓜 HAOS 新手一键安装与三端口巡检工具包 (ZIP) ( https://blog.margrop.net/downloads/home-assistant-wghaos-beginner-install-guide/wghaos-beginner-toolkit.zip )。

7.1

工具箱核心安全设计

• 100% 零第三方依赖：仅使用系统自带的原生脚本与 Python 3 标准库，无需 pip install 任何外部包；
• 纯本地运行，绝不依赖任何第三方云服务：只连接冬瓜官方固件站与你家局域网内的 HA 主机；
• 内置隐私脱敏与磁盘保护锁：输出的诊断报告自动对局域网地址做脱敏遮蔽，且只生成安全的建机指令，绝不直接覆写宿主机系统盘。

7.2

人工全自动执行指南（主流桌面与服务器系统全覆盖）

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

Windows 11 环境全自动执行

打开 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" -ForceSet-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

Ubuntu 26.04 LTS 环境全自动执行

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

#!/usr/bin/env bashset -euo pipefail# 1. 获取并解压零依赖工具箱mkdir -p ./wghaos-toolkit && cd ./wghaos-toolkitcurl -fsSL "https://blog.margrop.net/downloads/home-assistant-wghaos-beginner-install-guide/wghaos-beginner-toolkit.zip" -o toolkit.zipunzip -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 ./downloadsbash ubuntu-26.04.sh probebash ubuntu-26.04.sh wait --timeout 1200 --interval 15

macOS 27 环境全自动执行

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

#!/usr/bin/env zshset -euo pipefail# 1. 下载并进入工具箱目录mkdir -p ./wghaos-toolkit && cd ./wghaos-toolkitcurl -fsSL "https://blog.margrop.net/downloads/home-assistant-wghaos-beginner-install-guide/wghaos-beginner-toolkit.zip" -o toolkit.zipunzip -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 ./downloadszsh macos-27.sh probezsh macos-27.sh wait --timeout 1200 --interval 15

7.3

交给你的 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 地址或完整的计算机主机名。

8

新手常见高频问题深度解答

8.1

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

这是新手遇到频率很高的问题，通常由以下原因引起，按顺序排查即可快速定位：

• 光猫与路由器跨网段隔离（最常见）：如果你把冬瓜 HAOS 主机插在了入户光猫上，而手机和电脑连的是下级路由器的 Wi-Fi，它们根本不在同一个局域网段内；请务必把 HA 主机、电脑、手机全部接在同一个路由器下（且切勿误插到光猫的 IPTV 专用口）。
• 路由器拦截了 .local (mDNS) 广播解析：部分老旧路由器或开启了 AP 隔离的网络会拦截 mDNS 广播，此时只需登录路由器管理后台，在「已连接设备列表」里找到名为 homeassistant 的设备，用它获取到的真实局域网地址加上 :8124 访问即可。
• 虚拟机网卡未开启桥接模式：如果是 VMware Workstation 或 VirtualBox，请检查虚拟机网络适配器是否设置为了「桥接模式（Bridged）」，切勿选择 NAT 模式。

8.2

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

• 卡在 Booting from Hard Disk... 或 No bootable device：100% 是因为虚拟机的 BIOS 固件选成了传统的 SeaBIOS (Legacy)！冬瓜 HAOS 的 X86 镜像采用 UEFI GPT 引导，只需关机把虚拟机 BIOS 改为 OVMF (UEFI)（物理机在主板 BIOS 中开启 UEFI 模式）即可秒进系统。
• 重启后又回到蓝色 WinPE 桌面：说明你在写完硬盘关机后，忘了把 U 盘拔下来，或者忘了在虚拟机的 CD/DVD 光驱设置里把 win10pe...iso 镜像卸载掉，导致机器又从光盘引导了一次。

8.3

如果赶上晚间用网高峰，初始化进度条卡住不动了怎么办？

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

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

8.4

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

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

• 如果你使用的是本文推荐的 WinPE 安装法，脚本在写入你创建的 32G 硬盘时，开机就会自动把剩余空间扩展为数据区；
• 如果你是直接把 haos_x86-64-vm...img.xz 转成虚拟磁盘导入 VMware、VirtualBox、Hyper-V 或 PVE 的，请在导入后、开机前，在虚拟机硬件设置里将虚拟硬盘容量手动扩容到 32GB 或 64GB。HAOS 内置了自动扩容机制，检测到虚拟磁盘变大后，会在开机引导时自动把 Data 分区无损撑满整个硬盘！

8.5

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

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

8.6

给冬瓜 HAOS 设置固定局域网静态地址有什么避坑点？

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

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

9

参考资料与开源致谢

• 冬瓜 HAOS 官方网站 (wghaos.com) ( https://www.wghaos.com )：提供全系大陆优化版固件更新说明与刷机动态
• 冬瓜 HAOS 官方知识库 (wiki.wghaos.com) ( https://wiki.wghaos.com )：涵盖首次使用、冬瓜伴侣详解、静态地址配置与主流设备接入指南
• 冬瓜 HAOS 官方固件高速下载站 (fw.wghaos.com) ( https://fw.wghaos.com )：提供 X86-64 原生版、VM 虚拟机版、Win10PE 安装镜像及各类 ARM 盒子固件
• Home Assistant 官方文档：Installation & Operating System 架构规范 ( https://www.home-assistant.io/installation/ )
• 瀚思彼岸智能家居技术论坛：冬瓜 HAOS 专区 ( https://bbs.hassbian.com/forum-77-1.html )

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

本文配套的三端全自动脚本工具箱、完整配置模板及中英文双语博文，已同步发布在作者独立博客。点击文末左下角「阅读原文」即可直达下载与查阅。