Home Assistant 安装与部署完整指南树莓派、虚拟机与 Docker 四种装法【免费下载链接】home-assistant.io:blue_book: Home Assistant User documentation项目地址: https://gitcode.com/GitHub_Trending/ho/home-assistant.ioHome Assistant 是一个运行在你自己硬件上的开源智能家居中枢。它的安装分三种形态OS、Container、Core对应三条部署路线树莓派 SD 卡烧录、x86 虚拟机、Docker 容器。按你的硬件对号入座走完对应章节即可通过http://homeassistant.local:8123打开管理界面。选择 Home Assistant 安装形态OS、Container 还是 Core部署前先确定形态后面的路线由它决定。官方推荐大多数人使用 Home Assistant OS它是一个为智能家居定制的最小化系统内置 Add-ons附加组件、一键更新和图形化备份。安装形态适用场景最低配置关键限制Home Assistant OS新手树莓派 / x86 / 虚拟机2 GB 内存32 GB 存储无功能最完整Container已有 Docker 环境的用户2 GB 内存32 GB 存储Docker Engine ≥ 23.0无 Add-ons更新和备份需手动维护Core想深度定制的开发者1 GB 内存16 GB 存储需自备 Python 运行环境与 systemd 服务Docker Desktop 无法运行 Home Assistant 容器必须安装 Docker Engine。用 Raspberry Pi Imager 烧录官方镜像到 SD 卡适合场景在 Raspberry Pi 4/5 上烧录 SD 卡启动。硬件清单先核对一遍树莓派 4 或 5内存至少 2 GBmicroSD 卡容量 32 GB 以上优先选卡面印有 A2 标识的 Application Class 2 卡持续写入性能更好官方电源适配器输出 5V / 2.5A 以上手机充电头和电脑 USB 口供电都不够网线安装期间必须有和 SD 读卡器在任意一台电脑上完成烧录安装 Raspberry Pi Imager打开后点击OS开始选择依次选择Other specific-purpose OS Home assistants and home automation Home Assistant按实际硬件选择 Raspberry Pi 4 或 5 对应的镜像版本插入 SD 卡在存储设备下拉框中选中它卡内数据会被完全覆盖点击Next再点Write等待写入完成弹出 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 为例下载对应平台的 Home Assistant OS 磁盘镜像Intel/AMD 主机用 x86 VDI 镜像Apple SiliconM1/M2/M3必须用 ARM 版镜像x86 镜像在 ARM 芯片上无法启动新建虚拟机类型选Linux Oracle Linux (64-bit)Apple Silicon 机器改选Oracle Linux (ARM 64-bit)内存至少 2048 MB处理器至少 2 个并勾选Use EFI——UEFI 是启动硬性要求存储里挂上第 1 步下载的 VDI 文件网络选择桥接网卡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 TZAsia/Shanghai \ -v /home/user/homeassistant:/config \ --networkhost \ --restartunless-stopped \ --privileged \ # 如使用 Zigbee/Z-Wave 适配器追加 --device /dev/ttyUSB0:/dev/ttyUSB0 ghcr.io/home-assistant/home-assistant:stable参数逐个说明-e TZAsia/Shanghai设置时区换成你所在地的 tz 库名称-v /home/user/homeassistant:/config把宿主目录挂载为容器配置目录所有数据落在这里升级容器不丢配置--networkhost容器直接使用宿主机网络8123 端口直接对局域网暴露无需-p映射--restartunless-stopped崩溃或系统重启后容器自动拉起--privileged容器需要访问 USB、蓝牙等设备节点因此要特权模式--device /dev/ttyUSB0:/dev/ttyUSB0Zigbee/Z-Wave 适配器必须显式映射进容器设备名以dmesg或ls /dev实际输出为准Linux 宿主机通常开着防火墙需要为 Home Assistant 8123 端口放行sudo ufw allow 8123/tcp完成初始化并验证 Home Assistant 跑通三条路线都指向同一个初始化流程浏览器打开http://homeassistant.local:8123旧版 Windows 或不支持 mDNS 的网络改用http://homeassistant:8123或设备 IP创建管理员账户设置姓名和密码——这是唯一的登录凭证务必记牢填写地理位置与时区日出日落类自动化依赖它同意匿名数据统计可跳过进入首页后系统会通过 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_JEMALLOCtrue禁用磁盘定期在设置 系统 日志清理旧日志常见问题速查与下一步行动清单现象先查什么8123 端口打不开防火墙规则、桥接/NAT 网络类型、路由器里的设备 IP树莓派无响应电源是否 2.5A 以上、SD 卡等级、HDMI 控制台报错容器重启后实体消失USB 设备映射是否还在、/config目录是否挂载正确接下来做三件事在界面里添加第一批智能设备并验证状态联动创建第一份备份并确认能恢复把常用设备加进自动化。跑通这一步部署就算真正结束了。【免费下载链接】home-assistant.io:blue_book: Home Assistant User documentation项目地址: https://gitcode.com/GitHub_Trending/ho/home-assistant.io创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
