CloudPub Home Assistant — настройка без белого IP

Введение

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

Существует несколько способов организовать удалённый доступ к Home Assistant. Основные варианты разобраны в статье Удалённый доступ к Home Assistant: обзор способов. В этой публикации рассматривается один из практических сценариев — использование CloudPub при отсутствии белого IP-адреса или невозможности настраивать маршрутизацию у провайдера.

Ниже разобрана установка и подключение CloudPub для разных типов установки Home Assistant: HAOS, Supervised, Container и Core. Перед началом убедитесь, что Home Assistant установлен и работает, у вас есть доступ к панели администратора, создан аккаунт CloudPub и в личном кабинете доступен «Ваш ключ API».

Настройка прокси для Home Assistant

При публикации Home Assistant через CloudPub важно корректно настроить работу за обратным прокси. CloudPub передаёт в Home Assistant заголовки X-Forwarded-For и X-Forwarded-Proto, поэтому в configuration.yaml необходимо разрешить доверенные прокси. Без этой настройки при обращении по внешнему адресу появится ошибка 400: Bad Request, а в логах будет сообщение Received X-Forwarded-For header from an untrusted proxy.

Базовая конфигурация:

http:
  use_x_forwarded_for: true
  trusted_proxies:
    - 172.30.33.0/24

Подсеть 172.30.33.0/24 используется в HAOS и относится к внутренней сети Supervisor. При установке через Docker Compose эта подсеть обычно отличается. Чтобы определить её, выполните docker network ls — в списке будет сеть вида <имя_проекта>_default. Затем выполните docker network inspect <имя_сети> и найдите параметр Subnet. Именно эту подсеть необходимо добавить в trusted_proxies.

В типичной установке Docker Desktop на macOS используется подсеть, например 172.18.0.0/16. При публикации через CloudPub также может потребоваться добавить диапазон edge-прокси сервиса (например 172.64.0.0/13) и шлюз Docker Desktop (192.168.65.1), если в логах Home Assistant появляется сообщение о недоверенном прокси. Если после настройки сохраняется ошибка 400, выполните docker logs homeassistant — в выводе будет указан IP-адрес прокси, который необходимо добавить в trusted_proxies.

Если запрос приходит через IPv6 loopback-адрес ::1 (что часто происходит при запуске Home Assistant из исходного кода), его необходимо явно добавить в список доверенных прокси:

http:
  use_x_forwarded_for: true
  trusted_proxies:
    - 127.0.0.1
    - ::1

Установка CloudPub в Home Assistant

Home Assistant OS (HAOS)

В HAOS установка выполняется через систему дополнений.

1. Перейдите в раздел «Дополнения» → «Магазин дополнений»
2. В правом верхнем углу откройте меню и выберите «Репозитории»
3. Добавьте репозиторий: https://github.com/black-roland/hassio-addon-cloudpub
4. Найдите дополнение CloudPub и выполните установку
5. В настройках дополнения вставьте полученный API-ключ
6. Запустите дополнение и включите автозапуск

После запуска в логах появится сообщение о регистрации сервиса:

18:24:04 INFO: Выполнение команды: clo --conf /config/client.toml --log-level warn register --name homeassistant http homeassistant:8123
Сервис зарегистрирован: [homeassistant] http://homeassistant:8123 -> https://example-name.cloudpub.ru:443
INFO: Сервис успешно зарегистрирован
INFO: Запуск клиента CloudPub
Сервис опубликован: [homeassistant] http://homeassistant:8123 -> https://example-name.cloudpub.ru:443 Live

Внешний адрес (https://example-name.cloudpub.ru) также отображается в личном кабинете CloudPub в разделе «Публикации».

Home Assistant Supervised (Debian)

Установка выполняется через Supervisor и полностью повторяет шаги, описанные для HAOS: добавление репозитория, установка дополнения, вставка API-ключа и запуск сервиса. Процесс идентичен версии HAOS.

Home Assistant Container (Docker)

Для установки через Docker создайте файл docker-compose.yaml согласно официальной документации CloudPub: https://cloudpub.ru/docs/cases/home-assistant. После создания файла выполните запуск контейнеров через docker compose up -d и проверьте логи, чтобы убедиться, что сервис успешно зарегистрирован и опубликован. Внешний адрес будет доступен как в логах контейнера, так и в личном кабинете CloudPub в разделе «Публикации».

Если вы используете macOS и работаете через Docker Desktop, можно воспользоваться следующим примером конфигурации. Он отличается указанием platform: linux/amd64 и отсутствием network_mode: host.

services:
  homeassistant:
    container_name: homeassistant
    image: homeassistant/home-assistant:stable
    volumes:
      - ./config:/config
      - /etc/localtime:/etc/localtime:ro
    environment:
      - TZ=Your/Timezone
    restart: always
    ports:
      - 8123:8123

  cloudpub:
    container_name: cloudpub
    platform: linux/amd64
    image: cloudpub/cloudpub:latest
    environment:
      - TOKEN=YOUR_TOKEN_HERE
    command: publish http host.docker.internal:8123 --name homeassistant
    restart: always
    depends_on:
      - homeassistant

Home Assistant Core (Python)

1. В личном кабинете https://cloudpub.ru/ скачайте и установите приложение для вашей операционной системы (доступны версии с графическим интерфейсом и утилита командной строки)
2. Запустите Home Assistant Core из исходного кода, как описано в статье Установка Home Assistant Core: максимум контроля, минимум удобства. Для настроенного окружения запуск с исходного кода осуществляется командами source .venv/bin/activate && ./script/server
3. Убедитесь, что Home Assistant доступен по адресу http://localhost:8123/
4. В приложении CloudPub выберите пункт меню «Публикация», укажите локальный порт 8123 и выполните публикацию сервиса
5. После публикации проверьте доступ к системе по выданному внешнему адресу

Итог

CloudPub позволяет быстро и безопасно организовать удалённый доступ к Home Assistant для HAOS, Supervised, Container и Core при отсутствии белого IP без необходимости настраивать сложную сетевую инфраструктуру.

Полезные ссылки

• Использование CloudPub — официальная документация CloudPub по работе с Home Assistant.
• Дополнение CloudPub для Home Assistant — дополнение Home Assistant для интеграции с CloudPub.