企业官网建设流程全解析

Home Assistant 安装与部署完整指南：树莓派、虚拟机与 Docker 四种装法

【免费下载链接】home-assistant.io:blue_book: Home Assistant User documentation项目地址: https://gitcode.com/GitHub_Trending/ho/home-assistant.io

Home Assistant 是一个运行在你自己硬件上的开源智能家居中枢。它的安装分三种形态（OS、Container、Core），对应三条部署路线：树莓派 SD 卡烧录、x86 虚拟机、Docker 容器。按你的硬件对号入座，走完对应章节，即可通过http://homeassistant.local:8123打开管理界面。

选择 Home Assistant 安装形态：OS、Container 还是 Core

部署前先确定形态，后面的路线由它决定。官方推荐大多数人使用 Home Assistant OS：它是一个为智能家居定制的最小化系统，内置 Add-ons（附加组件）、一键更新和图形化备份。

Docker Desktop 无法运行 Home Assistant 容器，必须安装 Docker Engine。

用 Raspberry Pi Imager 烧录官方镜像到 SD 卡

适合场景：在 Raspberry Pi 4/5 上烧录 SD 卡启动。硬件清单先核对一遍：

• 树莓派 4 或 5，内存至少 2 GB
• microSD 卡：容量 32 GB 以上，优先选卡面印有 A2 标识的 Application Class 2 卡，持续写入性能更好
• 官方电源适配器，输出 5V / 2.5A 以上；手机充电头和电脑 USB 口供电都不够
• 网线（安装期间必须有）和 SD 读卡器

在任意一台电脑上完成烧录：

1. 安装 Raspberry Pi Imager，打开后点击OS开始选择
2. 依次选择Other specific-purpose OS > Home assistants and home automation > Home Assistant

3. 按实际硬件选择 Raspberry Pi 4 或 5 对应的镜像版本
4. 插入 SD 卡，在存储设备下拉框中选中它（卡内数据会被完全覆盖）

5. 点击Next再点Write，等待写入完成

6. 弹出 SD 卡，插入树莓派，接好网线再上电。首次启动会联网下载核心组件，Pi 4/5 上约一分钟内homeassistant.local可访问，最迟不超过 5 分钟。

在 Windows 与 macOS 上创建 x86 虚拟机

适合场景：复用一台闲置 x86 主机，或在桌面系统上跑虚拟机。x86 环境要求：64 位处理器、支持 UEFI 启动、4 GB 内存、64 GB SSD。

引导盘必须支持 512 字节逻辑扇区（512n/512e）；只支持 4Kn 扇区的 NVMe SSD 无法启动 Home Assistant OS。

以 VirtualBox 为例：

1. 下载对应平台的 Home Assistant OS 磁盘镜像：Intel/AMD 主机用 x86 VDI 镜像，Apple Silicon（M1/M2/M3）必须用 ARM 版镜像，x86 镜像在 ARM 芯片上无法启动
2. 新建虚拟机，类型选Linux > Oracle Linux (64-bit)；Apple Silicon 机器改选Oracle Linux (ARM 64-bit)
3. 内存至少 2048 MB，处理器至少 2 个，并勾选Use EFI——UEFI 是启动硬性要求
4. 存储里挂上第 1 步下载的 VDI 文件
5. 网络选择桥接网卡（Bridged Adapter），并绑定主机的实际网卡。桥接让虚拟机获得独立局域网 IP，其他设备才能访问 8123 端口；默认的 NAT 模式做不到这一点

启动虚拟机，同样通过homeassistant.local或它的局域网 IP 访问。

用 Docker 部署 Home Assistant 容器

适合场景：已有一台 Linux 服务器，想用 Docker 部署 Home Assistant。前提是装好 Docker Engine 23.0 及以上版本。

先建一个配置目录，然后运行：

docker run -d \ --name homeassistant \ -e TZ=Asia/Shanghai \ -v /home/user/homeassistant:/config \ --network=host \ --restart=unless-stopped \ --privileged \ # 如使用 Zigbee/Z-Wave 适配器，追加 --device /dev/ttyUSB0:/dev/ttyUSB0 ghcr.io/home-assistant/home-assistant:stable

参数逐个说明：

• -e TZ=Asia/Shanghai：设置时区，换成你所在地的 tz 库名称
• -v /home/user/homeassistant:/config：把宿主目录挂载为容器配置目录，所有数据落在这里，升级容器不丢配置
• --network=host：容器直接使用宿主机网络，8123 端口直接对局域网暴露，无需-p映射
• --restart=unless-stopped：崩溃或系统重启后容器自动拉起
• --privileged：容器需要访问 USB、蓝牙等设备节点，因此要特权模式
• --device /dev/ttyUSB0:/dev/ttyUSB0：Zigbee/Z-Wave 适配器必须显式映射进容器，设备名以dmesg或ls /dev实际输出为准

Linux 宿主机通常开着防火墙，需要为 Home Assistant 8123 端口放行：

sudo ufw allow 8123/tcp

完成初始化并验证 Home Assistant 跑通

三条路线都指向同一个初始化流程：

1. 浏览器打开http://homeassistant.local:8123，旧版 Windows 或不支持 mDNS 的网络改用http://homeassistant:8123或设备 IP
2. 创建管理员账户，设置姓名和密码——这是唯一的登录凭证，务必记牢
3. 填写地理位置与时区，日出日落类自动化依赖它
4. 同意匿名数据统计（可跳过）
5. 进入首页后，系统会通过 mDNS 自动发现局域网内的智能设备，在设置 > 设备与服务里按需添加

打开界面、能看到实体列表，即代表部署成功。容器路线注意一点：它没有 OS 的图形化更新入口，升级镜像和备份都要你自己安排。

排查启动失败、端口冲突与界面打不开

访问不到 8123 端口。先在目标机器本机curl该地址确认服务存活；再在路由器里核对设备是否拿到了 IP；最后检查防火墙。旧版 Windows 不识别.local域名，用http://X.X.X.X:8123直连。

树莓派点不亮或启动卡死。九成是供电不足：换上 5V/2.5A 的官方适配器，别用电脑 USB 口。其次是 SD 卡或烧录问题，连接 HDMI 显示器看控制台输出，报错就重烧一遍，仍不行就换一张 A2 级卡。

容器起不来或界面打不开。端口被占用时用netstat -tlpn | grep 8123查是谁占着，冲突就改掉占用方的端口；日志用docker logs homeassistant看；SELinux/AppArmor 拦截设备访问时确认--privileged已加上。

配置备份策略与轻量性能优化

• 备份：Home Assistant OS 用户在设置 > 系统 > 备份创建快照；容器用户定期打包整个/config目录（tar -czf到网络存储或云盘），配置全在里面
• 散热：树莓派长期运行建议加散热片，高温会导致性能下降
• 内存分配：容器内置 jemalloc 优化；若日志出现<jemalloc>: Unsupported system page size，追加环境变量DISABLE_JEMALLOC=true禁用
• 磁盘：定期在设置 > 系统 > 日志清理旧日志

常见问题速查与下一步行动清单

接下来做三件事：在界面里添加第一批智能设备并验证状态联动；创建第一份备份并确认能恢复；把常用设备加进自动化。跑通这一步，部署就算真正结束了。

【免费下载链接】home-assistant.io:blue_book: Home Assistant User documentation项目地址: https://gitcode.com/GitHub_Trending/ho/home-assistant.io