🧭 Zigbee2MQTT 是什么？

Zigbee2MQTT 是一个软件桥接器，它通过一个兼容的 Zigbee 协调器（一个 USB 棒或开发板）连接到你的 Zigbee 网络，然后将所有设备的事件（如开关状态、传感器读数）和命令转换为 MQTT 消息。这使得它能与几乎所有支持 MQTT 的智能家居平台（如 Home Assistant、Domoticz、ioBroker 等）无缝集成。

核心优势：

  • 告别专有网关：用一个通用协调器替代每个品牌（小米、宜家、飞利浦等）的专用网关，节省插座和成本。
  • 广泛的设备支持：支持来自 Xiaomi、Ikea、Philips、OSRAM 等众多品牌的数千种设备（可在 支持的设备列表 中查询）。
  • MQTT 原生集成：通过标准 MQTT 协议与现有系统通信，灵活且解耦。
  • 活跃的社区与更新：项目非常活跃，持续添加新设备支持和新功能。
  • 多种用户界面：自带 Web 前端（zigbee2mqtt-frontend），方便监控和管理。

📦 部署方式

Zigbee2MQTT 部署非常灵活，最推荐的方式是 通过 Docker 运行，尤其是与 Home Assistant 的 官方插件（Add-on） 集成。以下是几种主要方式。

方式一：Docker 部署（推荐，最通用）

这是独立运行 Zigbee2MQTT 的最简便方法，适用于任何支持 Docker 的系统（Linux、Windows、macOS、NAS 等）。

  1. 确保硬件连接：将你的 Zigbee 协调器（如 CC2531、CC2652 等 USB 棒）插入运行 Docker 的主机。

  2. 准备配置文件：创建一个本地目录（如 ./zigbee2mqtt-data）用于持久化配置和数据。

  3. 启动容器：在终端中运行以下命令（请根据你的协调器路径修改 --device 参数）：

    1
    2
    3
    4
    5
    6
    7
    8
    9
    docker run -d \
      --name=zigbee2mqtt \
      --restart=unless-stopped \
      --device=/dev/ttyUSB0:/dev/ttyUSB0 \ # 重要：替换为你的 USB 设备路径
      -p 8080:8080 \
      -v $(pwd)/zigbee2mqtt-data:/app/data \
      -v /run/udev:/run/udev:ro \
      -e TZ=Asia/Shanghai \
      koenkk/zigbee2mqtt

  4. 首次配置：容器启动后，会在数据目录生成一个 configuration.yaml 文件。你需要编辑此文件，至少配置 MQTT 服务器信息（mqtt 部分）和协调器串口设置（serial 部分，通常 Docker 已自动处理）。编辑后重启容器：docker restart zigbee2mqtt。

  5. 访问 Web 界面：浏览器访问 http://你的主机IP:8080。

方式二：Home Assistant 官方插件（最集成）

如果你使用 Home Assistant OS 或 Supervised 安装，这是最无缝的方式。

  1. 在 Home Assistant 的“加载项商店”中，搜索并添加 “Zigbee2MQTT” 加载项（由 Koenkk 维护）。
  2. 在加载项的“配置”标签页中，根据你的 USB 协调器和 MQTT 设置填写配置（大部分可留空自动检测）。
  3. 点击“启动”，加载项会自动运行并进行初始设置。

方式三：源码或系统包安装（高级用户）

对于需要高度定制或在非 Docker 环境下运行的用户，可以参考官方文档进行手动安装（基于 Node.js）。

  • 从 npm 安装：npm install -g zigbee2mqtt。
  • 从 Git 源码运行：克隆仓库，执行 pnpm install 和 pnpm run build 后启动。
  • 操作系统包：一些发行版（如 Debian/Ubuntu）可通过第三方仓库安装。

⚙️ 核心配置与优化

  • 配置文件 (configuration.yaml)：这是 Zigbee2MQTT 的核心。主要配置项包括：
    • mqtt：必填，设置你的 MQTT Broker 地址、端口、用户名和密码。
    • serial：指定 Zigbee 协调器的串口路径（如 port: /dev/ttyUSB0）。
    • frontend：配置内置 Web 界面的端口（默认 8080）和认证。
    • availability：启用后，设备会通过 MQTT 发布在线/离线状态。
    • advanced：高级设置，如网络密钥（network_key，强烈建议生成并固定，否则配对设备会丢失）、日志级别等。
  • 网络密钥：首次启动会生成随机密钥。务必在 advanced 中固定此密钥，否则重新启动或迁移后所有设备需重新配对。
  • 设备配对：在 Web 界面或通过 MQTT 启用“配对模式”，然后操作 Zigbee 设备进行配对。配对成功后，设备会自动出现在列表中。

📋 常用运维命令

  • 查看日志：docker logs -f zigbee2mqtt (Docker) 或 journalctl -u zigbee2mqtt -f (系统服务)
  • 重启服务：docker restart zigbee2mqtt (Docker) 或 sudo systemctl restart zigbee2mqtt (系统服务)
  • 备份数据：备份 data/ 目录下的 configuration.yaml 和 database.db 文件。database.db 存储了所有配对的设备信息和网络状态，是恢复系统的关键。
  • 更新：
    • Docker：docker pull koenkk/zigbee2mqtt 然后重新创建容器。
    • Home Assistant 插件：在加载项页面点击“更新”。
    • 源码/npm：执行 pnpm run update 或 npm update -g zigbee2mqtt。

❓ 常见问题与排查

  • 协调器无法访问 (Error: Failed to connect to device)：
    • 检查 USB 设备路径（在 Linux 中可能是 /dev/ttyACM0 或 /dev/ttyUSB0）。
    • 确保运行 Zigbee2MQTT 的用户（或 Docker 容器）有权限访问该设备（通常需要加入 dialout 或 plugdev 组）。
    • 在 Docker 中，确保 --device 参数正确映射了主机设备。
  • 设备无法配对或频繁掉线：
    • 确保配对期间设备处于配对模式（通常需要长按按钮）。
    • 检查 Zigbee 网络信号强度，必要时增加协调器附近的设备或使用带天线的协调器。
    • 检查 configuration.yaml 中 advanced 的 pan_id 和 channel 是否与其他 Zigbee 网络冲突。
  • MQTT 连接失败：
    • 检查 configuration.yaml 中的 MQTT Broker 地址、端口和认证信息。
    • 确认 MQTT Broker（如 Mosquitto）服务正在运行，且网络通畅。

总结

Zigbee2MQTT 是构建统一、开放、本地化的智能家居系统的关键组件。对于绝大多数用户，强烈推荐使用 Docker 方式部署，它隔离性好、易于管理和升级。如果你使用 Home Assistant，那么官方插件是集成度最高的选择。部署的核心步骤是：连接协调器 → 部署容器/插件 → 配置 MQTT 连接 → 启动并固定网络密钥。配置完成后，你就可以将所有 Zigbee 设备纳入同一个 MQTT 控制体系，与 Home Assistant 等其他系统无缝协作。遇到问题时，查阅其非常详尽的官方文档 是获取帮助的最佳途径。