Zigbee2MQTT на Ubuntu 24.04: пошаговая установка

MAATRIX

Фирменный Zigbee-хаб — это подписка на облако производителя, ограниченный список поддерживаемых устройств и риск, что через пару лет вендор просто закроет сервис вместе со всей автоматизацией. Zigbee2MQTT снимает эту зависимость: один USB-координатор и открытый софт понимают датчики, розетки и выключатели любого бренда, а вся логика остаётся у вас. Ниже — рабочая установка на Ubuntu 24.04 через Docker, с честным разбором того, где физически должен стоять адаптер и как это сочетается с арендованным сервером.

Что такое Zigbee2MQTT и когда он вместо фирменного хаба

Zigbee2MQTT — открытый проект, который превращает Zigbee-координатор в USB-исполнении в мост к MQTT-брокеру: устройство шлёт показания в топики вида zigbee2mqtt/датчик-двери, а команды приходят обратно тем же путём. С этим брокером умеет разговаривать что угодно — Home Assistant, Node-RED, собственный скрипт на Python — без привязки к облаку конкретного вендора.

Разница с фирменными хабами (Aqara Hub, Xiaomi Gateway, IKEA Dirigera) в трёх вещах: список поддерживаемых устройств у Zigbee2MQTT — это не «что решил производитель», а community-база из нескольких тысяч моделей разных брендов; данные не обязаны покидать вашу сеть; и обновления координатора с прошивками устройств вы контролируете сами, без внезапных «улучшений» от вендора, ломающих совместимость. Плата за это — придётся один раз настроить инфраструктуру самостоятельно, дальше система работает без внимания месяцами.

Zigbee-координатор: какой выбрать и где физическое ограничение

Прежде чем открывать терминал, стоит проговорить единственное по-настоящему жёсткое ограничение: Zigbee-радио — это физический USB-адаптер, и Zigbee2MQTT должен работать на машине, к которой этот адаптер физически подключён. Zigbee не передаётся по сети как Wi-Fi — сигнал координатора действует в радиусе обычной квартиры или дома, поэтому воткнуть его в облачный VPS в другой стране, разумеется, бессмысленно.

Из адаптеров, с которыми Zigbee2MQTT работает стабильно и без танцев с самодельными прошивками:

Для новой сети разумно брать ZBDongle-E или ZBDongle-P — у обоих активная поддержка проекта и понятная процедура обновления прошивки. Отсюда вытекает архитектура: если основной сервер — арендованный VPS, координатор физически стоит дома на недорогом мини-ПК, а на сервере крутится MQTT-брокер и, например, Home Assistant, получающие данные через VPN-туннель. Если умный дом целиком локальный, всё — координатор, Zigbee2MQTT, брокер — ставится на один сервер в квартире. Установка самого Zigbee2MQTT ниже одинакова в обоих случаях, разница только в том, где физически стоит машина с адаптером.

Подготовка Ubuntu 24.04 и определение USB-адаптера

Если сервер только что развёрнут, сначала стоит выполнить базовую настройку — обновления, отдельный пользователь, SSH-ключи. Это подробно разобрано в статье про первичную настройку Ubuntu 24.04.

Подключаем координатор к USB-порту и находим его в системе:

lsusb | grep -iE "silicon|texas|ftdi|cp210"
ls -l /dev/serial/by-id/

Вторая команда важнее первой: она покажет постоянный путь вида /dev/serial/by-id/usb-ITead_Sonoff_Zigbee_3.0_USB_Dongle_Plus_.... Использовать нужно именно его, а не /dev/ttyUSB0 или /dev/ttyACM0 — эти имена присваиваются в порядке подключения USB-устройств и после перезагрузки могут поменяться местами, из-за чего Zigbee2MQTT после ребута сервера внезапно перестаёт видеть сеть.

Дальше ставим Docker Engine из официального репозитория — версия из штатных пакетов Ubuntu обычно старее и без docker compose plugin. Подробности — в статье установка Docker на Ubuntu 24.04, здесь минимальный набор команд:

sudo apt update
sudo apt install -y ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc

echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu \
  $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin
sudo systemctl enable --now docker
sudo usermod -aG docker $USER
newgrp docker

Ещё один нюанс: пользователь, от имени которого работает Docker, должен иметь доступ к последовательному порту. Обычно устройство принадлежит группе dialout:

ls -l /dev/serial/by-id/*
sudo usermod -aG dialout $USER

После этой команды нужно перелогиниться (или перезапустить сессию SSH), иначе изменение группы не подхватится.

Установка MQTT-брокера и Zigbee2MQTT в Docker

Zigbee2MQTT сам по себе — не сервер, а клиент MQTT, поэтому первым делом нужен брокер. Проще всего — Eclipse Mosquitto тем же docker compose. Создаём структуру каталогов и файл конфигурации:

mkdir -p /opt/zigbee2mqtt/{data,mosquitto/config,mosquitto/data,mosquitto/log}
cd /opt/zigbee2mqtt
nano mosquitto/config/mosquitto.conf

Минимальный конфиг брокера — слушаем только внутри docker-сети и localhost, пароль настроим отдельно, если брокер понадобится извне:

listener 1883
allow_anonymous true
persistence true
persistence_location /mosquitto/data/
log_dest file /mosquitto/log/mosquitto.log

allow_anonymous true подходит только для брокера, который не торчит наружу — держите порт 1883 закрытым firewall'ом, к этому вернёмся ниже. Теперь docker-compose.yml:

services:
  mosquitto:
    container_name: mosquitto
    image: eclipse-mosquitto:2
    restart: unless-stopped
    ports:
      - "127.0.0.1:1883:1883"
    volumes:
      - ./mosquitto/config:/mosquitto/config
      - ./mosquitto/data:/mosquitto/data
      - ./mosquitto/log:/mosquitto/log

  zigbee2mqtt:
    container_name: zigbee2mqtt
    image: koenkk/zigbee2mqtt
    restart: unless-stopped
    depends_on:
      - mosquitto
    ports:
      - "8080:8080"
    volumes:
      - ./data:/app/data
      - /run/udev:/run/udev:ro
    devices:
      - /dev/serial/by-id/usb-ITead_Sonoff_Zigbee_3.0_USB_Dongle_Plus_XXXXXXXX-if00-port0:/dev/ttyACM0
    environment:
      - TZ=Europe/Moscow

Путь в devices нужно заменить на реальный, полученный на предыдущем шаге командой ls /dev/serial/by-id/. Запускаем оба контейнера:

docker compose up -d
docker compose logs -f zigbee2mqtt

При первом запуске Zigbee2MQTT сам создаст data/configuration.yaml со значениями по умолчанию и, если координатор определился штатно, начнёт слать в лог сообщения о старте адаптера.

Настройка configuration.yaml, первый запуск и привязка устройств

Открываем сгенерированный файл и приводим ключевые параметры к рабочему виду:

homeassistant: true
permit_join: false
mqtt:
  base_topic: zigbee2mqtt
  server: mqtt://mosquitto:1883
serial:
  port: /dev/ttyACM0
frontend:
  port: 8080
advanced:
  network_key: GENERATE
  log_level: info

homeassistant: true включает MQTT discovery — если рядом крутится Home Assistant, устройства появятся в нём автоматически, без ручного прописывания сущностей. network_key: GENERATE заставит Zigbee2MQTT сгенерировать случайный сетевой ключ при первом запуске вместо дефолтного публичного — сделать это стоит один раз, до привязки первых устройств: смена ключа позже означает заново привязывать всю сеть.

permit_join: false — сеть по умолчанию закрыта для новых устройств, это правильное состояние для повседневной работы. Привязка нового датчика или розетки выглядит так:

1. Открываем веб-интерфейс на http://IP-сервера:8080.
2. На вкладке устройств нажимаем «Permit join» — окно привязки открывается на 254 секунды.
3. Переводим физическое устройство в режим сопряжения (обычно — зажать кнопку на 5-10 секунд до мигания индикатора, для розеток часто достаточно нескольких быстрых включений-выключений).
4. Устройство появляется в списке автоматически, Zigbee2MQTT определяет модель по vendor ID и подгружает готовый профиль с нужными атрибутами.

После применения любых правок configuration.yaml контейнер нужно перезапустить:

docker compose restart zigbee2mqtt

Отдельно про топологию: Zigbee — mesh-протокол, устройства с постоянным питанием (розетки, реле, некоторые лампы) работают как ретрансляторы, а датчики на батарейках — нет. Сеть из одних батареечных датчиков в радиусе 15+ метров от координатора держится нестабильно; несколько розеток-ретрансляторов, равномерно расставленных по квартире, решают проблему без доплаты за более мощный координатор.

Firewall, удалённый доступ через VPN и интеграция с Home Assistant

Порт 8080 (веб-интерфейс) и 1883 (MQTT) не должны торчать в интернет напрямую — это прямой доступ к управлению вашим домом. Базовая настройка firewall с UFW разобрана в статье про настройку UFW на Ubuntu 24.04, для этой связки минимум такой:

sudo ufw allow from 127.0.0.1 to any port 8080
sudo ufw allow from 127.0.0.1 to any port 1883
sudo ufw deny 8080
sudo ufw deny 1883

Если Home Assistant или другой клиент MQTT работает на той же машине, в той же docker-сети — портам наружу открываться не нужно, обращение идёт по внутреннему имени контейнера mosquitto. Если архитектура распределённая — координатор дома, а сервер автоматизации в аренде — связывать их через открытый интернет не стоит. Правильная схема: поднять WireGuard-туннель между домашней машиной и сервером (пошагово — в статье про WireGuard на Ubuntu 24.04) и указать в mqtt.server адрес сервера внутри VPN-подсети вместо mosquitto:1883, включив у брокера авторизацию по логину и паролю.

С Home Assistant связка настраивается почти без ручной работы: если homeassistant: true включён в конфиге Zigbee2MQTT, а Home Assistant подключён к тому же MQTT-брокеру через интеграцию MQTT (Settings → Devices & Services → Add Integration → MQTT), все Zigbee-устройства появляются как обычные сущности сами, без YAML. Подробности установки самого Home Assistant на сервер — в статье про Home Assistant на Ubuntu 24.04.

Резервную копию конфигурации Zigbee2MQTT делать стоит регулярно — там хранится сетевой ключ, без которого при сбое пришлось бы перепривязывать все устройства заново:

tar -czf zigbee2mqtt-backup-$(date +%F).tar.gz -C /opt/zigbee2mqtt data

Общий подход к автоматизации бэкапов на сервере с ротацией и выгрузкой за пределы машины — в статье автоматические бэкапы на Ubuntu 24.04.

Частые вопросы