Zigbee2MQTT 容器部署完整指南：4 步跑通你的智能家居网关-开发者社区

Zigbee2MQTT 容器部署完整指南：4 步跑通你的智能家居网关

【免费下载链接】zigbee2mqttZigbee 🐝 to MQTT bridge 🌉, get rid of your proprietary Zigbee bridges 🔨项目地址: https://gitcode.com/GitHub_Trending/zi/zigbee2mqtt

Zigbee2MQTT 容器部署这条路，很多人栽在同一个坑：依赖装不干净，服务起一半就崩。它做的事很简单：把 Zigbee 设备的数据变成 MQTT 消息，让别的系统直接订阅。装进容器，依赖和环境一起打包，坏了整包重拉。照做完，你的服务几分钟内跑起来。

先花 30 秒认识它：为什么值得跑在容器里

Zigbee2MQTT 是个"翻译"：一头接 Zigbee 协调器（那个 USB 小棒或以太网网关），另一头接 MQTT broker（可以理解成局域网里的消息总线）。你的门磁、温度传感器上报数据，它翻译成标准 MQTT 消息发到总线上。

看图从左到右：协调器负责无线通信，核心服务做协议翻译，MQTT broker 负责发布订阅，右边的网页（默认 8080 端口）用来管理设备。

跑在容器里给的是具体结果：一条docker build就得到完整运行环境，不用折腾 Node.js 版本；镜像标签即版本，切换和回滚换个标签就行；坏了删掉容器重跑，两分钟恢复正常。

开工前备齐三样东西

Zigbee 协调器：USB 型（CC2531、CC2652）或以太网型均可。缺了它，服务直接报 USB adapter discovery error，根本启动不了。
Docker 和 Docker Compose：跑一下docker --version能出版本号就行。缺了它，后面所有容器命令都执行不了。
串口和设备权限：协调器插上后在主机上应显示为 /dev/ttyACM0 或 /dev/ttyUSB0，且当前用户在 dialout 组里。缺了它，容器会报 permission denied。

部署四步走：从克隆到跑通

1️⃣ 获取代码：把仓库克隆到本地

目的：拿到源码和 Docker 构建文件，后续所有命令都在这台机器上做。

git clone https://gitcode.com/GitHub_Trending/zi/zigbee2mqtt cd zigbee2mqtt

仓库里既有源码，也有现成的 Docker 构建文件，克隆完不需要单独装 Node.js。
cd进目录后，后面的命令都用相对路径，别跳开。
先确认docker/Dockerfile存在，再往下走。

怎么算成功：ls docker/Dockerfile能打印出这个文件路径。

2️⃣ 构建镜像：一次打包好运行环境

目的：按 docker/Dockerfile 把程序、依赖和运行时打进一个 Docker 镜像。

docker build -t zigbee2mqtt:latest -f docker/Dockerfile .

-t zigbee2mqtt:latest：给镜像起的名字和版本标签，启动时要用。
-f docker/Dockerfile：指定构建文件，基于 Alpine + Node.js 打包。
末尾的.：告诉 Docker 在当前目录找构建所需文件。

怎么算成功：docker images zigbee2mqtt能看到 latest 这一行。

3️⃣ 配置参数：写对你的 configuration.yaml

目的：把配置写对。这一步是 Docker 部署 Zigbee2MQTT 里最容易翻车的地方，它决定服务能不能连上设备和 broker。仓库里有一份样例 data/configuration.example.yaml 可照着抄。注意：配置文件放在主机目录里，别写进仓库。

mkdir -p ~/zigbee2mqtt-data

在~/zigbee2mqtt-data/configuration.yaml里写：

mqtt: base_topic: zigbee2mqtt server: "mqtt://localhost" frontend: enabled: true port: 8080 serial: port: /dev/ttyACM0 adapter: zstack

mqtt.server：你的 MQTT broker 地址，不在本机就换成真实 IP。
mqtt.base_topic：消息的根主题，设备数据会发到zigbee2mqtt/设备名下。
frontend.port：网页端口，和后面-p参数保持一致。
serial.port：协调器的串口路径，用ls /dev/tty*确认。
serial.adapter：芯片类型，zstack、ember、deconz、zboss 四选一。

怎么算成功：文件用纯空格缩进、没有 Tab；serial.port和实际设备路径一致。

4️⃣ 启动容器：把串口和数据目录挂进去

目的：把服务跑起来，让容器看得到协调器，你能打开管理页。

docker run -d --name zigbee2mqtt \ --restart unless-stopped \ -p 8080:8080 \ -v ~/zigbee2mqtt-data:/app/data \ --device=/dev/ttyACM0:/dev/ttyACM0 \ zigbee2mqtt:latest

-p 8080:8080：把容器里的网页端口映射到主机。
-v ...:/app/data：挂载数据目录，docker/docker-entrypoint.sh 约定数据就放在 /app/data。
--device=...：把协调器串口传进容器，换成你的实际设备路径。
--restart unless-stopped：崩溃或主机重启后服务自动拉起。

怎么算成功：docker logs -f zigbee2mqtt看到 "Started Zigbee2MQTT" 且没有 Error；浏览器打开 http://localhost:8080 能看到设备列表页。

跑起来之后：3 条保命建议 + 3 个高频翻车点

保命建议：

资源：加--memory 512m限制内存，日常几十 MB 够用，避免吃满宿主机。
日志：compose 里写logging: max-size: 10m, max-file: "3"，不然日志会越滚越大。
重启：--restart unless-stopped别省，断电后服务自己回来，不用人盯。

高频翻车点：

起不来：日志刷 USB adapter discovery error → 容器没拿到串口 → 补上--device参数，或核对serial.port是否写错。
设备配不上：入网一直超时无响应 → 设备没进配对模式或信号弱 → 靠近协调器，长按配对键 3~5 秒再试。
MQTT 断连：日志刷 MQTT connection failed → broker 地址或账号密码不对 → 改mqtt.server，必要时补 user/password 两行。