这套 Docker 部署 Home Assistant 的方案我自己实际跑了两年多。中间主机换过一次系统重装过三次config目录整个拷过去新环境里一条命令就能把整个智能家居中枢拉起来。这种“随便折腾、坏了也不心疼”的体验是我一直推荐大家用 Docker 来跑 Home Assistant 的最大理由。如果你手里已经囤了各种智能设备想用一个本地平台统一控制又不想把系统搞得乱七八糟这篇文章就是给你准备的。Home Assistant下文简称 HA本身是一个开源智能家居集成平台能干的事情是把不同生态、不同协议的设备统一纳管到一套界面和自动化引擎里。而 Docker 是它的容器运行环境相当于给 HA 套了一个干净、可随时回滚的沙箱。两者结合之后安装门槛大幅降低后续维护和备份也变得极其简单。1. 为什么要用 Docker 部署 Home Assistant1.1 智能家居平台到底解决了什么问题先聊点实际的。你家可能已经有几个智能插座、一个带网关的温湿度计、一套能远程控制的灯光系统但它们各自有各自的 App互相不认识。晚上想在客厅一键关闭所有设备得打开两个 App 分别操作这种体验谈不上“智能”。HA 的核心价值就是把这些七零八落的设备统一到一个平台里。它通过不同的集成组件去对接各生态的局域网或云接口设备接入后你可以在同一个界面里看到所有设备状态也可以把这些设备拖到一个自动化流程里让它们互相联动。比如傍晚日落时阳台灯自动打开、进门后客厅灯自动调到暖色、室温超过 30 度时风扇自动启动。这里有个关键词是“本地”。HA 默认把控制逻辑和设备状态放在本地网络环境里跑不依赖某个云平台来下发指令。这意味着哪怕外网断开家庭内的基础自动化依然能正常执行响应速度也比绕一圈云端再回来更快。对于在意隐私的人来说设备数据尽量留在本地心里也更踏实。1.2 在众多种安装方式里为什么选 DockerHome Assistant 官方提供了好几种安装形态最常见的是这三种。安装方式特点适合谁HAOS 独立操作系统安装到整块硬盘/U盘上像路由器固件一样开机即用自带 Supervisor 和 Add-on 商店有专门一台设备跑 HA、希望功能最完整的人Supervised 安装在 Debian/Ubuntu 系统里安装核心加 Supervisor同样有 Add-on想用 Add-on 但不想独占整机的人Docker 容器只跑 HA 核心用容器管理工具拉起不包含 Supervisor/Add-on 商店已经有 Docker 环境、追求干净和可迁移的人Docker 方案的第一个优势是环境隔离。HA 即使被折腾崩溃了也只是容器内部状态坏了宿主机系统本身毫发无损。第二个优势是备份和迁移极其简单整个 HA 的数据都在一个config目录里把它打个包放到任何一台装有 Docker 的机器上就能恢复。第三个优势是版本回滚往上升级之后如果发现新版本有坑改一个镜像标签就能退回旧版本整个过程不用重装系统。当然它也有明显短板Docker 版没有 Supervisor因此你在界面上不会看到完整的 Add-on 商店一些依赖 Supervisor 的组件装不了。如果你明确需要 MQTT 服务器、反代配置这类附加能力可以用额外的 Docker 容器来补这也是我后面会展开的内容。1.3 适用人群和前置条件用 Docker 跑 HA 比较适合两类人第一类是有一定 Linux 基础、喜欢自己掌控环境的新手照着本文操作一遍就能把平台搭好第二类是已经跑了不少 Docker 服务的老手想把这套平台纳入现有的容器管理体系里。前置条件不复杂一台能 7x24 小时开机的设备系统可以是主流的 Linux 发行版、常见的 NAS 系统或者专门用来折腾的小主机机器上装好 Docker 引擎和 Compose 插件最后是能看懂基本的目录挂载和端口映射概念。满足这些就可以开工了。2. 部署前准备硬件和 Docker 环境2.1 硬件怎么选在硬件选择上我的建议非常明确优先用 x86 架构的小主机或旧笔记本电脑而不是一味追求树莓派。原因有三点。第一x86 平台性能充足HA 核心本身不算重度应用但设备较多、历史数据累积后一些品牌集成会比较吃 CPUx86 处理这些轻松得多。第二很多 USB 智能网关在 x86 上的驱动兼容性比 ARM 小板上更好插上就能识别。第三x86 机器上的 Docker 生态成熟后续想在这台机器上跑 MQTT、数据库之类辅助容器也不会捉襟见肘。如果只是入门体验树莓派 4 或者性能相当的 ARM 开发板也不是不行但建议内存不低于 2GB存储用 SSD避免 SD 卡频繁读写导致系统卡死。现实经验里SD 卡装 HA 一年内挂掉的情况非常常见。2.2 安装 Docker 引擎在 Linux 系统上安装 Docker最省事的方式是用官方安装脚本。登录到你的机器后执行curl -fsSL https://get.docker.com | sh脚本执行完后把当前用户加入docker组这样运行 docker 命令就不用每次都加sudosudo usermod -aG docker $USER改完用户组需要退出重新登录才生效。然后用下面的命令确认环境可用docker --version docker compose version如果网络环境拉取镜像比较慢可以在/etc/docker/daemon.json里配置一个可用的镜像加速器配置完记得重启 Docker 服务。这一步是可选项但实际体验差异很大很多初次部署卡在镜像下载上多半就是这里没处理。2.3 确认部署目录HA 的所有配置、数据、历史记录都会放在一个目录里这个目录就是容器的持久化挂载点。建议新建一个独立工作目录比如/opt/homeassistantmkdir -p /opt/homeassistant cd /opt/homeassistant关于这个目录的位置我的建议是放到系统盘之外、最好是 SSD 上。原因很简单HA 长期运行会写很多历史数据放在机械盘上会导致响应变慢放在系统盘上则可能因为空间不足或系统重装而误删数据。如果 NAS 类设备把它放到专门的存储空间里即可。3. 一份可以照抄的 Docker Compose 配置3.1 为什么用 Compose 而不是直接 docker run部署一个容器理论上一条docker run命令也能搞定但那条命令会很长而且没法放进版本管理。docker compose是更合理的做法把运行参数写进一个 YAML 文件启动、停止、升级都只需要一行命令也方便你后续根据需求修改配置。我在实践里的工作流是所有智能家居相关容器都放在同一目录下每个服务一个子目录各自维护一份docker-compose.yml。需要调整时改文件然后执行docker compose up -d让改动生效。3.2 完整配置与字段解析直接看我的配置services: homeassistant: container_name: homeassistant image: ghcr.io/home-assistant/home-assistant:stable restart: unless-stopped network_mode: host privileged: true volumes: - ./config:/config - /etc/localtime:/etc/localtime:ro environment: - TZAsia/Shanghai这段配置是我踩了几次坑之后沉淀下来的稳定版本下面逐行解释每个配置的作用。image用的是官方稳定版镜像拉取的地址是ghcr.io/home-assistant/home-assistant:stable。如果你的网络环境拉取这个地址比较慢可以多试几次或者配置加速器不建议随便换非官方镜像源。restart: unless-stopped表示容器异常退出后会自动重启除非你手动停掉它。这个是跑长期服务的基本要求不然断电后你的智能家居平台不会自己回来。network_mode: host是网络模式的关键设置。这里不是用常见的端口映射而是让容器直接使用宿主机网络。这么做的直接好处是 HA 能通过 SSDP、mDNS 等协议自动发现局域网里的设备很多设备的自动发现功能在桥接网络下会失灵改 host 模式就好很多。代价是 8123 端口是直接用宿主机的 IP 绑定的如果宿主机上已有其他服务占用了 8123需要先处理冲突。privileged: true是给容器提供特权模式权限。严格来说这不是一个必要的配置但如果你准备插入 USB 网关设备比如常见的 Zigbee USB 棒privileged 模式能省去大量权限报错。它相当于把宿主机的 Device 映射权限放宽给容器权衡之下在一台专门跑智能家居服务的机器上可以接受。卷挂载里最核心的是./config:/config。左边的./config是宿主机当前目录下的config文件夹右边容器里的/config是 HA 内部读取配置的位置。两者对应之后容器内写入的所有配置、自动化、历史数据都会落到宿主机这个目录里。另外还挂载了宿主机的/etc/localtime并设置TZAsia/Shanghai。这两个配置共同解决时区问题。如果不做同步容器内时间可能会和宿主机差好几个小时直接影响自动化里的时间触发条件。还有一个可选项如果你要透传 USB 设备比如一个 Zigbee 网关需要把设备映射进容器devices: - /dev/serial/by-id/usb-xxxx:/dev/ttyUSB0这里有个经验要说推荐用/dev/serial/by-id/下的稳定设备路径来映射而不是直接写/dev/ttyUSB0。因为 USB 设备插入顺序变化时ttyUSB0 这个编号可能变成 ttyUSB1路径一错容器起来也识别不到设备。by-id路径是设备序列号导向的插哪个口都认同一个名。3.3 为什么推荐 host 网络而不是端口映射很多人第一次接触 Docker 部署 HA会习惯性地写ports: - 8123:8123这在大多数 Web 服务上没问题但在智能家居场景里会有隐藏问题。HA 需要向局域网广播自己的存在同时侦听其他设备的广播这样才能实现“自动发现”。在默认的 bridge 网络模式下容器处在独立子网广播包很难跨出去结果就是你手动填 IP 能接入设备但界面上那个“自动发现”按钮基本不工作。改成 host 模式之后容器和宿主机共享同一网络栈广播和组播恢复正常设备发现体验接近原生安装。所以我的结论是若这台机器不打算跑一堆端口冲突的容器直接 host 模式如果确实需要精密的网络隔离再退回 bridge 模式并把设备发现功能改为手动添加。4. 启动与初始化让容器真正跑起来4.1 首次启动与日志观察在/opt/homeassistant目录下把上面的配置保存为docker-compose.yml然后执行docker compose up -d首次启动会拉取镜像镜像比较大耐心等一会。启动不是立刻就绪HA 初始化时需要建数据库、安装基础依赖通常要 2 到 5 分钟具体看机器性能。这个过程里最好盯着日志看docker compose logs -f homeassistant当日志出现类似 “Home Assistant initialized” 的内容时说明服务已经就绪了。这时打开浏览器访问你的主机 IP 加 8123 端口http://你的主机IP:8123如果页面正常打开说明基础环境已经打好了。4.2 创建账号和基础设置第一次访问会进入初始化向导按提示创建一个管理员账号。这一步不需要想得太复杂账号是 HA 界面的登录凭证本身就是本地认证体系没有密级要求但建议设一个自己能记住的强密码。接着会让你设置家庭名称、位置和时区。位置一栏建议准确填写城市这会让 HA 的日出日落时间计算得比较准后续做基于日落的自动化才能用得上。时区要选对不然所有时间触发都会偏移。初始化完成后进入主界面先别急着接设备。到“配置 - 设备与服务”里看看HA 通常会通过自动发现列出局域网里已经存在的设备勾选确认就能接入。如果没有自动发现也没关系后面我们手动添加。4.3 一个重要的认知Docker 版没有 Add-on 商店很多从教程视频里了解 HA 的人上来就直奔 Add-on 商店装一堆插件。这里必须提前说清楚官方 Docker 镜像只提供 HA 核心不包含 Supervisor而 Add-on 商店依赖 Supervisor 运行。所以你在这个版本里打不开 Add-on 商店不是安装出了问题而是镜像本身就不带这个功能。对待这个限制有几种思路。一是如果你想完整拥有 Add-on 生态那就换用 HAOS 独立系统方案把一块硬盘或一台虚拟机整块交给 HA。二是继续用 Docker 思路缺什么服务就用额外的 Docker 容器补上比如后面要讲的 MQTT 服务器。我个人更偏向后者因为所有服务都统一在一个 Docker 体系里管理备份和回滚策略一致。5. 设备接入与第一套自动化实战5.1 集成与设备发现HA 把不同类型的设备接入抽象为“集成”。在“配置 - 设备与服务”里点击“添加集成”可以按设备类型搜索。常见的智能设备品牌方一般都有对应的 HA 集成组件通过局域网 IP 或者账号授权方式接入。我的建议是刚开始只接一两个设备走通流程之后再批量接。因为这里很容易踩进一个坑一次接太多设备会有一堆实体刷屏配置自动化时根本分不清哪个是哪个。先把一台灯接入确认能在界面上控制开和关再继续扩展。这种渐进式操作省下来的时间比一次全量接入后反复排查要多得多。设备接入时会要求填 IP 地址或其他密钥信息这类信息保存在 HA 的配置里属于本地凭据。注意不要把它随便分享出去否则别人知道你 IP 和凭据后可以从局域网层面控制设备。5.2 用 MQTT 打通更多设备如果你手里有 DIY 设备、自制传感器或者其他只支持 MQTT 协议的小物件就需要一个 MQTT Broker。HA 本身不带 BrokerDocker 版又没有 Add-on所以我们要在 Docker 里单独起一个。下面是一个常见的 MQTT 服务配置services: mqtt: image: eclipse-mosquitto:2 container_name: mqtt restart: unless-stopped ports: - 1883:1883 - 9001:9001 volumes: - ./mqtt/config:/mosquitto/config - ./mqtt/data:/mosquitto/data启动这个容器后在 HA 的“设备与服务”里添加 MQTT 集成填上宿主机 IP、端口、账号密码即可。之后那些支持 MQTT 的设备就能通过主题发布和订阅与 HA 通信。这个通道非常通用自制温湿度计、ESP 类设备、DIY 开关面板大多走这个协议。MQTT 的配置有一个常见误区如果你和我在同一个局域网里跑 HA 和 MQTTBroker 地址要填宿主机的局域网 IP不要填localhost或127.0.0.1。因为 HA 容器和 MQTT 容器虽然在同一个宿主机上但 Docker 的网络栈使两者不能通过本机回环地址通信填回环地址会连接失败。5.3 一个亲手验证过的自动化例子设备接入完成后就可以写自动化了。我用一个非常基础的场景举例晚上按一下实体按钮打开客厅灯并播放音乐再按一下全部关闭。在 HA 的可视化编辑器里可以直接创建自动化也可以把下面的 YAML 配置手动写到config/automations.yaml- id: living_room_button_toggle alias: 客厅按钮切换灯光音乐 trigger: - platform: state entity_id: binary_sensor.living_room_button to: on action: - service: light.toggle target: entity_id: light.living_room - service: media_player.toggle target: entity_id: media_player.living_room_player mode: single这个自动化的逻辑是当按钮状态变为on时同时切换灯光和播放器的开关状态。实体 ID 需要替换成你自己接入的设备实际生成的 ID所以直接复制前最好先到“设备与服务”里确认实体名称。写完 YAML 后到“开发者工具 - YAML”里执行配置检查确认无误后重启 HA 使配置生效。这里有个细节自动化文件改动后不一定非得重启整个容器HA 有自动热加载机制但如果改了实体 ID 或设备映射还是重启更稳妥。重启命令docker compose restart homeassistant6. 常见问题与排查清单6.1 容器起不来先看日志容器启动失败时第一件事就是把日志拉出来docker compose logs homeassistant常见的错误一般集中在以下几种。权限不足日志里报Permission denied。这种情况多半是config目录的宿主权限和容器内用户不匹配执行chown -R 1000:1000 ./config可解决。HA 容器默认以 UID 1000 运行把宿主机目录的属主改成 1000 就能让容器写入。端口冲突要是你同时开了其他服务占用 8123日志会显示Address in use。解决方法是停掉冲突服务或者换一台机器专门运行 HA。镜像拉不下来。这种情况很常见配置好镜像加速器后重试即可。6.2 USB 设备透传失败插上 Zigbee 或其他 USB 网关后容器里看不到设备这种问题我遇到不止一次。排查路径分两步。先在宿主机上确认设备路径ls -l /dev/serial/by-id/找到对应的稳定路径后在docker-compose.yml的 devices 字段里按我前面提到的by-id方式映射。注意改完 compose 文件后要重新创建容器才能生效docker compose up -d如果设备还是访问不了检查privileged: true有没有配置上。旧版配置里你可能会看到用--device参数但在 Compose 里对应的是devices列表两者等效。6.3 数据备份与恢复实操备份 HA 其实就是在备份config目录。我习惯在宿主机上直接打包tar -czvf ha-backup-$(date %F).tar.gz /opt/homeassistant/config恢复的流程也很直接新机器装好 Docker建好同样的工作目录把备份包解压到config位置再把原来的docker-compose.yml放回去执行docker compose up -d。配置、自动化、历史数据都会回来。这里有一个我反复强调的预防性经验不管做什么重大变更先打一个备份包成本只有一条命令但能救命。我之前有一次折腾设备接入配置把自动化文件改坏了直接回滚备份一分钟就恢复原状完全没有影响其他服务。6.4 升级镜像与安全回滚HA 镜像更新比较频繁。升级操作很简单docker compose pull docker compose up -dpull会拉取新镜像up -d会用新镜像重建容器。如果你是新版本发布后第一时间升级建议先到官方发行注记看一眼再动手避免踩已知问题。升级后如果发现功能异常回滚的思路是把镜像标签改回旧版本。例如image: ghcr.io/home-assistant/home-assistant:2024.1.0改完执行docker compose up -d容器就会用旧镜像重新创建。这时候升级前打的备份包就派上用场了万一配置文件和旧版本不兼容直接把config目录恢复即可。在实际操作中我见了太多人因为升级后回退失败而骂骂咧咧重装系统。其实只要养成了“升级前备份、异常时回滚镜像”的习惯整个升级过程就跟日常重启一样平常。这套 Docker 部署 Home Assistant 的方案说到底是帮你把“智能家居中枢”从一次性的系统安装里解放出来。平台坏了卷回滚机器换了目录拷过去新设备想试起个容器就跑全都不影响其他业务。容器化带来的这种可抛弃、可重建的底气才是这套方案最值得复制的地方。如果你也想在家里建一个不依赖云端的本地智能中枢拿一台旧电脑装上 Docker按本文的配置把 HA 拉起来后面的事就顺理成章了。