Слой за слоем / xoloxi.org
Офтоп /

HOMEd ZigBee: из аддона Home Assistant в Docker

Что сохранить при переносе существующего инстанса и как не запустить два процесса на одном координаторе.

Отдельной частью домашнего переноса стал HOMEd ZigBee, который работал аддоном Home Assistant. Его вынесли в собственный Compose-проект на Orange Pi Zero 3, рядом с другим экземпляром HOMEd ZigBee.

Это перенос существующей сети, а не инструкция по созданию новой. Сохранение привязок зависит от состояния координатора, перенесённых данных, параметров сети и совместимости версий.

Сначала разделить два случая

Перенос серверного процесса с сохранением того же координатора и замена самого координатора — разные операции. Во втором случае может потребоваться отдельная процедура резервного копирования и восстановления сети.

Эта заметка посвящена первому случаю: координатор остаётся прежним, меняется место запуска HOMEd.

Что сохранить до остановки

Нужно определить фактически используемые пути и сохранить:

Типичные имена файлов — database.json, properties.json, options.json и backup.json, но конкретные пути задаются конфигурацией. Отсутствующий файл нельзя заменять пустым только ради совпадения со списком.

Особое внимание — instance, MQTT-префиксам, параметрам Home Assistant Discovery, типу адаптера, адресу координатора и сетевому ключу. Секреты не выводятся в публичные логи.

Остановить аддон вместе с автоматическим запуском

Перед окончательным копированием аддон нужно остановить. Для него также отключаются запуск при загрузке и watchdog.

Иначе Home Assistant может снова поднять старый экземпляр, когда новый уже подключился к тому же координатору.

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

Перенести данные в отдельный проект

В нашем переносе второй экземпляр получил собственный каталог /opt/homed/zigbee-ha. Для него использовались отдельные Compose-конфигурация и каталог данных.

Важен фактический bind mount, а не похожее название каталога. Если данные проброшены в /data, ссылки в конфигурации должны указывать на файлы внутри /data.

Переносимый инстанс сохраняет свою идентичность. Переименовывать instance, MQTT-префиксы и сущности «заодно с переездом» не стоит: это добавляет отдельную миграцию.

Первый запуск — без создания новой сети

Перед запуском проверяются совместимость версий, права доступа и соответствие путей. Обновление HOMEd лучше не совмещать с переносом без отдельной необходимости.

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

В официальной инструкции отдельно отмечен риск write=true: случайная запись настроек может привести к необходимости повторного добавления устройств. Параметр нужно проверить по документации своей версии, а не копировать из примера.

Проверка после запуска

Успех — не просто статус контейнера Up.

Проверяются:

  1. Подключение к нужному координатору и MQTT.
  2. Загрузка ожидаемой базы устройств.
  3. Управление несколькими устройствами с питанием от сети.
  4. Поступление новых событий и показаний.
  5. Доступность прежних сущностей в Home Assistant.
  6. Отсутствие второго процесса, управляющего тем же координатором.

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

Откат

Если приёмка не пройдена, целевой Compose-проект останавливается. Только после этого можно возвращать старый аддон.

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

Документация