Продвинутый

Настройка MQTT-брокера Eclipse Mosquitto

Алексей Кузнецов
Алексей Кузнецов
Системный администратор16 ноября 2026 г.15 мин чтения

Разбор работы Eclipse Mosquitto: как развернуть надежный MQTT-брокер для передачи данных в IoT-системах и обеспечить предсказуемость обмена сообщениями.

Настройка MQTT-брокера Eclipse Mosquitto

Разбор работы Eclipse Mosquitto: как развернуть надежный MQTT-брокер для передачи данных в IoT-системах и обеспечить предсказуемость обмена сообщениями.

Принципы работы протокола MQTT

Принципы работы протокола MQTT

Прежде чем переходить к установке Mosquitto, важно понимать, чем MQTT отличается от привычного нам HTTP. Если в веб-разработке мы привыкли к модели «запрос — ответ», где клиент инициирует общение, то в мире IoT всё работает иначе. MQTT (Message Queuing Telemetry Transport) — это легковесный протокол, построенный на принципе асинхронности. Это критически важно для домашних серверов и IoT-устройств, так как позволяет экономить ресурсы процессора и заряд батареи датчиков.

Модель издатель-подписчик

В основе MQTT лежит архитектура Publish/Subscribe (издатель — подписчик). Здесь нет прямого взаимодействия между устройствами. Вместо этого появляется посредник — брокер (в нашем случае Mosquitto), который берет на себя всю логику маршрутизации.

Работа строится по следующему сценарию:

  1. Издатель (Publisher) отправляет сообщение брокеру, указывая определённую тему (topic).
  2. Подписчик (Subscriber) сообщает брокеру, что его интересует конкретная тема.
  3. Брокер получает сообщение и рассылает его всем, кто на эту тему подписан.

С практической точки зрения это даёт колоссальную гибкость. Например, ваш датчик температуры на базе ESP32 может просто «выплескивать» данные в сеть, не зная, кто их получит: система умного дома вроде Home Assistant, скрипт на Python для сбора статистики в базу данных или мобильное приложение.

Для понимания того, как это выглядит в консоли, можно использовать стандартные утилиты mosquitto_pub и mosquitto_sub.

Сначала откроем терминал и запустим процесс прослушивания темы home/livingroom/temp:

bash
# Подписываемся на топик и ждём сообщений
mosquitto_sub -h localhost -t "home/livingroom/temp" -v

Теперь в другом окне терминала отправим тестовое значение:

bash
# Публикуем значение температуры
mosquitto_pub -h localhost -t "home/livingroom/temp" -m "22.5"

После выполнения второй команды в первом окне вы увидите: home/livingroom/temp 22.5. Это и есть классический цикл обмена данными.

Структура топиков и качество обслуживания (QoS)

Предсказуемость системы напрямую зависит от того, как вы организуете иерархию топиков и какой уровень доставки сообщений выберете.

Иерархия топиков

Топики в MQTT — это строки, разделенные косой чертой /. Это не просто названия, а полноценная древовидная структура. Я всегда рекомендую строить иерархию от общего к частному.

Плохой пример: sensor1, temperature_kitchen, light_on. Хороший пример: home/kitchen/sensor/temperature, home/livingroom/light/status.

Использование слешей позволяет использовать подписки с подстановочными знаками (wildcards):

  • + — заменяет один уровень иерархии. Подписка на home/+/sensor/temperature позволит получать данные со всех датчиков во всех комнатах.
  • # — заменяет все последующие уровни. Подписка на home/kitchen/# вернёт вообще всё, что происходит на кухне.

Уровни QoS (Quality of Service)

Чтобы не гадать, дошло сообщение или нет, в протоколе предусмотрено три уровня качества обслуживания. Выбор уровня — это всегда компромисс между надёжностью и нагрузкой на сеть.

  1. QoS 0 (At most once) — «отправил и забыл». Сообщение доставляется максимум один раз. Если в момент передачи произошёл сбой сети, данные потеряны. Это идеальный вариант для потоковых данных, которые обновляются часто (например, текущая влажность воздуха), где потеря одного кадра не критична.
  2. QoS 1 (At least once) — «доставлено как минимум один раз». Брокер подтверждает получение сообщения. Если подтверждения нет, отправитель шлёт данные снова. Это гарантирует доставку, но может привести к дубликатам.
  3. QoS 2 (Exactly once) — «строго один раз». Самый сложный и ресурсоёмкий уровень. Используется четырёхэтапный процесс подтверждения, чтобы гарантировать, что сообщение дошло и не было продублировано. Это необходимо для критических команд, например, «открыть электронный замок».

При настройке клиентов важно помнить: уровень QoS, который вы указываете при публикации, не может быть выше, чем уровень, который поддерживает брокер или подписчик. Подробнее о механизмах работы каждого уровня можно прочитать в официальной документации MQTT.

Развертывание Mosquitto в Docker

Подготовка конфигурационного файла

Для работы Mosquitto достаточно небольшого файла конфигурации. Обычно его размещают в каталоге /mosquitto/config и монтируют в контейнер через Docker‑том. Ниже пример базового mosquitto.conf:

conf
#mosquitto.conf
listener 1883
allow_anonymous true          # при необходимости отключить: false
password_file /mosquitto/config/passwordfile
log_type all
  • listener — порт, на котором брокер принимает подключения.
  • allow_anonymous — разрешает подключение без авторизации; в продакшене обычно ставят false.
  • password_file — путь к файлу с пользователями и паролями.

Создать файл можно одной из команд. Например, в Linux‑терминале:

bash
cat > mosquitto.conf <<'EOF'
listener 1883
allow_anonymous true
password_file /mosquitto/config/passwordfile
log_type all
EOF

После этого подготовьте файл паролей. Mosquitto поставляется утилитой mosquitto_passwd:

bash
docker run -it --rm eclipse-mosquitto:2 \
  mosquitto_passwd -c /mosquitto/config/passwordfile alice

Команда запускает контейнер лишь для создания/обновления файла passwordfile. Пользователь alice будет иметь пароль, который вы вводите при запросе.

Важно: если вы отключаете allow_anonymous, не забудьте добавить пользователей через mosquitto_passwd — иначе брокер не будет принимать подключения.

Официальная документация Mosquitto Docker‑image — в ней описаны все параметры конфигурации и примеры монтирования файлов.

Запуск контейнера через Docker Compose

Docker Compose — удобный способ управлять многоконтейнерными приложениями. Ниже минимальный docker-compose.yml, который поднимает Mosquitto и привязывает конфигурацию и файл паролей:

yaml
version: "3.8"
services:
  mosquitto:
    image: eclipse-mosquitto:2
    container_name: mosquitto
    ports:
      - "1883:1883"
    volumes:
      - ./mosquitto.conf:/mosquitto/config/mosquitto.conf:ro
      - ./passwordfile:/mosquitto/config/passwordfile:rw
    restart: unless-stopped

Пояснения:

  • volumes — монтируем наш mosquitto.conf в контейнер в режиме только чтения (:ro) и файл паролей в режиме чт/записи (:rw). Путь внутри контейнера должен совпадать с тем, что указан в mosquitto.conf.
  • ports — пробрасываем порт 1883 наружу, чтобы клиентские приложения могли подключаться к брокеру.
  • restart: unless-stopped — гарантирует, что контейнер будет автоматически запущен после перезагрузки хоста.

Запуск выглядит так:

bash
docker compose up -d

Команда docker compose ps покажет статус контейнера, а docker compose logs -f позволит смотреть журнал работы брокера в реальном времени.

Практический совет: если планируете хранить сообщения на постоянный случай, смонтируйте также каталог /mosquitto/data (или /mosquitto/db) в отдельный том. Это обеспечит сохранение сообщений при перезапуске контейнера.

Таким образом, за несколько минут вы получаете полностью рабочий MQTT‑брокер, готовый к подключению IoT‑устройств и к вашим собственным клиентам. Всё работает предсказуемо, а настройка остаётся в ваших руках.

Обеспечение безопасности соединения

Обеспечение безопасности соединения

Настройка аутентификации пользователей

Для того чтобы брокер принимал только проверенных клиентов, создайте файл паролей и отключите анонимный доступ.

bash
# Установите утилиту, если её ещё нет
sudo apt-get install -y mosquitto-clients

# Создайте файл паролей (пример: пользователь alice с паролем secret123)
mosquitto_passwd -c /etc/mosquitto/passwd alice
# При появлении запроса введите пароль и подтвердите его

Файл /etc/mosquitto/passwd будет содержать строки вида alice:secret123.

В конфигурационном файле mosquitto.conf добавьте:

conf
# Требуем аутентификацию, отключаем анонимный вход
allow_anonymous false

# Указываем путь к файлу паролей
password_file /etc/mosquitto/passwd

Перезапустите сервис, чтобы изменения вступили в силу:

bash
sudo systemctl restart mosquitto

Теперь каждому клиенту необходимо указать логин и пароль при подключении, например:

bash
mosquitto_sub -h broker.example.com -p 8883 --username alice --password secret123 -t "home/+/temp"

Использование TLS для шифрования трафика

Шифрование через TLS защищает данные от перехвата. Для Mosquitto достаточно задать сертификат и ключ, а также включить требуемую проверку сертификата клиента (если нужно).

bash
# Создайте self‑signed сертификат (для теста) или используйте сертификат от CA
openssl req -new -x509 -days 365 -nodes \
  -out /etc/mosquitto/certs/mosquitto.crt \
  -keyout /etc/mosquitto/certs/mosquitto.key \
  -subj "/CN=broker.example.com"

В mosquitto.conf добавьте listener для TLS и укажите файлы:

conf
# Порт для зашифрованного соединения
listener 8883

# Путь к сертификату и ключу
certfile /etc/mosquitto/certs/mosquitto.crt
keyfile  /etc/mosquitto/certs/mosquitto.key

# Требуем клиентский сертификат (опционально)
require_certificate true
use_identity_as_username false

Если требуется проверка клиентских сертификатов, разместите их в каталоге и укажите cafile:

conf
cafile /etc/mosquitto/certs/ca.crt

Перезапустите брокер:

bash
sudo systemctl restart mosquitto

Подключение клиента теперь выглядит так:

bash
mosquitto_pub -h broker.example.com -p 8883 --cafile /etc/mosquitto/certs/ca.crt \
  --username alice --password secret123 -t "home/+/temp" -m "test message"

Таким образом, аутентификация и TLS совместно обеспечивают предсказуемое и безопасное обмен сообщениями в IoT‑системах.

Мониторинг и отладка брокера

Мониторинг и отладка брокера

Когда брокер начинает вести себя непредсказуемо — сообщения задерживаются или клиенты внезапно отключаются — первым делом нужно перестать гадать и посмотреть на то, что происходит внутри системы. В IoT-среде, где количество подключений может расти лавинообразно, мониторинг становится не роскошью, а базовым требованием к инфраструктуре.

Анализ логов через journald

Если вы разворачивали Mosquitto как системный сервис через systemd, то вся информация о его работе попадает в journald. Это гораздо удобнее, чем искать текстовые файлы в /var/log, потому что системный журнал позволяет фильтровать события по времени, приоритету и конкретному юниту.

Для начала стоит проверить текущее состояние сервиса. Это поможет понять, не находится ли процесс в состоянии постоянной перезагрузки (boot loop):

bash
# Проверяем статус сервиса и последние несколько строк лога
systemctl status mosquitto

Если нужно детально изучить историю событий, используйте journalctl. С практической точки зрения, я рекомендую два сценария работы с логами.

Во-первых, просмотр логов в реальном времени. Это незаменимо, когда вы подключаете новое устройство и хотите сразу увидеть, как брокер реагирует на его попытку авторизации:

bash
# Следим за логами Mosquitto в режиме реального времени
journalctl -u mosquitto -f

Во-вторых, поиск конкретных ошибок. Если в логах много «мусора», можно отфильтровать только критические сообщения. Например, если вы ищете ошибки аутентификации, которые часто возникают из-за неверных паролей в конфигурации устройств:

bash
# Выводим только ошибки (priority 3 и выше) для сервиса mosquitto
journalctl -u mosquitto -p err

Для более глубокого анализа поведения брокера я советую настроить уровень логирования в самом конфиге /etc/mosquitto/mosquitto.conf. По умолчанию Mosquitto может не писать подробности, которые критически важны для отладки протокола. Чтобы видеть всё, добавьте или измените следующие параметры:

conf
# Уровень логирования: error, warning, notice, information, debug, trace
log_type error
log_type warning
log_type notice
log_type information

# Записывать ли логи в stdout (полезно при работе в Docker)
log_dest stdout

Обратите внимание: уровень debug или trace генерирует огромный объём данных. Не оставляйте их включенными на постоянной основе в рабочей среде, иначе вы быстро исчерпаете дисковое пространство.

Проверка работы с помощью mosquitto_sub

Когда с логами разобрались, нужно проверить саму логику обмена сообщениями. Для этого не обязательно писать полноценный скрипт на Python — в комплекте с Mosquitto идут отличные утилиты командной строки: mosquitto_pub для отправки и mosquitto_sub для подписки.

mosquitto_sub — это ваш главный инструмент для проверки того, доходят ли сообщения до нужных топиков.

Чтобы проверить, слушает ли брокер конкретный топик, запустите подписку на него. Я всегда использую символ # (wildcard), чтобы увидеть вообще все сообщения, которые проходят через брокер:

bash
# Подписываемся на все топики (используем -v для отображения имени топика перед сообщением)
mosquitto_sub -h localhost -t "#" -v

Если вы настроили авторизацию, не забудьте передать параметры пользователя и пароля, иначе брокер просто сбросит соединение:

bash
# Подписка с использованием логина и пароля
mosquitto_sub -h 192.168.1.50 -t "home/livingroom/temperature" -u "sensor_user" -P "secure_password_123" -v

Для полноценного теста «петли» (проверка, что сообщение уходит и корректно принимается) я обычно открываю два терминала. В первом запускаю mosquitto_sub, а во втором — mosquitto_pub:

bash
# Отправка тестового сообщения во втором терминале
mosquitto_pub -h localhost -t "test/topic" -m "Hello from terminal"

Если в первом терминале вы увидели test/topic Hello from terminal, значит, транспортный уровень и маршрутизация работают корректно. Если же сообщения не приходят, проверьте настройки listener в конфиге — возможно, брокер слушает только на 127.0.0.1, а вы пытаетесь подключиться по внешнему IP.

Подробную документацию по флагам этих утилит можно найти в официальном репозитории Eclipse Mosquitto.

Заключение

Итоги настройки

Развернутый Mosquitto — это не просто запущенный процесс, а предсказуемая точка обмена данными. Если вы следовали шагам выше, у вас есть работающий брокер, который не «упадет» при первом же шторме сообщений от датчиков и не позволит посторонним перехватить управление вашими устройствами.

С практической точки зрения, важно понимать: MQTT — протокол легковесный, но его надёжность целиком зависит от того, как вы настроили сессии и уровни качества обслуживания (QoS). Если вы используете Mosquitto в домашней лаборатории для управления освещением или климатом, не стоит пренебрегать авторизацией. Даже если ваши устройства находятся внутри закрытого сегмента сети, наличие парольной защиты в mosquitto.conf — это базовый гигиенический минимум.

Когда стоит пересмотреть конфигурацию

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

  1. Лимиты подключений. Если у вас много клиентских устройств, убедитесь, что системные лимиты (ulimit) позволяют открывать достаточное количество сокетов.
  2. Размер очереди. При большом количестве сообщений с QoS 1 или 2, брокер хранит их в памяти или на диске. Если диск переполнится, Mosquitto может аварийно завершить работу.
  3. Мониторинг. Не оставляйте брокер «вслепую». Я рекомендую настроить экспорт метрик. В современных версиях Mosquitto есть встроенная поддержка Prometheus exporter, что позволяет визуализировать нагрузку в Grafana.

Для проверки текущего состояния и нагрузки на систему можно использовать стандартную утилиту mosquitto_sub, чтобы убедиться, что сообщения проходят без потерь:

bash
# Подписываемся на все топики, чтобы увидеть общую картину трафика
mosquitto_sub -h localhost -t "#" -v

Что делать дальше

Если ваша инфраструктура IoT разрослась, следующим логичным шагом будет внедрение системы сбора и визуализации данных. MQTT — это всего лишь транспорт. Чтобы превратить поток байтов в полезную информацию, вам понадобятся:

  • InfluxDB или TimescaleDB — для хранения временных рядов (телеметрии).
  • Telegraf — как посредник, который заберет данные из MQTT и положит их в базу.
  • Grafana — для построения графиков.

С точки зрения архитектуры, старайтесь разделять потоки данных. Например, критически важные команды управления (например, «открыть замок») должны идти через топики с высоким приоритетом и строгим контролем доставки, а обычная телеметрия температуры может работать в более «расслабленном» режиме. Это обеспечит ту самую предсказуемость, к которой стоит стремиться в любой инженерной системе.

FAQ

Как обеспечить безопасность доступа к брокеру

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

Сначала создайте файл с паролями, используя утилиту mosquitto_passwd. Например, создадим пользователя iot_device:

bash
# Флаг -c создаёт новый файл паролей, если его нет. 
# Будьте осторожны: если файл уже существует, он будет перезаписан.
sudo mosquitto_passwd -c /etc/mosquitto/passwd iot_device

После этого отредактируйте основной конфиг /etc/mosquitto/mosquitto.conf. Важно явно запретить анонимные подключения и указать путь к файлу аутентификации:

conf
# Запрещаем вход без логина и пароля
allow_anonymous false

# Указываем путь к базе пользователей
password_file /etc/mosquitto/passwd

После внесения изменений перезапустите сервис через systemd, чтобы конфигурация вступила в силу:

bash
sudo systemctl restart mosquitto

Что делать, если сообщения не доходят до подписчика

Когда обмен данными не работает, я всегда начинаю с проверки трех уровней: сетевой доступ, корректность топиков и статус QoS (Quality of Service).

Во-первых, убедитесь, что порт 1883 открыт и брокер слушает нужный интерфейс. Проверить это можно командой ss:

bash
# Проверяем, слушает ли Mosquitto порт 1883 на всех интерфейсах
ss -tln | grep 1883

Во-вторых, проверьте соответствие топиков. В MQTT топики чувствительны к регистру: home/livingroom/temp и Home/LivingRoom/temp — это разные пути.

В-третьих, если вы используете QoS 1 или 2, убедитесь, что клиент-подписчик подтверждает получение сообщений. Если клиент постоянно отключается, брокер может не успевать обрабатывать очередь, что снижает предсказуемость системы. Для глубокого анализа трафика рекомендую использовать Wireshark, он умеет разбирать протокол MQTT и показывать содержимое пакетов.

Можно ли использовать Mosquitto в Docker

Да, это один из самых удобных способов развертывания для домашней лаборатории. Использование контейнера позволяет изолировать брокер и легко переносить его на другие узлы кластера.

Для предсказуемого управления лучше всего использовать Docker Compose. Создайте файл docker-compose.yml:

yaml
services:
  mosquitto:
    image: eclipse-mosquitto:latest
    container_name: mosquitto
    restart: unless-stopped
    ports:
      - "1883:1883"
      - "9001:9001"
    volumes:
      # Монтируем конфиг и директории для данных и логов
      - ./mosquitto/config:/mosquitto/config
      - ./mosquitto/data:/mosquitto/data
      - ./mosquitto/log:/mosquitto/log

Важный нюанс: при работе в Docker вы должны заранее подготовить файл конфигурации на хост-машине в папке ./mosquitto/config/mosquitto.conf. Если этого не сделать, контейнер может не запуститься или использовать настройки по умолчанию, которые не позволят вам подключиться извне контейнера.

Как настроить логирование для отладки

Если система работает нестабильно, логи — ваш главный инструмент. В Mosquitto можно настроить уровень детализации: от простых ошибок до записи каждого входящего и исходящего сообщения.

В файле конфигурации измените параметры log_type и log_dest. Для отладки проблем в домашней сети я обычно использую такой набор:

conf
# Направляем логи в stdout (чтобы их видел Docker или journald)
log_dest file /mosquitto/log/mosquitto.log
log_dest stdout

# Уровни логирования
log_type error
log_type warning
log_type notice
log_type information

# Если нужно видеть каждое сообщение (использовать только при отладке!)
# log_type subscribe
# log_type unsubscribe

Помните, что включение log_type debug или запись всех подписок на высоконагруженном брокере быстро забьёт дисковое пространство. В промышленной эксплуатации или на стабильно работающих домашних серверах лучше оставлять только error и warning.

Часто задаваемые вопросы

Как обеспечить безопасность при использовании Mosquitto в локальной сети?

По умолчанию брокер может быть открыт для любых подключений, что недопустимо даже в изолированной домашней лаборатории. Чтобы защитить данные, необходимо настроить аутентификацию через файл паролей и использовать уникальные логины для каждого устройства. Если вы планируете передавать данные через внешние сети, обязательно настройте поддержку TLS/SSL, чтобы шифровать трафик и предотвратить перехват сообщений.

Что делать, если устройства теряют связь с брокером?

В таких ситуациях стоит проверить стабильность сетевого соединения и настройки Keep Alive в конфигурации клиента. Если устройства работают от аккумуляторов, важно правильно подобрать интервал проверки связи, чтобы не разрядить их слишком быстро, но и не допустить «зависания» сессии на брокере. Также проверьте логи Mosquitto через journalctl -u mosquitto, чтобы понять, не отбрасывает ли брокер подключения из-за превышения лимитов.

Зачем использовать QoS, если можно передавать данные без подтверждения?

Уровни качества обслуживания (Quality of Service) позволяют управлять надёжностью доставки в зависимости от критичности данных. Если вам достаточно знать текущую температуру раз в час, используйте QoS 0, чтобы минимизировать нагрузку на сеть. Однако для критических событий, таких как срабатывание датчика протечки или команды управления замком, лучше настроить QoS 1 или QoS 2, чтобы гарантировать, что сообщение точно дойдёт до адресата.

Можно ли хранить историю сообщений в Mosquitto?

Сам по себе Mosquitto — это брокер, а не база данных, поэтому он не предназначен для долгосрочного хранения истории. Его задача — максимально быстро доставить сообщение и забыть о нём. Если вам нужно анализировать динамику показаний датчиков за неделю или месяц, настройте отдельный сервис-подписчик, который будет забирать данные из топиков и записывать их в базу данных, например, в PostgreSQL или InfluxDB.

Поделиться:TelegramX / TwitterVK