用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：
Docker Image Puller
下载
使用 Python 脚本下载 Docker 镜像并打包为 tar 文件。用户说“下载镜像”“拉取镜像”“pull xxx”“帮我下载 nginx 镜像”等时触发。支持 SOCKS5 代理直连（推荐）和国内镜像站加速两种模式。
- volumes 挂载本地 ./config 到容器 /config，首次启动会自动生成默认配置
- privileged: true 是必需的，否则无法访问 USB 设备和调整系统时间
- network_mode: host 让 HA 直接使用宿主机网络，省去端口映射，访问地址就是 http://[IP]:8123
- devices 映射 Zigbee 设备，例如 - "/dev/ttyACM0:/dev/ttyACM0"
示例片段：
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 后重启宿主机
