家里买了温湿度传感器、门磁、人体感应,每换一个牌子就多一个网关,App 各管各的,哪天厂商关了云服务,设备就是一块砖。其实这些小传感器用的多是 Zigbee 协议:一根 USB 协调器插进小主机,跑一个开源服务,就能把全家的 Zigbee 设备统一收编。这个服务叫 Zigbee2MQTT,今晚就能跑起来。
项目名片
| 项目 | 内容 |
|---|---|
| 仓库 | Koenkk/zigbee2mqtt |
| Star / Fork | 15834 / 2128(2026-11-19 抓取) |
| 技术栈 | TypeScript(Node.js 运行时) |
| 许可证 | GPL-3.0(LICENSE 原文已核) |
| 最新版本 | 2.14.3(2026-11-01 发布) |
| 默认端口 | 8080(Web 前端与首次引导页) |
| 最近提交 | 2026-11-18(master 分支) |
它解决什么问题
Zigbee 设备本身不贵,贵在网关:厂商把网关做成私有云的入口,协议虽是标准的,接入却被各家锁死。Zigbee2MQTT 的做法是绕开网关这一层——用一根 USB 协调器(厂家推荐的型号见官方适配器列表),把 Zigbee 空口报文直接收下来,翻译成 MQTT 消息发出去。设备不再绑定某个 App,谁订阅了 MQTT,谁就能控制它。
某些场景它可以替代厂商网关;替不掉的是依赖厂商私有云的那部分功能,比如需要厂商账号和远程服务的联动,还有部分设备的私有报文,得靠社区转换器慢慢补。对动手党还有一层价值:所有状态都走标准 MQTT 主题,自己写个脚本订阅主题就能做联动,不必套在厂商的自动化引擎里。
核心机制
- 底层模块 zigbee-herdsman 负责跟 USB 协调器通信、收发 Zigbee 报文,官方 README 的 Architecture 小节写得很直白。
- zigbee-herdsman-converters 模块负责设备型号到 Zigbee 簇的映射,米家、宜家、飞利浦这些型号都在支持列表里,靠社区持续更新。
- 主程序把 Zigbee 消息映射成 MQTT 主题发布,同时用一个 database.db 文件记录设备清单和状态,这是它最要紧的数据。
- 自带 Web 前端,端口 8080,配对、改配置、看实时消息都在页面上做(推断:2.x 版本加了首次引导页,不用再手写配置文件)。
跑起来
前提两样:一个 MQTT broker(官方推荐 Mosquitto),一根 USB Zigbee 协调器。官方 Docker 文档给的是完整命令,适配器路径用变量缩一下:
IMG=ghcr.io/koenkk/zigbee2mqtt
DEV=$(ls /dev/serial/by-id/ | grep -i usb)
docker run -d --name zigbee2mqtt \
--restart=unless-stopped \
-p 8080:8080 \
-v $(pwd)/data:/app/data \
-v /run/udev:/run/udev:ro \
-e TZ=Asia/Shanghai \
--device=/dev/serial/by-id/$DEV:\
/dev/ttyACM0 $IMG
data 目录挂载是硬要求,设备清单就存在里面;/run/udev 是给协调器自动识别用的(官方文档原注)。MQTT broker 还没有的话,先按 Mosquitto 官方文档起一个,再回来跑上面这条。broker 跟它跑在同一台机器上时,地址填 mqtt://172.17.0.1(Docker 网桥地址,官方文档 TIP 原文)。
从零到能用
- 插上协调器,ls /dev/serial/by-id 找到设备名,替换命令里的 DEV 变量。
- 启动容器,浏览器打开 http://你的服务器IP:8080,看到的是引导页。
- 引导页会自动发现协调器;发现不了就手动填串口路径和适配器类型。
- 填 MQTT 地址和端口,提交配置,服务正式启动后进入前端页面。
- 前端里点配对(Permit join),同时长按设备的配对键让它复位进网,按键方式各品牌不一,查设备页说明。
- 日志出现 Successfully interviewed 字样就是配对成功(getting-started 文档示例),前端里立刻能看到温湿度、开关状态这些数据。
官方文档还有一个提示值得照做:配对困难、设备频繁掉线时,先给协调器换一根 USB 延长线,远离机箱的射频干扰。
适合谁用 / 别用
适合:买了米家、Aqara、宜家、飞利浦的 Zigbee 设备,不想每家装一个网关,想把数据接进 Home Assistant 或者自己写脚本处理的人;也适合想在简历里写智能家居工程实践的学生,把配对、组网、消息链路讲清楚就是一次完整的物联网实操。
别用:Wi-Fi 和蓝牙设备它管不了,只认 Zigbee,买之前先去支持设备列表里查型号;想零配置开箱即用的人也会劝退,它至少要一根协调器加一个 MQTT broker。
三个真实的坑
- 断电重启后设备全部丢失。issue #11759(56 条讨论,2026-11-19 查):容器重启后所有设备 unavailable,多数根因是 data 目录没挂卷、database.db 丢了,命令里那条挂载千万别省。
- 飞利浦设备 OTA 升级失败。issue #10139(168 条讨论,2026-11-19 查):Hue 系列的传感器和开关 OTA 反复卡住,固件通道要求高,先在设备页查固件版本再动手。
- 小米设备电池电量不准。issue #8499(338 条讨论,2026-11-19 查):电池百分比跳变是多年的老问题,做低电量告警时阈值要留出余量。
小结
回到开头那一排网关:一根 USB 协调器加一台小主机,就能把散落在各家 App 里的传感器统一收进自己的 MQTT 总线。今晚插上协调器配对第一个门磁,明早它的状态就落在你自己的服务器上了。
参考资料
- 仓库:https://github.com/Koenkk/zigbee2mqtt
- 入门文档:https://www.zigbee2mqtt.io/guide/getting-started/
- Docker 安装:https://www.zigbee2mqtt.io/guide/installation/02_docker.html
- issue #11759:https://github.com/Koenkk/zigbee2mqtt/issues/11759
- issue #10139:https://github.com/Koenkk/zigbee2mqtt/issues/10139
- issue #8499:https://github.com/Koenkk/zigbee2mqtt/issues/8499
默认评论
Halo系统提供的评论