用Docker部署Home Assistant并对接Zigbee网关的核心是：一要通过docker-compose挂载配置目录、启用privileged权限和host网络确保HA稳定运行与配置持久化；二要映射USB设备（如/dev/ttyACM0）并部署独立Zigbee2MQTT服务，通过MQTT协议实现本地自动发现与控制。

用 Docker 部署 Home Assistant 并对接 Zigbee 网关，核心是两件事：一是让 HA 容器能稳定运行并持久保存配置，二是让 Zigbee 网关（如 CC2652 或 Sonoff Zigbee 3.0 适配器）被容器识别、访问并交由 Zigbee2MQTT 正确驱动。整个过程不依赖云端，全部本地完成。

准备 Zigbee 硬件与确认设备节点

把 Zigbee 网关插入宿主机 USB 口后，先确认系统是否识别：

• 执行 dmesg | grep tty，看到类似 ttyACM0 或 ttyUSB0 的输出，说明设备已接入
• 若无反应，检查线缆、供电或换 USB 口；部分网关需按住复位键再插拔才能进入烧录模式
• 记录下设备路径，例如 /dev/ttyACM0，后续 docker-compose 中要用到

部署 Home Assistant 容器（推荐 docker-compose）

新建目录，例如 ~/ha，在里面创建 docker-compose.yml：

• volumes 挂载本地 ./config 到容器 /config，首次启动会自动生成默认配置
• privileged: true 是必需的，否则无法访问 USB 设备和调整系统时间
• network_mode: host 让 HA 直接使用宿主机网络，省去端口映射，访问地址就是 http://[IP]:8123
• devices 映射 Zigbee 设备，例如 - "/dev/ttyACM0:/dev/ttyACM0"

示例片段：

Docker Image Puller

使用 Python 脚本下载 Docker 镜像并打包为 tar 文件。用户说“下载镜像”“拉取镜像”“pull xxx”“帮我下载 nginx 镜像”等时触发。支持 SOCKS5 代理直连（推荐）和国内镜像站加速两种模式。

下载

version: '3.8'
services:
  homeassistant:
    container_name: homeassistant
    image: "ghcr.io/home-assistant/home-assistant:stable"
    volumes:
      - ./config:/config
      - /etc/localtime:/etc/localtime:ro
    restart: unless-stopped
    privileged: true
    network_mode: host
    devices:
      - "/dev/ttyACM0:/dev/ttyACM0"

部署 Zigbee2MQTT 并与 HA 对接

Zigbee2MQTT 不直接集成进 HA 容器，而是作为独立服务运行，通过 MQTT 协议通信：

• 单独拉取镜像：docker pull koenkk/zigbee2mqtt
• 挂载配置目录（如 ./z2m/data），确保 configuration.yaml 中开启 homeassistant: true 和正确 MQTT 地址
• 同样需要 privileged: true 和映射对应 USB 设备
• HA 侧无需额外插件，只要 MQTT 服务在线，Zigbee 设备会自动通过 discovery 出现在“设备与服务”里

验证与常见问题

启动后等待 1–2 分钟，访问 http://[宿主机IP]:8123 进入 HA：

• 查看日志：docker-compose logs -f homeassistant，重点排查“can’t open device”或 YAML 语法错误
• 若 Zigbee 设备未出现，进 Zigbee2MQTT 前端（默认 http://[IP]:8080）确认网关状态为 “Online”，且 permit_join 为 true
• 权限问题多因未加 privileged 或用户不在 dialout 组，可临时执行 sudo usermod -a -G dialout $USER 后重启宿主机