zigbee2mqtt 镜像文档

镜像概述和主要用途

zigbee2mqtt 是一个开源的 Zigbee 到 MQTT 协议桥接工具，允许用户无需依赖设备厂商提供的专有桥接/网关，即可将 Zigbee 设备接入网络。其核心功能是在 Zigbee 设备与 MQTT 服务器之间建立通信桥梁，实现设备数据的采集、控制指令的下发，以及与智能家居系统、自动化平台的集成。

核心功能和特性

核心功能

• 协议桥接：实现 Zigbee 协议与 MQTT 协议的双向转换，使 Zigbee 设备可通过 MQTT 进行通信。
• 设备管理：支持 Zigbee 设备的配对、移除、状态监控及固件更新（部分设备）。

主要特性

• 无需厂商网关：摆脱对设备厂商专有桥接/网关的依赖，降低硬件成本。
• 广泛设备支持：兼容数千种 Zigbee 设备（如传感器、开关、灯具等），涵盖主流品牌（如 Philips Hue、IKEA TRÅDFRI、Xiaomi Aqara 等）。
• MQTT 集成：无缝对接 MQTT 服务器（如 ***、EMQX），支持自定义 MQTT 主题、消息格式。
• 可配置性：通过配置文件自定义设备名称、网络参数、日志级别等，支持高级功能（如设备分组、规则引擎）。
• 数据持久化：本地存储设备网络配置、状态数据，确保容器重启后恢复设备连接。
• 开源免费：基于 MIT 许可证开源，社区活跃，持续更新设备支持库。

使用场景和适用范围

典型场景

• 智能家居系统集成：与 Home Assistant、OpenHAB、Domoticz 等智能家居平台联动，实现设备统一管理和自动化控制。
• 本地化部署：适用于对数据隐私有要求的场景，所有设备通信可在本地网络完成，无需依赖云服务。
• DIY 自动化项目：为开发者提供灵活的设备接入方案，用于构建自定义监控、报警或控制逻辑。
• 多品牌设备统一管理：解决不同厂商 Zigbee 设备兼容性问题，实现跨品牌设备联动。

使用方法和配置说明

前置条件

• 安装 Docker 及 Docker Compose（可选）。
• 准备 Zigbee 适配器（如 CC2531、CC2652P、EZSP 协议适配器等），并确认其设备路径（如 /dev/ttyACM0 或 /dev/ttyUSB0）。
• 部署 MQTT 服务器（如 ***），获取服务器地址、端口、认证信息（若需）。

Docker 快速启动

1. 直接运行容器（docker run）

docker run -d \
  --name zigbee2mqtt \
  --restart=always \
  -p 8080:8080 \  # 可选，Web 界面端口（若启用）
  -v /path/to/zigbee2mqtt/data:/app/data \  # 挂载配置和数据目录（持久化）
  --device=/dev/ttyACM0:/dev/ttyACM0 \  # 替换为实际 Zigbee 适配器路径
  -e TZ=Asia/Shanghai \  # 设置时区
  -e MQTT_SERVER=mqtt://your-mqtt-server:1883 \  # MQTT 服务器地址
  -e MQTT_USER=your-mqtt-user \  # 可选，MQTT 用户名
  -e MQTT_PASSWORD=your-mqtt-password \  # 可选，MQTT 密码
  koenkk/zigbee2mqtt

2. Docker Compose 配置（推荐）

创建 docker-compose.yml 文件：

version: '3.8'

services:
  zigbee2mqtt:
    image: koenkk/zigbee2mqtt
    container_name: zigbee2mqtt
    restart: always
    ports:
      - "8080:8080"  # Web 界面端口（若启用）
    volumes:
      - /path/to/zigbee2mqtt/data:/app/data  # 配置和数据持久化
    devices:
      - /dev/ttyACM0:/dev/ttyACM0  # 替换为实际 Zigbee 适配器路径
    environment:
      - TZ=Asia/Shanghai
      - MQTT_SERVER=mqtt://mqtt-server:1883  # MQTT 服务器地址
      - MQTT_USER=mqtt-user  # 可选，MQTT 用户名
      - MQTT_PASSWORD=mqtt-password  # 可选，MQTT 密码
      - ZIGBEE_DEVICE=/dev/ttyACM0  # 与 devices 挂载路径一致
      - LOG_LEVEL=info  # 日志级别：debug/info/warn/error

启动容器：

docker-compose up -d

配置文件说明

容器首次启动后，会在挂载的 /app/data 目录下生成配置文件 configuration.yaml，核心配置项如下（可手动编辑或通过环境变量覆盖）：

# 基础配置
homeassistant: false  # 是否启用 Home Assistant 自动发现
permit_join: true  # 是否允许新设备加入（初次配置时设为 true，完成后建议设为 false）
mqtt:
  server: mqtt://your-mqtt-server:1883
  user: your-mqtt-user  # 可选
  password: your-mqtt-password  # 可选
  topic_prefix: zigbee2mqtt  # MQTT 主题前缀（默认）
serial:
  port: /dev/ttyACM0  # Zigbee 适配器路径
advanced:
  log_level: info  # 日志级别
  network_key: GENERATE  # 自动生成网络密钥（首次启动后固定，请勿修改）

环境变量参数

设备配对与管理

1. 启用设备加入：

   • 方法 1：修改 configuration.yaml 中 permit_join: true，重启容器。
   • 方法 2：通过 MQTT 发送指令：***_pub -t "zigbee2mqtt/bridge/request/permit_join" -m '{"value": true}'（持续 255 秒）。

2. 配对设备：

   • 按照 Zigbee 设备说明，将设备置于配对模式（通常长按设备按钮至指示灯闪烁）。
   • 容器日志将显示设备配对进度，成功后可在 configuration.yaml 的 devices 节点或 MQTT 主题 zigbee2mqtt/bridge/devices 中查看设备信息。

3. 控制设备：

   • 通过 MQTT 发送控制指令，例如控制开关：
     ***_pub -t "zigbee2mqtt/[设备名称]/set" -m '{"state": "ON"}'

参考链接

• GitHub 项目主页
• ***文档
• Docker 容器运行指南