Как установить и настроить Zigbee2MQTT на VPS

MAATRIX

Фирменные хабы Aqara, Xiaomi и Tuya упираются в облако производителя: пропал интернет — не работают даже локальные сценарии, а иногда устройство и вовсе отваливается после очередного «улучшения» прошивки. Zigbee2MQTT убирает эту зависимость: он превращает обычный USB-донгл в универсальный Zigbee-координатор и публикует все данные в MQTT, откуда их читает Home Assistant, Node-RED или что угодно ещё. Ниже — рабочая связка Mosquitto + Zigbee2MQTT в Docker на VPS, включая честный разговор о том, где физически должен стоять сам радиомодуль.

Zigbee2MQTT и VPS: важный нюанс с координатором

Прежде чем копировать docker-compose.yml, стоит понять один момент, который часто упускают в общих мануалах. Zigbee2MQTT — это программный мост между Zigbee-сетью и MQTT-брокером, но радиосигнал он принимает через физический координатор: USB-донгл вроде Sonoff ZBDongle-P/E, ConBee II или модуль на CC2652/EFR32. Zigbee работает на частоте 2.4 ГГц с дальностью в десятки метров, и координатор обязан физически находиться там же, где ваши лампочки, розетки и датчики — то есть у вас дома или в офисе.

Облачный VPS в дата-центре Москвы, Франкфурта или Нью-Йорка физически не может «видеть» ваши Zigbee-устройства — даже если бы к серверу можно было подключить USB-донгл, толку от него не было бы: он слушал бы эфир дата-центра, а не вашей квартиры. Поэтому есть два рабочих варианта:

1. Сетевой координатор. Устройства вроде SLZB-06 (SMLIGHT) или ZigStar LAN/PoE содержат Zigbee-радио и Ethernet-порт одновременно: координатор стоит дома, отдаёт поток по TCP, а сам Zigbee2MQTT может работать где угодно — хоть на VPS, если между сервером и координатором поднят VPN-туннель.
2. Проброс обычного USB-донгла по сети через ser2net на любом мини-компьютере дома (Raspberry Pi, старый ноутбук, роутер с OpenWrt) — донгл остаётся дешёвым USB-модулем, а по сети «наружу» торчит TCP-порт с сериальным потоком.

В обоих случаях между домашней сетью и VPS нужен VPN — для этого подойдёт обычный WireGuard на Ubuntu 24.04. Дальше статья строится вокруг этой архитектуры: VPS хранит Zigbee2MQTT, брокер и всю автоматизацию, а координатор физически остаётся дома.

Выбор координатора и подготовка сети

Если координатора ещё нет, для связки с удалённым сервером логичнее сразу брать модель со встроенным Ethernet или Wi-Fi, а не голый USB-донгл — так вы избегаете лишнего звена в виде отдельного мини-ПК под ser2net:

Для варианта с ser2net на Raspberry Pi (Raspberry Pi OS/Debian) конфиг простой — файл /etc/ser2net.yaml:

connection: &con01
  accepter: tcp,6638
  connector: serialdev,/dev/ttyUSB0,115200n81,local
  options:
    kickolduser: true

Проверьте, что порт донгла действительно /dev/ttyUSB0 — ls -l /dev/serial/by-id/ покажет стабильный путь, который лучше использовать вместо ttyUSB0 (номер может меняться при переподключении). После правки конфига:

sudo systemctl restart ser2net
sudo systemctl enable ser2net

Порт 6638 наружу в интернет не открываем — он будет доступен только внутри VPN-туннеля, который поднимем следующим шагом.

Туннель между домашней сетью и VPS

На VPS и дома поднимается WireGuard: сервер на VPS, клиент — на роутере или том же Raspberry Pi с ser2net. Подробный пошаговый разбор установки — в статье про WireGuard на Ubuntu 24.04, здесь только ключевые адреса для примера:

• VPS (сервер): 10.10.0.1/24
• Домашний узел с координатором: 10.10.0.2/24

После поднятия туннеля с VPS должен открываться TCP-порт координатора:

nc -zv 10.10.0.2 6638

Если соединение установлено — можно переходить к самому Zigbee2MQTT. Если нет — сначала чините туннель, дальнейшие шаги без него бессмысленны.

Установка Docker и Mosquitto на VPS

На чистом Ubuntu 24.04 ставим Docker Engine и Compose-плагин:

curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker $USER

Создаём рабочую директорию и структуру:

mkdir -p ~/z2m-stack/{mosquitto/config,mosquitto/data,mosquitto/log,zigbee2mqtt/data}
cd ~/z2m-stack

Конфиг брокера mosquitto/config/mosquitto.conf:

listener 1883
allow_anonymous false
password_file /mosquitto/config/passwd
persistence true
persistence_location /mosquitto/data/
log_dest file /mosquitto/log/mosquitto.log

Анонимный доступ отключаем сразу — MQTT без пароля на сервере с выходом в интернет через Docker-порт лучше не оставлять, даже если планируете открывать порт только внутри VPN. Пароль создаётся после первого запуска контейнера.

Docker Compose: Mosquitto + Zigbee2MQTT

Файл ~/z2m-stack/docker-compose.yml:

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

  zigbee2mqtt:
    image: koenkk/zigbee2mqtt
    container_name: zigbee2mqtt
    restart: unless-stopped
    depends_on:
      - mosquitto
    volumes:
      - ./zigbee2mqtt/data:/app/data
      - /run/udev:/run/udev:ro
    ports:
      - "8080:8080"
    environment:
      - TZ=Europe/Moscow

Запускаем Mosquitto первым и создаём пользователя:

docker compose up -d mosquitto
docker exec -it mosquitto mosquitto_passwd -c /mosquitto/config/passwd z2muser
docker compose restart mosquitto

Конфиг Zigbee2MQTT zigbee2mqtt/data/configuration.yaml — ключевой момент здесь строка serial.port, которая указывает не на локальное устройство, а на сетевой адрес координатора через туннель:

homeassistant: true
permit_join: false
mqtt:
  base_topic: zigbee2mqtt
  server: mqtt://mosquitto:1883
  user: z2muser
  password: 'ваш_пароль'

serial:
  port: tcp://10.10.0.2:6638
  adapter: zstack   # для CC2652/CC1352; для EFR32 (Sonoff P/E) — ember

frontend:
  port: 8080

advanced:
  network_key: GENERATE
  log_level: info

Значение adapter зависит от чипа координатора: для Sonoff ZBDongle-E и большинства современных EFR32-модулей — ember, для TI CC2652/CC1352 (Sonoff ZBDongle-P, ряд ZigStar) — zstack. Если ошибиться, Zigbee2MQTT либо не запустится, либо будет падать при первых пакетах — в логах это видно сразу.

Поднимаем весь стек:

docker compose up -d
docker compose logs -f zigbee2mqtt

В логах должно появиться сообщение о успешном подключении к координатору и старте MQTT-соединения. Если видите таймаут на подключении к 10.10.0.2:6638 — проблема в туннеле или в ser2net, а не в самом Zigbee2MQTT.

Веб-интерфейс, привязка устройств и безопасность

Frontend Zigbee2MQTT слушает порт 8080. Открывать его в интернет напрямую не стоит — правильный путь через nginx с базовой авторизацией либо доступ только через тот же WireGuard-туннель (заходите на http://10.10.0.1:8080 уже находясь в VPN). Проверьте файрвол на VPS:

sudo ufw allow from 10.10.0.0/24 to any port 8080
sudo ufw allow 51820/udp   # порт WireGuard
sudo ufw enable

Для добавления устройства открываете фронтенд, жмёте Permit join (All) и включаете режим сопряжения на самом датчике или розетке (обычно долгое нажатие кнопки или пятикратный щелчок выключателем — смотрите инструкцию к конкретной модели). Устройство появится в списке за 10–30 секунд, дальше его можно переименовать и добавить в зону.

Раздел homeassistant: true в конфиге включает MQTT-автообнаружение — если на том же VPS или на соседнем сервере крутится Home Assistant в Docker Compose, устройства из Zigbee2MQTT появятся там сами, без ручной настройки интеграций. Для более сложных сценариев (условная логика, задержки, внешние API) удобно добавить рядом Node-RED на VPS — он читает те же MQTT-топики и не требует Home Assistant в качестве обязательного посредника.

Резервное копирование и восстановление после сбоя

Вся конфигурация Zigbee2MQTT, включая привязку устройств и сетевой ключ, лежит в zigbee2mqtt/data — этого достаточно для полного восстановления без повторного сопряжения каждого датчика:

tar czf z2m-backup-$(date +%F).tar.gz -C ~/z2m-stack zigbee2mqtt/data mosquitto/config

Сетевой ключ (network_key) стоит сохранить отдельно и не терять — без него после переустановки координатора придётся заново привязывать все устройства вручную, штука не быстрая, если их в доме под полсотни. Автоматизировать бэкапы на VPS удобно обычным cron с копированием архива на другой сервер или в объектное хранилище — держать единственную копию бэкапа на том же диске, где стоит сам стек, смысла немного.

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